- Platform Overview
- Resources and Guides
-
POS Integration
-
Getting Started
-
Core Concepts
-
Integration SDK
-
Certification
-
-
Order Ahead
-
Getting Started
-
Endpoints
-
-
Provider Enablement
-
Provider Enablement
-
Endpoints
-
Developer Endpoints
-
-
API Reference
-
Getting Started
-
v15
-
- Access Tokens
- Campaigns
- Credit Cards
- Users
- Credit
- Locations
- Payment Methods
- QR Codes
- Progress Adjustments
- Orders
- Rewards
- Gift Cards
-
-
v14
-
- Credit
- Access Tokens
- Campaigns
- Categories
- Credit Cards
- Interstitials
- Locations
- Loyalty
- Orders
- Payment Tokens
- Support Tickets
- Users
-
-
Start Order
Order Ahead / Endpoints
Start an Order Ahead Order
This endpoint starts the order ahead order submission process by creating a “proposed” order. After starting an order, LevelUp performs validations, including contacting the merchant or their order ahead fulfillment service, to determine whether the order can be completed.
The response includes an order_url that the client should poll until the order validation process is complete. (See Show a Proposed Order Ahead Order for details.)
If the user adds or removes items from his or her shopping cart, adjusts the tip, or changes any other aspect of the order, the client should make a new request to this endpoint.
Request Endpoint
Authorization Required
A user token with the create_orders
and read_user_basic_info
permissions is required for this
request.
Authorization: token user="USER_TOKEN"
cURL Example
curl https://api.thelevelup.com/v15/order_ahead/orders \
-H Accept:application/json \
-H Content-Type:application/json \
-H 'Authorization:token user="123897-99SCvr3kSe3TqqQid3DyPXfo2Kq98MyhF6CaNPqoDeMhJ18Uopq19uddcznu6R"'
-d '{
"order": {
"location_id": 1855,
"conveyance": {
"fulfillment_type": "delivery",
"desired_ready_time": null,
"delivery_address_id": 434
},
"items": [
{
"item": {
"id": 103,
"quantity": 1,
"upsell_id": 52,
"special_instructions": "Toast the bun.",
"option_ids": [525, 527]
}
}
],
"upsell_ids": [52, 53, 54],
"special_instructions": "Buzzer is broken. Call 867-5309.",
"tip_amount": 200
}
}'
Request Parameters
Name | Type | Description |
---|---|---|
location_id |
Integer | Location ID. Required. |
conveyance |
Object | An object containing details about how the order will be fulfilled. Required. |
conveyance[fulfillment_type] |
String | Either “pickup” or “delivery”. Required. |
conveyance[desired_ready_ time]
|
Time, null | Optional. ISO 8601 format. Omitting this means the order is wanted ASAP. |
conveyance[delivery_address_ id]
|
Integer, null | User delivery address ID. Required for delivery, ignored for pickup. |
item[id] |
Integer | Menu item ID. Required. |
item[quantity] |
Integer | Required, and must be ≥ 1. |
item[upsell_id] |
Integer | ID of the upsell that prompted the user to add this item to their cart. Optional. |
item[special_instructions] |
String, null | Special instructions specific to this item. Optional. |
item[option_ids] |
Array of integers | An array of option IDs to include with the item. |
upsell_ids |
Array of integers | An array of upsell IDs that have been presented to the user during the course of order validation. Optional. |
special_instructions |
String, null | Special instructions for the entire order. Optional. |
tip_amount |
Integer | Tip amount in cents. Optional. |
Example Response
{
"order": {
"order_url": "https://api.thelevelup.com/v15/order_ahead/orders/1a2b3c4d5e6f7g8h9i9h8g7f6e5d4c3b2a1",
"state": "externally_validating",
"uuid": "1a2b3c4d5e6f7g8h9i9h8g7f6e5d4c3b2a1"
}
}
Response Parameters
Name | Type | Description |
---|---|---|
order_url |
String | Poll this URL with GET requests. While the order is still validating, it will return HTTP 202 Accepted. If the order validates successfully, it will return HTTP 200 OK. If an error occurs, it will return HTTP 422 Unprocessable Entity. |
state |
String | The order’s state. During validation, the state may be one of externally_validating , externally_valid , or externally_invalid . |
uuid |
String | A unique identifier for the order. |
Upsells
The upsell object will include a title for the upsell, and the items to be presented to the user as upsell opportunities. If an upsell is selected, it should be added to the cart, and the cart should be re-validated. It is important in that next validation to:
- Append this
upsell_id
to theupsell_ids
array and - Add this
upsell_id
as an attribute to the item that was added as a direct result of the upsell display. This is important for analytics purposes.