# Create item **POST /items/integration/v2/business-locations/{businessLocationId}/items** Creates an item for a business location, optionally sharing it across locations and placing it on menus. Once the item exists the call always answers `201`: a sharing or placement failure does **not** fail the request, it is reported in `sharingWarnings` or `menuPlacementWarnings` on the returned item. Do not retry a `201` response that carries warnings — retrying creates a duplicate item, and menu placement is not idempotent. `sharingType`, `sharedLocations` and `menuPlacements` on the response always reflect the state actually achieved, so a client can diff them against what it requested. If `menuPlacementWarnings` is non-empty, `menuPlacements` may be incomplete — re-fetch the item to confirm its actual placements. ## Servers - Demo URL: https://api.trial.lsk.lightspeed.app (Demo URL) - Production URL: https://api.lsk.lightspeed.app (Production URL) ## Authentication methods - O auth2 ## Parameters ### Path parameters - **businessLocationId** (integer(int64)) The unique identifier for the business location. ### Body: application/json (object) - **name** (string) The name of the item. - **docketName** (string) The name used in the docket for the item. - **sku** (string) A stock keeping unit. - **active** (boolean) Indicates whether or not the item is archived from the menu. - **barcodes** (array[string]) A list of barcodes associated with the item. - **accountingGroupId** (integer(int64)) The unique identifier for the accounting group. Must be an existing `accountingGroupId`. - **costPrice** (number) The cost price of the item. - **defaultPrice** (number) The default price of the item. - **priceMode** (string) - **sharing** (object) How the created item is shared across locations. For a business with a single location any sharing input is rejected with `400`. For a Locations Manager business, sharing is only accepted from the business main location. Businesses without a Locations Manager may share from any location, but their sharing always spans every location and `businessLocationIds` is not supported. `businessLocationIds` names **sibling** locations only: it must not contain the item's own `businessLocationId`, which always receives the item implicitly. Omit it to share with every sibling location; on a Locations Manager business an empty array is rejected for `SHARED`/`GLOBAL`. Elsewhere the field is not supported, so an empty array is simply equivalent to omitting it. - **menuPlacements** (array[object]) Optional list (null or empty list) of menu screens to place the item on at creation time. Omitting this field creates the item without any menu placement. Each entry targets a `screenId`, which already identifies its menu. A placement referencing a `screenId` that does not exist at the path `businessLocationId` returns `400`. ## Responses ### 201 Item created. Check `sharingWarnings` and `menuPlacementWarnings` to confirm the requested sharing and menu placements were fully applied. #### Body: application/json (object) - **id** (integer(int64)) The unique identifier for the item. - **name** (string) The name of the item. - **docketName** (string) The name used in the docket for the item. - **sku** (string) A stock keeping unit. - **active** (boolean) Indicates whether or not the item is archived from the menu. - **barcodes** (array[string]) A list of barcodes associated with the item. - **accountingGroup** (object) The accounting group associated with the item. - **statisticGroups** (array[object]) List of statistic groups associated with the item. - **costPrice** (number) The cost price of the item. - **prices** (array[object]) List of prices associated with the item. - **sharingType** (string) - **sharedLocations** (array[integer(int64)]) The business locations the item is available in, including its own. - **priceMode** (string) - **inventorySource** (string) Source of inventory for the item. - **disabled** (boolean) Whether or not stock management is disabled for the item. - **contentDimension** (string) - **contentUom** (string) The unit of measure of the item for stock management. - **contentValue** (number) The measurement value. - **itemType** (string) - **menuPlacements** (array[object]) Which menus and screens the item is placed on. Always an array, empty when the item is placed on none. Each entry carries the full `screenPath` down to the screen, so a placement can be located in a large menu without walking the menu tree. Only placements this location can reach are listed: a placement on a menu that is not shared with the location the item is read from is omitted, the same way that menu is invisible to the location elsewhere. - **sharingWarnings** (array[object]) Set only on the create response, where it is always present and empty when the requested `sharing` fully applied. On a read the field is `null` and says nothing about the item. A warning means the item **was created** but the requested `sharing` did not fully complete. The item exists — do **not** retry the request; adjust the sharing with the sharing endpoints instead. `errorCode` values match those of the corresponding `400` responses, plus `internal_error`, which means the step failed for a reason with no more specific code, or that its result could not be confirmed — neither indicates anything wrong with the request. A warning is per problem, not per request: several may be present, and `details` identifies what each one applies to. - **menuPlacementWarnings** (array[object]) Set only on the create response, where it is always present and empty when the requested `menuPlacements` fully applied. On a read the field is `null` and says nothing about the item. A warning means the item **was created** but the requested `menuPlacements` did not fully complete. Same shape and rules as `sharingWarnings`. When it is non-empty, `menuPlacements` may be incomplete — re-fetch the item to confirm the item's actual placements. ### 400 The request was rejected and **no item was created**. A request that fails schema validation returns `message` `"Constraint violation"` with the offending fields listed in `apiSubExceptions`, and no `errorCode`. Every other rejection carries an `errorCode` instead, and an empty `apiSubExceptions`. Possible `errorCode` values: * `error.business-objects.accounting-groups.not-found` — `accountingGroupId` does not exist at this business location. * `screens_not_found` — a `screenId` in `menuPlacements` does not exist at the item's `businessLocationId`, or is not a v2 screen. * `ikentoo.error.item_is_linked_to_shared_menu` — the item is placed on a shared menu from a regular location, but that menu does not allow local edits. * `ikentoo.error.item-sharing-incompatible-with-menu-sharing` — the item is placed on a shared menu from the main location but is not shared with every location of that menu. `details` lists the uncovered locations. * `ikentoo.error.item-sharing-single-location-business` — `sharing` was supplied for a business with a single location. * `ikentoo.error.item-sharing-target-locations-require-shared-or-global` — `businessLocationIds` was supplied with `sharingType` `LOCAL`. * `ikentoo.error.item-sharing-v2-invalid-target-location-ids` — a `businessLocationIds` entry is not a sibling location of the item's business, or is the item's own location. * `ikentoo.error.item-sharing-business-location-ids-empty` — `businessLocationIds` was an empty array for `SHARED`/`GLOBAL` on a Locations Manager business. Omit the field to share with every location. On a business without a Locations Manager an empty array is equivalent to omitting the field, since targeted sharing is not supported there at all. * `ikentoo.error.item-sharing-targeted-nonlm-conflict` — `businessLocationIds` was supplied for a business without a Locations Manager. * `ikentoo.error.item-sharing-not-allowed-from-nonlm-locations` — a Locations Manager business tried to share from a location other than its main location. * `ikentoo.error.item-sharing-global-price-list-conflict` — `GLOBAL` sharing while price lists are enabled. #### Body: application/json (object) - **status** (string) The HTTP status, as its Spring `HttpStatus` name. - **timestamp** (string(date-time)) - **message** (string) A human-readable summary of the failure. - **errorCode** (string) A stable, machine-readable code identifying the failure. - **details** (string) Context identifying what the failure applies to. - **apiSubExceptions** (array[object]) Per-field failures. Always present, and empty when the failure is not field-scoped. ### 409 The item conflicts with one that already exists at this business location, or in a location it would be shared with, and **no item was created**. Possible `errorCode` values: * `ikentoo.error.name.in-use` — an item with this `name` already exists, either at this business location or in a location the item would be shared with. * `ikentoo.error.sku.in-use` — an item with this `sku` already exists. #### Body: application/json (object) - **status** (string) The HTTP status, as its Spring `HttpStatus` name. - **timestamp** (string(date-time)) - **message** (string) A human-readable summary of the failure. - **errorCode** (string) A stable, machine-readable code identifying the failure. - **details** (string) Context identifying what the failure applies to. - **apiSubExceptions** (array[object]) Per-field failures. Always present, and empty when the failure is not field-scoped. [Powered by Bump.sh](https://bump.sh)