Add an item to a screen

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://api-docs.lsk.lightspeed.app/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json 
{
  "Lightspeed Restaurant K-Series MCP server": {
    "url": "https://api-docs.lsk.lightspeed.app/mcp"
  }
}
Close
POST /items/integration/v2/business-locations/{businessLocationId}/items/{itemId}/screens/{screenId}
O auth2

Adds an existing item to a v2 menu screen, using the item's current button styling and appending in backend order. Returns 201 when the item was added and 204 when it was already there, so replay is safe.

Path parameters

  • businessLocationId integer(int64) Required

    The unique identifier for the business location.

  • itemId integer(int64) Required

    Item id

  • screenId integer(int64) Required

    The unique identifier for the screen.

    Minimum value is 1.

Responses

  • 201

    Item added to the screen.

  • 204

    Item already present on the screen; nothing was written.

  • 400 application/json

    The request was rejected, or the item or the screen cannot be used for this placement.

    A non-positive screenId fails schema validation and returns message "Constraint violation" with screenId listed in apiSubExceptions, and no errorCode. Every other rejection carries an errorCode instead, and an empty apiSubExceptions. Possible errorCode values:

    • ikentoo.error.item_is_archived — the item is archived; no placement is possible.

    • screens_not_found — no v2 screen with this id is reachable from this business location. Only v2 menus are supported, so a v1 screen is reported the same way.

    • ikentoo.error.item_is_linked_to_shared_menu — the request comes from a regular location and the menu does not allow local edits.

    • ikentoo.error.item-sharing-incompatible-with-menu-sharing — the request comes from the main location, where the button is synced to the whole menu, and the item is not active in every location the menu is shared with. Placing from a regular location creates a local override instead and is not subject to this rule.

    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
  • 404 application/json

    No item with this id exists at this business location.

    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
POST /items/integration/v2/business-locations/{businessLocationId}/items/{itemId}/screens/{screenId} 
curl \
 --request POST 'https://api.trial.lsk.lightspeed.app/items/integration/v2/business-locations/{businessLocationId}/items/{itemId}/screens/{screenId}' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (400) 
{
  "status": "BAD_REQUEST",
  "timestamp": "2026-05-04T09:42:00Z",
  "message": "string",
  "errorCode": "ikentoo.error.name.in-use",
  "details": "My Item",
  "apiSubExceptions": [
    {
      "field": "string",
      "rejectedValue": "string",
      "message": "string"
    }
  ]
}
Response examples (404) 
{
  "status": "BAD_REQUEST",
  "timestamp": "2026-05-04T09:42:00Z",
  "message": "string",
  "errorCode": "ikentoo.error.name.in-use",
  "details": "My Item",
  "apiSubExceptions": [
    {
      "field": "string",
      "rejectedValue": "string",
      "message": "string"
    }
  ]
}