Add an item to screens

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

{
  "Lightspeed Restaurant K-Series MCP server": {
    "url": "https://api-docs.lsk.lightspeed.app/mcp"
  }
}

POST /items/integration/v2/business-locations/{businessLocationId}/items/{itemId}/screens

O auth2

Adds an existing item to v2 menu screens, using the item's current button styling and appending to each screen. Every screen is handled independently, so one bad screen never blocks the others. The call therefore answers 200 whenever the item exists and is active. Inspect added, unchanged and failed to find out what happened; fix the reported errors and retry only the screens in failed. Retrying is safe: a screen the item is already on, and that this location is allowed to write to, is reported in unchanged. A screen this location may not write to is reported in failed whether or not the item is already on it, since the permission is decided before anything is looked up on the screen.

Path parameters

businessLocationId integer(int64) Required

The unique identifier for the business location.
itemId integer(int64) Required

Item id

application/json

Body Required

screenPlacements array[object] Required

The screens to place the item on. Duplicates are collapsed and the order is preserved.

At least 1 but not more than 100 elements.
Hide screenPlacements attribute Show screenPlacements attribute object
A request to place an existing item on one v2 menu screen.
- screenId integer(int64) Required
  
  The screen within a v2 menu to place the item on.
  
  Minimum value is 1.

Responses

200 application/json

Per-screen outcomes. Partial success is expected, and failed may contain every requested screen.
Hide response attributes Show response attributes object
- added array[integer(int64)] Required
  
  Screens the item was newly placed on.
- unchanged array[integer(int64)] Required
  
  Screens the item was already on; nothing was written.
- failed array[object] Required
  
  Screens the item could not be placed on, each with the error explaining why.
  
  Hide failed attributes Show failed attributes object
  
  One screen the item could not be placed on, and why.
  
  screenId integer(int64) Required
  
  Minimum value is 1.
  
  error object Required
  
  The standard error body produced by this service.
  
  Hide error attributes Show error 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
400 application/json

The request cannot be applied at all and no placements were written. Either the request body is malformed — screenPlacements was absent, empty, or carried a non-positive screen id — or the item is archived, reported as ikentoo.error.item_is_archived.
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; no placements were written.
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

curl \
 --request POST 'https://api.trial.lsk.lightspeed.app/items/integration/v2/business-locations/{businessLocationId}/items/{itemId}/screens' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{
  "screenPlacements": [
    {
      "screenId": 101
    }
  ]
}'

Request examples

{
  "screenPlacements": [
    {
      "screenId": 101
    }
  ]
}

Response examples (200)

{
  "added": [
    101,
    102
  ],
  "unchanged": [
    103
  ],
  "failed": [
    {
      "screenId": 101,
      "error": {
        "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 (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"
    }
  ]
}