Order Ahead .: List Suggested Orders

API Reference / v15

List Suggested Orders

This endpoint returns a list of the user’s past order ahead orders and any available recommendations. As a user builds up more history within the app, and as LevelUp improves its recommendation algorithms, the API will return suggested orders generated based on the user’s order history and what’s popular with other users. You can use this endpoint to get past/suggested orders for a given location, or just for the user which will include past/suggested orders across their entire order history. The response includes a full shopping cart, including items and selected options, so that the order can be repeated. The response already removes any orders that can no longer be re-ordered due to changes in the merchant’s menu. The response already de-duplicates past orders, so if the user orders the same thing many times, it will only show up with a single represented order below, though that frequency will be factored into the sequencing in which the past orders are listed. It will return a maximum of 25 suggestions.

Request Endpoint

GET /v15/order_ahead/orders/suggested?location_id=1855&types=past,popular&lat=42.3557498&lng=-71.0565637

Authorization

A user token with the read_user_orders and read_user_basic_info permissions is required for this request.

Query Parameters

By default, the endpoint will return orders from all merchants and locations associated with the requesting app. You may specify a location_id query parameter to restrict the response to one location. If you’d like walking time estimates (see the walking_time_minutes response field below), you may include lat and lng query parameters corresponding to the user’s current latitude and longitude.

Include the types query parameter to filter which order types are returned, as a comma-separated list. If you don’t include the types parameter, orders of all types are returned. Invalid types are ignored. Valid types are:

Type Description
past Orders from the user’s order history.
popular Popular orders, as determined from the pool of all LevelUp users.

cURL Example

curl https://api.thelevelup.com/v15/order_ahead/orders/suggested?location_id=1855&types=past,popular&lat=42.3557498&lng=-71.0565637 \
  -H Accept:application/json \
  -H Content-Type:application/json \
  -H 'Authorization:token user="1123-15d2aeedc9f4e0e7094a9d283868f8fbe873cb85ceaa0c511727245aec8c9e"'

Example Response

[
  {
    "order": {
      "banner": "past",
      "conveyance": {
        "fulfillment_type": "delivery",
        "desired_ready_time": null,
        "delivery_address_id": 434
      },
      "description": "Carne asada burrito, Spindrift",
      "location_id": 1855,
      "location_extended_address": "",
      "location_locality": "Boston",
      "location_name": "",
      "location_postal_code": "02114",
      "location_region": "Massachusetts",
      "location_street_address": "1234 Test Street",
      "latitude": 42.3557498,
      "longitude": -71.0565637,
      "menu_url": "https://api.thelevelup.com/v15/menus/2",
      "merchant_name": "LevelUp Cafe",
      "items": [
        {
          "item": {
            "id": 103,
            "name": "Carne Asada Burrito",
            "option_ids": [525, 527],
            "price_amount": 1092,
            "quantity": 1,
            "selected_options": [
              {
                "option": {
                  "id": 525,
                  "name": "Flour Tortilla",
                  "quantity": 1
                }
              },
              {
                "option": {
                  "id": 527,
                  "name": "Green Salsa",
                  "quantity": 2
                }
              }
            ],
            "selected_options_description": "Flour Tortilla, Green Salsa (Quantity: 2)",
            "special_instructions": "Toast the bun."
          }
        }
      ],
      "soonest_available_at": "2016-06-13T14:09:32Z",
      "special_instructions": "No guacamole please!",
      "total_amount": 1138,
      "uuid": "1a2b3c4d5e6f7g8h9i9h8g7f6e5d4c3b2a1",
      "walking_time_minutes": 5.014737883211898
    }
  }
]

Response Parameters

Name Type Description
banner String The type of banner to display with the suggested order. One of “past” or “popular”. Never null.
conveyance Object, null For “past” orders, details about how the order was fulfilled, like whether it was pickup or delivery. Null for “popular” orders.
description String A human-readable summary of the order contents to display to the user. Never null.
location_id Integer The ID of the location at which the order was placed or is suggested for. Never null.
menu_url String The URL of the applicable menu from which this order was created. See the “Show Menu” endpoint for details. Never null.
merchant_name String The name of the merchant for the order. Never null.
items Array of objects A collection of items, in the same format as they were submitted to the “Start an Order Ahead Order” endpoint. Never null, and the array will always contain at least one item.
soonest_available_at Time The soonest time at which this order can be picked up at the merchant, in ISO 8601 format.
special_instructions String, null For past orders, any special instructions the user submitted with the order.
total_amount Integer The total of the order in cents. Never null.
uuid String, null For past orders, the order’s UUID. Null for “popular” orders.
walking_time_minutes Decimal, null Iflatandlngquery parameters are included in the request, the approximate number of minutes to walk from the user’s current location to the merchant location. If lat and lng are omitted, walking_time_minutes will be null.