Search in documentation
ctrl+4K
Modules
Authentication
Merchant
Catalog
Order
Events
Logistics
Shipping
Review
Financial
Solutions

Fundamentals

Conceptual reference of Catalog API v2.0 objects. For tutorials and calls, see Introduction and Endpoints.

Catalog hierarchy

Catalog
├── Context (DEFAULT, WHITELABEL, INDOOR)
│   ├── Category
│   │   └── Item
│   │       ├── Products (products)
│   │       └── Add-on groups (optionGroups)
│   │           └── Options (options)
Each level has its own status. Price and status can vary per context via contextModifiers.Catalog hierarchy diagram showing the structure from Merchant through Catalogs, Categories, Items, and Complements

Contexts

One catalog serves multiple sales channels. Each channel is a context:
ContextChannel
DEFAULTDelivery
WHITELABELDigital Menu
INDOORDine-in
The same item can have different price, status, and POS code per context. Use contextModifiers to customize values per context instead of duplicating the item.Diagram showing how a single catalog serves multiple contexts

Categories

Categories group items in the menu. The template field defines the type:
  • DEFAULT — Common items (sandwiches, drinks, desserts).
  • PIZZA — Pizza items, with mandatory add-on groups (SIZE, CRUST, EDGE, TOPPING). A store accepts at most one PIZZA category. See Pizza.
Other item types, such as combos, use the DEFAULT template on the item and the add-on structure (optionGroups) to model the required complexity. See Combos.Example of a category with items and how they appear in Delivery and Digital Menu contexts

Items

Item is the product sold to the end customer (X-Burger, Soft drink, Calabresa Pizza).

Item types

typeUseMandatory groups
DEFAULTSimple itemNone
PIZZAPizzaSIZE, CRUST, EDGE, TOPPING
COMBO_V2Combo with up to 3 levels of customizationNone

Main fields

FieldTypeRequiredDescription
idstringYesIdentifier you generate. Use it to reference the item in updates.
typeenumYesDEFAULT, PIZZA, or COMBO_V2.
categoryIdstringYesCategory ID.
statusenumYesAVAILABLE (visible) or UNAVAILABLE (paused).
priceobjectYesObject with value (number) and originalValue (optional).
externalCodestringYesYour POS code. Unique per merchant.

id — Item identifier

The id is an identifier you generate and must follow the UUID v4 standard. It uniquely identifies the item in your system.If you send an id that is not in UUID v4 format, the API will return a 404 error.Examples of valid UUID v4s:
  • 550e8400-e29b-41d4-a716-446655440000
  • 123e4567-e89b-12d3-a456-426614174000

externalCode — Custom POS code

The externalCode is your custom identifier for POS integration. Unlike the id, does not need to follow the UUID pattern — it's an arbitrary string you control. Must be unique within the merchant.Valid examples:
  • BURGER_001, COKE_001, COLDRINK_GROUP
  • xburger-default, frappuccino-large
If you send an item with an externalCode that already exists, the API reuses the item instead of creating another. You can use the externalCode as your POS's primary identifier instead of the id — they are interoperable for synchronization purposes.Item with external code field example

Price

{
  "value": 25.00,
  "originalValue": 30.00
}
  • value — Price charged.
  • originalValue — Original price, used to display discount. Optional.
Item pricing example

Add-ons

Add-ons are choices the customer makes when buying an item (drink, size, sauce). Organize add-ons into groups (optionGroups) that contain options (options).
{
  "optionGroups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "name": "Choose a drink",
      "optionGroupType": "OFFER_UNIT",
      "min": 0,
      "max": 1,
      "optionIds": ["opt-coke"]
    }
  ],
  "options": [
    {
      "id": "opt-coke",
      "productId": "prod-coke",
      "price": {"value": 8.00}
    }
  ]
}
Complement group example showing add-on groups and options

Group types

Every group needs an optionGroupType:
TypeUseExample
OFFER_UNITAdditional sale (cross-sell)Drink in combo
SPECIFICATIONPreparation specificationMeat doneness
INGREDIENTSIngredient modificationWith or without onion
CUTLERYUtensilsFork, knife, napkin
Pizzas use special types SIZE, CRUST, EDGE, and TOPPING. See Pizza.

Mandatory requirements (min and max)

Use min and max in the group to control how many options the customer can choose:
Ruleminmax
Mandatory, 1 choice11
Mandatory, multiple choices23
Optional, 1 choice01
Optional, multiple choices05
Example showing mandatory add-on group requirementsExample showing optional add-on group requirements

contextModifiers

Use contextModifiers to override item or option fields in specific contexts, without duplicating the object:
{
  "item": {
    "id": "item-burger",
    "price": {"value": 25.00},
    "status": "AVAILABLE",
    "contextModifiers": [
      {
        "catalogContext": "WHITELABEL",
        "price": {"value": 28.00},
        "status": "UNAVAILABLE"
      }
    ]
  }
}
Fields accepted in contextModifiers:
  • catalogContext — Affected context (required).
  • price — Price in the context.
  • status — Status in the context.
  • externalCode — POS code in the context.
Contexts not listed inherit values from the root.

Inventory

Inventory limits the sellable quantity of a product. When stock reaches zero, the item becomes UNAVAILABLE automatically. Use inventory for products with limited quantity (e.g., artisanal cake). See Manage Availability.Product quantity served example

Next steps

Was this page helpful?
Rate your experience in the new Developer portal:
On this page
Fundamentals
Catalog hierarchy
Contexts
Categories
Items
Item types
Main fields
id — Item identifier
externalCode — Custom POS code
Price
Add-ons
Group types
Mandatory requirements (min and max)
contextModifiers
Inventory
Next steps
Content read0%