---
title: "Changes a property's name, data type or options."
method: PATCH
path: "/api/v1/items/{id}/properties/{propertyId}"
tags: ["ItemProperties"]
---

# Changes a property's name, data type or options.

`PATCH /api/v1/items/{id}/properties/{propertyId}`

## Request

- Base URL: `https://app.flexonthejob.com`
- URL: `https://app.flexonthejob.com/api/v1/items/{id}/properties/{propertyId}`
- Auth: HTTP bearer

Requires `ManageTemplates` and an `Idempotency-Key` header — in the app a property's
definition is edited on the Item Templates page. Only the fields sent change, all in one
save (every field is validated first). Rules as on that page: names are unique on the item;
changing `dataType` clears the value unless the new type is `Text` and is refused
while the property has an enabled calculation. Additionally: options are allowed only for
`Dropdown` / `MultiSelect` and dropped when the type leaves them; `Cost` /
`Unit Price` cannot be changed and are reserved names. Inventory units keep their copies
under the old name / type (as with the page).
Example: `{ "dataType": "Dropdown", "options": ["Red", "Blue"] }`.

## Path parameters

- `id` integer, required
- `propertyId` integer, required

## Request body

- UpdateItemPropertyApiRequest: Body of `PATCH /api/v1/items/{id}/properties/{propertyId}`: change a property's definition. Omitted (or null) fields are unchanged; at least one is required. Example: `{ "dataType": "Dropdown", "options": ["Red", "Blue"] }`.
  - `name` string, nullable: New name, 1-100 characters, unique on the item (case-insensitive); `Cost` / `Unit Price` are reserved.
  - `dataType` 'Text' | 'Number' | 'Date' | 'Boolean' | 'Dropdown' | 'MultiSelect'
  - `options` string[], nullable: Full replacement option list for a `Dropdown` / `MultiSelect` property (at most 200 options, each 1-200 characters, no commas, no duplicates); `[]` clears it. Existing values are not re-checked.

## Response `200`

Changed; body is the item's properties.

- ItemPropertiesResponse: Body of `GET /api/v1/items/{id}/properties` and of every custom-field write: all of an item's properties (custom fields) with their definitions and current values, ordered by name.
  - `itemId` integer: The item (template) id, e.g. `12`.
  - `properties` ItemPropertyDto[]: Every property of the item, including the pricing properties `Cost` and `Unit Price`.
    - `id` integer: Property id, e.g. `341`; used by the per-property routes.
    - `name` string: Property name as shown in the app, e.g. `"Color"` (unique per item, case-insensitive).
    - `value` string: Current value as stored, never null (`""` = no value). Numbers are decimal strings (`"12.5"`), booleans `"true"`/`"false"`, dates `yyyy-MM-dd`, MultiSelect a comma-separated list of options (`"Red,Blue"`). A calculated property shows its last computed value.
    - `dataType` 'Text' | 'Number' | 'Date' | 'Boolean' | 'Dropdown' | 'MultiSelect'
    - `options` string[]: Allowed values for `Dropdown` / `MultiSelect`, e.g. `["Red","Blue"]`; empty for other types (and for a list property that has no options yet, which then accepts any value).
    - `isCalculated` boolean: True when the value comes from a calculation (a formula authored in the app). Calculated properties are read-only here: value writes answer `409`.
    - `calculationExpression` string, nullable: The calculation's formula as stored (references appear as `{n}` placeholders), or null when not calculated. Informational only.
    - `isItemLevel` boolean: True for an item-level property added to this item only (Items page "add property", or `POST /api/v1/items/{id}/properties`); false for a property that came from the item's Item Template (template builder), its category or item creation.
    - `isCustomized` boolean: True when a template-builder property's value was set on this item and so no longer follows the Item Template ("Customized" in the app). `POST .../properties/{propertyId}/revert` undoes it.
    - `isPricing` boolean: True for `Cost` and `Unit Price`: required on every item and changed through `PATCH /api/v1/items/{id}` (`cost` / `unitPrice`), never through the custom-field routes (`409`).
  - `propagated` integer: Writes only (0 on GET): how many inventory units' copies of the property were changed by the write (a new value flowing to units that were not individually customized, a new item-level property added to existing units, or the copies removed with a deleted one).

## Other responses

- `400`: Empty body (no field to change), malformed body, or missing `Idempotency-Key`.
- `401`: Unauthorized
- `403`: The key lacks `ManageTemplates`.
- `404`: No such property on an active item in this organization.
- `409`: Another property already has the name, the type change is blocked by an enabled calculation, the property is `Cost` / `Unit Price`, or the key's creator is unknown on this server.
- `422`: Blank or reserved name, options on a non-list type, or an invalid option (blank, comma, duplicate); or `Idempotency-Key` reused with a different body.
- `429`: Too Many Requests

---

[API](https://skmtc.dev/flexonthejob/apis/flex-api.md) · [All operations](https://skmtc.dev/flexonthejob/apis/flex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/flexonthejob/apis/flex-api/revisions/19c8f4d27acf?raw)