Menu Layouts

Server

Download schema

Menu structure and organization

GET

https://common-api.karma.life

/api/v1/menu-layouts

List menu layouts with optional filtering by location, schedule, and channels

Permissions: 🔵 menu_layouts.read

locationId

number

Filter by location ID

page

number · min: 1

Page number

Default: 1

limit

number · min: 1 · max: 100

Items per page

Default: 20

availableOnly

string

Filter by schedule availability (ISO timestamp or "true")

channels

string

Filter by channels (comma-separated channel types)

templatesOnly

string · enum

Filter to only return templates

Enum values:

true

false

excludeTemplates

string · enum

Exclude templates from results

Enum values:

true

false

resolveReferences

string · enum

Resolve linked template references in the context

Enum values:

true

false

excludeUnmapped

string · enum

Drop product nodes whose item lacks a POS integration_resource_mappings row. Used by storefront to hide items that would silently fail at the POS. No-op when the location has no active POS integration.

Enum values:

true

false

Default Response

status

string · enum · required

Enum values:

success

object · required

POST

https://common-api.karma.life

/api/v1/menu-layouts

Create a new menu layout

Permissions: 🟢 menu_layouts.create

locationId

number · required

Location ID

object · required

JSON object with POS screen layout configuration

isTemplate

boolean

Whether this layout should be a reusable template

templateName

string

Display name for the template (required if isTemplate is true)

Default Response

status

string · enum · required

Enum values:

success

object · required

GET

https://common-api.karma.life

/api/v1/menu-layouts/{id}

Get a single menu layout by ID. Use resolveReferences=true to expand linked template references.

Permissions: 🔵 menu_layouts.read

id

string · uuid · required

Menu layout ID (UUID)

resolveReferences

string · enum

Resolve linked template references in the context

Enum values:

true

false

excludeUnmapped

string · enum

Drop product nodes whose item lacks a POS integration_resource_mappings row. No-op when the location has no active POS integration.

Enum values:

true

false

Default Response

status

string · enum · required

Enum values:

success

object · required

PUT

https://common-api.karma.life

/api/v1/menu-layouts/{id}

Update an existing menu layout

Permissions: 🟠 menu_layouts.update

id

string · uuid · required

Menu layout ID (UUID)

object

Updated JSON object with POS screen layout configuration

isTemplate

boolean

Whether this layout should be a reusable template

templateName

string

Display name for the template

Default Response

status

string · enum · required

Enum values:

success

object · required

DELETE

https://common-api.karma.life

/api/v1/menu-layouts/{id}

Delete a menu layout. If the layout is a template that is being used, set force=true to delete anyway.

Permissions: 🔴 menu_layouts.delete

id

string · uuid · required

Menu layout ID (UUID)

force

string · enum

Force delete a template even if it is being used in menus

Enum values:

true

false

Menu layout successfully deleted

status

string · enum

Enum values:

success

object

Get template usage

GET

https://common-api.karma.life

/api/v1/menu-layouts/{id}/usage

Get information about which menus are using a template

Permissions: 🔵 menu_layouts.read

Get template usage › path Parameters

id

string · uuid · required

Menu layout ID (UUID)

Get template usage › Responses

Default Response

status

string · enum · required

Enum values:

success

object · required

POST

https://common-api.karma.life

/api/v1/menu-layouts/reorder

Reorder menu layouts by updating their sort order

Permissions: 🟠 menu_layouts.update

layoutIds

string[] · required

Array of menu layout IDs in the desired display order

Menu layouts successfully reordered

status

string · enum

Enum values:

success

object

POST

https://common-api.karma.life

/webhook/menu-layouts.created

Fired when a new menu layout is created. The full layout object is spread into data.

This is an outbound webhook event. Karma POSTs this payload to the URL you registered via POST /api/v1/webhooks/subscriptions. Your endpoint should respond 2xx within 30 seconds to acknowledge delivery.

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

menu-layouts.created

resource

string · enum · required

Enum values:

menu-layouts

resourceId

string · required

String ID of the affected resource

timestamp

string · date-time · required

ISO 8601 timestamp when the event was emitted

apiVersion

string · enum · required

Enum values:

object

200

Acknowledged. Karma considers any 2xx response a successful delivery; non-2xx triggers retry with exponential backoff.

No data returned

POST

https://common-api.karma.life

/webhook/menu-layouts.updated

Fired when a menu layout changes — either directly via PUT, or indirectly when channel/schedule changes affect the layout. The two emission paths produce slightly different payloads.

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

menu-layouts.updated

resource

string · enum · required

Enum values:

menu-layouts

resourceId

string · required

String ID of the affected resource

timestamp

string · date-time · required

ISO 8601 timestamp when the event was emitted

apiVersion

string · enum · required

Enum values:

200

Acknowledged. Karma considers any 2xx response a successful delivery; non-2xx triggers retry with exponential backoff.

No data returned

POST/webhook/menu-layouts.updated

curl --request POST \
  --url https://common-api.karma.life/webhook/menu-layouts.updated \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "evt_01HZK3...",
  "event": "menu-layouts.updated",
  "resource": "menu-layouts",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "changes": {},
    "locationId": 0
  }
}
'

Example Request Body

{
  "id": "evt_01HZK3...",
  "event": "menu-layouts.updated",
  "resource": "menu-layouts",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "changes": {},
    "locationId": 0
  }
}

json

Example Responses

No example specified for this content type

POST

https://common-api.karma.life

/webhook/menu-layouts.deleted

Soft delete — the layout remains in the database.

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

menu-layouts.deleted

resource

string · enum · required

Enum values:

menu-layouts

resourceId

string · required

String ID of the affected resource

timestamp

string · date-time · required

ISO 8601 timestamp when the event was emitted

apiVersion

string · enum · required

Enum values:

object

200

Acknowledged. Karma considers any 2xx response a successful delivery; non-2xx triggers retry with exponential backoff.

No data returned

POST/webhook/menu-layouts.deleted

curl --request POST \
  --url https://common-api.karma.life/webhook/menu-layouts.deleted \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "evt_01HZK3...",
  "event": "menu-layouts.deleted",
  "resource": "menu-layouts",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "locationId": 0,
    "deletedAt": "2024-08-25T15:00:00Z"
  }
}
'

Example Request Body

{
  "id": "evt_01HZK3...",
  "event": "menu-layouts.deleted",
  "resource": "menu-layouts",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "locationId": 0,
    "deletedAt": "2024-08-25T15:00:00Z"
  }
}

json

Example Responses

No example specified for this content type

Loyalty Programs Notes

Karma Common API

Menu Layouts

Server

Download schema

Menu structure and organization

GET

https://common-api.karma.life

/api/v1/menu-layouts

List menu layouts with optional filtering by location, schedule, and channels

Permissions: 🔵 menu_layouts.read

locationId

number

Filter by location ID

page

number · min: 1

Page number

Default: 1

limit

number · min: 1 · max: 100

Items per page

Default: 20

availableOnly

string

Filter by schedule availability (ISO timestamp or "true")

channels

string

Filter by channels (comma-separated channel types)

templatesOnly

string · enum

Filter to only return templates

Enum values:

true

false

excludeTemplates

string · enum

Exclude templates from results

Enum values:

true

false

resolveReferences

string · enum

Resolve linked template references in the context

Enum values:

true

false

excludeUnmapped

string · enum

Enum values:

true

false

Default Response

status

string · enum · required

Enum values:

success

object · required

POST

https://common-api.karma.life

/api/v1/menu-layouts

Create a new menu layout

Permissions: 🟢 menu_layouts.create

locationId

number · required

Location ID

object · required

JSON object with POS screen layout configuration

isTemplate

boolean

Whether this layout should be a reusable template

templateName

string

Display name for the template (required if isTemplate is true)

Default Response

status

string · enum · required

Enum values:

success

object · required

GET

https://common-api.karma.life

/api/v1/menu-layouts/{id}

Get a single menu layout by ID. Use resolveReferences=true to expand linked template references.

Permissions: 🔵 menu_layouts.read

id

string · uuid · required

Menu layout ID (UUID)

resolveReferences

string · enum

Resolve linked template references in the context

Enum values:

true

false

excludeUnmapped

string · enum

Drop product nodes whose item lacks a POS integration_resource_mappings row. No-op when the location has no active POS integration.

Enum values:

true

false

Default Response

status

string · enum · required

Enum values:

success

object · required

PUT

https://common-api.karma.life

/api/v1/menu-layouts/{id}

Update an existing menu layout

Permissions: 🟠 menu_layouts.update

id

string · uuid · required

Menu layout ID (UUID)

object

Updated JSON object with POS screen layout configuration

isTemplate

boolean

Whether this layout should be a reusable template

templateName

string

Display name for the template

Default Response

status

string · enum · required

Enum values:

success

object · required

DELETE

https://common-api.karma.life

/api/v1/menu-layouts/{id}

Delete a menu layout. If the layout is a template that is being used, set force=true to delete anyway.

Permissions: 🔴 menu_layouts.delete

id

string · uuid · required

Menu layout ID (UUID)

force

string · enum

Force delete a template even if it is being used in menus

Enum values:

true

false

Menu layout successfully deleted

status

string · enum

Enum values:

success

object

Get template usage

GET

https://common-api.karma.life

/api/v1/menu-layouts/{id}/usage

Get information about which menus are using a template

Permissions: 🔵 menu_layouts.read

Get template usage › path Parameters

id

string · uuid · required

Menu layout ID (UUID)

Get template usage › Responses

Default Response

status

string · enum · required

Enum values:

success

object · required

POST

https://common-api.karma.life

/api/v1/menu-layouts/reorder

Reorder menu layouts by updating their sort order

Permissions: 🟠 menu_layouts.update

layoutIds

string[] · required

Array of menu layout IDs in the desired display order

Menu layouts successfully reordered

status

string · enum

Enum values:

success

object

POST

https://common-api.karma.life

/webhook/menu-layouts.created

Fired when a new menu layout is created. The full layout object is spread into data.

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

menu-layouts.created

resource

string · enum · required

Enum values:

menu-layouts

resourceId

string · required

String ID of the affected resource

timestamp

string · date-time · required

ISO 8601 timestamp when the event was emitted

apiVersion

string · enum · required

Enum values:

object

200

Acknowledged. Karma considers any 2xx response a successful delivery; non-2xx triggers retry with exponential backoff.

No data returned

POST

https://common-api.karma.life

/webhook/menu-layouts.updated

Fired when a menu layout changes — either directly via PUT, or indirectly when channel/schedule changes affect the layout. The two emission paths produce slightly different payloads.

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

menu-layouts.updated

resource

string · enum · required

Enum values:

menu-layouts

resourceId

string · required

String ID of the affected resource

timestamp

string · date-time · required

ISO 8601 timestamp when the event was emitted

apiVersion

string · enum · required

Enum values:

200

Acknowledged. Karma considers any 2xx response a successful delivery; non-2xx triggers retry with exponential backoff.

No data returned

POST/webhook/menu-layouts.updated

curl --request POST \
  --url https://common-api.karma.life/webhook/menu-layouts.updated \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "evt_01HZK3...",
  "event": "menu-layouts.updated",
  "resource": "menu-layouts",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "changes": {},
    "locationId": 0
  }
}
'

Example Request Body

{
  "id": "evt_01HZK3...",
  "event": "menu-layouts.updated",
  "resource": "menu-layouts",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "changes": {},
    "locationId": 0
  }
}

json

Example Responses

No example specified for this content type

POST

https://common-api.karma.life

/webhook/menu-layouts.deleted

Soft delete — the layout remains in the database.

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

menu-layouts.deleted

resource

string · enum · required

Enum values:

menu-layouts

resourceId

string · required

String ID of the affected resource

timestamp

string · date-time · required

ISO 8601 timestamp when the event was emitted

apiVersion

string · enum · required

Enum values:

object

200

Acknowledged. Karma considers any 2xx response a successful delivery; non-2xx triggers retry with exponential backoff.

No data returned

POST/webhook/menu-layouts.deleted

curl --request POST \
  --url https://common-api.karma.life/webhook/menu-layouts.deleted \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "evt_01HZK3...",
  "event": "menu-layouts.deleted",
  "resource": "menu-layouts",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "locationId": 0,
    "deletedAt": "2024-08-25T15:00:00Z"
  }
}
'

Example Request Body

{
  "id": "evt_01HZK3...",
  "event": "menu-layouts.deleted",
  "resource": "menu-layouts",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "locationId": 0,
    "deletedAt": "2024-08-25T15:00:00Z"
  }
}

json

Example Responses

No example specified for this content type

Loyalty Programs Notes

Menu Layouts

List menu layouts

List menu layouts › query Parameters

List menu layouts › Responses

Create menu layout

Create menu layout › Request Body

Create menu layout › Responses

Get menu layout

Get menu layout › path Parameters

Get menu layout › query Parameters

Get menu layout › Responses

Update menu layout

Update menu layout › path Parameters

Update menu layout › Request Body

Update menu layout › Responses

Delete menu layout

Delete menu layout › path Parameters

Delete menu layout › query Parameters

Delete menu layout › Responses

Get template usage

Get template usage › path Parameters

Get template usage › Responses

Reorder menu layouts

Reorder menu layouts › Request Body

Reorder menu layouts › Responses

Webhook: Menu layout created

Webhook: Menu layout created › Request Body

Webhook: Menu layout created › Responses

Webhook: Menu layout updated

Webhook: Menu layout updated › Request Body

Webhook: Menu layout updated › Responses

Webhook: Menu layout deleted

Webhook: Menu layout deleted › Request Body

Webhook: Menu layout deleted › Responses

Menu Layouts

List menu layouts

List menu layouts › query Parameters

List menu layouts › Responses

Create menu layout

Create menu layout › Request Body

Create menu layout › Responses

Get menu layout

Get menu layout › path Parameters

Get menu layout › query Parameters

Get menu layout › Responses

Update menu layout

Update menu layout › path Parameters

Update menu layout › Request Body

Update menu layout › Responses

Delete menu layout

Delete menu layout › path Parameters

Delete menu layout › query Parameters

Delete menu layout › Responses

Get template usage

Get template usage › path Parameters

Get template usage › Responses

Reorder menu layouts

Reorder menu layouts › Request Body

Reorder menu layouts › Responses

Webhook: Menu layout created

Webhook: Menu layout created › Request Body

Webhook: Menu layout created › Responses

Webhook: Menu layout updated

Webhook: Menu layout updated › Request Body

Webhook: Menu layout updated › Responses

Webhook: Menu layout deleted

Webhook: Menu layout deleted › Request Body

Webhook: Menu layout deleted › Responses