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

POST /v15/order_ahead/orders

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 \
  -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.
Time, null Optional. ISO 8601 format. Omitting this means the order is wanted ASAP.
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": "",
    "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.


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