Inventory

Server

Download schema

Menu items, products, and modifiers

List inventory items

GET

https://common-api.karma.life

/api/v1/inventory

Retrieve a paginated list of inventory items with filtering and search capabilities

Permissions: 🔵 inventory.read

List inventory items › query Parameters

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

sort

string

Field to sort by (title, basePrice, createdAt, etc.)

Default: title

order

string · enum

Sort order

Enum values:

asc

desc

Default: asc

deleted

boolean

Include deleted items

Default: false

search

string

Search term for title/description

tags

string[]

Filter by tags

itemType

string

Filter by item type

excludeUnmapped

boolean

When true and the location has an active POS integration, drop items that lack an integration_resource_mappings row. Used by storefront-web to hide items that would otherwise produce empty kitchen tickets.

Default: false

List inventory items › Responses

Default Response

status

string · enum · required

Enum values:

success

object · required

Create inventory item

POST

https://common-api.karma.life

/api/v1/inventory

Add a new menu item or product to the inventory

Permissions: 🟢 inventory.create

Create inventory item › Request Body

locationId

number · required

Location ID

title

string · minLength: 1 · maxLength: 255 · required

Item title

basePrice

number · min: 0 · required

Base price in cents

itemType

string · maxLength: 255 · required

Item type

description

string | null · maxLength: 255

Item description

Item tags (array of strings or grouped tags object)

vatId

integer | null

VAT ID

vatValue

number | null

VAT value (legacy)

accountIds

string[]

Bookkeeping account IDs

printerGroupIds

string[]

Printer group IDs

variantGroupIds

number[]

Variant group IDs

visibility

string[]

Visibility settings

Create inventory item › Responses

Default Response

status

string · enum · required

Enum values:

success

object · required

POST/api/v1/inventory

curl --request POST \
  --url https://common-api.karma.life/api/v1/inventory \
  --header 'Content-Type: application/json' \
  --data '
{
  "locationId": 0,
  "title": "title",
  "description": "description",
  "basePrice": 0,
  "itemType": "itemType",
  "tags": [
    "string"
  ],
  "vatId": 0,
  "vatValue": 0,
  "accountIds": [
    "string"
  ],
  "printerGroupIds": [
    "string"
  ],
  "variantGroupIds": [
    0
  ],
  "visibility": [
    "string"
  ]
}
'

Example Request Body

{
  "locationId": 0,
  "title": "title",
  "description": "description",
  "basePrice": 0,
  "itemType": "itemType",
  "tags": [
    "string"
  ],
  "vatId": 0,
  "vatValue": 0,
  "accountIds": [
    "string"
  ],
  "printerGroupIds": [
    "string"
  ],
  "variantGroupIds": [
    0
  ],
  "visibility": [
    "string"
  ]
}

json

Example Responses

No example specified for this content type

application/json

Get inventory item

GET

https://common-api.karma.life

/api/v1/inventory/{id}

Retrieve detailed information about a specific inventory item by its ID

Permissions: 🔵 inventory.read

Get inventory item › path Parameters

id

string · pattern: ^[0-9]+$ · required

Inventory item ID

Get inventory item › Responses

Default Response

status

string · enum · required

Enum values:

success

object · required

Update inventory item

PUT

https://common-api.karma.life

/api/v1/inventory/{id}

Modify an existing inventory item's details

Permissions: 🟠 inventory.update

Update inventory item › path Parameters

id

string · pattern: ^[0-9]+$ · required

Inventory item ID

Update inventory item › Request Body

title

string · minLength: 1 · maxLength: 255

description

string | null · maxLength: 255

basePrice

number · min: 0

itemType

string · maxLength: 255

available

boolean

takeawayVatId

integer | null

integrationId

string | null · maxLength: 255

integrationItemId

string | null · maxLength: 255

imageUrl

string | null · maxLength: 255

externalImageUrl

string | null · maxLength: 255

titlePrep

string | null · maxLength: 255

color

string | null · maxLength: 255

kitchenSortOrder

integer | null

Sort order within groups on printed kitchen tickets and KDS. Lower numbers appear first. NULL = sort last alphabetically.

Update inventory item › Responses

Default Response

status

string · enum · required

Enum values:

success

object · required

PUT/api/v1/inventory/{id}

curl --request PUT \
  --url https://common-api.karma.life/api/v1/inventory/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "title",
  "description": "description",
  "basePrice": 0,
  "itemType": "itemType",
  "available": true,
  "takeawayVatId": 0,
  "integrationId": "integrationId",
  "integrationItemId": "integrationItemId",
  "imageUrl": "imageUrl",
  "externalImageUrl": "externalImageUrl",
  "context": {},
  "titlePrep": "titlePrep",
  "color": "color",
  "kitchenSortOrder": 0
}
'

Example Request Body

{
  "title": "title",
  "description": "description",
  "basePrice": 0,
  "itemType": "itemType",
  "available": true,
  "takeawayVatId": 0,
  "integrationId": "integrationId",
  "integrationItemId": "integrationItemId",
  "imageUrl": "imageUrl",
  "externalImageUrl": "externalImageUrl",
  "context": {},
  "titlePrep": "titlePrep",
  "color": "color",
  "kitchenSortOrder": 0
}

json

Example Responses

No example specified for this content type

application/json

Delete inventory item

DELETE

https://common-api.karma.life

/api/v1/inventory/{id}

Soft-delete an inventory item (marks as deleted without removing from database)

Permissions: 🔴 inventory.delete

Delete inventory item › path Parameters

id

string · pattern: ^[0-9]+$ · required

Inventory item ID

Delete inventory item › Responses

Item successfully deleted

status

string · enum

Enum values:

success

object

Update item inheritance

PUT

https://common-api.karma.life

/api/v1/inventory/{id}/inheritance

Update inheritance settings for an inventory item in a multi-location hierarchy

Permissions: 🟠 inventory.update

Update item inheritance › path Parameters

id

string · pattern: ^[0-9]+$ · required

Inventory item ID

Update item inheritance › Request Body

inheritToChildren

boolean

Whether this item should be inherited to child locations

allowedOverrides

string[]

Fields that child locations are allowed to override

Update item inheritance › Responses

Default Response

status

string · enum

Enum values:

success

object

Get item overrides

GET

https://common-api.karma.life

/api/v1/inventory/{id}/overrides

Get all location-specific overrides for an inherited inventory item

Permissions: 🔵 inventory.read

Get item overrides › path Parameters

id

string · pattern: ^[0-9]+$ · required

Inventory item ID

Get item overrides › query Parameters

locationId

number

Filter overrides by location ID

Get item overrides › Responses

Default Response

status

string · enum

Enum values:

success

object

Update item overrides

PUT

https://common-api.karma.life

/api/v1/inventory/{id}/overrides

Update location-specific overrides for an inherited inventory item

Permissions: 🟠 inventory.update

Update item overrides › path Parameters

id

string · pattern: ^[0-9]+$ · required

Inventory item ID

Update item overrides › query Parameters

locationId

number

Location ID for the override

Update item overrides › Request Body

Fields to override at this location

Update item overrides › Responses

Default Response

status

string · enum

Enum values:

success

object

Toggle item availability

POST

https://common-api.karma.life

/api/v1/inventory/{itemId}/availability

Enable or disable an inventory item for customer ordering

Permissions: 🟠 inventory.update

Toggle item availability › path Parameters

itemId

string · pattern: ^[0-9]+$ · required

Inventory item ID

Toggle item availability › Request Body

action

string · enum · required

Action to perform: ACTIVATE to make item available, DEACTIVATE to hide it

Enum values:

ACTIVATE

DEACTIVATE

Toggle item availability › Responses

Default Response

status

string · enum · required

Enum values:

success

object · required

Validate inventory items

POST

https://common-api.karma.life

/api/v1/inventory/validate

Validate inventory items and variants before creating an order. Returns validation results for each item.

Validate inventory items › Request Body

locationId

number · min: 1 · required

object[] · minItems: 1 · required

validateMenu

boolean

Validate inventory items › Responses

Validation response containing valid and invalid items with nested variant structures

POST/api/v1/inventory/validate

curl --request POST \
  --url https://common-api.karma.life/api/v1/inventory/validate \
  --header 'Content-Type: application/json' \
  --data '
{
  "locationId": 1,
  "items": [
    {
      "itemId": 1,
      "variants": [
        {
          "id": 1,
          "quantity": 0.01
        }
      ],
      "quantity": 1,
      "menuId": "menuId"
    }
  ],
  "validateMenu": true
}
'

Example Request Body

{
  "locationId": 1,
  "items": [
    {
      "itemId": 1,
      "variants": [
        {
          "id": 1,
          "quantity": 0.01
        }
      ],
      "quantity": 1,
      "menuId": "menuId"
    }
  ],
  "validateMenu": true
}

json

Example Responses

No example specified for this content type

application/json

Webhook: Inventory item created

POST

https://common-api.karma.life

/webhook/inventory.created

Fired when a new inventory item is created (POST /api/v1/inventory). The full item object is included in data along with locationId.

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.

Webhook: Inventory item created › Request Body

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

inventory.created

resource

string · enum · required

Enum values:

inventory

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

Webhook: Inventory item created › Responses

200

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

No data returned

POST/webhook/inventory.created

curl --request POST \
  --url https://common-api.karma.life/webhook/inventory.created \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "evt_01HZK3...",
  "event": "inventory.created",
  "resource": "inventory",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "id": 0,
    "locationId": 0,
    "title": "title",
    "weight": 0,
    "discountPercentage": 0,
    "basePrice": 0,
    "deleted": true,
    "fullPrice": true,
    "madeToOrder": true,
    "ingredients": "ingredients",
    "imageUrl": "imageUrl",
    "producer": "producer",
    "weightString": "weightString",
    "externalImageUrl": "externalImageUrl",
    "integrationId": "integrationId",
    "integrationItemId": "integrationItemId",
    "vatValue": 0,
    "articleNumber": "articleNumber",
    "itemType": "itemType",
    "ministock": 0,
    "visibility": [
      "string"
    ],
    "tags": [
      "string"
    ],
    "nonSurplusAvailable": true,
    "createdDate": "2024-08-25T15:00:00Z"
  }
}
'

Example Request Body

{
  "id": "evt_01HZK3...",
  "event": "inventory.created",
  "resource": "inventory",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "id": 0,
    "locationId": 0,
    "title": "title",
    "weight": 0,
    "discountPercentage": 0,
    "basePrice": 0,
    "deleted": true,
    "fullPrice": true,
    "madeToOrder": true,
    "ingredients": "ingredients",
    "imageUrl": "imageUrl",
    "producer": "producer",
    "weightString": "weightString",
    "externalImageUrl": "externalImageUrl",
    "integrationId": "integrationId",
    "integrationItemId": "integrationItemId",
    "vatValue": 0,
    "articleNumber": "articleNumber",
    "itemType": "itemType",
    "ministock": 0,
    "visibility": [
      "string"
    ],
    "tags": [
      "string"
    ],
    "nonSurplusAvailable": true,
    "createdDate": "2024-08-25T15:00:00Z"
  }
}

json

Example Responses

No example specified for this content type

Webhook: Inventory item updated

POST

https://common-api.karma.life

/webhook/inventory.updated

Fired when an inventory item changes (PUT /api/v1/inventory/:id). changes contains only the fields that were modified. Also fired from channel assignment changes when they affect items.

Webhook: Inventory item updated › Request Body

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

inventory.updated

resource

string · enum · required

Enum values:

inventory

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

Webhook: Inventory item updated › Responses

200

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

No data returned

POST/webhook/inventory.updated

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

Example Request Body

{
  "id": "evt_01HZK3...",
  "event": "inventory.updated",
  "resource": "inventory",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "itemId": 0,
    "changes": {},
    "locationId": 0,
    "updatedAt": "2024-08-25T15:00:00Z",
    "channels_updated": true
  }
}

json

Example Responses

No example specified for this content type

Webhook: Inventory item soft-deleted

POST

https://common-api.karma.life

/webhook/inventory.deleted

Fired when an inventory item is soft-deleted (DELETE /api/v1/inventory/:id). The row remains in the database with deleted: true.

Webhook: Inventory item soft-deleted › Request Body

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

inventory.deleted

resource

string · enum · required

Enum values:

inventory

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

Webhook: Inventory item soft-deleted › Responses

200

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

No data returned

POST/webhook/inventory.deleted

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

Example Request Body

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

json

Example Responses

No example specified for this content type

Extended Waiting Time Invoices