Inventory
Menu items, products, and modifiers
Authorization
ApiKeyAuth API key authentication. Format: karma_live_* or karma_dev_*
In: header
Query Parameters
length <= 255Value in
- "contains"
- "eq"
length <= 200Value in
- "contains"
- "eq"
Value in
- "local"
- "inherited"
Minimum effective price in currency units for the requested channel
0 <= valueMaximum effective price in currency units for the requested channel
0 <= valueFilter by location ID
Page number
1 <= value1Items per page
1 <= value <= 10020Field to sort by (title, calculatedPrice, pricing, source, basePrice, createdAt)
"title"Sort order
"asc"Value in
- "asc"
- "desc"
Include deleted items
falseSearch term for title/description
Return only these inventory item IDs. Repeat the query parameter for multiple IDs.
1 <= items <= 100Filter by item type
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.
falseJSON-encoded jsonb-containment filter on items.metadata. Example: ?metadata={"someKey":"value"}. The dotted shorthand ?metadata.someKey=value is also accepted (all dotted values arrive as strings — use the JSON form for non-string values).
Channel context for pricing. Defaults to ONLINE. Use POS, KIOSK, TAKEAWAY, or any custom channel name (e.g. FOODORA) to get channel-specific calculatedPrice.
"ONLINE"Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/inventory"{ "status": "success", "data": { "items": [ { "customFields": [ { "fieldId": "string", "key": "string", "label": "string", "group": "string", "type": "string", "displayValue": "string", "value": null, "version": 0, "status": "string" } ], "metadata": { "externalItemId": "sku-se-3732185", "externalCountryCode": "SE" }, "pricingGroupId": "ffc3cac5-6bcf-49c9-b5c9-20079daf92b0", "pricingGroupName": "string", "measurement": { "unit": "mg", "priceQuantityMicros": 1, "defaultAmountMicros": 1, "storefrontInput": true }, "measuredStockAtoms": 0, "guestInput": { "schemaToken": "string", "fields": [ { "id": "string", "key": "string", "label": "string", "description": "string", "group": "string", "type": "string", "required": true, "revision": 0, "config": { "taxonomyDisplay": "select", "options": [ { "id": "string", "label": "string", "parentId": "string" } ], "currency": "string", "min": 0, "max": 0, "maxLength": 0, "condition": { "field": "string", "equals": "string" } } } ] }, "id": 0, "locationId": 0, "title": "string", "description": "string", "calculatedPricesByChannel": { "property1": 0, "property2": 0 }, "calculatedPrice": 0, "itemType": "string", "vatId": 0, "vatValue": 0, "takeawayVatId": 0, "takeawayVatValue": 0, "takeawayAccountId": "string", "manualIsAvailable": true, "ingredientPaused": true, "isAvailable": true, "allowedTabTypes": [ "table" ], "ean": "string", "deleted": true, "madeToOrder": true, "tags": { "property1": [ "string" ], "property2": [ "string" ] }, "customTagDetails": [ { "id": 0, "key": "string", "categoryHandle": "string" } ], "createdDate": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z", "ingredients": "string", "imageUrl": "string", "externalImageUrl": "string", "images": [ { "url": "string", "name": "string", "size": 0, "type": "string" } ], "integrationId": 0, "integrationItemId": "string", "context": { "gift_card": { "template_id": 0, "preset_amounts_cents": [ 1 ], "allow_digital": true, "allow_physical": true, "allow_pickup": true, "allow_delivery": true, "delivery_fee_cents": 0, "physical_card_fee_cents": 0, "recipient_instructions": "string" } }, "pricings": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "price": 0, "name": "BASE", "order": 0, "metadata": { "mode": "absolute", "percentage": 0, "maxAdjustment": 0, "minPrice": 0, "maxPrice": 0, "formula": "string", "variables": { "property1": 0, "property2": 0 } }, "validFrom": "string", "validTo": "string", "scheduleId": "string", "channelTypes": [ "string" ], "scheduleActive": true } ], "purchaseCostCents": 0, "ministock": 0, "ministockCents": 0, "isAlcohol": true, "variablePricing": true, "minPriceCents": 0, "maxPriceCents": 0, "variableQuantity": true, "tagIds": [ 0 ], "accountIds": [ "string" ], "variantGroupIds": [ 0 ], "printerGroupIds": [ "string" ], "servingCenterId": 0, "titlePrep": "string", "prepTimeMinutes": 0, "coursingOrder": 0, "preparation": "string", "printPreparation": true, "color": "string", "kitchenSortOrder": 0, "scheduleRules": [ { "id": "string", "dayOfWeek": 0, "startTime": "string", "endTime": "string", "active": true } ], "isInherited": true, "inheritToChildren": true, "parentItemId": 0, "sourceLocationId": 0, "overriddenFields": [ "string" ], "allowedOverrides": [ "string" ], "inheritanceUpdatedAt": "2019-08-24T14:15:22Z", "isPosSynced": true, "posOverriddenFields": [ "string" ], "channelAvailability": { "byChannel": { "KIOSK": true, "POS": true, "ONLINE": true, "TAKEAWAY": true, "WOLT": true, "FOODORA": true, "UBER_EATS": true }, "online": true, "qr": true, "kiosk": true, "pos": true, "wolt": true, "foodora": true, "uberEats": true }, "posIntegration": { "integrationConfigId": 0, "provider": "string", "externalItemId": "string", "isMapped": true } } ], "pagination": { "page": 1, "limit": 1, "total": 0, "totalPages": 0 } }, "meta": { "requestId": "string", "timestamp": "2019-08-24T14:15:22Z", "executionTimeMs": 0 }}Authorization
ApiKeyAuth API key authentication. Format: karma_live_* or karma_dev_*
In: header
Request Body
application/json
Create request using camelCase property names. Every writable property is listed; any other key is ignored and not stored. See /docs/inventory-items for pricing, VAT and relationship rules.
TypeScript Definitions
Use the request body type in TypeScript.
Create request using camelCase property names. Every writable property is listed; any other key is ignored and not stored. See /docs/inventory-items for pricing, VAT and relationship rules.
Ingredient text.
Item image URL.
External/integration image URL.
Existing integration identifier; does not create an integration.
Item reference within the external integration.
JSON settings for specific item kinds. The public key is gift_card, the settings of a gift_card item. Karma's own systems store other keys here too: an update replaces the whole object, so read the item first and send back the keys you did not mean to change.
Additional images, shown after imageUrl. Replaces the stored list.
Optional custom field operations, saved atomically with this record. Omitted values are unchanged; null clears. Use fieldId or a stable key. expectedVersion is optional; supply it to reject conflicting edits.
items <= 100Optional canonical product hierarchy; validated against the venue taxonomy. Null clears classification. Legacy category tags remain separate.
Configured purchase cost in currency minor units.
Soft-deletion flag; defaults to false on creation.
Whether prepared on demand; defaults to false on creation.
Article number stored in legacy item metadata; keep as a string to preserve leading zeros. Separate from customer-owned identifiers in the metadata JSON object.
Explicit item pricing definitions. On creation, use this array or pricingGroupId for the persisted price. No tag or variant group is required merely to save a price. On update, replaces the item's pricing selection; do not mix with pricingGroupId.
Takeaway VAT rate ID (see GET /api/v1/vat-rates). There is no percentage-based alternative.
Bookkeeping account used when the line is sold as takeaway; its VAT rate overrides takeawayVatId
Configured stock quantity in units; supports fractional quantities.
Stock quantity in hundredths of a unit, not currency. When supplied with ministock, takes precedence for fractional stock.
Existing serving-center identifier.
Preparation-facing title.
Configured preparation time in minutes.
Configured course order.
Kitchen preparation instructions.
Print preparation instructions; defaults to false on creation.
Kitchen/display colour.
Kitchen ticket/display sort order; lower numbers appear first.
Alcohol flag; defaults to false on creation.
Allow POS price changes; defaults to false on creation.
Ask for a quantity in POS; defaults to false on creation.
Variable-price lower bound in currency minor units.
Variable-price upper bound in currency minor units.
Location ID
Existing shared-price UUID. Alternative to explicit pricings, not a variant-group ID. See the shared-prices guide.
uuidSells the item by weight, volume or length instead of by piece. Null sells it by piece. All amounts are in millionths of unit (1,000,000 = 1 unit).
Stock of a measured item in hundred-millionths of measurement.unit (100,000,000 = 1 unit). When supplied it sets ministock and ministockCents. Null = unlimited.
0 <= value <= 9007199254740991Item title
1 <= length <= 255Item description
length <= 500Ignored. Set the price with pricings (currency units) or pricingGroupId.
0 <= valueCatalogue item classification, stored unchanged (an empty string included) and at most 50 characters. Not a closed enum, but only recognised values carry behaviour: regular (ordinary product; null and "" behave the same), variant (exists only as another product's option), delivery (storefront shipping-fee product) and gift_card (each sale issues a gift card for the line amount). Other strings are stored and returned without effect. See /docs/inventory-items. Separate from purchase_line_items.item_type and legacy item_meta_data.item_type_key.
length <= 50Grouped object keyed by tag type, e.g. {"CATEGORY_PRIMARY":["DRINK"],"ALLERGEN":["NUTS"],"CUSTOM":["existing-custom-key"]}. Tag types and tag keys must already exist: unknown ones are skipped silently (the request still succeeds), and nothing is created. Read the item back to confirm. CUSTOM resolves existing custom tags in the CUISINE category. Not required for price or VAT; CATEGORY_PRIMARY only groups the item in reports and analytics. When supplied, tags REPLACES every legacy non-custom tag on the item (canonical ITEM_CLASS_* classification is preserved): a type you leave out (CATEGORY_PRIMARY included) is removed. Omit CUSTOM to keep custom tags; CUSTOM: [] clears them. Don't send the legacy string-array shape: it matches no tag type, so it removes every non-custom tag.
VAT rate ID (see GET /api/v1/vat-rates). Takes priority over vatValue.
VAT as a percentage, e.g. 12 means 12%. Responses report vatValue in basis points (1200 = 12%), so never send back the value you read; send vatId instead. Not required to set a price: without vatId, vatValue or accountIds the item gets the location country's default VAT, which may be wrong for the product, so set it explicitly.
0 <= value <= 100Existing bookkeeping account UUIDs. When supplied without vatId or vatValue, the item gets no country-default VAT.
Existing printer (prep) group UUIDs that receive the item's kitchen tickets
Existing variant-group IDs for modifiers/options; does not create groups. Optional, including for priced items. Omitted or [] on creation stores no group links; on update [] removes links.
Legacy channel memberships. Stored, but nothing reads them: they don't change where the item is sold and aren't returned when reading the item. Omitted on creation stores none; on update the array replaces them. Use the menu layouts' channel availability (returned as channelAvailability), isAvailable and allowedTabTypes to control where an item can be ordered.
Tab types this item may be ordered onto. Null or omitted = any tab. An order for a tab type outside this list is refused.
EAN/barcode
length <= 64Your own identifiers and context, stored as you send them and returned unchanged. Karma reads none of these keys. Keys are case-sensitive; prefix them with your company or system name to avoid collisions, and never store secrets.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/inventory" \ -H "Content-Type: application/json" \ -d '{ "locationId": 0, "title": "string", "itemType": "regular" }'{ "status": "success", "data": { "customFields": [ { "fieldId": "string", "key": "string", "label": "string", "group": "string", "type": "string", "displayValue": "string", "value": null, "version": 0, "status": "string" } ], "metadata": { "externalItemId": "sku-se-3732185", "externalCountryCode": "SE" }, "pricingGroupId": "ffc3cac5-6bcf-49c9-b5c9-20079daf92b0", "pricingGroupName": "string", "measurement": { "unit": "mg", "priceQuantityMicros": 1, "defaultAmountMicros": 1, "storefrontInput": true }, "measuredStockAtoms": 0, "guestInput": { "schemaToken": "string", "fields": [ { "id": "string", "key": "string", "label": "string", "description": "string", "group": "string", "type": "string", "required": true, "revision": 0, "config": { "taxonomyDisplay": "select", "options": [ { "id": "string", "label": "string", "parentId": "string" } ], "currency": "string", "min": 0, "max": 0, "maxLength": 0, "condition": { "field": "string", "equals": "string" } } } ] }, "id": 0, "locationId": 0, "title": "string", "description": "string", "calculatedPricesByChannel": { "property1": 0, "property2": 0 }, "calculatedPrice": 0, "itemType": "string", "vatId": 0, "vatValue": 0, "takeawayVatId": 0, "takeawayVatValue": 0, "takeawayAccountId": "string", "manualIsAvailable": true, "ingredientPaused": true, "isAvailable": true, "allowedTabTypes": [ "table" ], "ean": "string", "deleted": true, "madeToOrder": true, "tags": { "property1": [ "string" ], "property2": [ "string" ] }, "customTagDetails": [ { "id": 0, "key": "string", "categoryHandle": "string" } ], "createdDate": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z", "ingredients": "string", "imageUrl": "string", "externalImageUrl": "string", "images": [ { "url": "string", "name": "string", "size": 0, "type": "string" } ], "integrationId": 0, "integrationItemId": "string", "context": { "gift_card": { "template_id": 0, "preset_amounts_cents": [ 1 ], "allow_digital": true, "allow_physical": true, "allow_pickup": true, "allow_delivery": true, "delivery_fee_cents": 0, "physical_card_fee_cents": 0, "recipient_instructions": "string" } }, "pricings": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "price": 0, "name": "BASE", "order": 0, "metadata": { "mode": "absolute", "percentage": 0, "maxAdjustment": 0, "minPrice": 0, "maxPrice": 0, "formula": "string", "variables": { "property1": 0, "property2": 0 } }, "validFrom": "string", "validTo": "string", "scheduleId": "string", "channelTypes": [ "string" ], "scheduleActive": true } ], "purchaseCostCents": 0, "ministock": 0, "ministockCents": 0, "isAlcohol": true, "variablePricing": true, "minPriceCents": 0, "maxPriceCents": 0, "variableQuantity": true, "tagIds": [ 0 ], "accountIds": [ "string" ], "variantGroupIds": [ 0 ], "printerGroupIds": [ "string" ], "servingCenterId": 0, "titlePrep": "string", "prepTimeMinutes": 0, "coursingOrder": 0, "preparation": "string", "printPreparation": true, "color": "string", "kitchenSortOrder": 0, "scheduleRules": [ { "id": "string", "dayOfWeek": 0, "startTime": "string", "endTime": "string", "active": true } ], "isInherited": true, "inheritToChildren": true, "parentItemId": 0, "sourceLocationId": 0, "overriddenFields": [ "string" ], "allowedOverrides": [ "string" ], "inheritanceUpdatedAt": "2019-08-24T14:15:22Z", "isPosSynced": true, "posOverriddenFields": [ "string" ], "channelAvailability": { "byChannel": { "KIOSK": true, "POS": true, "ONLINE": true, "TAKEAWAY": true, "WOLT": true, "FOODORA": true, "UBER_EATS": true }, "online": true, "qr": true, "kiosk": true, "pos": true, "wolt": true, "foodora": true, "uberEats": true }, "posIntegration": { "integrationConfigId": 0, "provider": "string", "externalItemId": "string", "isMapped": true } }, "meta": { "requestId": "string", "timestamp": "2019-08-24T14:15:22Z", "executionTimeMs": 0 }}Authorization
ApiKeyAuth API key authentication. Format: karma_live_* or karma_dev_*
In: header
Path Parameters
Inventory item ID
^[0-9]+$Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/inventory/string"{ "status": "success", "data": { "customFields": [ { "fieldId": "string", "key": "string", "label": "string", "group": "string", "type": "string", "displayValue": "string", "value": null, "version": 0, "status": "string" } ], "metadata": { "externalItemId": "sku-se-3732185", "externalCountryCode": "SE" }, "pricingGroupId": "ffc3cac5-6bcf-49c9-b5c9-20079daf92b0", "pricingGroupName": "string", "measurement": { "unit": "mg", "priceQuantityMicros": 1, "defaultAmountMicros": 1, "storefrontInput": true }, "measuredStockAtoms": 0, "guestInput": { "schemaToken": "string", "fields": [ { "id": "string", "key": "string", "label": "string", "description": "string", "group": "string", "type": "string", "required": true, "revision": 0, "config": { "taxonomyDisplay": "select", "options": [ { "id": "string", "label": "string", "parentId": "string" } ], "currency": "string", "min": 0, "max": 0, "maxLength": 0, "condition": { "field": "string", "equals": "string" } } } ] }, "id": 0, "locationId": 0, "title": "string", "description": "string", "calculatedPricesByChannel": { "property1": 0, "property2": 0 }, "calculatedPrice": 0, "itemType": "string", "vatId": 0, "vatValue": 0, "takeawayVatId": 0, "takeawayVatValue": 0, "takeawayAccountId": "string", "manualIsAvailable": true, "ingredientPaused": true, "isAvailable": true, "allowedTabTypes": [ "table" ], "ean": "string", "deleted": true, "madeToOrder": true, "tags": { "property1": [ "string" ], "property2": [ "string" ] }, "customTagDetails": [ { "id": 0, "key": "string", "categoryHandle": "string" } ], "createdDate": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z", "ingredients": "string", "imageUrl": "string", "externalImageUrl": "string", "images": [ { "url": "string", "name": "string", "size": 0, "type": "string" } ], "integrationId": 0, "integrationItemId": "string", "context": { "gift_card": { "template_id": 0, "preset_amounts_cents": [ 1 ], "allow_digital": true, "allow_physical": true, "allow_pickup": true, "allow_delivery": true, "delivery_fee_cents": 0, "physical_card_fee_cents": 0, "recipient_instructions": "string" } }, "pricings": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "price": 0, "name": "BASE", "order": 0, "metadata": { "mode": "absolute", "percentage": 0, "maxAdjustment": 0, "minPrice": 0, "maxPrice": 0, "formula": "string", "variables": { "property1": 0, "property2": 0 } }, "validFrom": "string", "validTo": "string", "scheduleId": "string", "channelTypes": [ "string" ], "scheduleActive": true } ], "purchaseCostCents": 0, "ministock": 0, "ministockCents": 0, "isAlcohol": true, "variablePricing": true, "minPriceCents": 0, "maxPriceCents": 0, "variableQuantity": true, "tagIds": [ 0 ], "accountIds": [ "string" ], "variantGroupIds": [ 0 ], "printerGroupIds": [ "string" ], "servingCenterId": 0, "titlePrep": "string", "prepTimeMinutes": 0, "coursingOrder": 0, "preparation": "string", "printPreparation": true, "color": "string", "kitchenSortOrder": 0, "scheduleRules": [ { "id": "string", "dayOfWeek": 0, "startTime": "string", "endTime": "string", "active": true } ], "isInherited": true, "inheritToChildren": true, "parentItemId": 0, "sourceLocationId": 0, "overriddenFields": [ "string" ], "allowedOverrides": [ "string" ], "inheritanceUpdatedAt": "2019-08-24T14:15:22Z", "isPosSynced": true, "posOverriddenFields": [ "string" ], "channelAvailability": { "byChannel": { "KIOSK": true, "POS": true, "ONLINE": true, "TAKEAWAY": true, "WOLT": true, "FOODORA": true, "UBER_EATS": true }, "online": true, "qr": true, "kiosk": true, "pos": true, "wolt": true, "foodora": true, "uberEats": true }, "posIntegration": { "integrationConfigId": 0, "provider": "string", "externalItemId": "string", "isMapped": true } }, "meta": { "requestId": "string", "timestamp": "2019-08-24T14:15:22Z", "executionTimeMs": 0 }}Authorization
ApiKeyAuth API key authentication. Format: karma_live_* or karma_dev_*
In: header
Path Parameters
Inventory item ID
^[0-9]+$Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/api/v1/inventory/string"{ "status": "success", "data": { "deleted": true }, "meta": { "requestId": "string", "timestamp": "2019-08-24T14:15:22Z", "executionTimeMs": 0 }}Authorization
ApiKeyAuth API key authentication. Format: karma_live_* or karma_dev_*
In: header
Path Parameters
Inventory item ID
^[0-9]+$Request Body
application/json
Update only supplied fields; omitted fields are preserved. Relationship arrays, tags, context and metadata replace what is stored. Every writable property is listed; any other key is ignored. Availability is changed with POST /api/v1/inventory/{itemId}/availability, not here. See /docs/inventory-items.
TypeScript Definitions
Use the request body type in TypeScript.
Update only supplied fields; omitted fields are preserved. Relationship arrays, tags, context and metadata replace what is stored. Every writable property is listed; any other key is ignored. Availability is changed with POST /api/v1/inventory/{itemId}/availability, not here. See /docs/inventory-items.
Ingredient text.
Item image URL.
length <= 255Image URL from an integration; re-hosted on Karma media after the write.
length <= 255Existing integration identifier; does not create an integration.
Item reference within the external integration.
length <= 255JSON settings for specific item kinds. The public key is gift_card, the settings of a gift_card item. Karma's own systems store other keys here too: an update replaces the whole object, so read the item first and send back the keys you did not mean to change.
Additional images, shown after imageUrl. Replaces the stored list.
Optional custom field operations, saved atomically with this record. Omitted values are unchanged; null clears. Use fieldId or a stable key. expectedVersion is optional; supply it to reject conflicting edits.
items <= 100Optional canonical product hierarchy; validated against the venue taxonomy. Null clears classification. Legacy category tags remain separate.
Configured purchase cost in currency minor units.
Soft-deletion flag; defaults to false on creation.
Whether prepared on demand; defaults to false on creation.
Article number stored in legacy item metadata; keep as a string to preserve leading zeros. Separate from customer-owned identifiers in the metadata JSON object.
Explicit item pricing definitions. On creation, use this array or pricingGroupId for the persisted price. No tag or variant group is required merely to save a price. On update, replaces the item's pricing selection; do not mix with pricingGroupId.
Takeaway VAT rate ID (see GET /api/v1/vat-rates); null clears it. There is no percentage-based alternative.
Bookkeeping account used when the line is sold as takeaway; its VAT rate overrides takeawayVatId
Configured stock quantity in units; supports fractional quantities.
Stock quantity in hundredths of a unit, not currency. When supplied with ministock, takes precedence for fractional stock.
Existing serving-center identifier.
Shorter title for kitchen tickets and the KDS.
length <= 255Configured preparation time in minutes.
Configured course order.
Kitchen preparation instructions, shown to staff in the POS
Print the preparation instructions under the item's line on kitchen tickets
Kitchen/display colour.
length <= 255Sort order within groups on printed kitchen tickets and KDS. Lower numbers appear first. NULL = sort last alphabetically.
Alcohol flag; defaults to false on creation.
Allow POS price changes; defaults to false on creation.
Ask for a quantity in POS; defaults to false on creation.
Variable-price lower bound in currency minor units.
Variable-price upper bound in currency minor units.
Grouped object keyed by tag type, e.g. {"CATEGORY_PRIMARY":["DRINK"],"ALLERGEN":["NUTS"],"CUSTOM":["existing-custom-key"]}. Tag types and tag keys must already exist: unknown ones are skipped silently (the request still succeeds), and nothing is created. Read the item back to confirm. CUSTOM resolves existing custom tags in the CUISINE category. Not required for price or VAT; CATEGORY_PRIMARY only groups the item in reports and analytics. When supplied, tags REPLACES every legacy non-custom tag on the item (canonical ITEM_CLASS_* classification is preserved): a type you leave out (CATEGORY_PRIMARY included) is removed. Omit CUSTOM to keep custom tags; CUSTOM: [] clears them. Don't send the legacy string-array shape: it matches no tag type, so it removes every non-custom tag.
Legacy channel memberships. Stored, but nothing reads them: they don't change where the item is sold and aren't returned when reading the item. Omitted on creation stores none; on update the array replaces them. Use the menu layouts' channel availability (returned as channelAvailability), isAvailable and allowedTabTypes to control where an item can be ordered.
Existing VAT row ID; when supplied takes priority over vatValue. Null clears the explicit VAT.
VAT as a percentage, e.g. 12 means 12%. Responses report vatValue in basis points (1200 = 12%), so never send back the value you read; send vatId instead. Used when vatId is omitted; null clears the VAT.
0 <= value <= 100Existing bookkeeping account UUIDs; replaces account mappings.
Existing printer-group UUIDs; replaces printer-group links.
Existing modifier/option group IDs; replaces links. [] removes links. Not required to set a price.
Existing shared-price UUID to link. Null detaches the shared price and then requires pricings. Omitted keeps the current link.
uuidSells the item by weight, volume or length instead of by piece. Null sells it by piece. All amounts are in millionths of unit (1,000,000 = 1 unit).
Stock of a measured item in hundred-millionths of measurement.unit (100,000,000 = 1 unit). When supplied it sets ministock and ministockCents. Null = unlimited.
0 <= value <= 9007199254740991Item title
1 <= length <= 255Item description
length <= 500Catalogue item classification, stored unchanged (an empty string included) and at most 50 characters. Not a closed enum, but only recognised values carry behaviour: regular (ordinary product; null and "" behave the same), variant (exists only as another product's option), delivery (storefront shipping-fee product) and gift_card (each sale issues a gift card for the line amount). Other strings are stored and returned without effect. See /docs/inventory-items. Separate from purchase_line_items.item_type and legacy item_meta_data.item_type_key.
length <= 50EAN/barcode
length <= 64Tab types this item may be ordered onto. Null or omitted = any tab. An order for a tab type outside this list is refused.
Your own identifiers and context, stored as you send them and returned unchanged. Karma reads none of these keys. Keys are case-sensitive; prefix them with your company or system name to avoid collisions, and never store secrets. Replaces the whole object; use PATCH /api/v1/inventory/{id}/metadata to merge selected top-level keys instead.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PUT "https://example.com/api/v1/inventory/string" \ -H "Content-Type: application/json" \ -d '{}'{ "status": "success", "data": { "customFields": [ { "fieldId": "string", "key": "string", "label": "string", "group": "string", "type": "string", "displayValue": "string", "value": null, "version": 0, "status": "string" } ], "metadata": { "externalItemId": "sku-se-3732185", "externalCountryCode": "SE" }, "pricingGroupId": "ffc3cac5-6bcf-49c9-b5c9-20079daf92b0", "pricingGroupName": "string", "measurement": { "unit": "mg", "priceQuantityMicros": 1, "defaultAmountMicros": 1, "storefrontInput": true }, "measuredStockAtoms": 0, "guestInput": { "schemaToken": "string", "fields": [ { "id": "string", "key": "string", "label": "string", "description": "string", "group": "string", "type": "string", "required": true, "revision": 0, "config": { "taxonomyDisplay": "select", "options": [ { "id": "string", "label": "string", "parentId": "string" } ], "currency": "string", "min": 0, "max": 0, "maxLength": 0, "condition": { "field": "string", "equals": "string" } } } ] }, "id": 0, "locationId": 0, "title": "string", "description": "string", "calculatedPricesByChannel": { "property1": 0, "property2": 0 }, "calculatedPrice": 0, "itemType": "string", "vatId": 0, "vatValue": 0, "takeawayVatId": 0, "takeawayVatValue": 0, "takeawayAccountId": "string", "manualIsAvailable": true, "ingredientPaused": true, "isAvailable": true, "allowedTabTypes": [ "table" ], "ean": "string", "deleted": true, "madeToOrder": true, "tags": { "property1": [ "string" ], "property2": [ "string" ] }, "customTagDetails": [ { "id": 0, "key": "string", "categoryHandle": "string" } ], "createdDate": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z", "ingredients": "string", "imageUrl": "string", "externalImageUrl": "string", "images": [ { "url": "string", "name": "string", "size": 0, "type": "string" } ], "integrationId": 0, "integrationItemId": "string", "context": { "gift_card": { "template_id": 0, "preset_amounts_cents": [ 1 ], "allow_digital": true, "allow_physical": true, "allow_pickup": true, "allow_delivery": true, "delivery_fee_cents": 0, "physical_card_fee_cents": 0, "recipient_instructions": "string" } }, "pricings": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "price": 0, "name": "BASE", "order": 0, "metadata": { "mode": "absolute", "percentage": 0, "maxAdjustment": 0, "minPrice": 0, "maxPrice": 0, "formula": "string", "variables": { "property1": 0, "property2": 0 } }, "validFrom": "string", "validTo": "string", "scheduleId": "string", "channelTypes": [ "string" ], "scheduleActive": true } ], "purchaseCostCents": 0, "ministock": 0, "ministockCents": 0, "isAlcohol": true, "variablePricing": true, "minPriceCents": 0, "maxPriceCents": 0, "variableQuantity": true, "tagIds": [ 0 ], "accountIds": [ "string" ], "variantGroupIds": [ 0 ], "printerGroupIds": [ "string" ], "servingCenterId": 0, "titlePrep": "string", "prepTimeMinutes": 0, "coursingOrder": 0, "preparation": "string", "printPreparation": true, "color": "string", "kitchenSortOrder": 0, "scheduleRules": [ { "id": "string", "dayOfWeek": 0, "startTime": "string", "endTime": "string", "active": true } ], "isInherited": true, "inheritToChildren": true, "parentItemId": 0, "sourceLocationId": 0, "overriddenFields": [ "string" ], "allowedOverrides": [ "string" ], "inheritanceUpdatedAt": "2019-08-24T14:15:22Z", "isPosSynced": true, "posOverriddenFields": [ "string" ], "channelAvailability": { "byChannel": { "KIOSK": true, "POS": true, "ONLINE": true, "TAKEAWAY": true, "WOLT": true, "FOODORA": true, "UBER_EATS": true }, "online": true, "qr": true, "kiosk": true, "pos": true, "wolt": true, "foodora": true, "uberEats": true }, "posIntegration": { "integrationConfigId": 0, "provider": "string", "externalItemId": "string", "isMapped": true } }, "meta": { "requestId": "string", "timestamp": "2019-08-24T14:15:22Z", "executionTimeMs": 0 }}Authorization
ApiKeyAuth API key authentication. Format: karma_live_* or karma_dev_*
In: header
Path Parameters
Inventory item ID
^[0-9]+$Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Whether this item should be inherited to child locations
Fields that child locations are allowed to override
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PUT "https://example.com/api/v1/inventory/string/inheritance" \ -H "Content-Type: application/json" \ -d '{}'{ "status": "success", "data": { "id": 0, "inheritToChildren": true, "allowedOverrides": [ "string" ] }, "meta": { "requestId": "string", "timestamp": "2019-08-24T14:15:22Z", "executionTimeMs": 0 }}Authorization
ApiKeyAuth API key authentication. Format: karma_live_* or karma_dev_*
In: header
Path Parameters
Inventory item ID
^[0-9]+$Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Top-level metadata keys to merge into the item.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/api/v1/inventory/string/metadata" \ -H "Content-Type: application/json" \ -d '{ "metadata": { "externalItemId": "sku-se-3732185", "externalCountryCode": "SE" } }'{ "status": "success", "data": { "customFields": [ { "fieldId": "string", "key": "string", "label": "string", "group": "string", "type": "string", "displayValue": "string", "value": null, "version": 0, "status": "string" } ], "metadata": { "externalItemId": "sku-se-3732185", "externalCountryCode": "SE" }, "pricingGroupId": "ffc3cac5-6bcf-49c9-b5c9-20079daf92b0", "pricingGroupName": "string", "measurement": { "unit": "mg", "priceQuantityMicros": 1, "defaultAmountMicros": 1, "storefrontInput": true }, "measuredStockAtoms": 0, "guestInput": { "schemaToken": "string", "fields": [ { "id": "string", "key": "string", "label": "string", "description": "string", "group": "string", "type": "string", "required": true, "revision": 0, "config": { "taxonomyDisplay": "select", "options": [ { "id": "string", "label": "string", "parentId": "string" } ], "currency": "string", "min": 0, "max": 0, "maxLength": 0, "condition": { "field": "string", "equals": "string" } } } ] }, "id": 0, "locationId": 0, "title": "string", "description": "string", "calculatedPricesByChannel": { "property1": 0, "property2": 0 }, "calculatedPrice": 0, "itemType": "string", "vatId": 0, "vatValue": 0, "takeawayVatId": 0, "takeawayVatValue": 0, "takeawayAccountId": "string", "manualIsAvailable": true, "ingredientPaused": true, "isAvailable": true, "allowedTabTypes": [ "table" ], "ean": "string", "deleted": true, "madeToOrder": true, "tags": { "property1": [ "string" ], "property2": [ "string" ] }, "customTagDetails": [ { "id": 0, "key": "string", "categoryHandle": "string" } ], "createdDate": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z", "ingredients": "string", "imageUrl": "string", "externalImageUrl": "string", "images": [ { "url": "string", "name": "string", "size": 0, "type": "string" } ], "integrationId": 0, "integrationItemId": "string", "context": { "gift_card": { "template_id": 0, "preset_amounts_cents": [ 1 ], "allow_digital": true, "allow_physical": true, "allow_pickup": true, "allow_delivery": true, "delivery_fee_cents": 0, "physical_card_fee_cents": 0, "recipient_instructions": "string" } }, "pricings": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "price": 0, "name": "BASE", "order": 0, "metadata": { "mode": "absolute", "percentage": 0, "maxAdjustment": 0, "minPrice": 0, "maxPrice": 0, "formula": "string", "variables": { "property1": 0, "property2": 0 } }, "validFrom": "string", "validTo": "string", "scheduleId": "string", "channelTypes": [ "string" ], "scheduleActive": true } ], "purchaseCostCents": 0, "ministock": 0, "ministockCents": 0, "isAlcohol": true, "variablePricing": true, "minPriceCents": 0, "maxPriceCents": 0, "variableQuantity": true, "tagIds": [ 0 ], "accountIds": [ "string" ], "variantGroupIds": [ 0 ], "printerGroupIds": [ "string" ], "servingCenterId": 0, "titlePrep": "string", "prepTimeMinutes": 0, "coursingOrder": 0, "preparation": "string", "printPreparation": true, "color": "string", "kitchenSortOrder": 0, "scheduleRules": [ { "id": "string", "dayOfWeek": 0, "startTime": "string", "endTime": "string", "active": true } ], "isInherited": true, "inheritToChildren": true, "parentItemId": 0, "sourceLocationId": 0, "overriddenFields": [ "string" ], "allowedOverrides": [ "string" ], "inheritanceUpdatedAt": "2019-08-24T14:15:22Z", "isPosSynced": true, "posOverriddenFields": [ "string" ], "channelAvailability": { "byChannel": { "KIOSK": true, "POS": true, "ONLINE": true, "TAKEAWAY": true, "WOLT": true, "FOODORA": true, "UBER_EATS": true }, "online": true, "qr": true, "kiosk": true, "pos": true, "wolt": true, "foodora": true, "uberEats": true }, "posIntegration": { "integrationConfigId": 0, "provider": "string", "externalItemId": "string", "isMapped": true } }, "meta": { "requestId": "string", "timestamp": "2019-08-24T14:15:22Z", "executionTimeMs": 0 }}Authorization
ApiKeyAuth API key authentication. Format: karma_live_* or karma_dev_*
In: header
Path Parameters
Inventory item ID
^[0-9]+$Query Parameters
Filter overrides by location ID
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/inventory/string/overrides"{ "status": "success", "data": { "title": null, "description": null, "ingredients": null, "isAvailable": null, "imageUrl": null, "pricingGroupId": "ffc3cac5-6bcf-49c9-b5c9-20079daf92b0", "pricings": null, "ministock": null, "measuredStockAtoms": 0, "ministockCents": null, "ministockEnabled": null, "variantGroupsAdded": [ 0 ], "variantGroupsRemoved": [ 0 ], "printerGroupIds": null }, "meta": { "requestId": "string", "timestamp": "2019-08-24T14:15:22Z", "executionTimeMs": 0 }}Authorization
ApiKeyAuth API key authentication. Format: karma_live_* or karma_dev_*
In: header
Path Parameters
Inventory item ID
^[0-9]+$Query Parameters
Location ID for the override
Request Body
application/json
Fields to override at this location
TypeScript Definitions
Use the request body type in TypeScript.
Fields to override at this location
length <= 255length <= 1000length <= 1000length <= 2048uuid0 <= value <= 10000000 <= value <= 90071992547409910 <= value <= 100000000null inherits stock, false disables it locally, true uses ministock/ministockCents
Variant-group ids to attach on top of the POS-provided links (POS-synced items). Ids must belong to the item's location. null / [] clears.
Variant-group ids to hide from the POS-provided links (POS-synced items). Removed wins over added. null / [] clears.
Prep-group ids that replace the inherited item's assignments at this location. [] assigns no prep group; null resumes inheritance.
items <= 3Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PUT "https://example.com/api/v1/inventory/string/overrides" \ -H "Content-Type: application/json" \ -d '{}'{ "status": "success", "data": { "title": null, "description": null, "ingredients": null, "isAvailable": null, "imageUrl": null, "pricingGroupId": "ffc3cac5-6bcf-49c9-b5c9-20079daf92b0", "pricings": null, "ministock": null, "measuredStockAtoms": 0, "ministockCents": null, "ministockEnabled": null, "variantGroupsAdded": [ 0 ], "variantGroupsRemoved": [ 0 ], "printerGroupIds": null }, "meta": { "requestId": "string", "timestamp": "2019-08-24T14:15:22Z", "executionTimeMs": 0 }}Authorization
ApiKeyAuth API key authentication. Format: karma_live_* or karma_dev_*
In: header
Path Parameters
Inventory item ID
^[0-9]+$Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Action to perform: ACTIVATE to make item available, DEACTIVATE to hide it
Value in
- "ACTIVATE"
- "DEACTIVATE"
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/inventory/string/availability" \ -H "Content-Type: application/json" \ -d '{ "action": "ACTIVATE" }'{ "status": "success", "data": { "itemId": 0, "action": "ACTIVATE", "isAvailable": true }, "meta": { "requestId": "string", "timestamp": "2019-08-24T14:15:22Z", "executionTimeMs": 0 }}Authorization
ApiKeyAuth API key authentication. Format: karma_live_* or karma_dev_*
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
1 <= value1 <= items <= 5001 <= propertiesResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/api/v1/inventory/bulk" \ -H "Content-Type: application/json" \ -d '{ "locationId": 1, "itemIds": [ 1 ], "patch": {} }'{}Authorization
ApiKeyAuth API key authentication. Format: karma_live_* or karma_dev_*
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
1 <= value1 <= items <= 500Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/api/v1/inventory/bulk" \ -H "Content-Type: application/json" \ -d '{ "locationId": 1, "itemIds": [ 1 ] }'{}Authorization
ApiKeyAuth API key authentication. Format: karma_live_* or karma_dev_*
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
1 <= value1 <= items <= 500Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/inventory/bulk-upsert" \ -H "Content-Type: application/json" \ -d '{ "locationId": 1, "items": [ { "title": "string" } ] }'{}Authorization
ApiKeyAuth API key authentication. Format: karma_live_* or karma_dev_*
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
1 <= value1 <= itemsResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/inventory/validate" \ -H "Content-Type: application/json" \ -d '{ "locationId": 1, "items": [ { "itemId": 1 } ] }'{}Authorization
ApiKeyAuth API key authentication. Format: karma_live_* or karma_dev_*
In: header
Query Parameters
1 <= value1 <= value <= 100500 <= value0length <= 2001 <= value1 <= valueResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/price-clusters?locationId=1"{ "status": "success", "data": { "items": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "version": 0, "ownerLocationId": 0, "ownerLocationName": "string", "inherited": true, "entries": [ { "itemId": 0, "itemName": "string", "price": null, "pricingGroupId": "ffc3cac5-6bcf-49c9-b5c9-20079daf92b0", "pricingGroupName": null } ], "locations": [ { "id": 0, "name": "string" } ] } ], "hasMore": true }, "meta": { "requestId": "string", "timestamp": "2019-08-24T14:15:22Z", "executionTimeMs": 0 }}Authorization
ApiKeyAuth API key authentication. Format: karma_live_* or karma_dev_*
In: header
Query Parameters
1 <= value1 <= value <= 100500 <= value0length <= 2001 <= value1 <= valueRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
1 <= length <= 2001 <= value1 <= itemsResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/price-clusters?locationId=1" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "entries": [ { "itemId": 1 } ], "locationIds": [ 1 ] }'{ "status": "success", "data": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "version": 0 }, "meta": { "requestId": "string", "timestamp": "2019-08-24T14:15:22Z", "executionTimeMs": 0 }}Authorization
ApiKeyAuth API key authentication. Format: karma_live_* or karma_dev_*
In: header
Path Parameters
uuidQuery Parameters
1 <= value1 <= value <= 100500 <= value0length <= 2001 <= value1 <= valueResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/api/v1/price-clusters/497f6eca-6276-4993-bfeb-53cbbbba6f08?locationId=1&version=1"{ "status": "success", "data": { "deleted": true }, "meta": { "requestId": "string", "timestamp": "2019-08-24T14:15:22Z", "executionTimeMs": 0 }}Authorization
ApiKeyAuth API key authentication. Format: karma_live_* or karma_dev_*
In: header
Path Parameters
uuidQuery Parameters
1 <= value1 <= value <= 100500 <= value0length <= 2001 <= value1 <= valueRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
1 <= length <= 2001 <= value1 <= itemsResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PUT "https://example.com/api/v1/price-clusters/497f6eca-6276-4993-bfeb-53cbbbba6f08?locationId=1" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "version": 1, "entries": [ { "itemId": 1 } ], "locationIds": [ 1 ] }'{ "status": "success", "data": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "version": 0 }, "meta": { "requestId": "string", "timestamp": "2019-08-24T14:15:22Z", "executionTimeMs": 0 }}Authorization
ApiKeyAuth API key authentication. Format: karma_live_* or karma_dev_*
In: header
Query Parameters
1 <= value1 <= value <= 100500 <= value0length <= 2001 <= value1 <= valueResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/price-clusters/active?locationId=1&itemId=1"{ "status": "success", "data": { "cluster": null }, "meta": { "requestId": "string", "timestamp": "2019-08-24T14:15:22Z", "executionTimeMs": 0 }}Authorization
ApiKeyAuth API key authentication. Format: karma_live_* or karma_dev_*
In: header
Query Parameters
1 <= value1 <= value <= 100500 <= value0length <= 2001 <= value1 <= valueResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/price-clusters/descendants?locationId=1"{ "status": "success", "data": { "items": [ { "id": 0, "name": "string" } ], "hasMore": true }, "meta": { "requestId": "string", "timestamp": "2019-08-24T14:15:22Z", "executionTimeMs": 0 }}Authorization
ApiKeyAuth API key authentication. Format: karma_live_* or karma_dev_*
In: header
Query Parameters
1 <= value1 <= value <= 100500 <= value0length <= 200Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/prices?locationId=1"{ "status": "success", "data": { "items": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "locationId": 0, "locationName": "string", "inherited": true, "inheritToChildren": true, "version": 0, "itemCount": 0, "overrideCount": 0, "pricings": [ { "id": "string", "name": "BASE", "price": 0, "order": 0, "metadata": null, "scheduleId": "b7b4f318-018f-4d71-ac1a-f61e4bfaefbe", "channelTypes": null, "validFrom": null, "validTo": null } ] } ], "hasMore": true }, "meta": { "requestId": "string", "timestamp": "2019-08-24T14:15:22Z", "executionTimeMs": 0 }}Authorization
ApiKeyAuth API key authentication. Format: karma_live_* or karma_dev_*
In: header
Query Parameters
1 <= value1 <= value <= 100500 <= value0length <= 200Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
1 <= length <= 2001 <= value1 <= items <= 100Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/prices?locationId=1" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "inheritToChildren": true, "pricings": [ { "name": "BASE", "price": 0 } ] }'{ "status": "success", "data": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "version": 0 }, "meta": { "requestId": "string", "timestamp": "2019-08-24T14:15:22Z", "executionTimeMs": 0 }}Authorization
ApiKeyAuth API key authentication. Format: karma_live_* or karma_dev_*
In: header
Path Parameters
uuidQuery Parameters
1 <= value1 <= value <= 100500 <= value0length <= 200Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
1 <= length <= 2001 <= value1 <= items <= 100Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PUT "https://example.com/api/v1/prices/497f6eca-6276-4993-bfeb-53cbbbba6f08?locationId=1" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "inheritToChildren": true, "version": 1, "pricings": [ { "name": "BASE", "price": 0 } ] }'{ "status": "success", "data": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "version": 0 }, "meta": { "requestId": "string", "timestamp": "2019-08-24T14:15:22Z", "executionTimeMs": 0 }}