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:

Name	Type	Description
`private_ref` optional	string	An 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.
`status`	OrderStatus	The order status.
`service_type` optional	string	How the order is delivered/served to the customer. One of: `delivery`, `collection` or `eat_in`.
`service_type_ref` optional	string	A 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` optional	Time	The time the customer is expecting to get his order.
`confirmed_time` optional	Time	The time the customer will receive his order.
`customer_notes` optional	string	Information provided by the customer about the order.
`seller_notes` optional	string	Information or message by the merchant, for example a note to notify the customer that a product has been switched with another.
`collection_code` optional	string	An order reference shared with the customer to ease the processing and collection or delivery of an order. It does not have to be unique.
`coupon_codes` optional	string[]	The coupon codes used in this order.
`items` optional	OrderItem[]	The order items.
`deals` optional	OrderDeal[]	The deals used in this order.
`discounts` optional	OrderDiscount[]	The discounts applied.
`charges` optional	OrderCharge[]	The charges incurred on this order.
`payments` optional	OrderPayment[]	The payment method(s) used.
`customer_id` optional	string	The 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` optional	string	The 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` optional	Customer	When 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.
`loyalty_operations` optional	OrderLoyaltyOperation[]	Add or remove points to the customer loyalty card(s). Can only be used for orders linked to a customer.
`custom_fields` optional	CustomFields	Additional data attached to the 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",  "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.

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:

Name	Type	Description
...		See the order creation fields.
`id`	string	Unique id of the order, generated by HubRise.
`location_id`	string	The id of the location where the order was created.
`created_at`	Time	Order creation time.
`created_by`	string	Name of the API client that created the order.
`total`	Money	Order total amount. Calculated by HubRise from items, charges and discounts.
`customer`	Customer	Customer details at the time of the order creation.

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_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,      "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",          "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": {}  },  "loyalty_operations": [],  "custom_fields": {}}

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:

Name	Type	Description
`private_ref`	string	Filters orders by `private_ref`, for instance: `private_ref=13456`.
`status`	string	Filters orders by `status`, for instance: `status=accepted`.
`created_by`	string	Filters orders by client name. For instance, `created_by=shopify` only returns the orders placed through this client.
`after, before`	Time	Filters orders by creation time. `after` is inclusive, `before` is exclusive. For instance, `after=2020-07-01T00:00:00+02:00&before=2020-07-02T00:00:00+02:00` returns orders placed on 2020-07-01.
`customer_id`	string	Returns 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,   "items": [     ...   ],   ... }, ...]

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
discounts
charges
payments

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

Name	Description
`new`	Order placed but not received yet in the EPOS. Default status for a new order placed outside of the EPOS (eg an online order).
`received`	Order which was previously new, but it has later been received by the POS.
`accepted`	Order accepted by the store. Default status for an order created from within the POS.
`in_preparation`	Order is being prepared.
`awaiting_shipment`	Order is ready to be shipped.
`awaiting_collection`	Order is ready to be collected by the customer.
`in_delivery`	Order has been sent out for delivery.
`completed`	Order successfully delivered to the customer.

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

Name	Description
`rejected`	Order could not be transmitted to the store, generally because of a system error.
`cancelled`	Order has been cancelled by either the customer or the store.
`delivery_failed`	Order 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:

new (order placed online)
received (received in the POS)
accepted (accepted by a store operator)
in_delivery
completed

Retail order created in the POS:

accepted (order placed in the POS)
completed

4. Order Items

Name	Type	Description
`private_ref` optional	string	An optional private reference for the item. See Private Refs.
`product_name`	string	The product name.
`sku_name` optional	string	The sku name. Typically the product size or color.
`sku_ref` optional	string	The ref of the sku.
`price`	Money	The unit price of the sku, without the cost of options.
`quantity`	decimal	The quantity of items ordered.
`subtotal` optional	Money	Calculated by HubRise. It is the sum of the price of the item and its options, multiplied by the quantity.
`tax_rate` optional	decimal	The tax rate applied to the item. See Tax Rates.
`customer_notes` optional	string	Information provided by the customer about the preparation of the item.
`points_earned` optional	decimal	Loyalty 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` optional	decimal	Loyalty points used by the customer. Same remark as above.
`options` optional	OrderOption[]	Item customization.
`deleted` optional	boolean	`false` 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",      "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:

Name	Type	Description
`deal_key`	string	A key in the order's `deals` object.
`label` optional	string	Content of the deal line, for instance "Drink".
`pricing_effect` optional	string	One of: `unchanged`, `fixed_price`, `price_off`, `percentage_off`.
`pricing_value` optional	depends	The 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

Name	Type	Description
`option_list_name`	string	The name of the list the option belongs to, eg. "Toppings", "Sauce", etc.
`name`	string	The option name.
`ref` optional	string	The optional ref of the option.
`price` optional	Money	The unit price of the option. If omitted the option is free.
`quantity` optional	integer	The number of selections for this option, relative to a single item unit. Default: `1`.
`removed` optional	boolean	When 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",  "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 Deals

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

Attributes:

Name	Type	Description
`name`	string	The name of the deal.
`ref` optional	string	The 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:

Name	Type	Description
`private_ref` optional	string	An optional private reference for the discount. See Private Refs.
`name`	string	The name of the discount.
`ref` optional	string	The ref that identifies the discount.
`price_off`	Money	The discount value.
`deleted` optional	boolean	`false` 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:

Name	Type	Description
`private_ref` optional	string	An optional private reference for the charge. See Private Refs.
`name`	string	The name of the charge.
`ref` optional	string	The ref that identifies the charge.
`price`	Money	The charge amount.
`tax_rate` optional	decimal	The tax rate applied to the charge. See Tax Rates.
`deleted` optional	boolean	`false` 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:

Name	Type	Description
`private_ref` optional	string	An optional private reference for the discount. See Private Refs.
`name` optional	string	The name of the payment method.
`ref` optional	string	Identifies the payment method.
`amount`	Money	Amount paid with this payment method.
`info` optional	object	Additional info on the payment: transaction id, etc. The content is free and typically depends on the payment method.
`deleted` optional	boolean	`false` 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:

Name	Type	Description
`ref` optional	string	The loyalty card unique ref. Defaults to `null` if omitted.
`delta`	decimal	The number of points to add to the card balance. Use a negative number to remove points.
`reason` optional	string	Additional 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.

Feedback on this page

Order Management

1. Orders

1.1. Create Order

Parameters:

1.2. Retrieve Order

Response:

1.3. List Orders

Parameters:

Response:

1.4. Update Order

Delete elements

Response:

Add elements

Response:

Set private refs on elements

Response:

2. Order's Customer

Order with an attached customer

Order with no attached customer (guest order)

3. Order Status

Delivery order placed online:

Retail order created in the POS:

4. Order Items

Example:

5. Order Items in a Deal

6. Order Options

Example:

7. Order Deals

Attributes:

Example:

8. Order Discounts

Attributes:

Example:

9. Order Charges

Attributes:

Example:

10. Order Payments

Attributes:

Example:

11. Order Loyalty Operations

Attributes:

Example:

12. Tax Rates

API Reference

API Reference