Conventions and special cases

The HubRise API aims to address multiple markets by carefully avoiding over specialisation.

To cover the edge cases for specific markets, such as the restaurant industry, some partners have started to enforce some rules and conventions. Some of these conventions have spread to other partners, turning them into a de facto standard.

This page attempts to be a comprehensive list of the most widespread conventions used by HubRise partners. The conventions described here are not strictly enforced by the API, but using them in your solution will improve interoperability with other integrated solutions.

General conventions

Tags on products

The following tag can be set at the product level.

For more information on the deposit_cc tag, read our blog post on deposits.

Tags on SKUs

The following tags can be set at the SKU level.

Conventions for restaurants

Tags on products

The following tags can be set at the product level. They apply to every SKU of the product.

Orders custom fields

The following custom fields can be attached to an order:

Typical uses:

• The restaurant.table_name custom field is set by the ordering application when the order is created. It is used by the EPOS to associate the order to a specific table. It can also be used by a payment application to find an order associated with a table.
• The restaurant.staff.[name,id] custom fields are typically set by the EPOS, and used by kitchen display screens and ordering applications.

{  "status": "received",  "items": [    ...  ],  ...,  "custom_fields": {    "restaurant": {      "table_name": "13",      "staff": {        "name": "Michel",        "id": "6a1b8e55-55c7-47fb-8c1b-f39ae2eee4f5"      }    }  }}

Half & half products

Half & half products are a common occurrence in the restaurant industry, especially the pizzeria industry. A half & half product lets customers mix two recipes, and customise each of them separately. Think of a half & half pizza as a normal size pizza split in two halves, each half having its own ingredients.

Orders

The recipe and toppings on each half are passed in 4 option lists: Side 1, Side 2, Toppings 1, and Toppings 2. These names should be treated as reserved words. In particular, they should not be translated when used in the API.

{  ...  "items": [    {      "price": "13.00 GBP",      "quantity": "1",      "product_name": "Half & half",      "sku_name": "14\"",      "sku_ref": null,      "options": [        {          "option_list_name": "Side 1",          "name": "Vesuvio",          "ref": "pa_50555",          "price": "0.00 GBP"        },        {          "option_list_name": "Side 2",          "name": "Caprino",          "ref": "pa_50585",          "price": "0.00 GBP"        },        {          "option_list_name": "Toppings 1",          "name": "Ricotta Cheese",          "ref": "54641",          "price": "1.50 GBP"        },        {          "option_list_name": "Toppings 1",          "name": "Jalapenos",          "ref": "54643",          "price": "1.50 GBP"        },        {          "option_list_name": "Toppings 2",          "name": "Jalapenos",          "ref": "54643",          "price": "1.50 GBP"        }      ]    }  ],  ...}

Catalogs

A half & half product is a product with one or more skus. It has the following features:

• SKU prices are usually zero. The price of the item will come entirely from options, which include the two selected sides.
• 2 mandatory option lists, named Side 1 and Side 2. For each option list, the options are the recipes available on the half. Each option is generally priced half the amount of the full recipe.
• 2 optional option lists, named Toppings 1 and Toppings 2. For each option list, the options are the additions available on the half. They can be priced half the amount of the topping, or the full price of it, depending on restaurant preferences.
• A half_half tag, to identify the product as a half & half. This allows the ordering solution to apply extra half & half pricing logic, and override the sides and toppings prices if needed.

Conventions for delivery

Location custom fields

The following custom field can be set on a location:

Typical uses:

• The EPOS sets the delivery.door_time custom field, and it is used by ordering apps and platforms.

{  "id": "3r4s3-1",  "name": "Paris",  ...,  "custom_fields": {    "delivery": {      "door_time": "35"    }  }}

Orders custom fields

IMPORTANT NOTE: Orders delivery custom fields have been deprecated in favor of the Delivery resource.

The following custom fields can be attached to an order to provide details about the delivery:

Typical workflow:

• An order is placed from an ordering solution.
• The delivery solution is notified about the order, via a webhook. The delivery solution sets the delivery.xxx custom fields.
• The EPOS is informed about the order update via a webhook. It displays delivery.driver_pickup_time for the staff to prepare the order in time, and delivery.driver.first_name and delivery.driver.phone for the staff to reach out to the driver if needed.
• The ordering solution is also informed about the order update, and it displays a link to delivery.tracking_url, so the customer can track their delivery.

{  "status": "received",  "items": [    ...  ],  ...,  "custom_fields": {    "delivery": {      "driver_assigned_time": "2021-03-02T12:31:20+02:00",      "driver_pickup_time": "2021-03-02T12:55:00+02:00",      "tracking_url": "https://delivery-service.com/track/664566410894-dbfqs",      "driver": {        "first_name": "John",        "phone": "+440123456789"      }    }  }}

Conventions for EPOS

Location custom fields

The following custom field can be attached to a location:

Typical uses:

• The epos.push_catalog custom field triggers the EPOS to push its catalog to HubRise when its value changes, applicable for supported EPOS systems. It is recommended to increment this value or set it to 0 the first time.

{  "id": "3r4s3-1",  "name": "Paris",  ...,  "custom_fields": {    "epos": {      "push_catalog": 11    }  }}

Order custom fields

The following custom fields can be attached to an order:

Typical uses:

• The EPOS sets the epos.order_id custom field on order creation. Ordering solutions may use this field to include the order identifier in customer emails or in their back-office.
• When the EPOS rejects an order, it sets the epos.rejection object. This field is visible in the HubRise back-office, and it helps support teams and users troubleshoot an issue.

The rejection cause appears in the HubRise back-office, on the order page, which potentially allows users to troubleshoot the issue. The info object is visible when the user clicks See more information.

{  "status": "rejected",  "items": [    ...  ],  ...,  "custom_fields": {    "epos": {      "order_id": "645433012",      "rejection": {        "cause": "At least one item in this order is not attached to a menu. See [documentation](https://epos.com/info/35346).",        "info": {          "status": "FAILED",          "reason": "Could not add item 117192477640169 (not found)",          "thirdPartyReference": "p81xp|719v7-2|52k399"        }      }    }  }}