Skip to content
innovorder
⌘K

Product graph

POS Layout

Read POS Layout

The POS Layout API allows retrieval of the visual configuration of the menu on the Point of Sale (POS) device. This defines how categories and products are arranged on the screen.

GET/v2/menus/{menuId}/pos_layout/groups/{parentPosLayoutItemId}Get POS Layout

Retrieve the layout structure for a menu. The `parentPosLayoutItemId` parameter is used to navigate through nested groups. Use `0` to retrieve the root level.

Parameters

NameTypeRequiredDescription
menuIdintegerYesThe unique identifier of the menu.
parentPosLayoutItemIdintegerYesThe ID of the parent layout group. Use 0 for the root level.

Response

json
{
  "status": 200,
  "code": "menu_pos_layout_items_get_all_succeed",
  "message": "POS layout items have been retrieved successfully.",
  "data": {
    "color": "-13330213",
    "createdAt": "2025-01-01",
    "menuId": 106477,
    "parentPosLayoutItemId": 0,
    "posLayoutItemId": 12,
    "posLocalId": 456,
    "position": 1,
    "type": "category",
    "updatedAt": "2025-01-05",
    "posLayoutItems": [
      {
        "color": "-16777216",
        "createdAt": "2025-01-02",
        "menuId": 106477,
        "parentPosLayoutItemId": 12,
        "posLayoutItemId": 13,
        "posLocalId": 789,
        "position": 0,
        "type": "product",
        "updatedAt": "2025-01-05"
      }
    ]
  }
}
Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

PropertyTypeExampleDescription
statusinteger200HTTP status code returned by the API.
codestring"menu_pos_layout_items_get_all_succeed"Machine-readable application code for the result.
messagestring"POS layout items have been retrieved successfully."Human-readable result message. Do not use this value for program logic.
dataobject{…}Endpoint-specific response payload.
data.colorstring"-13330213"The color value.
data.createdAtstring"2025-01-01"Timestamp when this resource was created.
data.menuIdinteger106477Identifier of the menu.
data.parentPosLayoutItemIdinteger0Identifier of the associated parent pos layout item.
data.posLayoutItemIdinteger12Identifier of the associated pos layout item.
data.posLocalIdinteger456Identifier of the associated pos local.
data.positioninteger1The position value.
data.typestring"category"The type value.
data.updatedAtstring"2025-01-05"Timestamp when this resource was last updated.
data.posLayoutItemsarray[…]List of pos layout items entries.
data.posLayoutItems[]object{…}Object containing pos layout items fields.
data.posLayoutItems[].colorstring"-16777216"The color value.
data.posLayoutItems[].createdAtstring"2025-01-02"Timestamp when this resource was created.
data.posLayoutItems[].menuIdinteger106477Identifier of the menu.
data.posLayoutItems[].parentPosLayoutItemIdinteger12Identifier of the associated parent pos layout item.
data.posLayoutItems[].posLayoutItemIdinteger13Identifier of the associated pos layout item.
data.posLayoutItems[].posLocalIdinteger789Identifier of the associated pos local.
data.posLayoutItems[].positioninteger0The position value.
data.posLayoutItems[].typestring"product"The type value.
data.posLayoutItems[].updatedAtstring"2025-01-05"Timestamp when this resource was last updated.

POS Layout Models

GetPosLayoutItem Schema
yaml
type: object
allOf:
  - $ref: BasePosLayoutItem
  - type: object
    properties:
      posLayoutItems:
        type: array
        items:
          $ref: BasePosLayoutItem

BasePosLayoutItem:
  type: object
  properties:
    color:
      type: string
      description: Color decimal value in string (e.g. "-13330213")
    createdAt:
      type: string
      format: date
    menuId:
      type: number
    parentPosLayoutItemId:
      type: number
      description: 0 if root level
    posLayoutItemId:
      type: number
      posLocalId:
      type: number
      description: Links to Category/Product posLocalId
    position:
      type: number
      description: Linear position (layout depends on device screen size)
    type:
      type: string
      enum: [category, product]
    updatedAt:
      type: string
      format: date

Write POS Layout

You can upsert (create or replace) the entire layout structure for a menu.

PUT/v2/menus/{menuId}/pos_layoutUpsert POS Layout

Create or replace the POS layout items for a menu. Provide a nested tree of layout items; the system will replace the existing layout.

Parameters

NameTypeRequiredDescription
menuIdintegerYesThe unique identifier of the menu.

Request Body

json
{
  "data": [
    {
      "posLocalId": 456,
      "type": "category",
      "position": 0,
      "color": "-13330213",
      "posLayoutItems": [
        {
          "posLocalId": 789,
          "type": "product",
          "position": 0,
          "color": "-16777216",
          "posLayoutItems": []
        }
      ]
    }
  ]
}
Request Body Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

PropertyTypeExampleDescription
dataarray[…]Endpoint-specific response payload.
data[]object{…}Endpoint-specific response payload.
data[].posLocalIdinteger456Identifier of the associated pos local.
data[].typestring"category"The type value.
data[].positioninteger0The position value.
data[].colorstring"-13330213"The color value.
data[].posLayoutItemsarray[…]List of pos layout items entries.
data[].posLayoutItems[]object{…}Object containing pos layout items fields.
data[].posLayoutItems[].posLocalIdinteger789Identifier of the associated pos local.
data[].posLayoutItems[].typestring"product"The type value.
data[].posLayoutItems[].positioninteger0The position value.
data[].posLayoutItems[].colorstring"-16777216"The color value.
data[].posLayoutItems[].posLayoutItemsarray[]List of pos layout items entries.

Response

json
HTTP 204 No Content. The layout update succeeds without a JSON response body.

Data Models

PosLayoutItemUpsert
yaml
type: object
required: [posLocalId, type, position]
properties:
  posLocalId:
    type: integer
    description: Links to the Category or Product posLocalId
  type:
    type: string
    enum: [category, product]
  position:
    type: integer
    description: Linear position in the layout
  color:
    type: string
    default: "0"
    description: Color decimal value (e.g. "-13330213")
  posLayoutItems:
    type: array
    items:
      $ref: PosLayoutItemUpsert
    description: Nested child layout items (recursive)

POS Layout Functions

POS Layout Functions allow embedding custom webview buttons in the POS layout. Each function is scoped to a menu and defines a webview URL along with display dimensions. The POS devices linked to the menu must support functions (version check is enforced server-side).

GET/v2/menus/{menuId}/pos_layout_functionsList POS Layout Functions

Retrieve all POS layout functions for a menu.

Parameters

NameTypeRequiredDescription
menuIdintegerYesThe unique identifier of the menu.

Response

json
{
  "status": 200,
  "code": "pos_layout_function_get_all_succeed",
  "message": "POS layout functions have been retrieved successfully.",
  "data": [
    {
      "posLayoutFunctionId": 1,
      "menuId": 106477,
      "functionType": "webview",
      "name": "Loyalty Lookup",
      "config": {
        "url": "https://loyalty.example.com/lookup",
        "widthPercent": 80,
        "heightPercent": 60
      },
      "createdAt": "2025-07-01T10:00:00.000Z",
      "updatedAt": "2025-07-01T10:00:00.000Z"
    }
  ]
}
Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

PropertyTypeExampleDescription
statusinteger200HTTP status code returned by the API.
codestring"pos_layout_function_get_all_succeed"Machine-readable application code for the result.
messagestring"POS layout functions have been retrieved successfully."Human-readable result message. Do not use this value for program logic.
dataarray[…]Endpoint-specific response payload.
data[]object{…}Endpoint-specific response payload.
data[].posLayoutFunctionIdinteger1Identifier of the associated pos layout function.
data[].menuIdinteger106477Identifier of the menu.
data[].functionTypestring"webview"The function type value.
data[].namestring"Loyalty Lookup"The name value.
data[].configobject{…}Object containing config fields.
data[].config.urlstring"https://loyalty.example.com/lookup"The url value.
data[].config.widthPercentinteger80The width percent value.
data[].config.heightPercentinteger60The height percent value.
data[].createdAtstring"2025-07-01T10:00:00.000Z"Timestamp when this resource was created.
data[].updatedAtstring"2025-07-01T10:00:00.000Z"Timestamp when this resource was last updated.

GET/v2/menus/{menuId}/pos_layout_functions/{posLayoutFunctionId}Get POS Layout Function

Retrieve a single POS layout function by its ID.

Parameters

NameTypeRequiredDescription
menuIdintegerYesThe unique identifier of the menu.
posLayoutFunctionIdintegerYesThe unique identifier of the POS layout function.

Response

json
{
  "status": 200,
  "code": "pos_layout_function_get_succeed",
  "message": "POS layout function has been retrieved successfully.",
  "data": {
    "posLayoutFunctionId": 1,
    "menuId": 106477,
    "functionType": "webview",
    "name": "Loyalty Lookup",
    "config": {
      "url": "https://loyalty.example.com/lookup",
      "widthPercent": 80,
      "heightPercent": 60
    }
  }
}
Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

PropertyTypeExampleDescription
statusinteger200HTTP status code returned by the API.
codestring"pos_layout_function_get_succeed"Machine-readable application code for the result.
messagestring"POS layout function has been retrieved successfully."Human-readable result message. Do not use this value for program logic.
dataobject{…}Endpoint-specific response payload.
data.posLayoutFunctionIdinteger1Identifier of the associated pos layout function.
data.menuIdinteger106477Identifier of the menu.
data.functionTypestring"webview"The function type value.
data.namestring"Loyalty Lookup"The name value.
data.configobject{…}Object containing config fields.
data.config.urlstring"https://loyalty.example.com/lookup"The url value.
data.config.widthPercentinteger80The width percent value.
data.config.heightPercentinteger60The height percent value.

POST/v2/menus/{menuId}/pos_layout_functionsCreate POS Layout Function

Create a new POS layout function for a menu. The POS devices linked to the menu must support functions (server-side version check is enforced).

Parameters

NameTypeRequiredDescription
menuIdintegerYesThe unique identifier of the menu.

Request Body

json
{
  "functionType": "webview",
  "name": "Customer Survey",
  "config": {
    "url": "https://survey.example.com",
    "widthPercent": 90,
    "heightPercent": 70
  }
}
Request Body Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

PropertyTypeExampleDescription
functionTypestring"webview"The function type value.
namestring"Customer Survey"The name value.
configobject{…}Object containing config fields.
config.urlstring"https://survey.example.com"The url value.
config.widthPercentinteger90The width percent value.
config.heightPercentinteger70The height percent value.

Response

json
{
  "status": 201,
  "code": "pos_layout_function_create_succeed",
  "message": "POS layout function has been created successfully.",
  "data": {
    "posLayoutFunctionId": 2,
    "menuId": 106477,
    "functionType": "webview",
    "name": "Customer Survey",
    "config": {
      "url": "https://survey.example.com",
      "widthPercent": 90,
      "heightPercent": 70
    },
    "createdAt": "2025-07-02T10:00:00.000Z"
  }
}
Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

PropertyTypeExampleDescription
statusinteger201HTTP status code returned by the API.
codestring"pos_layout_function_create_succeed"Machine-readable application code for the result.
messagestring"POS layout function has been created successfully."Human-readable result message. Do not use this value for program logic.
dataobject{…}Endpoint-specific response payload.
data.posLayoutFunctionIdinteger2Identifier of the associated pos layout function.
data.menuIdinteger106477Identifier of the menu.
data.functionTypestring"webview"The function type value.
data.namestring"Customer Survey"The name value.
data.configobject{…}Object containing config fields.
data.config.urlstring"https://survey.example.com"The url value.
data.config.widthPercentinteger90The width percent value.
data.config.heightPercentinteger70The height percent value.
data.createdAtstring"2025-07-02T10:00:00.000Z"Timestamp when this resource was created.

PUT/v2/menus/{menuId}/pos_layout_functions/{posLayoutFunctionId}Update POS Layout Function

Update an existing POS layout function. All body fields are optional.

Parameters

NameTypeRequiredDescription
menuIdintegerYesThe unique identifier of the menu.
posLayoutFunctionIdintegerYesThe unique identifier of the POS layout function.

Request Body

json
{
  "name": "Updated Survey",
  "config": {
    "url": "https://survey-v2.example.com",
    "widthPercent": 100,
    "heightPercent": 80
  }
}
Request Body Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

PropertyTypeExampleDescription
namestring"Updated Survey"The name value.
configobject{…}Object containing config fields.
config.urlstring"https://survey-v2.example.com"The url value.
config.widthPercentinteger100The width percent value.
config.heightPercentinteger80The height percent value.

Response

json
{
  "status": 200,
  "code": "pos_layout_function_update_succeed",
  "message": "POS layout function has been updated successfully.",
  "data": {
    "posLayoutFunctionId": 2,
    "menuId": 106477,
    "functionType": "webview",
    "name": "Updated Survey",
    "config": {
      "url": "https://survey-v2.example.com",
      "widthPercent": 100,
      "heightPercent": 80
    },
    "updatedAt": "2025-07-03T10:00:00.000Z"
  }
}
Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

PropertyTypeExampleDescription
statusinteger200HTTP status code returned by the API.
codestring"pos_layout_function_update_succeed"Machine-readable application code for the result.
messagestring"POS layout function has been updated successfully."Human-readable result message. Do not use this value for program logic.
dataobject{…}Endpoint-specific response payload.
data.posLayoutFunctionIdinteger2Identifier of the associated pos layout function.
data.menuIdinteger106477Identifier of the menu.
data.functionTypestring"webview"The function type value.
data.namestring"Updated Survey"The name value.
data.configobject{…}Object containing config fields.
data.config.urlstring"https://survey-v2.example.com"The url value.
data.config.widthPercentinteger100The width percent value.
data.config.heightPercentinteger80The height percent value.
data.updatedAtstring"2025-07-03T10:00:00.000Z"Timestamp when this resource was last updated.

DELETE/v2/menus/{menuId}/pos_layout_functions/{posLayoutFunctionId}Delete POS Layout Function

Delete a POS layout function.

Parameters

NameTypeRequiredDescription
menuIdintegerYesThe unique identifier of the menu.
posLayoutFunctionIdintegerYesThe unique identifier of the POS layout function.

Response

json
{
  "status": 200,
  "code": "pos_layout_function_delete_succeed",
  "message": "POS layout function has been deleted successfully."
}
Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

PropertyTypeExampleDescription
statusinteger200HTTP status code returned by the API.
codestring"pos_layout_function_delete_succeed"Machine-readable application code for the result.
messagestring"POS layout function has been deleted successfully."Human-readable result message. Do not use this value for program logic.

Data Models

PosLayoutFunctionAttributes
typescript
interface PosLayoutFunctionAttributes {
  posLayoutFunctionId: number;
  menuId: number;
  functionType: 'webview';
  name: string;
  config: WebviewConfig;
  createdAt: Date;
  updatedAt: Date;
}

interface WebviewConfig {
  url: string;          // Must be a valid URI
  widthPercent: number; // 10-100
  heightPercent: number; // 10-100
}
PreviousAvailability & Cross-SellingNext Menu Operations