--- title: "Changes some of an item's name, description, category, price, cost, preferred vendor or vendor part number." method: PATCH path: "/api/v1/items/{id}" tags: ["Items"] --- # Changes some of an item's name, description, category, price, cost, preferred vendor or vendor part number. `PATCH /api/v1/items/{id}` ## Request - Base URL: `https://app.flexonthejob.com` - URL: `https://app.flexonthejob.com/api/v1/items/{id}` - Auth: HTTP bearer Requires `ManageInventory` and an `Idempotency-Key` header. Partial update: only the fields present in the body change; omitted (or `null`) fields are left alone, and `"description": ""` (or whitespace only) clears the description. The same rules as the Items page apply — renaming also renames every inventory unit of the item; a new `unitPrice` / `cost` is written to the item and its future stock only (existing units keep their own pricing, as with "push to existing inventory" left off); changing `categoryId` copies that category's properties onto the item. A rename to an active item's name is refused with `409`. Optional optimistic concurrency: send the `ETag` from `GET /api/v1/items/{id}` as `If-Match` to get `412` instead of overwriting a change made in the meantime (the tag covers stock too, so a concurrent stock move also yields 412 — GET again and retry). Fires the `item.updated` webhook naming the changed fields. Permissions mirror the app exactly: name, price/cost and category are edited on the Items page under `ManageInventory`; `description` is edited only on the Item Templates page, so sending it (including `""` to clear) additionally requires `ManageTemplates` (`403` otherwise, nothing changed). The same applies to `preferredVendorId` (an active vendor of the organization; `0` removes the link) and `vendorPartNumber` (`""` clears it), which the app edits on Item Templates → Edit; an unknown or inactive vendor is `422`. Example: `{ "unitPrice": 1.35 }` or `{ "preferredVendorId": 3, "vendorPartNumber": "PX-12C" }`. ## Path parameters - `id` integer, required ## Request body - UpdateItemApiRequest: Body of `PATCH /api/v1/items/{id}`: change some of an item's name, description, category, selling price, cost, preferred vendor or vendor part number. Partial update: a field that is omitted (or sent as `null`) is left unchanged, so send only what should change. At least one field is required. Example: `{ "unitPrice": 1.35 }` or `{ "name": "PEX Coupling 1/2\"", "categoryId": 7 }`. - `name` string, nullable: New name, 1-100 characters; omit to keep. Whitespace-only → 422. Renaming also renames every inventory unit of the item. - `description` string, nullable: New description, max 2000 characters; omit to keep. Send `""` (or whitespace only) to clear it. - `categoryId` integer, nullable: New primary category id; omit to keep. Changing it copies the category's properties onto the item. Unknown or another organization's id → 422. - `unitPrice` number, double, nullable: New selling price, 0 or more; omit to keep. Written to the item and its future stock only — existing units keep their own pricing. - `cost` number, double, nullable: New purchase cost, 0 or more; omit to keep. Written to the item and its future stock only. - `preferredVendorId` integer, nullable: New preferred vendor id (from `GET /api/v1/vendors`; must be an active vendor of the organization, 422 otherwise); omit to keep, send `0` to remove the link. Like `description` it is edited on the Item Templates page, so it requires `ManageTemplates`. Example: `3`. - `vendorPartNumber` string, nullable: New vendor part number, max 100 characters; omit to keep, send `""` to clear it. Requires `ManageTemplates` (edited on the Item Templates page). Example: `"PX-12C"`. - `hasAnyField` boolean: True when at least one field was supplied. - `hasTemplatePageField` boolean: True when a field only the Item Templates page edits (`ManageTemplates`) was supplied. ## Response `200` Updated; body is the item exactly as `GET /api/v1/items/{id}` returns it. - ItemDetail: Full item as returned by `GET /api/v1/items/{id}`. - `item` ItemSummary: One sellable/stockable item (an `ItemTemplate`) as listed by `GET /api/v1/items`. Physical rows in inventory are instances of a template; the API exposes templates because that is what agents price, sell and reorder. - `id` integer: Numeric id, usable in `/api/v1/items/{id}`. - `syncId` string, uuid: Stable cross-device id; also the pagination cursor. - `name` string: Display name. - `description` string, nullable: Free-text description, if any. - `categoryId` integer, nullable: Primary category id, if any. - `categoryName` string, nullable: Primary category name, if any. - `unitPrice` number, double, nullable: Selling price from the template's `Unit Price` property; null when not priced. - `cost` number, double, nullable: Purchase cost from the template's `Cost` property; null when unknown. - `onHand` number, double: Units on hand across stock locations (job sites excluded). Decimal because items sold by sub-unit report partial rows; negative when the organization allows overselling. - `isMiscItem` boolean: True for ad-hoc "misc" items that never carry stock. - `isParentTemplate` boolean: True for a grouping template whose children are the stocked variants. - `sellByUnits` boolean: True when the item is sold in sub-units of a parent row. - `unitName` string, nullable: Name of the sub-unit when SellByUnits is true. - `createdAt` string, date-time: UTC creation time. - `updatedAt` string, date-time, nullable: UTC last modification time; null when never edited. - `preferredVendorId` integer, nullable: Id of the vendor this item is normally reordered from (see `GET /api/v1/vendors`); null when none is set. Set on Item Templates → Edit or with `PATCH /api/v1/items/{id}`. Example: `3`. - `preferredVendorName` string, nullable: Name of the preferred vendor; null when none is set. Example: `"Ferguson"`. - `vendorPartNumber` string, nullable: The vendor's own part / catalogue number for this item, max 100 characters; null when unknown. Example: `"PX-12C"`. - `properties` object: Every template property by name (includes `Unit Price` and `Cost` when set). - `priceTiers` ItemPriceTier[]: Quantity-break pricing, ascending by quantity. Empty when the item has a single price. - `minQuantity` integer: Smallest quantity at which UnitPrice applies. - `unitPrice` number, double: Price per unit at or above MinQuantity. - `barcodes` ItemBarcodeDto[]: Barcodes attached to the item. - `value` string: Encoded value. - `type` string: Symbology (e.g. `UPC`, `Code128`). - `isPrimary` boolean: True for the barcode printed on labels. - `stock` StockSummary: Stock position of an item. - `onHand` number, double: Total on hand; same semantics as `onHand`. - `byLocation` LocationStock[]: Per-location breakdown of physical rows. Sums to the row count, which may differ from OnHand for oversold or sub-unit items. - `locationId` integer: Location id. - `locationName` string: Location name. - `quantity` integer: Whole item rows at the location (not deleted, not in a job site). - `parentItemId` integer, nullable: Id of the parent template for variant children; null otherwise. ## Other responses - `400`: Empty body (no field to change), malformed body, out-of-range value, or missing `Idempotency-Key`. - `401`: Unauthorized - `403`: The key lacks `ManageInventory`, or it sent `description`, `preferredVendorId` or `vendorPartNumber` without holding `ManageTemplates`. - `404`: No such active item in this organization. - `409`: An active item with the new name already exists, or the key's creator is unknown on this server. - `412`: `If-Match` does not match the item's current `ETag`. - `422`: Blank `name`, no such category in this organization (`categoryId`), no such active vendor (`preferredVendorId`), or `Idempotency-Key` reused with a different body. - `429`: Too Many Requests - `500`: The item could not be saved; nothing changed. --- [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)