Catalogs

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.

There is no individual endpoint to update a particular item of the catalog (eg. a SKU or an option). To update a single item, you must use this endpoint and pass the whole catalog content.

{  "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 the Catalog Variants 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:

Barcodes

Each SKU may be associated with multiple barcodes. This is useful for products sourced from different suppliers, each assigning a unique barcode, or for products that carry multiple types of identifiers.

Applications that support only one barcode will typically use the first listed.

Each barcode must be a numeric string comprising exactly 8, 12, or 13 digits. Example formats that meet these requirements include EAN-8, GTIN-12, EAN-13, ISBN-13, ISSN-13.

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"],  "barcodes": ["1234567890123", "1234567890124"]}

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:

{  "ref": "BLU",  "name": "Blue",  "restrictions": {    "variant_refs": ["1"]  },  "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 set to [], in which case the item is disabled for all variants (or service types, or service type refs).

The service_types and service_type_refs fields have been deprecated in favor of variant_refs. Catalog variants are more flexible, as they can represent arbitrary conditions. The variant to use for a particular order type is configured in the application using the catalog.

All conditions must be met simultaneously for an item to be available. In particular, setting enabled to false disables the item regardless of the other conditions.

Example:

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

The item is only enabled for variants with refs 2 and 3, on Monday and Friday, from 7:00 to 13:30, until February 2nd 2020, for orders equal or greater than 20.00 EUR, and with a maximum of 1 item per order.

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 the conditions under which this price applies. The structure of a rule is described below.

Parameters:

The price field is mandatory. All the other fields are optional, but at least one of them must be set.

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.

The service_types and service_type_refs fields have been deprecated. See Restrictions for more details.

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"  },]

• If the item is ordered through any channel or location that use variants 2 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; the second rule overrides the first one.

13. Images

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

Image Management

Images must be uploaded before catalog data. The sequence is:

1. If you are not reusing a catalog, create an empty one first: POST /catalogs.
2. Upload all images: POST /catalogs/:catalog_id/images and retain their ids for the following step.
3. Upload the catalog: PUT /catalogs/:catalog_id, using the image ids.

If you are updating an existing catalog, you should only upload new images to reduce the amount of data to be sent. Follow this sequence:

1. Fetch the existing images: GET /catalogs/:catalog_id/images. This request returns the ids and md5 hashes of the existing images.
2. Determine which images are new, either by id or by calculating the md5 hash of each image to upload.
3. Upload the new images: POST /catalogs/:catalog_id/images and retain their ids.
4. Update the catalog: PUT /catalogs/:catalog_id, using the existing and new image ids.

There is no endpoint to delete an image. Images that are not used for 30 days are automatically removed.

13.1. Create Image

Upload an image to a catalog.

The Content-Type header must contain the image MIME type, for example: image/png. The image data must be sent in the request body.

HubRise supports the following image formats: JPEG, PNG, WEBP, GIF, and BMP. Image data must not exceed 1 Mb per image.

HubRise does not impose any restrictions on image dimensions. However, we recommend using images in 1200x800 format or larger to ensure a good quality across all channels.

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 SKUs and options at a specific location.

An inventory consists of multiple inventory entries. An inventory entry represents the stock of a specific SKU or option.

Inventories are specific to locations. If multiple locations share the same catalog, each location will have its own separate inventory.

Inventories cannot be created or deleted. They are inherently associated with each location.

14.1. Retrieve Inventory

Returns the inventory of SKUs and options in the specified catalog.

Example request:

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

[  {    "sku_ref": "COKE",    "stock": "3",    "expires_at": null  },  {    "sku_ref": "PEPSI",    "stock": "0",    "expires_at": "2020-08-05T08:00:00+02:00"  },  {    "option_ref": "EGG",    "stock": "1",    "expires_at": null  }]

In the above example:

• The sku with the ref COKE has 3 items available.
• The sku with the ref PEPSI is out of stock and will be available again at the specified date.
• The option with the ref EGG has 1 item available.

Inventories are empty by default. SKUs or options not specified in the inventory are considered to have an unlimited supply.

14.2. Update Inventory

Overwrites the inventory, for SKUs and options in the specified catalog.

This operation will reset inventory entries for any SKUs or options in the catalog not included in the request. Items with ref codes outside the catalog will not be affected.

The request body has the same format as the Retrieve Inventory response. Each entry in the request should include:

• A sku_ref or an option_ref key.
• A stock key indicating quantity. The value should be a positive decimal, with up to 3 decimal places. A value of 0 means out of stock. Entries with a value of null are ignored.
• An optional expires_at key, only available if stock is 0, indicating the date at which the item will be available again.

Example request:

PUT /catalogs/87yu4/location/inventory

[  {    "sku_ref": "COKE",    "stock": "5"  },  {    "option_ref": "EGG",    "stock": "0",    "expires_at": "2020-08-05T08:00:00+02:00"  }]

Clients listening to the inventory.patch callback will receive a notification each time an entry expires. If multiple entries expire at the same time, a single notification will be sent with all the expired entries.

14.3. Patch Inventory

Updates a selected set of entries, while leaving the other entries unchanged.

Similar to the PUT method, this request can only alter the stock of SKUs and options whose ref codes exist in the catalog referenced in the endpoint.

The request body has the same format as Update Inventory. A stock value of null means that the entry should be removed from the inventory, signifying that the stock is unlimited.

The response returns only the modified entries for brevity and utility.

Example request:

Given the existing inventory:

[  {    "sku_ref": "COKE",    "stock": "3",    "expires_at": null  },  {    "option_ref": "EGG",    "stock": "1",    "expires_at": null  }]

When applying this operation:

PATCH /catalogs/87yu4/location/inventory

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

The updated inventory becomes:

[  {    "sku_ref": "PEPSI",    "stock": "2",    "expires_at": null  },  {    "option_ref": "EGG",    "stock": "1",    "expires_at": null  }]