List Suggested Orders

Order Ahead / Endpoints

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="123897-99SCvr3kSe3TqqQid3DyPXfo2Kq98MyhF6CaNPqoDeMhJ18Uopq19uddcznu6R"'

Example Response

[
  {
    "order": {
      "banner": "past",
      "conveyance": {
        "delivery_address_id": 434,
        "desired_ready_time": null,
        "fulfillment_type": "delivery",
      },
      "created_at": "2017-11-27T21:13:33Z",
      "description": "Carne asada burrito, Spindrift",
      "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",
                  "price_amount": 0,
                  "quantity": 1
                }
              },
              {
                "option": {
                  "id": 527,
                  "name": "Green Salsa",
                  "price_amount": 75,
                  "quantity": 2
                }
              }
            ],
            "selected_options_description": "Flour Tortilla, Green Salsa (Quantity: 2)",
            "special_instructions": "Toast the bun.",
            "upsell_id": null
          }
        }
      ],
      "location_id": 1855,
      "location": {
        "extended_address": "Suite 500",
        "latitude": 42.3557498,
        "locality": "Boston",
        "longitude": -71.0565637,
        "postal_code": "02114",
        "region": "MA",
        "street_address": "1234 Test Street"
      },
      "image_url": "https://api.thelevelup.com/v15/order_ahead/menus/1148051/items/123757621/image",
      "menu_url": "https://api.thelevelup.com/v15/order_ahead/menus/2",
      "merchant_name": "LevelUp Cafe",
      "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.
created_at Time The time of order creation, in ISO 8601 format.
description String A human-readable summary of the order contents to display to the user. Never null.
image_url String The image URL for the most expensive item in the cart.
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 The items ordered by the user.
item[id] Integer The item’s menu ID.
item[name] String The item’s name.
item[option_ids] Array of Integers An array of option IDs included with the item.
item[price_amount] Integer The items price.
item[quantity] Integer The quantity ordered by the user.
item[selected_options] Array of objects An array of options for the item. Properties include the option’s menu ID, name, price, and quantity.
item[selected_options_
description]
String A human-readable description of the options selected by the user, if any. May be an empty string, but will never be null.
item[special_instructions] String, null Any special instructions for the 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 If lat and lng query 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.