Your channel integration can use this endpoint to place a new order for a linked location.

📘

Deliverect will check the 'scope' within the request target URL to ensure your channel is permitted to send orders for the specified customer. The ScopeScope - This is provided by Deliverect 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 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.

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 Type

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

Type

Integer Value

pick up

1

delivery

2

eat in

3

curbside

4

Payment Types

For payment type, send one of these values:

Payment Type

Integer Value

credit card online

0

cash

1

Payment object

The example below shows the payment amount which is sent as an integer with 2 decimal digits, for example, 5 euros would be sent as 500.

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

Rebate

"Rebate" includes any discounts offered by the channels (not the restaurant). POS may need this information for reporting purposes. The ordering customer needs to pay the amount without the rebate, but the restaurant will receive the total amount from the channel.

Discounts

Ordering platforms may offer multiple forms of discount e.g. special offers on selected items, % discounts, based on the customers' request (restaurant, dark kitchen etc.)

When orders are sent to Deliverect, we can support only overall order discount, as the parameter "discountTotal"

A discount total should be sent through as a minus value representing the deduction from the total order. Please note the paid 'amount' should factor any discount deducted from the total payment.

Tips

It is possible for a tip amount to be passed through with an order as a parameter "tip".

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 is tax exclusive, your channel API should send orders from that store in a slightly different way.

First, make sure that the store is tax exclusive. 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.
This setting determines whether Deliverect will parse orders as tax exclusive or not.

As for the order itself, this is what must be taken into account:

  • Prices of products sent must exclude taxes.
  • deliveryCost and serviceCharge must also exclude taxes, total taxes for those should be sent with keys deliveryCostTax and serviceChargeTax, respectively.
  • The total payment amount must include taxes.
  • An extra array taxes must be sent, which details all tax amounts (excluding deliveryCostTax and serviceChargeTax) per tax class.

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

Key

Value

taxClassId

the ID corresponding to this tax class as used by Deliverect

name

the display name for this category of taxes, which is how it should be printed on a receipt

total

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

Make sure to send all tax amounts as integers, bearing in mind the number of decimalDigits.
In the end, the equation below must always hold true:

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

Make sure to check out the example request for a tax-exclusive order at the top of this page.

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

📘

Your channel is not yet required to support order cancellation in order to become or remain certified.

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 status to the order and pass this to the connected POS. At this point, the POS can confirm the cancellation by sending a status CANCELED (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"
}
Language
Authentication
OAuth2
Click Try It! to start a request and see the response here!