---
title: "Sets one custom-field value on one inventory unit."
method: PUT
path: "/api/v1/items/{id}/units/{unitId}/properties/{name}"
tags: ["ItemUnits"]
---

# Sets one custom-field value on one inventory unit.

`PUT /api/v1/items/{id}/units/{unitId}/properties/{name}`

## Request

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

Requires `ManageInventory` and an `Idempotency-Key` header. Same as editing the
value on the unit's Inventory edit page: the unit's copy becomes customized
(`isCustomized`) and stops following the item's value, and the unit's calculated values
that read it are recomputed in the same write. Only this unit changes — to change the item
and every uncustomized unit use `PATCH /api/v1/items/{id}/properties`. The value is
checked against the property's type and options; calculated values and `Cost` /
`Unit Price` are refused. `{name}` is the property name, URL-encoded,
case-insensitive. Fires `item.updated` (`changedFields``unitProperties`).
Example: `PUT /api/v1/items/12/units/5012/properties/Color` with `{ "value": "Blue" }`.

## Path parameters

- `id` integer, required
- `unitId` integer, required
- `name` string, required

## Request body

- SetItemUnitPropertyApiRequest: Body of `PUT /api/v1/items/{id}/units/{unitId}/properties/{name}`: the unit's new value. Example: `{ "value": "Blue" }`.
  - `value` string, nullable: New value, at most 4000 characters, in the property's format (Number `"12.5"`, Boolean `"true"`/`"false"`, Date `yyyy-MM-dd`, Dropdown one option, MultiSelect comma-separated options); `""` or null clears it.

## Response `200`

Saved; body is the unit as GET returns it.

- ItemUnitDto: One inventory unit (a physical stock row) of an item, as returned by `GET /api/v1/items/{id}/units`, with its own copy of the item's custom fields.
  - `id` integer: Unit id, e.g. `5012`; used by `PUT /api/v1/items/{id}/units/{unitId}/properties/{name}`.
  - `syncId` string, uuid: Globally unique sync id (GUID). Use it as the `after` pagination cursor.
  - `name` string: The unit's display name (normally the item's name).
  - `status` 'Available' | 'InTransit' | 'AtJobSite' | 'InBundle': Where an inventory unit stands, derived from its location and transfer state.
  - `locationId` integer, nullable: Id of the location holding the unit (see `GET /api/v1/locations`); null when it has none.
  - `locationName` string, nullable: Name of that location; null when the unit has none.
  - `createdAt` string, date-time: UTC creation timestamp (ISO-8601) — when the unit entered stock.
  - `updatedAt` string, date-time, nullable: UTC timestamp of the unit's last edit or move, including a change to one of its custom-field values; null when never changed.
  - `properties` ItemUnitPropertyDto[]: The unit's custom-field values, ordered by name. Includes `Cost` (the unit's own cost) and the pricing copy `Unit Price`, flagged `isPricing`.
    - `id` integer: The unit's property id, e.g. `88213` (differs from the item's property id).
    - `name` string: Property name, e.g. `"Color"`; the `{name}` of the per-unit PUT.
    - `value` string: The unit's value as stored, never null (`""` = none); formats as on `GET /api/v1/items/{id}/properties`.
    - `dataType` 'Text' | 'Number' | 'Date' | 'Boolean' | 'Dropdown' | 'MultiSelect'
    - `isCalculated` boolean: True when the value comes from a calculation on this unit; such values cannot be set (`409`).
    - `isCustomized` boolean: True when the value was set on this unit and no longer follows the item's value.
    - `isItemLevel` boolean: True when the property does not come from the item's Item Template (an item-level property of the item, or one added on this unit).
    - `isPricing` boolean: True for `Cost` and `Unit Price`, which cannot be set per unit through the API (`409`).

## Other responses

- `400`: Malformed body, a value over 4000 characters, or missing `Idempotency-Key`.
- `401`: Unauthorized
- `403`: The key lacks `ManageInventory`.
- `404`: No such active item, unit, or property on the unit.
- `409`: The property is calculated on this unit or is `Cost` / `Unit Price`, or the key's creator is unknown on this server.
- `422`: The value does not fit the property's type or options (keyed `value`); 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)