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 https://api.thelevelup.com/v15/order_ahead/orders \
  -H Accept:application/json \
  -H Content-Type:application/json \
  -H 'Authorization:token user="1123-15d2aeedc9f4e0e7094a9d283868f8fbe873cb85ceaa0c511727245aec8c9e"'
  -d '{
        "order": {
          "location_id": 1855,
          "conveyance": {
            "fulfillment_type": "delivery",
            "desired_ready_time": null,
            "delivery_address_id": 434
          },
          "items": [
            {
              "item": {
                "id": 103,
                "quantity": 1,
                "special_instructions": "Toast the bun.",
                "option_ids": [525, 527]
              }
            }
          ],
          "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[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.
special_instructions String, null Special instructions for the entire order. Optional.
tip_amount Integer Tip amount in cents. Optional. If you supply both tip_amount and tip_percent, then tip_amount will take precedence.

Example Response

{
  "order": {
    "order_url": "https://api.thelevelup.com/v15/users/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.