Orders

1. Orders

1.1. Create Order

This method creates an order.

Almost all the fields are optional. In fact the simplest order that can be created only has a status.

Parameters:

{  "ref": "17654321",  "status": "new",  "service_type": "delivery",  "service_type_ref": "WEBSITE-DEL",  "expected_time": "2021-06-24T11:30:00+02:00",  "items": [    {      "product_name": "Margarita",      "sku_name": "Small",      "sku_ref": "MAR-SM",      "price": "9.00 EUR",      "quantity": "2",      "options": [        {          "option_list_name": "Sauce",          "name": "Barbecue",          "ref": "BBQ",          "price": "1.00 EUR",          "quantity": 1        }      ]    },    {      "product_name": "Brownie",      "sku_ref": "BROWN",      "price": "3.00 EUR",      "quantity": "1",      "deal_line": {        "deal_key": "0",        "label": "Dessert"      }    },    {      "product_name": "Coke",      "sku_ref": "COK",      "price": "1.00 EUR",      "quantity": "1",      "deal_line": {        "deal_key": "0",        "label": "Drink"      }    },    {      "product_name": "Wings BBQ",      "sku_ref": "WBBQ",      "price": "4.00 EUR",      "quantity": "1",      "points_used": "5.0"    }  ],  "deals": {    "0": {      "name": "Buy a dessert, get a drink for 1€",      "ref": "FREEDRINK"    }  },  "discounts": [    {      "name": "5€ off your order",      "ref": "5OFF",      "price_off": "5.00 EUR"    }  ],  "charges": [    {      "name": "Delivery < 15 km",      "ref": "DEL",      "price": "1.50 EUR"    }  ],  "payments": [    {      "name": "PayPal",      "ref": "PP",      "amount": "23.50 EUR",      "info": {        "email": "john@doe.com"      }    }  ],  "customer_id": "ve343",  "loyalty_operations": [    {      "ref": "LOY",      "delta": "-5",      "reason": "Points used on order"    }  ]}

1.2. Retrieve Order

Returns an order resource.

All the fields of an order creation request are returned, plus a few more:

Note: total_discrepancy and payment_discrepancy fields are also returned, but these fields are deprecated and their values should not be used.

In addition, each item, charge, payment and discount is returned with a HubRise generated id, which uniquely identifies the resource and can be used to delete it. See Update Order.

{  "id": "5dpm9",  "location_id": "3r4s3-1",  "ref": "17654321",  "private_ref": null,  "status": "in_delivery",  "service_type": "delivery",  "service_type_ref": null,  "created_at": "2021-06-24T17:07:53+02:00",  "created_by": "MyClient",  "channel": "Website",  "connection_name": null,  "expected_time": "2021-06-24T19:07:52+02:00",  "confirmed_time": null,  "customer_notes": null,  "seller_notes": null,  "collection_code": null,  "coupon_codes": [],  "total": "18.90 EUR",  "total_discrepancy": null,  "payment_discrepancy": "0.00 EUR",  "items": [    {      "id": "w6nd4",      "private_ref": null,      "product_name": "Carbonara",      "sku_name": "Large",      "sku_ref": "3",      "price": "11.90 EUR",      "quantity": "1.0",      "subtotal": "11.90 EUR",      "tax_rate": null,      "subset": null,      "customer_notes": null,      "points_earned": null,      "points_used": null,      "options": [],      "deleted": false,      "deal_line": {        "deal_key": "0",        "position": null,        "label": null,        "pricing_effect": null,        "pricing_value": null      }    },    {      "id": "zvme8",      "private_ref": null,      "product_name": "Basil and Pesto",      "sku_name": null,      "sku_ref": "17",      "price": "3.00 EUR",      "quantity": "2.0",      "subtotal": "7.00 EUR",      "tax_rate": null,      "subset": null,      "customer_notes": null,      "points_earned": null,      "points_used": null,      "options": [        {          "option_list_name": "Sauce",          "name": "BBQ",          "ref": "31",          "price": "0.50 EUR",          "quantity": 1        }      ],      "deleted": false    }  ],  "deals": {    "0": {      "name": "30% off on pasta",      "ref": "10"    }  },  "discounts": [    {      "id": "wv281",      "private_ref": null,      "name": "2€ off",      "ref": "45",      "pricing_effect": "price_off",      "pricing_value": "2.00 EUR",      "price_off": "2.00 EUR",      "deleted": false    }  ],  "charges": [    {      "id": "wk843",      "private_ref": null,      "type": "other",      "name": "Courier Service",      "ref": "DEL",      "price": "2.00 EUR",      "tax_rate": null,      "charge_type": "other",      "charge_ref": "DEL",      "charge_price": "2.00 EUR",      "deleted": false    }  ],  "payments": [    {      "id": "w2qq8",      "private_ref": null,      "type": "online",      "name": "Payment by cash",      "ref": "CSH",      "amount": "18.90 EUR",      "info": null,      "deleted": false    }  ],  "customer": {    "id": "wbq93",    "customer_list_id": "1dmy1",    "anonymised": false,    "private_ref": "49751",    "email": "charles.moore@dummy-mail.org",    "first_name": "Charles",    "last_name": "Moore",    "gender": "male",    "birth_date": "1999-01-01",    "company_name": "HubRise",    "phone": "+33123456789",    "phone_access_code": "8888",    "address_1": "1 avenue des Champs Elysées",    "address_2": null,    "postal_code": "75001",    "city": "Paris",    "state": null,    "country": "FR",    "latitude": "48.858951",    "longitude": "2.277021",    "delivery_notes": null,    "sms_marketing": false,    "email_marketing": false,    "nb_orders": 8,    "order_total": "151.20 EUR",    "first_order_date": "2021-06-22T11:04:27+02:00",    "last_order_date": "2021-06-24T17:07:53+02:00",    "loyalty_cards": [],    "custom_fields": {}  },  "delivery": {    "carrier": "Uber Direct",    "carrier_ref": "uber",    "ref": "1Z12345E0291980793",    "status": "pickup_approaching",    "fee": "4.00 EUR",    "estimated_pickup_at": "2021-06-24T19:01:00+02:00",    "estimated_dropoff_at": "2021-06-24T19:07:00+02:00",    "tracking_url": "https://uber.com/track/1Z12345E0291980793",    "driver_name": "John",    "driver_phone": "+33612345678",    "driver_phone_access_code": "1234",    "driver_latitude": "48.856614",    "driver_longitude": "2.3522219"  },  "loyalty_operations": [],  "custom_fields": {}}

1.3. List Orders

Returns the orders of a location or an account.

Orders of a given location:

Orders of any location of the account:

Parameters:

[ {   "id": "5dpm9",   "location_id": "3r4s3-1",   "private_ref": "3345",   "status": "new",   "service_type": "collection",   "service_type_ref": null,   "created_at": "2021-06-24T17:07:53+02:00",   "created_by": "MyClient",   "expected_time": "2021-06-24T19:07:52+02:00",   "confirmed_time": null,   "items": [     ...   ],   ... }, ...]

1.4. Update Order

Updates an order.

The following fields can be updated by sending their new value:

• status
• confirmed_time
• seller_notes
• collection_code
• private_ref
• custom_fields

You can also delete or add elements to the following collections, and set their private ref:

• items
• discounts
• charges
• payments

{  "status": "accepted",  "items": [    {      "id": "xe834v",      "deleted": true    }  ],  "payments": [    {      "name": "Cash",      "ref": "CSH",      "amount": "5.90 EUR"    }  ]}

Further in this section, element will interchangeably refer to an item, a charge, a payment, or a discount.

Delete elements

To delete an element, pass the id field along with "deleted": true. No other fields should be included.

Deleted elements are still present in the order representation, but they are irreversibly marked as deleted. Their deleted field cannot be reverted to false.

{  "items": [    {      "id": "xe834v",      "deleted": true    }  ]}

{  "id": "5dpm9",  "location_id": "3r4s3-1",  "private_ref": "3345",  "status": "new",  ...  "items": [    {      "id": "xe834v",      "private_ref": null,      "product_name": "Carbonara",      "sku_name": null,      "sku_ref": "81502",      "price": "11.90 EUR",      "quantity": "1.0",      "subtotal": "11.90 EUR",      "tax_rate": null,      "subset": null,      "customer_notes": null,      "points_earned": null,      "points_used": null,      "options": [],      "deleted": true    }  ],  ...}

Add elements

To add elements to an existing order, simply include their JSON representation in the request.

Note that it is not possible to modify an element. Instead, you should delete the element and add a new one.

{  "payments": [    {      "name": "Cash",      "ref": "CSH",      "amount": "5.90 EUR"    },    {      "name": "Online",      "ref": "OL",      "amount": "11.20 EUR"    }  ]}

{  "id": "5dpm9",  "location_id": "3r4s3-1",  "private_ref": "3345",  "status": "new",  ...  "payments": [    {      "id": "zq33y",      "private_ref": null,      "type": "online",      "name": "Cash",      "ref": "CSH",      "amount": "5.90 EUR",      "info": null,      "deleted": false    },    {      "id": "1999d",      "private_ref": null,      "type": "online",      "name": "Online",      "ref": "OL",      "amount": "11.20 EUR",      "info": null,      "deleted": false    }  ],  ...}

Set private refs on elements

It is possible to set a private ref on each element. To do so, pass the id and private_ref fields. No other fields should be included.

Private refs are typically used to map HubRise objects with the client's internal objects. See Private Refs for more information.

{  "items": [    {      "id": "xe834v",      "private_ref": "96"    }  ]}

{  "id": "5dpm9",  "location_id": "3r4s3-1",  "private_ref": "3345",  "status": "new",  ...  "items": [    {      "id": "xe834v",      "private_ref": "96",      "product_name": "Carbonara",      ...    }  ],  ...}

2. Order's Customer

When you create an order, you can attach a customer to it. You usually want to do this, unless no customer identifier is available. An order with no attached customer is called a guest order.

When customers are uniquely identified, we recommend attaching customers to orders. This not only allows tracking of orders placed by a single customer, but it is also a requirement for some POS systems to successfully process orders.

Guest orders can however be useful in a limited number of cases, such as:

• Orders placed on a self ordering kiosk, where no customer identification is usually available.
• Orders placed on an online platform not willing to share unique identifiers for their customers.

Order with an attached customer

There are two ways to create an order with an attached customer:

• By passing customer_id in the order creation request as in the example below. If a customer with this id exists, it is attached to the order, otherwise an error is returned.

{  "status": "new",  "customer_id": "ve343",  "items": [...]}

• By passing customer_list_id and customer_private_ref simultaneously. If a customer with this private ref exists in this customer list, it is attached to the order, otherwise an error is returned.

{  "status": "new",  "customer_list_id": "ag8u4",  "customer_private_ref": "charles@dummy-mail.org",  "items": [...]}

When you retrieve an order using a GET request, you will find the customer fields encoded in a customer object. The customer object contains the customer values at the time of the order creation.

The presence of a id field with a non-null value in the order.customer object indicates that the order is attached to this customer. Conversely, a null value indicates a guest order.

Order with no attached customer (guest order)

To create a guest order, simply omit the customer_id, customer_list_id, and customer_private_ref fields in the order creation request. Doing so "unlocks" a customer object, which you can optionally use to pass customer data relative to this order, as in the following POST /location/orders request:

{  "status": "new",  "customer": {    "first_name": "John",    "last_name": "Doe"  },  "items": [...]}

The following fields are available in the customer object:

• email
• first_name
• last_name
• gender
• birth_date
• company_name
• phone
• phone_access_code
• address_1
• address_2
• postal_code
• city
• state
• country
• latitude
• longitude
• delivery_notes
• sms_marketing
• email_marketing

When you retrieve a guest order, the customer fields passed at creation time are returned in the customer object, along with a few fields computed by HubRise.

3. Order Status

The status of an order. Used in the order's status field.

Here are the possible "normal" values, and their meaning:

These additional statuses can be used in the event of an anomaly:

Orders do not have to go through all steps. The sequence actually depends on the use case. Let's consider two sample scenarios and a possible workflow for each:

Delivery order placed online:

1. new (order placed online)
2. received (received in the POS)
3. accepted (accepted by a store operator)
4. in_delivery
5. completed

Retail order created in the POS:

1. accepted (order placed in the POS)
2. completed

4. Order Items

Example:

{  "product_name": "Margarita",  "sku_name": "Small",  "sku_ref": "MAR-SM",  "price": "9.00 EUR",  "quantity": "2",  "tax_rate": "20.0",  "subset": "Alice",  "customer_notes": "Well cooked",  "points_earned": "1.5",  "points_used": null,  "options": [    {      "option_list_name": "Sauce",      "name": "Barbecue",      "ref": "BBQ",      "price": "1.00 EUR",      "quantity": 1    }  ]}

5. Order Items in a Deal

Order items which are part of a deal include a deal_line field. This field is an object with the following fields:

deal_key associates an order item to a particular order deal. The particular value of a key has no significance and HubRise renumbers the keys to: "0", "1", … When an order is created, every deal_key must have a corresponding entry in the order's deals field or the request will fail.

pricing_effect and pricing_value can be useful in some applications but can generally be omitted. HubRise does not make any computation with these fields.

All the other fields of an order item are the same as in Order Items. For example, an order item in a deal can have options, as in the example below.

Example:

{  "product_name": "Margarita",  "price": "9.00 EUR",  "quantity": "1",  "options": [    {      "option_list_name": "Sauce",      "name": "Barbecue",      "price": "1.00 EUR"    }  ],  "deal_line": {    "deal_key": "0",    "label": "Pizza"  }}

6. Order Options

Example:

{  "option_list_name": "Sauce",  "name": "Barbecue",  "ref": "BBQ",  "price": "1.00 EUR",  "quantity": 1}

A removed option can define a price. In this case, it's the price charged to the customer to remove the option.

7. Order Deal Map

An order deal map associates order items' deal_keys with their corresponding deals names and refs.

Attributes:

Example:

{  "0": {    "name": "Buy a dessert, get a drink for 1€",    "ref": "FREEDRINK"  }}

8. Order Discounts

An order discount is a discount applied to the whole order, as opposed to deals which apply to a set of order items.

Attributes:

Note: the pricing_effect and pricing_value fields are deprecated. They are still present in the API output for backwards compatibility, but their values should be ignored.

Example:

[  {    "name": "5€ off your order",    "ref": "5OFF",    "price_off": "5.00 EUR"  },  {    "name": "30% off your order",    "ref": "30OFF",    "price_off": "7.65 EUR"  }]

9. Order Charges

Order charges increase the price paid by the customer.

Attributes:

Note: the charge_type, charge_price and charge_ref fields are deprecated. They are present in the API for backwards compatibility, but their values should be ignored.

Note: the type field is deprecated and should be ignored in new integrations.

Example:

[  {    "name": "Delivery < 15 km",    "ref": "DEL",    "price": "1.50 EUR"  }]

10. Order Payments

If one or several payments are defined, the sum of the payment amounts should equal the order's total. Otherwise, the difference is stored in the order's payment_discrepancy field.

If payments are omitted, the order should be considered as unpaid.

Attributes:

Note: the type field is deprecated and should be ignored in new integrations.

Example:

[  {    "name": "PayPal",    "ref": "PP",    "amount": "15.00 EUR",    "info": {      "email": "john@doe.com"    }  },  {    "name": "Freebies4me",    "ref": "FBFM",    "amount": "4.50 EUR",    "info": {      "card_id": "648664679312"    }  }]

11. Order Delivery

A delivery can be attached to an order whose service type is delivery. This is used for tracking delivery status, pickup and drop-off times, driver details and other details. For more information about attaching and updating deliveries, see Deliveries.

An order with an attached delivery includes a delivery field. This field contains the same fields as the Delivery resource, except for the driver_latitude and driver_longitude fields.

Attaching or updating a delivery triggers an order.update callback event, which includes the delivery field in its payload.

The driver_latitude and driver_longitude fields are typically updated at a high frequency, but intentionally do not trigger order.update callback events to minimise the number of events for subscribers. To monitor these fields, opt for delivery.update webhooks.

12. Order Loyalty Operations

Loyalty operations are used to add or remove points from a customer's loyalty card(s).

Each operation targets a specific loyalty card, identifiable by its ref. By default, this ref is null.

When performing an operation, if a card with the provided ref already exists, its balance is updated based on the operation. If a name is also supplied and differs from the existing card's name, the card's name is updated to match.

If there is no existing card with the given ref, a new one is created automatically with an initial balance set according to the operation.

Attributes:

Example:

[  {    "ref": "LOY",    "name": "Come back!",    "delta": "3.5",    "reason": "Points earned on order"  }]

13. Tax Rates

A tax_rate can be specified for each order item and order charge.

Tax rate are decimal numbers, representing a percentage of the price. For example, tax_rate="15.5" means that the tax is 15.5% of the price of the item or charge.

Whether prices are tax-inclusive or exclusive is a decision taken at the account level. The chosen convention must then be enforced by all clients connected to the account. As a general rule, you can assume that prices in HubRise are tax-inclusive for accounts situated in markets where consumer prices are tax-inclusive, for example European countries. On the contrary, prices can generally be considered as tax-exclusive in the other markets, for example the U.S.

HubRise does not perform any computation with tax_rate, and does not require this field to be present. If needed, use a default value for items with unspecified tax rates.