Create / Cancel Order

Your channel integration can use this endpoint to place a new order or process a cancellation of an existing order.

📘

Deliverect will check the 'scope' within the request target URL to ensure your channel is permitted to send orders for the specified customer. The Scope is represented by the {channelname} which will be provided to integrating parties along with their API credentials.

If the channelname used is invalid or does not have access to an account, the request is considered unauthorised.

Order Type

Depending on the format of the order created, the relevant orderType should be sent with one of the following values (as an integer):

TypeInteger Value
pick up1
delivery2
eat in3
"orderType": 1,

Payments

Depending on the method of payment, the relevant payment types should be sent with one of two following values (as an integer):

Payment TypeInteger Value
credit card online0
cash1

Paid/Unpaid Orders

In some ordering platforms, users can checkout without processing a payment. A typical scenario would be for pickup orders where cash will be paid on collection. If allowing for this option at checkout, it is important to set the flag "orderIsAlreadyPaid": false,

Where payment is processed online during checkout, then set this as "orderIsAlreadyPaid": true,

Rebate

A rebate represents any discount where the cost is absorbed by the channel, not the restaurant. The restaurant may want to distinguish these type of discounts clearly in their POS from ones which they absorb the cost of.

Where a rebate applies, it is important that the full payment amount without the deduction of the rebate is specified, as it will be the amount which the restaurant receive.

"payment": {
    "amount": 400,
    "type": 0
    "rebate":100 
  },

📘

Payment format

Payment amounts should be sent as an integer with 2 decimal digits, for example, 5 euros would be sent as 500.

Discounts

Ordering platforms may offer multiple forms of discount e.g. special offers on selected items, % discounts etc

We can support one single overall order discount only and it should be specified as a minus value e.g. "discountTotal": -100

This should only be applied where the restaurant is absorbing the cost of the discount.

The paid 'amount' should factor in any discount deducted from the total payment.

Tips

To send a tip through with an order, there are two possible parameters allowing a channel to distinguish between the intended recipient of tips. i.e

If a tip is intended for the restaurant;

"tip": 500,.

If intended for the driver;

"driverTip": 500,.

Please be aware that not all POS partners will handle this addition to an order, in which case we have a toggle setting to not include these.

Tax exclusive orders

If a store operates in a region such as the United States, where prices are set without tax included i.e tax exclusive your channel should process orders with tax calculations made within a separate "taxes" array. See the format shown in the 'Tax Exclusive Delivery Order' example on the right hand side.

Within the published menu content (See menu update URL) , you will know the tax rate to apply to each item dependant on the order type.

"deliveryTax": 9000,
"takeawayTax": 9000,
"eatInTax": 9000,

You must ensure the following when sending tax exclusive orders;

  • Each item "price" must be sent without tax included

  • The total payment "amount" must include calculated taxes

  • The "taxes" array must be sent detailing the tax amount applied as an integer with 2 decimal digits (It is optional to specify these per tax class e.g. GST, HST etc)

  • Both deliveryCost and serviceCharge must be sent without tax included

  • Both "deliveryCostTax" and "serviceChargeTax" should not be included in the "taxes" array and be sent separately.

The table below outlines the structure for the dicts in taxes, which each describe a tax class.

KeyValue
taxClassIdthe ID corresponding to this tax class as used by Deliverect
namethe display name for this category of taxes, which is how it should be printed on a receipt
totalthe sum of all tax amounts for this category

📘

A note on taxClassIds

We have yet to formalize tax class IDs. In the future, expect menu push requests to include which tax classes (by ID) should be applied to which product(s). For now, we will not use the provided value sent by your channel API.

Testing with Tax Exclusive Accounts

You can check this by going to the Locations page and clicking on the Edit button for the location. Next, activate the Show More toggle. The Tax Exclusive option will be displayed. If it isn't enabled, you can now do so.

Payment Formula

payment total = sum of prices of all products in the order + deliveryCost + serviceCharge + deliveryCostTax + serviceChargeTax + sum of all tax amounts in the taxes array

About estimated pickup time

If you look at the example requests, you'll notice the estimatedPickupTime field. Make sure to fill this in with a valid timestamp in the format used in the example request.

If your channel doesn't use an estimate for the pickup time, the easiest thing to do is to reuse pickupTime, and just send the same value for estimatedPickupTime.

Canceling an order

If your channel supports canceling an order, you can send a cancellation request but this should only be attempted for orders that have not yet been accepted. Once an order has been accepted by the POS, it should no longer be eligible for cancelation.

To cancel an order, use the create order endpoint and specify the same original order details as shown below. Deliverect will then apply the CANCEL (100) status to the order and pass this to the connected POS. At this point, the POS will confirm the cancellation by sending back a status CANCELED (110) (see Update Order Status Webhook on how to receive this, and other statuses from the POS)

To test this out, see the Cancel order example on the right hand side of this page.

{
    "channelOrderId":"channelOrderId",
    "channelOrderDisplayId":"channelDisplayOrderId",
    "channelLinkId":"5e****abc11dec0001****9b",
    "status": 100,
    "cancellationReason": "Customer requests order cancellation"
}

Orders for restaurant 'Self Delivery'

📘

Creating orders for Restaurant Delivery / Dispatch Service

To ensure an order for Delivery is handled by a Dispatch service via Deliverect, you would send; "courier": "restaurant, any other string than "restaurant" can be specified if the channel is handling delivery for the customer.

Package sizes & Transport types

When creating an order, the channel can specify the package sizes and transport types which will be sent using the format below:

"deliveryInfo": {
        "packageSize": "large",
        "transportType": "car"
 }
Package Size NameString ValueDimensionsDescription
SMALLsmall22 x 42 x 45 cmStandard delivery with a Courier on a bicycle or scooter.
LARGElarge30 x 124 x 80 cmDelivery which will require to be delivered via car
EXTRA LARGEextraLargeLarger than 30 x 124 x 80 cmFor large catering orders with many different trays to be delivered requiring a van
Transport Type NameString Valuea
BICYCLEbicycle
CARGOBIKEcargobike
MOTORBIKEmotorbike
MOTORBIKE XLmotorbikexl
CARcar

Request parameters

Parameter

Meaning

channelOrderId

The full unique ID from the delivery channel.

channelOrderDisplayId

The more human-readable ID from the channel (only unique in a certain duration, like a day).

by

When filled in, this field contains information about the subchannel through which the end customer ordered. This can be for example 'app' or 'mobile', 'web', 'unknown', or a third party. This field can be empty.

(courier).deliveryBy

This specifies who is delivering an order. There are only two possible variations
• A channel creating the order can specify their own channel name, if they are handling delivery for the restaurant.
• If the restaurant are arranging their own delivery, "restaurant" needs to be specified here. This is required where delivery of orders is being fulfilled by an integrated 'Dispatch' partner.

❗️

Order Response

All orders sent in a valid format with correct scope applied will receive a 201. This does not indicate the POS has successfully processed the order, you should reference the events sent to your 'Order Status Update' webhook to understand if successful.

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