Catalog Management

1. Catalogs

Catalogs can be created at account or location level.

Account-level catalogs are accessible by all locations of the account, while location-level catalogs are visible only to the location they belong to. Account-level catalogs are useful when several locations share a common catalog of products.

Catalogs are identified by their name. Catalog names must be unique for any account or location. For instance, two locations can have two different location-level catalogs with the same name. But a location and its holding account cannot have two catalogs with the same name.

1.1. Retrieve Catalog

Request parameters:

The response either contains a location_id (location level catalog) or an account_id (account level catalog) field.

{  "id": "87yu4",  "location_id": "3r4s3-1",  "name": "Web",  "created_at": "2020-06-25T11:43:51+02:00",  "data": {    "variants": [...],    "categories": [...],    "products": [...],    "options_lists": [...],    "deals": [...],    "discounts": [...],    "charges": [...]  }}

1.2. List Catalogs

Return the catalogs a location has access to, including the account-level and location-level catalogs.

Return the account-level catalogs of an account:

Catalogs returned by the location level form of this request can be either location or account level catalogs:

• For retrieval, this makes no practical difference. Both types of catalogs can be handled in the same way since the URL construction scheme is identical, eg: /catalogs/:id.

• For update and delete operations, an account access token is required to modify an account level catalog. A 401 (unauthorized request) error code is returned otherwise.

The data field of the catalogs is not returned by this request. To retrieve the actual content of catalogs, use the /catalogs/:id endpoint for each catalog.

[  {    "id": "87yu4",    "name": "Web",    "created_at": "2020-06-25T11:43:51+02:00"  },  {    "id": "sdm3b",    "name": "Common menu",    "created_at": "2020-05-19T13:23:10+02:00"  }]

1.3. Create Catalog

Creates a new catalog. The products, categories, options, etc. of the catalog can be passed along in the request.

To create a location-level catalog, use this request:

To create an account-level catalog:

Request parameters:

{  "name": "In Store",  "data": {    "categories": [      {        "name": "Cars",        "ref": "1"      },      {        "name": "Electric cars",        "ref": "2",        "parent_ref": "1"      }    ],    "products": [      {        "name": "Tesla model S",        "ref": "TESLA_S",        "category_ref": "2",        "skus": [          {            "ref": "TS_DUAL",            "name": "Dual Motor",            "price": "80000.00 USD",            "option_list_refs": ["TES_COL"]          },          {            "ref": "TS_PLAID",            "name": "Plaid",            "price": "110000.00 USD",            "option_list_refs": ["TES_COL"]          }        ]      }    ],    "option_lists": [      {        "ref": "TES_COL",        "name": "Tesla Color",        "min_selections": 1,        "max_selections": 1,        "options": [          {            "name": "White",            "ref": "COLOR_WHITE"          },          {            "name": "Vantablack",            "ref": "COLOR_VANTABLACK",            "price": "4500.00 USD"          }        ]      }    ]  }}

1.4. Update Catalog

Update a catalog. The request parameters are the same as for the create catalog request.

If the data field is passed, the whole catalog content is cleared and recreated from the passed data.

{  "name": "Crouch End menu",  "data": {    "categories": [...],    "products": [...]  }}

{  "id": "87yu4",  "name": "Crouch End menu",  "created_at": "2020-06-28T18:23:10+02:00",  "data": {    "categories": [...],    "products": [...]  }}

1.5. Delete Catalog

Delete a catalog and all its content (ie categories, products, ...).

2. Variants

A catalog can optionally contain variants. Variants are used in conjunction with:

• PriceOverrides, to define different prices for different channels or locations.
• Restrictions, to restrict items to certain channels or locations.

Each variant has a ref and a name. Refs identify variants in a catalog, whereas names are displayed to the user. Refs should be unique, auto-generated, and stable, and names should be descriptive and customisable.

For a more detailed explanation of variants, read this blog post.

Variant in Catalog Upload

Parameters:

Example:

{  "ref": "1",  "name": "Uber Eats & Deliveroo"}

3. Categories

The categories of a catalog form a tree: categories without a parent_id are the main categories. The other categories are their children, grandchildren, etc. Every product belongs to a category. Deals can also optionally belong to a category.

The tree is sorted. Categories and products are retrieved in the same order as they were uploaded in the catalog creation/update.

3.1. Category in Catalog Upload

Parameters:

Example:

{  "ref": "SPIZ",  "parent_ref": "PIZ",  "name": "Spicy Pizzas",  "description": "Awesome spicy pizzas",  "tags": ["spicy"]}

3.2. Retrieve Category

Example request:

GET /catalogs/87yu4/categories/lsndh

{  "id": "lsndh",  "ref": "SPIZ",  "parent_id": "dadj5",  "name": "Spicy Pizzas",  "description": "Awesome spicy pizzas",  "tags": ["spicy"]}

3.3. List Categories

Return the categories of the catalog. Categories are returned in a deep first traversal order (category 1, then category 1's children, then category 2, then category 2's children, etc.)

Example request:

GET /catalogs/87yu4/categories

[  {    "id": "lsndh",    "ref": null,    "parent_id": "dadj5",    "name": "Cocktails",    "description": "Awesome cocktails",    "tags": ["alcohol"]  },  ...]

4. Products

A product belongs to a category. A product has one or several skus.

4.1. Product in Catalog Upload

Parameters:

Example:

{  "ref": "REG",  "category_ref": "PIZ",  "name": "Regina",  "tags": ["pizza", "vegetarian"],  "image_ids": ["clom9"],  "skus": [    {      "name": "Small",      "ref": "REG-SM",      "price": "10.30 EUR",      "option_list_refs": ["SAUCE", "PIZZA_TOPPINGS"]    }  ]}

4.2. Retrieve Product

Example request:

GET /catalogs/87yu4/products/abg5a

{  "id": "abg5a",  "category_id": "lsndh",  "name": "Margarita",  "skus": [    {      "id": "sb65k",      "name": "Small",      "ref": "MAR-SM",      "price": "9.80 EUR",      "option_list_ids": ["e2sfj"]    },    {      "id": "xps5s",      "name": "Large",      "ref": "MAR-LG",      "price": "16.80 EUR"    }  ]}

4.3. List Products

Retrieve the list of products in the catalog.

Example request:

GET /catalogs/87yu4/products

[  {    "id": "abg5a",    "category_id": "lsndh",    "name": "Margarita"    ...  },  ...]

5. Skus

Skus ("Stock Keeping Unit") is a distinct type of item for sale, such as a product or service, and all attributes associated with the item type that distinguish it from other item types, such as the size.

A product contains one or several skus. A sku is always attached to a product.

5.1. Sku in Catalog Upload

Parameters:

Example:

{  "ref": "MAR-SM",  "name": "Small",  "restrictions": {    "end_time": "13:30"  },  "price": "9.80 EUR",  "price_overrides": [    {      "variant_refs": ["1"],      "price": "12.30 EUR"    }  ],  "option_list_refs": ["SAUCE", "PIZZA_TOPPINGS"],  "tags": ["hidden"]}

5.2. Retrieve Sku

Example request:

GET /catalogs/87yu4/products/abg5a/skus/sb65k

{  "id": "sb65k",  "ref": "MAR-SM",  "name": "Small",  "product_id": "abg5a",  "restrictions": {    "end_time": "13:30"  },  "price": "9.80 EUR",  "price_overrides": [],  "option_list_ids": ["e2sfj"],  "tags": ["hidden"]}

5.3. List Skus

Example request:

GET /catalogs/87yu4/products/abg5a/skus

[  {    "id": "sb65k",    "ref": "MAR-SM",    "name": "Small"    ...  }]

6. Option Lists

An option list can be attached to one or several skus. It has one or several options.

6.1. Option List in Catalog Upload

Parameters:

Example:

{  "ref": "COL",  "name": "Color",  "min_selections": 1,  "max_selections": 1,  "tags": ["style"],  "options": [    {      "name": "Blue",      "ref": "BLU",      "price": "0.00 EUR",      "default": true    },    {      "name": "Red",      "ref": "RED",      "price": "1.00 EUR"    }  ]}

If max_selections is set, no more than max_selections options can have their default field set to true.

The type field is deprecated and should be replaced with min_selections and max_selections. For compatibility purposes, when this field is present, it is mapped to the new fields:

• If type = single, min_selections is set to 1 and max_selections is set to 1.
• If type = multiple, min_selections is set to 0 and max_selections is set to null.

6.2. Retrieve Option List

Retrieve an option list and the possible choices (options).

Example request:

GET /catalogs/87yu4/option_lists/e2sfj

{  "id": "e2sfj",  "ref": "SAU-SM",  "name": "Sauce",  "min_selections": 0,  "max_selections": null,  "type": "multiple",  "options": [    {      "id": "m9d6e",      "name": "BBQ",      "ref": "BBQ",      "price": "2.50 EUR"    },    ...  ]}

6.3. List Option Lists

Example request:

GET /catalogs/87yu4/option_lists

[  {    "id": "e2sfj",    "ref": "SAU-SM",    "name": "Sauce"    ...  },  ...]

7. Options

7.1. Option in Catalog Upload

Parameters:

Example:

{  "name": "Blue",  "ref": "BLU",  "price": "250.00 EUR",  "price_overrides": [    {      "start_date": "2020-08-20",      "price": "280.00 EUR"    }  ],  "default": false}

7.2. Retrieve Option

Example request:

GET /catalogs/87yu4/option_lists/e2sfj/options/m9d6e

{  "id": "m9d6e",  "ref": "BBQ",  "option_list_id": "e2sj3",  "name": "BBQ",  "price": "2.50 EUR"}

7.3. List Options

Example request:

GET /catalogs/87yu4/option_lists/e2sfj/options

[  {    "id": "m9d6e",    "ref": "BBQ",    "option_list_id": "e2sj3",    "name": "BBQ",    "price": "2.50 EUR"  },  ...]

8. Deals

8.1. Deal in Catalog Upload

Parameters:

Example:

{  "ref": "DDRINK",  "name": "Buy a Small Pizza, Get A Coke for 0.50€ (1€ for Coke XXL)",  "restrictions": {    "dow": "123-5--",    "start_time": "07:00",    "end_time": "13:30",    "end_date": "2020-02-02",    "min_order_amount": "20.00 EUR"  },  "tags": ["upselling", "landing-page"],  "lines": [    {      "label": "Pizza",      "skus": [{ "ref": "REG-SM" }, { "ref": "CAL-SM" }],      "pricing_effect": "unchanged"    },    {      "label": "Drink",      "skus": [{ "ref": "COK33" }, { "ref": "COK50", "extra_charge": "0.50 EUR" }],      "pricing_effect": "fixed_price",      "pricing_value": "0.50 EUR"    }  ]}

8.2. Retrieve Deal

Example request:

GET /catalogs/87yu4/deals/zee1f

{  "id": "zee1f",  "ref": "BOGOF",  "name": "Buy a Small Pizza, Get One Free",  "description": "Choose two of our small pizza, the second one is on us! (1€ extra for Calzone)",  "lines": [    {      "skus": [        { "id": "cksp8", "ref": "REG-SM", "extra_charge": null },        { "id": "12c35", "ref": "CAL-SM", "extra_charge": null }      ],      "pricing_effect": "unchanged"    },    {      "skus": [        { "id": "cksp8", "ref": "REG-SM", "extra_charge": null },        { "id": "12c35", "ref": "CAL-SM", "extra_charge": "1.00 EUR" }      ],      "pricing_effect": "free"    }  ]}

8.2. List Deals

Example request:

GET /catalogs/87yu4/deals

[  {    "id": "zee1f",    "ref": "BOGOF",    "name": "Buy a Small Pizza, Get One Free",    "description": "Choose two of our small pizza, the second one is on us! (1€ extra for Calzone)",    "lines": [...]  },  ...]

9. Discounts

A discount is a reduction of the order total price.

9.1. Discount in Catalog Upload

Parameters:

Example:

{  "ref": "25OFF",  "name": "25% off your order",  "restrictions": {    "min_order_amount": "30.00 EUR"  },  "pricing_effect": "percentage_off",  "pricing_value": "25"}

9.2. Retrieve Discount

Example request:

GET /catalogs/87yu4/discounts/av1up

{  "id": "av1up",  "ref": "5OFF",  "name": "5€ off your order",  "restrictions": {    "dow": "123----"  },  "pricing_effect": "price_off",  "pricing_value": "5.00 EUR"}

9.3. List Discounts

Example request:

GET /catalogs/87yu4/discounts

[  {    "id": "av1up",    "ref": "5OFF",    "name": "5€ off your order",    "pricing_effect": "price_off",    "pricing_value": "5.00 EUR"  },  ...]

10. Charges

A charge is an additional fee billed to the customer. Examples of charges include delivery charge and tip.

10.1. Charge in Catalog Upload

Parameters:

Example:

{  "ref": "DEL1",  "name": "Delivery < 15 km",  "type": "delivery",  "price": "1.50 EUR"}

10.2. Retrieve Charge

Parameters:

Example request:

GET /catalogs/87yu4/charges/fjes3

{  "id": "fjes3",  "ref": "DEL1",  "name": "Delivery < 15 km",  "type": "delivery",  "price": "1.50 EUR"}

10.3. List Charges

Retrieve the list of charges in the catalog.

Example request:

GET /catalogs/87yu4/charges

[  {    "id": "fjes3",    "ref": "DEL1",    "name": "Delivery < 15 km",    "type": "delivery",    "price": "1.50 EUR"  },  ...]

11. Restrictions

A restrictions object can be used in Sku, Option, Deal, Discount and Charge resources. It defines a set of conditions for a particular item to be enabled.

Parameters:

All the fields above are optional. Fields with a null value are ignored.

Fields with a string[] type can be empty, in which case the restriction applies to all variants, service types or service type refs. Passing variant_refs: [] is the standard way to disable an item, but keep it in the catalog for future use.

All conditions must be met simultaneously for an item to be available.

Example:

"restrictions": {  "variant_refs": ["2", "3"],  "dow": "123-5--",  "start_time": "07:00",  "end_time": "13:30",  "end_date": "2020-02-02",  "min_order_amount": "20.00 EUR",  "max_per_order": "1"}

12. Price Overrides

A price_overrides is an array of rules that can be used in Skus and Options, to override their price in different contexts.

Each rule defines a price and a set of conditions. The structure of a rule is described below.

Parameters:

All the fields above are optional, except price. Fields with a null value are ignored. Fields with a string[] value must be either omitted or contain at least one value, and they cannot contain duplicate values.

All conditions must be met simultaneously for a rule to match. When one or several rules match, the price of the last matching rule applies. When no rule matches, or when the item has no price overrides, the default price applies.

Example:

"price_overrides": [  {    "variant_refs": ["2", "3"],    "price": "20.00 EUR"  },  {    "end_time": "14:00",    "price": "15.00 EUR"  },]

Assuming the default price is 25.00 EUR:

• If the item is ordered through any channel or location that use variants 1 or 3, the price is 20.00 EUR.
• Additionally, if the item is ordered before 14:00, the price is 15.00 EUR, no matter the variant. Indeed, the second rule overrides the first one.

13. Images

Images can be attached to products and deals, via their image_ids fields.

Images must be uploaded before catalog data, since the images' ids must be passed in the products and deals. Upload sequence is as follows:

1. create an empty catalog: POST /catalogs or reuse an existing catalog
2. upload images: POST /catalogs/:catalog_id/images
3. upload catalog data: PUT /catalogs/:catalog_id

There is no endpoint to delete an image: when an image is left unattached for 30 days in a row, it is automatically removed.

13.1. Create Image

Upload an image.

The Content-Type header must contain the image MIME type (eg image/png).

The image data is passed in the request body.

Image data must not exceed 1 Mb per image. There are no constraints on the image size or resolution, or on the number of images per catalog.

Example request:

POST /catalogs/3ncct/images

Content-Type: image/jpegRequest body: [insert image data]

Response:

{  "id": "zxdxw",  "type": "image/jpeg",  "size": 126934,  "md5": "39857d16289e814484f4229ca40cc2b1",  "seconds_before_removal": 2592000}

13.2. Retrieve Image

Parameters:

Example request:

GET /catalogs/ldof9/images/tsll2

{  "id": "tsll2",  "type": "image/jpeg",  "size": 240330,  "md5": "39857d16289e814484f4229ca40cc2b1",  "seconds_before_removal": 33102}

13.3. Retrieve Image Data

Return the image data. The reply's Content-Type header contains the MIME image type.

Example request:

GET /catalogs/ldof9/images/tsll2/data

Content-Type: image/jpegResponse body: image data

13.4. List Images

Retrieve the list of images in the catalog.

Example request:

GET /catalogs/87yu4/images

[  {    "id": "tsll2",    "type": "image/jpeg",    "size": 240330,    "md5": "39857d16289e814484f4229ca40cc2b1",    "seconds_before_removal": 33102  },  {    "id": "mpsml"    ...  }]

14. Inventories

Inventories keep track of the stock of every sku or option in a catalog, for a particular location.

An inventory is a set of inventory entries. An inventory entry is the stock of a particular sku or option.

An inventory is specific to a particular location. If several locations share the same catalog, each location will have its own inventory.

Inventories cannot be created or deleted. An inventory is automatically associated to each pair of catalog and location, where location has access to catalog.

14.1. Retrieve Inventory

Returns the list of inventory entries of the inventory.

Example request:

GET /catalogs/87yu4/locations/3r4s3-1/inventory

[  {    "sku_id": "ab19d",    "sku_ref": "COKE",    "stock": "3"  },  {    "sku_id": "sb65k",    "sku_ref": "PEPSI",    "stock": "0"  },  {    "option_id": "a8da5",    "option_ref": "EGG",    "stock": "1"  }]

In the above example:

• the sku ab19d has 3 items available
• the sku sb65k is out of stock
• the option a8da5 has 1 item available

The skus and options' refs are also provided for convenience in the reply.

An inventory is an empty set by default. Every sku or option not specified in the inventory set has unlimited supply.

14.2. Update Inventory

Overwrites the inventory. The request body has the same format as the Retrieve inventory response body.

Each entry consists of:

• either a sku_id or option_id key (select by id), or a sku_ref or option_ref key (select by ref)
• and a stock key

stock must be a positive decimal (with up to 3 decimal places). 0 means out of stock. An entry with a null stock is ignored.

A select by id entry affects a single sku or option. A select by ref entry can affect several skus/options at the same time. The latter form provides a convenient way to update an inventory without storing ids.

Example request:

PUT /catalogs/87yu4/location/inventory

[  {    "sku_id": "ab19d",    "stock": "5"  },  {    "option_ref": "EGG",    "stock": "0"  }]

14.3. Patch inventory

Updates a selected set of entries. Leave the other entries unchanged.

The request body has the same format as Update inventory. A null stock indicates that the entry must be removed from the inventory, ie the stock is unlimited.

Unlike the PUT method which returns the full inventory, the PATCH method only returns the modified entries, to keep the response small and useful.

Example request:

If we have the following inventory:

[  {    "sku_id": "ab19d",    "sku_ref": "COKE",    "stock": "3"  },  {    "option_id": "a8da5",    "option_ref": "EGG",    "stock": "1"  }]

And apply this operation:

PATCH /catalogs/87yu4/location/inventory

[  {    "sku_ref": "COKE",    "stock": null  },  {    "sku_id": "a5f4e",    "stock": "2"  }]

The resulting inventory is:

[  {    "option_id": "a8da5",    "option_ref": "EGG",    "stock": "1"  },  {    "sku_id": "a5f4e",    "sku_ref": null,    "stock": "2"  }]

Note that just like in the PUT operation, you can use select by id or select by ref entries in the PATCH operation.