Path parameters

• businessLocationId integer(int64) Required

  The unique identifier for the business location.

Responses

• 201 application/json

  Item created. Check sharingWarnings and menuPlacementWarnings to confirm the requested sharing and menu placements were fully applied.

  Hide response attributes Show response attributes object

  • id integer(int64)

    The unique identifier for the item.

  • name string

    The name of the item.

    Minimum length is 1, maximum length is 180.

  • docketName string

    The name used in the docket for the item.

    Maximum length is 64.

  • sku string

    A stock keeping unit.

    Minimum length is 1, maximum length is 32.

  • active boolean

    Indicates whether or not the item is archived from the menu.

  • barcodes array[string]

    A list of barcodes associated with the item.

    Minimum length of each is 1, maximum length of each is 64.

  • accountingGroup object

    The accounting group associated with the item.

    Hide accountingGroup attributes Show accountingGroup attributes object

    • id integer(int64)

      The unique identifier for the accounting group.

    • name string

      The name of the accounting group.

  • statisticGroups array[object]

    List of statistic groups associated with the item.

    Hide statisticGroups attributes Show statisticGroups attributes object

    • category string

      The name of the statistic group category.

    • value string

      The statistic group value.

  • costPrice number

    The cost price of the item.

  • prices array[object]

    List of prices associated with the item.

    Hide prices attributes Show prices attributes object

    • amount number

      The item price.

    • name string

      The name for this item price.

  • sharingType string

    Values are GLOBAL, LOCAL, or SHARED.

  • sharedLocations array[integer(int64)]

    The business locations the item is available in, including its own.

  • priceMode string

    Values are AMOUNT, PERCENT, POSITIVE_OPEN_PRICE, or NEGATIVE_OPEN_PRICE. Default value is AMOUNT.

  • inventorySource string

    Source of inventory for the item.

    Values are PURCHASED or PRODUCED.

  • disabled boolean

    Whether or not stock management is disabled for the item.

  • contentDimension string

    Values are DIMENSION_LESS, VOLUME, or MASS.

  • contentUom string

    The unit of measure of the item for stock management.

  • contentValue number

    The measurement value.

  • itemType string

    Values are ITEM, SEQUENCE, GROUP, SUB_ITEM, MODIFIER_GROUP, or MODIFIER.

  • 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.

    Hide menuPlacements attributes Show menuPlacements attributes object

    A single placement of an item on a menu screen.

    • buttonId integer(int64)

      The button id realising this placement.

    • buttonName string

      The label shown on the button.

    • buttonColor string

      The colour of the button.

    • buttonTheme string

      Values are FULL or ACCENT.

    • menuId integer(int64)

      The menu the item is placed on.

    • menuName string

      The name of the menu.

    • screenId integer(int64)

      The screen (category) within the menu the item is placed on.

    • screenName string

      The name of the screen.

    • position integer(int32)

      The position of the item within the screen.

    • businessLocationId integer(int64)

      The location owning the button that realises this placement. null means the button is not a local override and is visible in every location the menu is shared with. A non-null value means the button exists only in that location.

    • screenPath array[object]

      The screens leading to this placement, ordered from the top screen of the menu down to screenId, which is always the last entry. The menu itself is not part of the path; see menuId and menuName.

      Hide screenPath attributes Show screenPath attributes object

      A single screen on the path from the top of a menu down to a placement.

      • screenId integer(int64)

        The screen.

      • name string

        The name of the screen.

  • 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.

    Hide sharingWarnings attributes Show sharingWarnings attributes object

    The standard error body produced by this service.

    • 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.

      Hide apiSubExceptions attributes Show apiSubExceptions attributes object

      • field string
      • rejectedValue string
      • message string
  • 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.

    Hide menuPlacementWarnings attributes Show menuPlacementWarnings attributes object

    The standard error body produced by this service.

    • 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.

      Hide apiSubExceptions attributes Show apiSubExceptions attributes object

      • field string
      • rejectedValue string
      • message string
• 400 application/json

  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.
  Hide response attributes Show response attributes 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.

    Hide apiSubExceptions attributes Show apiSubExceptions attributes object

    • field string
    • rejectedValue string
    • message string
• 409 application/json

  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.
  Hide response attributes Show response attributes 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.

    Hide apiSubExceptions attributes Show apiSubExceptions attributes object

    • field string
    • rejectedValue string
    • message string