Menu

Order Management

1. Orders

1.1. Create Order

This method creates an order.

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

Endpoint:
POST /locations/:location_id/orders
Short endpoint:
POST /location/orders (location only)
Access level:
location, account

Parameters:

NameTypeDescription
private_ref optionalstringAn optional client internal reference for this order. Must be unique if defined. This field can typically be used to lookup an order. See Private Refs.
statusOrderStatusThe order status.
service_type optionalstringHow the order is delivered/served to the customer. One of: delivery, collection or eat_in.
service_type_ref optionalstringA ref identifying the order type. Order type may depend on how the order was placed, and how it must be delivered or served to the customer.
expected_time optionalTimeThe time the customer is expecting to get his order.
confirmed_time optionalTimeThe time the customer will receive his order.
customer_id optionalstringThe id of the customer who placed the order. Cannot be used together with customer_list_id, customer_private_ref, or customer. For more information, see Order's Customer.
customer_list_id & customer_private_ref optionalstringThe private ref and customer list of the customer who placed the order. Cannot be used together with customer_id or customer. For more information, see Order's Customer.
customer optionalCustomerWhen none of customer_id, customer_list_id, or customer_private_ref are passed, the order is a guest order. In this case, the customer object can include customer details specific to this order. For more information, see Order's Customer.
customer_notes optionalstringInformation provided by the customer about the order.
seller_notes optionalstringInformation or message by the merchant, for example a note to notify the customer that a product has been switched with another.
coupon_codes optionalstring[]The coupon codes used in this order.
collection_code optionalstringAn order reference shared with the customer to ease the processing and collection or delivery of an order. It does not have to be unique.
total optionalMoneyThe amount paid by the customer.
custom_fields optionalCustomFieldsAdditional data attached to the order.
items optionalOrderItem[]The order items.
loyalty_operations optionalOrderLoyaltyOperation[]Add or remove points to the customer loyalty card(s). Can only be used for orders linked to a customer.
charges optionalOrderCharge[]The charges incurred on this order.
payments optionalOrderPayment[]The payment method(s) used.
discounts optionalOrderDiscount[]The discounts applied.
deals optionalOrderDeal[]The deals used in this order.
Example request

POST /locations/3r4s3-1/orders

{ "private_ref": "3345", "status": "new", "service_type": "delivery", "service_type_ref": "WEBSITE-DEL", "expected_time": "2021-06-24T11:30:00+02:00", "customer_id": "ve343", "items": [ { "product_name": "Margarita", "sku_ref": "MAR-SM", "sku_name": "Small", "price": "9.00 EUR", "quantity": "2", "options": [ { "option_list_name": "Sauce", "name": "Barbecue", "ref": "BBQ", "price": "1.00 EUR" } ] }, { "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" } ], "loyalty_operations": [ { "ref": "LOY", "delta": "-5", "reason": "Points used on order" } ], "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" } } ], "discounts": [ { "name": "5€ off your order", "ref": "5OFF", "price_off": "5.00 EUR" } ], "deals": { "0": { "name": "Buy a dessert, get a drink for 1€", "ref": "FREEDRINK" } }}

1.2. Retrieve Order

Returns an order resource.

Endpoint:
GET /locations/:location_id/orders/:order_id
Short endpoint:
GET /location/orders/:order_id (location only)
Access level:
location, account

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

NameTypeDescription
...See the order creation fields.
idstringUnique id of the order, generated by HubRise.
location_idstringThe id of the location where the order was created.
created_atTimeOrder creation time.
created_bystringName of the API client that created the order.
customerCustomerCustomer details at the time of the order creation.
totalMoneyOrder total amount. Calculated by HubRise from items, charges and discounts.

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.

Example request

GET /locations/3r4s3-1/orders/5dpm9

Response:

{ "id": "5dpm9", "location_id": "3r4s3-1", "private_ref": null, "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, "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", "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": {} }, "customer_notes": null, "seller_notes": null, "coupon_codes": [], "collection_code": null, "total": "18.90 EUR", "total_discrepancy": null, "payment_discrepancy": "0.00 EUR", "custom_fields": {}, "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, "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, "customer_notes": null, "points_earned": null, "points_used": null, "options": [ { "option_list_name": "Sauce", "name": "BBQ", "ref": "31", "price": "0.50 EUR" } ], "deleted": false } ], "loyalty_operations": [], "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 } ], "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 } ], "deals": { "0": { "name": "30% off on pasta", "ref": "10" } }}

1.3. List Orders

Returns the orders of a location or an account.

Orders of a given location:

Endpoint:
GET /locations/:location_id/orders
Short endpoint:
GET /location/orders (location only)
Access level:
location, account

Orders of any location of the account:

Endpoint:
GET /accounts/:account_id/orders
Short endpoint:
GET /account/orders (account only)
Access level:
account

Parameters:

NameTypeDescription
private_refstringFilters results by private_ref, for instance: private_ref=13456.
statusstringFilters results by status, for instance: status=accepted.
created_bystringFilters results by client name. For instance, created_by=shopify only returns the orders placed through this client.
after, beforeTimeafter is inclusive, before is exclusive. For instance, after=2020-07-01T00:00&before=2020-07-02T00:00 returns orders placed on 2020-07-01.
customer_idstringReturns the orders placed by a customer, for instance: customer_id=ve343.
Example request

GET /locations/3r4s3-1/orders?customer_id=wbq93

Response:

[ { "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, "customer": { "id": "wbq93", ... }, ... }, ...]

1.4. Update Order

Updates an order.

Endpoint:
PATCH /locations/:location_id/orders/:order_id
Short endpoint:
PATCH /location/orders/:order_id (location only)
Access level:
location, account

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
  • charges
  • payments
  • discounts
Example request

This request changes the order status to accepted, deletes an item, and adds a payment.

PATCH /locations/3r4s3-1/orders/5dpm9

{ "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.

Example request

PATCH /locations/3r4s3-1/orders/5dpm9

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

Response:

{ "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, "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.

Example request

This request adds two payments to the order.

PATCH /locations/3r4s3-1/orders/5dpm9

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

Response:

{ "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.

Example request

This request sets a private ref on an item.

PATCH /locations/3r4s3-1/orders/5dpm9

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

Response:

{ "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 presence of an id field with a non null value in this object indicates that the order is attached to this customer. Conversely, a null value indicates a guest order.

Note that the customer values at the time of the order creation are returned in the customer object when you retrieve the order. The only exception is the custom_fields customer field, whose value at the time of the order retrieval is returned.

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
  • 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:

NameDescription
newOrder placed but not received yet in the EPOS. Default status for a new order placed outside of the EPOS (eg an online order).
receivedOrder which was previously new, but it has later been received by the POS.
acceptedOrder accepted by the store. Default status for an order created from within the POS.
in_preparationOrder is being prepared.
awaiting_shipmentOrder is ready to be shipped.
awaiting_collectionOrder is ready to be collected by the customer.
in_deliveryOrder has been sent out for delivery.
completedOrder successfully delivered to the customer.

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

NameDescription
rejectedOrder could not be transmitted to the store, generally because of a system error.
cancelledOrder has been cancelled by either the customer or the store.
delivery_failedOrder could not be delivered.

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. shipped
  5. completed

Retail order created in the POS:

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

4. Order Items

NameTypeDescription
private_ref optionalstringAn optional private reference for the item. See Private Refs.
product_namestringThe product name.
sku_name optionalstringThe sku name. Typically the product size or color.
sku_ref optionalstringThe ref of the sku.
priceMoneyThe unit price of the sku, without the cost of options.
quantitydecimalThe quantity of items ordered.
subtotal optionalMoneyCalculated by HubRise. It is the sum of the price of the item and its options, multiplied by the quantity.
tax_rate optionaldecimalThe tax rate applied to the item. See Tax Rates.
customer_notes optionalstringInformation provided by the customer about the preparation of the item.
points_earned optionaldecimalLoyalty points earned by the customer. This field is not linked to a particular loyalty card: a loyalty operation must be included in the order to effectively add/remove points to a card.
points_used optionaldecimalLoyalty points used by the customer. Same remark as above.
options optionalOrderOption[]Item customization.
deleted optionalbooleanfalse by default. Setting this field to true marks the resource as irreversibly deleted.

Example:

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

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:

NameTypeDescription
deal_keystringA key in the order's deals object.
label optionalstringContent of the deal line, for instance "Drink".
pricing_effect optionalstringOne of: unchanged, fixed_price, price_off, percentage_off.
pricing_value optionaldependsThe presence and value of this field depends on pricing_effect. It is a Money for fixed_price and price_off, a decimal between "0" and "100" for percentage_off, and null for unchanged.

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.

6. Order Options

NameTypeDescription
option_list_namestringThe name of the list the option belongs to, eg. "Toppings", "Sauce", etc.
namestringThe option name.
ref optionalstringThe optional ref of the option.
price optionalMoneyThe unit price of the option. If omitted the option is free.
removed optionalbooleanWhen this flag is true, the option is removed (for instance, a removed ingredient in a dish).

Example:

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

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

7. Order Deals

An order deal associates an order item's deal_key to a particular deal.

Attributes:

NameTypeDescription
namestringThe name of the deal.
ref optionalstringThe ref that identifies the deal.

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:

NameTypeDescription
private_ref optionalstringAn optional private reference for the discount. See Private Refs.
namestringThe name of the discount.
ref optionalstringThe ref that identifies the discount.
price_offMoneyThe discount value.
deleted optionalbooleanfalse by default. Setting this field to true marks the resource as irreversibly deleted.

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:

NameTypeDescription
private_ref optionalstringAn optional private reference for the charge. See Private Refs.
namestringThe name of the charge.
ref optionalstringThe ref that identifies the charge.
priceMoneyThe charge amount.
tax_rate optionaldecimalThe tax rate applied to the charge. See Tax Rates.
deleted optionalbooleanfalse by default. Setting this field to true marks the resource as irreversibly deleted.

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:

NameTypeDescription
private_ref optionalstringAn optional private reference for the discount. See Private Refs.
name optionalstringThe name of the payment method.
ref optionalstringIdentifies the payment method.
amountMoneyAmount paid with this payment method.
info optionalobjectAdditional info on the payment: transaction id, etc. The content is free and typically depends on the payment method.
deleted optionalbooleanfalse by default. Setting this field to true marks the resource as irreversibly deleted.

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 Loyalty Operations

Add or remove points to a customer's loyalty card(s).

Each operation is linked to a loyalty card, uniquely identified by its name. If a card does not exist with this name, it is created automatically with an initial balance equal to 0.0

Each loyalty operation triggers the automatic recalculation of the loyalty card balance.

Attributes:

NameTypeDescription
ref optionalstringThe loyalty card unique ref. Defaults to null if omitted.
deltadecimalThe number of points to add to the card balance. Use a negative number to remove points.
reason optionalstringAdditional information on the operation.

Example:

[ { "ref": "LOY", "delta": "-5", "reason": "Points used on order" }, { "ref": "LOY", "delta": "1.5", "reason": "Points earned on order" }]

12. 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.