Menu
HubRise

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 categories

TagDescription
hiddenThe category is hidden, but its products are available. Typically used to hide products only available within deals.

Tags on SKUs

The following tag can be set at the SKU level:

TagDescription
deal_onlyThe SKU is only available as part of a deal.

Customer custom fields

The following custom field can be attached to a customer:

Custom fieldEncodingDescription
contact.phone_access_codestringThe access code to reach the customer. Used when the customer's phone is a call center number.
Example of a customer with contact information
{ "first_name": "Charles", "last_name": "Moore", "phone": "+44123456789", "custom_fields": { "contact": { "phone_access_code": "821 645 884" } }}

Conventions for restaurants

Tags on products

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

TagDescription
alcoholicContains alcohol.
spicy_1Midly spicy.
spicy_2Spicy.
spicy_3Very spicy.
gluten_freeContains no gluten.
veganContains no animal product.
vegetarianContains no meat.
no_allergensContains no allergens.
allergen_celeryContains this allergen.
allergen_crustaceansContains this allergen.
allergen_eggsContains this allergen.
allergen_fishContains this allergen.
allergen_glutenContains this allergen.
allergen_lupinContains this allergen.
allergen_milkContains this allergen.
allergen_molluscsContains this allergen.
allergen_mustardContains this allergen.
allergen_nutsContains this allergen.
allergen_peanutsContains this allergen.
allergen_sesame_seedsContains this allergen.
allergen_soybeansContains this allergen.
allergen_sulphur_dioxide_sulphitesContains this allergen.
half_halfHalf & half product. See Half & half products.

Orders custom fields

The following custom fields can be attached to an order:

Custom fieldEncodingDescription
restaurant.table_namestringA unique identifier of the table.
restaurant.staff.namestringThe name of the employee looking after the order.
restaurant.staff.idstringThe id of the employee.

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.
Example of an order with restaurant information
{ "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.

Example of half & half pizza in an online ordering solution

Half & half pizza in an online ordering solution

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.

Example of an order containing a H&H item
{ ... "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:

Custom fieldEncodingDescription
delivery.door_timedecimalMinimum time in minutes between order creation and customer door.

Typical uses:

  • The EPOS sets the delivery.door_time custom field, and it is used by ordering apps and platforms.
Example of a location with delivery information
{ "id": "3r4s3-1", "name": "Paris", ..., "custom_fields": { "delivery": { "door_time": "35" } }}

Orders custom fields

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

Custom fieldEncodingDescription
delivery.driver_pickup_timestringThe time in ISO 8601 format format when the driver is expected to pick up the delivery.
delivery.tracking_urlstringURL of the page showing the status of the delivery.
delivery.driver.first_namestringDriver's first name.
delivery.driver.phonestringDriver's phone number in E.164 format.

Typical uses:

  • The delivery solution sets the delivery.driver_pickup_time custom field, and it is displayed in the EPOS for the staff to prepare the order in time.
  • The delivery solution sets the delivery.driver.first_name and delivery.driver.phone custom fields, and they are displayed in the EPOS to provide the staff with a convenient way to reach out to the driver.
  • The delivery solution sets the delivery.tracking_url custom fields, and it is displayed in the ordering application for customers to track their delivery.
Example of an order with delivery information
{ "status": "received", "items": [ ... ], ..., "custom_fields": { "delivery": { "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

Order custom fields

The following custom fields can be attached to an order:

Custom fieldEncodingDescription
epos.order_idstringOrder identifier on the EPOS.
epos.rejection(see below)Information about an order rejection. Can only be present if the order status is rejected.
epos.rejection.causestringShort description of the problem. Ideally includes resolution steps. Use Markdown syntax for links.
epos.rejection.infoobjectFree-format JSON object containing information about the problem.

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.

The EPOS rejected the order

Example of an order with EPOS 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" } } } }}
Feedback on this page