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 optionalstringThe client internal id for this order. This field is only visible by the client and will typically be used to lookup an order.
statusOrderStatusThe order status
service_type optionalServiceTypeHow the order is delivered/served to the customer.
customer optionalCustomerThe id of the customer who placed the order. See the customer matching rules section.
customer_list_id / customer_private_ref optionalstringIf customer_id is not provided, a combination of customer_list_id and customer_private_ref can be used to identify the customer. See the customer matching rules section.
expected_time optionalTimeThe time the customer is expecting to get his order.
customer_notes optionalstringInformation given by the customer, eg: delivery notes, etc.
total optionalMoneyThe amount paid by the customer.
custom_fields optionalCustomFieldsAdditional data attached to the order.
items optionalOrderItem[]The order items.
deals optionalOrderDeal[]The deals used in this order.
discounts optionalOrderDiscount[]The discounts applied.
charges optionalOrderCharge[]The charges incurred on this order.
payments optionalOrderPayment[]The payment method(s) used.
loyalty_operations optionalOrderLoyaltyOperation[]Add or remove points to the customer loyalty card(s). Can only be used for orders linked to a customer.

Example request:

POST /locations/3r4s3-1/orders

{ "status": "new", "private_ref": "3345", "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 } ], "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": [ { "type": "delivery", "name": "Delivery < 15 km", "ref": "DEL", "price": "1.50 EUR" } ], "payments": [ { "type": "online", "name": "PayPal", "info": { "email": "john@doe.com" }, "ref": "PP", "amount": "23.50 EUR" } ], "loyalty_operations": [ { "name": "", "delta": -5, "reason": "Points used" } ], "total": "23.50 EUR"}

HubRise calculates the order total. If total is passed but not matching HubRise's calculation, the difference is stored in the total_discrepancy field.

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

Example request:

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

{ "id": "5dpm9", "status": "new", "private_ref": "3345", "items": [ { "product_name": "Margarita", "sku_name": "Small", "sku_ref": "MAR-S", "price": "7.80 EUR", "quantity": 2.0, "subtotal": "15.60 EUR" }, ... ], "customer": { "id": "s9Egdk", "private_ref": "charles@gmail.com", "customer_list_id": "ag8u4", "first_name": "Charles" ... }}

The customer object represents the state of the customer at the time of order creation. It is not present if the order was created without a customer attached.

The id, private_ref and customer_list_id fields of this object are returned only if the customer has not been deleted since the order was created.

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_refstringfilter results by private_ref, for instance: private_ref=13456
statusstringfilter results by status, for instance: status=accepted
created_bystringfilter results by client name. For instance, created_by=shopify only returns orders placed through this client
after, beforeTimeafter is inclusive, before is exclusive. For instance, after=2017-07-01T00:00&before=2017-07-02T00:00 returns orders placed on 2017-07-01
customer_idstringreturns the orders placed by a customer, for instance: customer_id=ve343

Example request:

GET /locations/3r4s3-1/orders

[ { "id": "5dpm9", "status": "new", "private_ref": "3345", ... }, ...]

1.4. Update Order

Updates an order. The following fields can be updated:

  • status
  • private_ref
  • customer_notes
  • confirmed_time
Endpoint:
PUT /locations/:location_id/orders/:order_id
Short endpoint:
PUT /location/orders/:order_id (location only)
Access level:
location, account

Example request:

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

{ "status": "accepted"}

2. Order's Customer

A customer can optionally be attached to an order. There are 3 possible cases:

  • customer_id is passed: if a customer with this id exists, the customer is attached to the order. Otherwise an error is returned.
  • customer_list_id and customer_private_ref are passed: if a customer has this private_ref in the customer list, it is attached to the order. Otherwise an error is returned.
  • Otherwise the order is not attached to a customer.

When a customer is attached to an order, all customer fields are copied in the order. If the order is later retrieved using a GET operation, the customer state at the time of the order creation is returned in the customer field.

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 POS. Default status for a new order placed outside of the POS (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 has been rejected by the store
cancelledOrder has been cancelled by the customer
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 example 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
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.
options optionalOrderOption[]Item customization.
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.

Example:

{ "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" } ], "points_earned": 1.0}

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.

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, each deal_key used in an order item must exist in the order's deals field, or the request will fail.

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.
priceMoneyThe option price. The option is free when price is omitted.
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
namestringThe name of the discount
ref optionalstringThe ref that identifies the discount
price_offMoneyThe discount value

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
typestringCan be one of: delivery, payment_fee, tip, tax or other.
namestringThe name of the charge
ref optionalstringThe ref that identifies the charge
priceMoneyThe charge amount

Example:

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

10. Order Payments

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

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

Attributes:

NameTypeDescription
typestringEither online, gift_card or cash
name optionalstringThe name of the payment method
info optionalobjectAdditional info on the payment: transaction id, etc. The content is free and typically depends on the payment method
ref optionalstringIdentifies the payment method
amountMoneyAmount paid with this payment method

Example:

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

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
namestringThe loyalty card name
deltadecimalThe number of points to add to the card balance. Use a negative number to remove points.
reason optionalstringAdditional information on the operation.

Example:

[ { "name": "", "delta": -5, "reason": "Points used" }, { "name": "", "delta": 1.5, "reason": "Points earned" }]