HubRise
Sign upLog in
Menu
HubRise
navigate_before
Menu

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.

TagDescription
deal_onlyThe product is only available as part of a deal.
deposit_ccThe product requires a deposit. cc is an amount in cents, e.g. deposit_25. The deposit is charged on top of the item price.

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.

TagDescription
deposit_ccSame as the product tag, but applies to a specific SKU. cc is an amount in cents. When set, it overrides the product tag.

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


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:

Custom fieldEncodingDescription
delivery.driver_assigned_time deprecatedTimeThe time the driver was assigned the delivery.
delivery.driver_pickup_time deprecatedTimeThe time the driver is expected to pick up the delivery.
delivery.tracking_url deprecatedstringURL of the page showing the status of the delivery.
delivery.driver.first_name deprecatedstringDriver's first name.
delivery.driver.phone deprecatedstringDriver's phone number in E.164 format.

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

Custom fieldEncodingDescription
epos.push_catalognumberWhen this value changes, the EPOS pushes its catalog to HubRise. Only works for supported EPOS.

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.
Example of a location with EPOS information
{ "id": "3r4s3-1", "name": "Paris", ..., "custom_fields": { "epos": { "push_catalog": 11 } }}

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, code blocks, and emphasis.
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