The 'Source of Truth' in terms of product data and structure is almost always sourced from an integrated POS system. When a POS successfully syncs products with their unique identifiers (PLUs), these will be selected by the customer for inclusion in their menu(s).

In turn, orders will be created with these same PLUs and injected into the POS via an 'Order Webhook'

This process does not necessarily need a complete transfer of products stored in the POS, but can involve only a subset of products i.e. 'Online Only products' which a customer can possibly flag as being suitable for selling online.

📘

Menus vs Products

We do expect products to be sourced from a POS, but don't have a facility to push structured menus built within a POS into Deliverect.

This process of 'Menu Building' is fully handled in Deliverect (see guide on this here)

Price

Price is stored as an int with 2 decimal digits, for example, 5 euros is stored as 500.

Price Levels

Price levels allow having a single menu with different prices per channel and delivery type. The products have a base price field and can define optional prices in their priceLevels section, as pairs of a PriceLevel identifier and a price.

The price levels are defined during the product sync in the priceLevels section with an identifier posId and a descriptive name name.

After syncing products on a location at least once, a price level can be selected in the channel link settings. When previewing or pushing menus for these channel links, the selected price level is applied.

{
    "name": "Burger",
    "price": 1000,
    "priceLevels": {
        "B1": 1000,
        "D1":  900,
        "BD2020":  500
    }
}
{
    "name": "Burger Deal 2020",
    "posId": "BD2020"
}

📘

Note that when no data is available on a product for the selected price level, the base price is applied.

Overloads

Certain product structures could contain overloads. On the example 4 and 5 a modifier and a product can have different prices depending on which grouping it belongs to. e. This is determined by the "scope" of the modifier group.

On the example, the modifier group's name is "Choose Your First Topping with PLU "FREE-TOP". Inside each of the modifiers, such as "Pepperoni" an array Overloads should be included specifying the scope that applies on each case.

Tax

When syncing products to Deliverect, it is important to specify the sales tax rate which applies. The sales tax which applies can be differentiated between the order types of;

  • Delivery (deliveryTax)
  • Takeaway (takeawayTax)
  • Eat-in (eatInTax)

Tax rates are always stored as an int with 3 decimal digits e.g. 5% would be stored as 5000

It's acceptable to have products which have 0% tax, and even a 0 price.

{
  "productType": 1,
  "plu": "GB-02",
  "name": "Ginger Beer",
...
  "deliveryTax": 5000,
  "takeawayTax": 5000,
  "eatInTax": 5000,

🚧

Price format

Make sure the values of product price, tax and price level are sent as integers and not floats.

PLU

The PLU is typically something that's easier for the customer to use, and it should be the same across all locations for the same product. The PLU is what will be used for mapping orders coming from the channels. It is therefore mandatory and shouldn't exceed 36 chars.

📘

deliveryTax and takeawayTax

The above sales taxes are not the same as deliveryCostTax or serviceChargeTax which are seperate taxes applied by an ordering channel to the cost of delivery or service charge

Images

The image URL you provide here is cached and put behind a CDN. Images are cached on access for 24 hours. Channels will download the images and also cache them. Depending on the channel, images can/will be resized. Deliverect supports images of up to 16.8 megapixels in size.

Overrides

Customers are able to overwrite certain details of products within the menu builder in Deliverect, including;

  • Names
  • Descriptions
  • Prices
  • Images

*Everything that is not overwritten in Deliverect can be updated via a this endpoint

Product types

When pushing products to us, you need to specify the relevant value which represents the product type used

Product Type

Integer Value

Integer Value

Product

A 'top level' item on a menu (can also be grouped within a modifier group or bundle)

1

Modifier

Options selectable when ordering a product, typically modifications of the product

2

Modifier Group

A grouping of modifiers (can also group products)

3

Bundle

Can only contain products which are offered as part of a 'Meal Deal' and which Deliverect will set to zero value

4

Categories

A category is a way to organise products into a section to be referenced when building a menu. Products can be in one or more categories denoted by an array of posCategoryIds. It's important to have at least one category per product.

Deleting products

There is currently no way to directly delete a product. To achieve the desired effect, a list of products can be pushed again, in which products "to be deleted" are omitted.

Duplicate products

When you push products, make sure there are no duplicate PLUs. If there are duplicate PLUs, the product will still go through, but the duplicate products will be emitted.

Example: Basic Example

The first example on the right, consists of a simple Product, Delicious Steak, with two modifiers attached. It corresponds to the following structure:

It also contains examples with the following structures:

  • min and max values: allow setting up a minimum and maximum value for a modifier.
  • multiMax: allows setting up a quantity to choose more than once the same modifier.
  • defaultQuantity: makes a modifier preselected by default.

Regarding the first modifier group, 'Cooking Instructions' , the customer is required to choose one option. This is done by setting min and max to a value of 1.

The second modifier group, 'Choose Your Side' has a max value of 2, which allows selecting up to two options. The Fries modifier will be selected by default, this is done using "defaultQuantity": 1. Besides, this modifier group also contains the value "multiMax": 2. For instance, the modifier Fries or any other attached to this group could be selected twice.

Example: Meal Deals

In the payload examples to the right, you can select several examples of sets of products to be sent to Deliverect that form together various types meal deal.

These examples use the following structure, where products are linked together using the subProducts field.

Meal Deal Structure

Combo/Meal Deal:

Bundle:

  • Product Type:1
  • Bundle Type:4
    • Product Type:1
      • Modifier group Type:3
        • Modifier Type:2

There are several request examples of meal deals to the right.

Nested Modifiers

The second example shows you a product with nested modifiers. These are modifiers that are part of a modifier group which is nested within another modifier group. In the specific example, you can select your dish and add a modifier from Rice or Noodles selection. After you do that, you will be asked to choose additional modifiers, like the sate or hot sauce which are nested.

Meal Deal with 'Upsell'

In the Meal Deal with upsell (example 3) we have a modifier group in addition to the bundles. This allows for Fries to be ordered which are not included as part of the deal and the customer will be charged accordingly. This is referred to as an 'upsell', which can be modifier groups containing products or modifiers.

It is also possible to construct combo products as follows:

  • Combo product Type:1
  • Modifier group Type:3
    • Modifier Type:2
      • Modifier group Type:3
        • Modifier Type:2

Click here to see examples of how orders with these meal deal examples are sent to your POS in an order.

Multi-select modifiers

You can indicate if modifiers in a specified modifier group can be selected more than once.
To do this, have a look at the first basic example . Please refer to the example section in the top right hand corner of the page..

The only difference is that the 'Choose Your Side' modifier group has two fields added: max and multiMax.

The max field gets a value of two. This limits the maximum number of modifiers that can be selected to two. As there are only two modifiers in the group, this in itself wouldn't make much of a difference when modifiers can only be selected once.

Adding multiMax makes it so that modifiers in this modifier group can be selected more than once. Because it has a value of two, each modifier can be selected at most two times.

Because of this, the customer can pick two sides, which can be different or the same kind.

Selected by default

It's possible to set a default quantity for modifiers and meal deal items. With a default quantity of 1, the item is selected by default in the channel menu.

This is shown in the first example (please refer to the example section in the top right hand corner of the page), where the Fries modifier have a value of 1 for "defaultQuantity": 1. Because of this, the Fries modifier will be selected by default.

Auto Apply

There can be a use case where products ordered online should be received with a pre-defined set of sub products applied. This is not the same as items being pre-selected in the menu interface via defaultQuantity, but is a mechanism for specific items to be auto-applied (by Deliverect) following a completed order.

This is shown in the first example (please refer to the example section in the top right hand corner of the page), where the Parsley Garnish and Melted Butter are within a modifier group 'Garnishes' which is set to apply these items automatically when the Steak Frites is ordered.

NB: Neither the channel platform or end-consumer will see these items, and as such there can be no price associated with them. If de-selection of pre-set items or charging for them is a requirement, see instead the above section for Selected by default

"autoApply": [
    {
        "plu": "PR1"
    },
    {
        "plu": "PR2"
    }
],

Product translations

Translations of product names and descriptions can be provided in the JSON. A base name (field name) is always required and translations are optional (field nameTranslations). Translations are supported for all product types.
The translations are passed as a nested JSON object where the property names are language tags and the values are the translations themselves.

Example

{
    "productType": 1,
    "plu": "MEAT-02",
    "price": 200,
    "name": "Chicken",
    "nameTranslations": {
        "ar": "دجاج",
        "en": "Chicken",
        "es": "Pollo",
        "nl": "Kip"
    },  
    "description": "Grilled chicken",
    "descriptionTranslations": {
        "ar": "دجاج مشوي",
        "en": "Grilled chicken.",
        "es": "Pollo asado.",
        "nl": "Gegrilde kip."
    }
}

The language tags are ISO 639-1 language codes. They can be complemented by a lowercase ISO 3166-1 country code.

Example

After defining a BurgerDeal price level on your burgers, sync products and apply the price level to a single (or any) channel to run the BurgerDeal on.

Product visibility

A product can be marked as invisible (disabled) by setting visible property to false. After this action the product will be hidden all menus where it was used and will not be pushed to channels until it marked as visible again.

{
    "productType": 1,
    "plu": "SI-01",
    "price": 100,
    "name": "Fries",
    "visible": false
}

Product tags: consumable types and allergens

A product can have one or more product tags. These are are contained inside productTags. Use this to indicate consumable types and/or allergens.

See a link here for the complete list of allergens with corresponding tag value:

Calories

If POS supports syncing calories this should be sent in the payload as shown in table of attributes below

Parameter

Meaning

calories

This is the base calorie amount, where a maximum calories is set, this should be interpreted as the 'minimum'

caloriesRangeHigh

The maximum calorie amount of an item

posProductId

The posProductId is the internal ID used for products. It is unique across locations but is entirely optional as a reference only.

"products": [
          {
               "productType": 1,
               "plu": "PR03",
               "price": 900,
               "name": "Cheese Lovers Pizza",
               ...
               "calories": 500,
               "caloriesRangeHigh": 750
               },
               ...
               ]
          },

Nutritional Information

You can pass the nutritional information of the products with the payload via the object nutritionalInfo, look at the example below:

📘

The unit of the values is gram.

"nutritionalInfo": {
                "fat": 1,
                "sugar": 4,
                "saturatedFat": 1,
                "carbohydrates": 1,
                "protein": 1,
                "salt": 1
            }

Product sync (GET Products)

The expected application of this endpoint is that it is used in response to a GET Request from Deliverect. See the section on responding to this request here.

Language
Authentication
OAuth2
Click Try It! to start a request and see the response here!