- Developers
- API Reference
- Catalog Management
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
Endpoint: | GET /catalogs/:id |
Access level: | location, account |
Request parameters:
Name | Type | Description |
---|---|---|
hide_data optional | true | If present, return the catalog without the data. |
The response either contains a location_id
(location level catalog) or an account_id
(account level catalog) field.
Example request
GET /catalogs/87yu4
Response:
{ "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.
Endpoint: | GET /locations/:location_id/catalogs |
Short endpoint: | GET /location/catalogs (location only) |
Access level: | location, account |
Return the account-level catalogs of an account:
Endpoint: | GET /accounts/:account_id/catalogs |
Short endpoint: | GET /account/catalogs (account only) |
Access level: | 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.
Example request
GET /locations/3r4s3-1/catalogs
Response:
[ { "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:
Endpoint: | POST /locations/:location_id/catalogs |
Short endpoint: | POST /location/catalogs (location only) |
Access level: | location, account |
To create an account-level catalog:
Endpoint: | POST /accounts/:account_id/catalogs |
Short endpoint: | POST /account/catalogs (account only) |
Access level: | account |
Request parameters:
Name | Type | Description |
---|---|---|
name | string | The name of the catalog. |
data.variants optional | Variant[] | List of variants. |
data.categories optional | Category[] | List of categories. |
data.products optional | Product[] | List of products. |
data.option_lists optional | OptionList[] | List of option lists. |
data.deals optional | Deal[] | List of deals. |
data.discounts optional | Discount[] | List of discounts. |
data.charges optional | Charge[] | List of charges. |
Example request
POST /accounts/3r4s3/catalogs
{ "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.
Endpoint: | PUT /catalogs/:id |
Access level: | account |
Example request
PUT /catalogs/87yu4
{ "name": "Crouch End menu", "data": { "categories": [...], "products": [...] }}
Response:
{ "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, ...).
Endpoint: | DELETE /catalogs/:id |
Access level: | location, account |
Example request
DELETE /catalogs/87yu4
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:
Name | Type | Description |
---|---|---|
ref | string | The ref of the variant. Must be unique among all variants of the catalog. |
name | string | The name of the variant. |
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:
Name | Type | Description |
---|---|---|
ref | string | The unique ref of the category. Must be unique among all categories of the catalog. |
parent_ref optional | string | If not present, the category will be considered as a root category. |
name | string | The name of the category. |
description optional | string | The description of the category. |
tags optional | string[] | List of tags. A tag is a free text used to describe some particular characteristics of a product or a category. |
image_ids optional | string[] | List of image ids attached to the category. |
Example:
{ "ref": "SPIZ", "parent_ref": "PIZ", "name": "Spicy Pizzas", "description": "Awesome spicy pizzas", "tags": ["spicy"]}
3.2. Retrieve Category
Endpoint: | GET /catalogs/:catalog_id/categories/:id |
Access level: | location, account |
Name | Type | Description |
---|---|---|
id | string | The id of the category. |
ref | string | The ref of the category. |
parent_id | string or null | The id of the parent category, or null if the category is a root category. |
name | string | The name of the category. |
description | string or null | The description of the category. |
tags | string[] | List of tags. A tag is a free text used to describe some particular characteristics of a product or a 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.)
Endpoint: | GET /catalogs/:catalog_id/categories |
Access level: | location, account |
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:
Name | Type | Description |
---|---|---|
ref optional | string | The ref of the product. |
category_ref | string | The ref of the parent category. |
name | string | The name of the product. |
description optional | string | The description of the product. |
tags optional | string[] | List of tags. A tag is a free text used to describe some particular characteristics of a product or a category. |
image_ids optional | string[] | List of image ids attached to the product |
skus | Sku[] | List of skus of this product. A product must contain at least one sku. |
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
Endpoint: | GET /catalogs/:catalog_id/products/:id |
Access level: | location, account |
Name | Type | Description |
---|---|---|
id | string | The id of the product. |
ref | string or null | The ref of the product. |
category_id | string | The id of the parent category. |
name | string | The name of the product. |
description | string or null | The description of the product. |
tags | string[] | List of tags. |
image_ids | string[] | List of image ids attached to the product |
skus | Sku[] | List of skus of this 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.
Endpoint: | GET /catalogs/:catalog_id/products |
Access level: | location, account |
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:
Name | Type | Description |
---|---|---|
ref optional | string | The ref of the sku, which will be passed along in orders. |
name optional | string | The name of the sku. Skus belonging to a same product must have unique names. One sku per product can have a null name. |
restrictions optional | Restrictions | An optional set of conditions that must be matched for the sku to be available. |
price | Money | The price of the sku. |
price_overrides | PriceOverrides | Price overrides in different contexts, such as a specific service type. |
option_list_refs optional | string[] | The refs of the option lists this sku is attached to. |
tags optional | string[] | List of tags. |
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
Endpoint: | GET /catalogs/:catalog_id/products/:product_id/skus/:id |
Access level: | location, account |
Name | Type | Description |
---|---|---|
id | string | The id of the sku. |
ref | string or null | The ref of the sku. |
name | string or null | The name of the sku. |
product_id | string | The id of the sku's parent product. |
restrictions | Restrictions | Set of conditions that must be matched for the sku to be available. |
price | Money | The price of the sku. |
price_overrides | PriceOverrides | Price overrides in different contexts. |
option_list_ids | string[] | The ids of the option lists this sku is attached to. |
tags | string[] | List of tags. |
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
Endpoint: | GET /catalogs/:catalog_id/products/:product_id/skus |
Access level: | location, account |
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:
Name | Type | Description |
---|---|---|
ref | string | The ref of the option list. Must be unique among the catalog's option lists. |
name | string | The name of the option list. |
min_selections optional | integer | The minimum number of selected options. Default: 0 . |
max_selections optional | integer or null | The maximum number of selected options. If the value is null , there is no upper limit on the number of selections. Default: null . |
type deprecated optional | string | This field is deprecated. Use min_selections and max_selections instead. |
tags optional | string[] | List of tags. |
options | Option[] | A list of options. An option list must contain at least one option. |
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 to1
andmax_selections
is set to1
. - If
type
=multiple
,min_selections
is set to0
andmax_selections
is set tonull
.
6.2. Retrieve Option List
Retrieve an option list and the possible choices (options).
Endpoint: | GET /catalogs/:catalog_id/option_lists/:id |
Access level: | location, account |
Name | Type | Description |
---|---|---|
id | string | The id of the option list. |
ref | string | The ref of the option list. |
name | string | The name of the option list. |
min_selections | number | The minimum number of selected options. |
max_selections | number or null | The maximum number of selected options. If the value is null , there is no upper limit on the number of selections. |
type deprecated | string | Either single or multiple . This field is deprecated: the min_selections and max_selections fields should be used instead. |
tags | string[] | List of tags. |
options | Option[] | A list of 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
Endpoint: | GET /catalogs/:catalog_id/option_lists |
Access level: | location, account |
Example request:
GET /catalogs/87yu4/option_lists
[ { "id": "e2sfj", "ref": "SAU-SM", "name": "Sauce" ... }, ...]
7. Options
7.1. Option in Catalog Upload
Parameters:
Name | Type | Description |
---|---|---|
ref optional | string | The ref of the option. |
name | string | The name of the option. |
price | Money | The price of the option. Should be set to 0.00 EUR (adjust the currency) if the option is free. |
price_overrides | PriceOverrides | Price overrides in different contexts, such as a specific service type. |
default optional | boolean | Whether this option is on by default. Default is false . |
tags optional | string[] | List of tags. |
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
Endpoint: | GET /catalogs/:catalog_id/option_lists/:option_list_id/options/:id |
Access level: | location, account |
Name | Type | Description |
---|---|---|
id | string | The id of the option. |
ref | string or null | The ref of the option. |
option_list_id | string | The id of the option list. |
name | string | The name of the option. |
price | Money | The price of the option. |
price_overrides | PriceOverrides | Price overrides in different contexts. |
default | boolean | Whether this option is on by default. |
tags | string[] | List of tags. |
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
Endpoint: | GET /catalogs/:catalog_id/option_lists/:option_list_id/options |
Access level: | location, account |
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:
Name | Type | Description |
---|---|---|
ref optional | string | The ref of the deal. |
category_ref optional | string | The category this deal will appear in. |
name | string | The deal name. |
description optional | string | The description of the deal. |
restrictions optional | Restrictions | An optional set of conditions that must be matched for the deal to be available. |
coupon_codes optional | string[] | The coupon codes that trigger this deal. |
tags optional | string[] | List of tags. |
image_ids optional | string[] | List of image ids attached to the deal. |
lines | array | List of deal lines. A deal should contain at least one line, with at least one sku. |
lines.skus | array | The skus eligible for this line. Skus are referenced by their ref . |
lines.skus.ref | string | The ref of the eligible sku. Skus with no ref cannot be included in deals. |
lines.skus.extra_charge optional | Money | An optional extra charge applied when the sku is selected. |
lines.pricing_effect | string | One of: unchanged , fixed_price , price_off , percentage_off . |
lines.pricing_value optional | depends | The presence and value of this field depends on pricing_effect . It is a Money for fixed_price and price_off , a decimal between "0" and "100" for percentage_off , and null for unchanged . |
lines.label optional | string | A label describing the type of skus that can be selected in this line. |
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
Endpoint: | GET /catalogs/:catalog_id/deals/:id |
Access level: | location, account |
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
Endpoint: | GET /catalogs/:catalog_id/deals |
Access level: | location, account |
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:
Name | Type | Description |
---|---|---|
ref optional | string | The ref of the discount. |
name | string | The name of the discount. |
description optional | string | The description of the discount. |
restrictions optional | Restrictions | An optional set of conditions that must be matched for the discount to be available. |
coupon_codes optional | string[] | The coupon codes that trigger the discount. |
pricing_effect | string | One of: price_off , percentage_off . |
pricing_value optional | depends | Depends on pricing_effect . It is a Money for price_off , and a decimal between "0" and "100" for percentage_off . |
image_ids optional | string[] | List of image ids attached to the discount. |
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
Endpoint: | GET /catalogs/:catalog_id/discounts/:id |
Access level: | location, account |
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
Endpoint: | GET /catalogs/:catalog_id/discounts |
Access level: | location, account |
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:
Name | Type | Description |
---|---|---|
ref optional | string | The ref of the charge. |
name | string | The name of the charge. |
type | string | One of: delivery , payment_fee , tip , tax or other . |
price optional | Money | The charge price. Should be omitted if the charge is variable. |
Example:
{ "ref": "DEL1", "name": "Delivery < 15 km", "type": "delivery", "price": "1.50 EUR"}
10.2. Retrieve Charge
Endpoint: | GET /catalogs/:catalog_id/charges/:id |
Access level: | location, account |
Parameters:
Name | Type | Description |
---|---|---|
id | string | The id of the charge. |
ref | string or null | The ref of the charge. |
name | string | The name of the charge. |
type | string | One of: delivery , payment_fee , tip , tax or other . |
price | Money or null | The charge amount, or null for variable amount. |
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.
Endpoint: | GET /catalogs/:catalog_id/charges |
Access level: | location, account |
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:
Name | Type | Description |
---|---|---|
variant_refs optional | string[] | Enabled for the specified variants, identified by their ref. The variants must exist in the catalog. |
dow optional | DOW | Enabled on certain days of the week. |
start_time optional | string | Enabled from a certain time of the day. Format: HH:MM . |
end_time optional | string | Enabled until a certain time of the day. Format: HH:MM . |
start_date optional | Date | Enabled from a certain date. |
end_date optional | Date | Enabled until a certain date. |
service_types deprecated optional | string[] | Enabled for the specified service types. One or several values among: delivery , collection or eat_in . This field is deprecated, variant_refs should be used instead. |
service_type_refs deprecated optional | string[] | Enabled for the specified service type refs. This field is deprecated, variant_refs should be used instead. |
min_order_amount optional | Money | Enabled for order equal or greater than. |
max_per_order optional | decimal | Max number of items per order. |
max_per_customer optional | decimal | Max number of items per customer. |
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:
Name | Type | Description |
---|---|---|
variant_refs optional | string[] | Applies to the specified variants, identified by their ref. The variants must exist in the catalog. |
dow optional | DOW | Applies on certain days of the week. |
start_time optional | string | Applies from a certain time of the day. Format: HH:MM . |
end_time optional | string | Applies until a certain time of the day. Format: HH:MM . |
start_date optional | Date | Applies from a certain date. |
end_date optional | Date | Applies until a certain date. |
service_types deprecated optional | string[] | Applies for the specified service types. One or several values among: delivery , collection or eat_in . This field is deprecated, variant_refs should be used instead. |
service_type_refs deprecated optional | string[] | Applies for orders using one of the specified service type refs. This field is deprecated, variant_refs should be used instead. |
price | Money | The new price if the rule matches. |
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
or3
, the price is20.00 EUR
. - Additionally, if the item is ordered before
14:00
, the price is15.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' id
s must be passed in the products and deals. Upload sequence is as follows:
- create an empty catalog:
POST /catalogs
or reuse an existing catalog - upload images:
POST /catalogs/:catalog_id/images
- 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.
Endpoint: | POST /catalogs/:catalog_id/images |
Access level: | location, account |
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
Endpoint: | GET /catalogs/:catalog_id/images/:id |
Access level: | location, account |
Parameters:
Name | Type | Description |
---|---|---|
id | string | The id of the image. |
type | string | The MIME type of the image. Example values: image/jpeg , image/png . |
size | integer | Image size in bytes. |
md5 | string | MD5-hash of the image data. |
seconds_before_removal | integer | Time left before this image is removed. For unattached images only. This field is null if the image is attached to at least one product or deal. |
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.
Endpoint: | GET /catalogs/:catalog_id/images/:id/data |
Access level: | location, account |
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.
Endpoint: | GET /catalogs/:catalog_id/images |
Access level: | location, account |
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.
Endpoint: | GET /catalogs/:id/locations/:id/inventory |
Short endpoint: | GET /catalogs/:id/location/inventory (location only) |
Access level: | location, account |
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' ref
s 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
oroption_id
key (select by id), or asku_ref
oroption_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.
Endpoint: | PUT /catalogs/:id/locations/:id/inventory |
Short endpoint: | PUT /catalogs/:id/location/inventory (location only) |
Access level: | location, account |
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.
Endpoint: | PATCH /catalogs/:id/locations/:id/inventory |
Short endpoint: | PATCH /catalogs/:id/location/inventory (location only) |
Access level: | location, account |
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.