Show Menu

Order Ahead / Endpoints

Show a Menu

This endpoint returns a collection of menu categories and category groups, each containing a collection of menu items, their option groups, and options.

Request Endpoint

GET /v15/order_ahead/menus/:menu_id

Authorization

No authorization is required for this request.

cURL Example

curl https://api.thelevelup.com/v15/order_ahead/menus/319

Example Response

HTTP/1.1 200 OK

{
  "menu": {
    "id": 319,
    "allows_special_instructions": true,
    "special_instructions_character_limit": 50,
    "category_groups": [
      {
        "category_group": {
          "id": 23,
          "name": "Meats",
          "description": "Animal based proteins.",
          "display_order": "1"
        }
      }
    ],
    "categories": [
      {
        "category": {
          "id": 129,
          "name": "Burgers",
          "category_group_id": 23,
          "description": "Meat or veggies, we'll grill it all!",
          "display_order": 1,
          "items": [
            {
              "item": {
                "id": 2436,
                "name": "The Octoburger",
                "description": "Premium Massachusetts beef fed with South Dakota corn.",
                "display_order": 1,
                "metadata": {},
                "price_amount": 450,
                "price_with_defaults_amount": 475,
                "image_url": "https://api.thelevelup.com/v15/order_ahead/menus/319/items/2436/image",
                "allows_special_instructions": true,
                "special_instructions_character_limit": 50,
                "nutrition": {
                  "calories": "690",
                  "carbohydrates": "120"
                },
                "sku": "2EC6DC79",
                "tax_rate": 0.099,
                "timescopes": [
                  {
                    "time_of_day_ends_at" : "19:00",
                    "time_of_day_starts_at" : "12:00",
                    "day_of_week_ends_at" : "Friday",
                    "day_of_week_starts_at" : "Monday",
                    "date_ends_at" : "2017-09-01",
                    "date_starts_at" : "2017-06-01"
                  },
                  {
                    "time_of_day_ends_at" : "17:00",
                    "time_of_day_starts_at" : "14:00",
                    "day_of_week_ends_at" : "Sunday",
                    "day_of_week_starts_at" : "Saturday",
                    "date_ends_at" : "2017-09-01",
                    "date_starts_at" : "2017-06-01"
                  }
                ],
                "upc": null,
                "option_groups": [
                  {
                    "option_group": {
                      "id": 497,
                      "name": "Bun",
                      "display_order": 1,
                      "minimum_choices": 1,
                      "maximum_choices": 1,
                      "free_choices": 0,
                      "default_option_ids": [9881],
                      "options": [
                        {
                          "option": {
                            "id": 9881,
                            "name": "White",
                            "display_order": 1,
                            "image_url": "https://api.thelevelup.com/v15/order_ahead/menus/1067/items/177339/options/650/image",
                            "price_amount": 0,
                            "maximum_quantity": 2,
                            "option_groups": [
                              {
                                "option_group": {
                                  "id": 563,
                                  "name": "Sesame Seeds",
                                  "display_order": 1,
                                  "minimum_choices": 1,
                                  "maximum_choices": 1,
                                  "free_choices": 0,
                                  "default_option_ids": [5468],
                                  "options": [
                                    {
                                      "option": {
                                        "id": 5468,
                                        "name": "A little",
                                        "display_order": 1,
                                        "image_url": null,
                                        "price_amount": 25
                                      },
                                      "option": {
                                        "id": 5469,
                                        "name": "A lot",
                                        "display_order": 2,
                                        "image_url": null,
                                        "price_amount": 50
                                      }
                                    }
                                  ]
                                }
                              }
                            ]
                          }
                        }
                      ]
                    }
                  }
                ]
              }
            }
          ]
        }
      }
    ]
  }
}
Name Type Description
menu[id] Integer The menu’s ID.
menu[allows_special_
instructions]
Boolean, null Whether or not the menu allows special instructions to be sent in
menu[special_instructions_
character_limit]
Integer, null The number of characters allowed in the special instructions attribute
category[id] Integer The category’s ID.
category[name] String The category’s name.
category[description] String, null The category’s description, if it has one.
category[display_order] Integer The order in which the category should be displayed relative to its sibling categories. Display orders start at zero. The array of categories is guaranteed to be sorted by ascending display order.
category_group[id] Integer The category group’s ID.
category_group[name] String The category group’s name.
category_group[description] String, null The category group’s description, if it has one.
category_group[display_
order]
Integer The order in which the category group should be displayed relative to its sibling category groups. Display orders start at zero. The array of category groups is guaranteed to be sorted by ascending display order.
menu[allows_special_
instructions]
Boolean, null Whether or not an order allows special instructions to be sent in.
menu[special_instructions_
character_limit]
Integer, null The number of characters allowed in the order-level special instructions attribute.
item[id] Integer The item’s ID.
item[name] String The item’s name.
item[description] String, null The item’s description, if it has one.
item[display_order] Integer The order in which the item should be displayed relative to its sibling items. Display orders start at zero. The array of items is guaranteed to be sorted by ascending display order.
item[metadata] Object A hash of arbitrary string keys to arbitrary string values representing additional data about the item. Will always be an object, but may be empty.
item[price_amount] Integer The item’s price is its base price in cents. Does not include option items that could have associated pricing. May be zero.
item[price_with_defaults
_amount]
Integer The item’s base price plus the total price of all of the item’s default options in cents. May be zero.
item[image_url] String, null A base URL to the item’s image, if it has one. See the “Show Menu Item Image” endpoint for details.
item[nutrition] Object A hash of arbitrary string keys to arbitrary string values representing nutrition data, such as{“calories”: “130”}. Will always be an object, but may be empty.
item[sku] String, null The item’s SKU, if it has one.
item[upc] String, null The item’s UPC, if it has one.
item[allows_special_
instructions]
Boolean, null Whether or not an item allows special instructions to be sent in
item[special_instructions_
character_limit]
Integer, null The number of characters allowed in the special instructions attribute
item[tax_rate] Float, null The tax rate to be applied to this item, e.g., 0.099 would mean a 9.9% tax rate on the item.
option_group[id] 64 bit Integer The option group’s ID. Note that this can exceed 32 bit integer values.
option_group[name] String The option group’s name.
option_group[display_order] Integer The order in which the option group should be displayed relative to its sibling option groups. Display orders start at zero. The array of option groups is guaranteed to be sorted by ascending display order.
option_group[minimum_
choices]
Integer The minimum number of options the user must choose for this option group.
option_group[maximum_
choices]
Integer, null The maximum number of options the user may choose for this option group. Null means there is no maximum, i.e. the user may select as many options as he or she wishes.
option_group[free_choices] Integer The number of options the user may choose for this option group that will be considered free, if any. Any additional chosen options will be charged accordingly. When considering which of the user’s chosen options are free, LevelUp will sort the user’s choices in descending order by price, so the most expensive options are free.
option_group[default_
option_ids]
Array of integers The IDs of the options for this option group that will be selected by default if the user does not customize his or her choices.
option[id] 64 bit Integer The option’s ID. Note that this can exceed 32 bit integer values.
option[image_url] String, null A base URL to the option’s image, if it has one.
option[maximum_quantity] Integer The maximum quantity that can be ordered of this option on a single item.
option[name] String The option’s name.
option[display_order] Integer The order in which the option should be displayed relative to its sibling options. Display orders start at zero. The array of options is guaranteed to be sorted by ascending display order.
option[price_amount] Integer The option’s price in cents, independent of the base price of any associated item. May be zero.
timescope[time_of_day_
starts_at]
String Start time of day for entity availability in ISO 8601 format. h:mm or hh:mm only.
timescope[time_of_day_ends_
at]
String End time for entity availability in ISO 8601 format. h:mm or hh:mm only.
timescope[day_of_week_
starts_at]
String The day of the week that entity availability starts on. Supported values are “Monday” through “Sunday”.
timescope[day_of_week_ends_
at]
String The day of the week that entity availability ends on (inclusive). Supported values are “Monday” through “Sunday”.
timescope[date_starts_at] String The date that entity availability starts on. In ISO 8601 YYYY-MM-DD format only.
timescope[date_ends_at] String The date that entity availability ends on (inclusive). In ISO 8601 YYYY-MM-DD format only.

Option ID Length & Uniqueness

It’s important to note that item ids and options ids can both be up to 64 bit integers in length. Additionally, item ids are always unique within a menu (and across menus). And option group and option ids are always unique within a menu (not necessarily across menus).

Timescoped Menu Entities

A timescope object is used to specify when a menu entity is available for ordering. Categories, category groups, items, options, and option groups are the menu entities with which timescopes may be associated. In the response JSON above, for example, The Octoburger item has timescopes indicating that it can only be ordered on weekdays from noon to 7pm and on weekends from 2 to 5pm, all throughout the summer (1 June to 1 September).

A single timescope object is composed of 3 pairs of fields:

  • time_of_day_starts_at and time_of_day_ends_at
  • day_of_week_starts_at and day_of_week_ends_at
  • date_starts_at and date_ends_at

Each pair is optional and when no timescopes are specified, the menu entity is assumed to be available all the time (all day, all week, all year). For example, you can specify time_of_day_starts_at and time_of_day_ends_at (without specifying the other pairs) to indicate the menu entity is available during a certain period of the day, every day of the week, all year.

Set both time_of_day_starts_at and time_of_day_ends_at to null if available all day.
Set both day_of_week_starts_at and day_of_week_ends_at to null if available all week.
Set both date_starts_at and date_ends_at to null if available all year.

Menu entities that need to provide timescope information must do so using an array of timescopes. The array allows multiple availability periods to be specified (e.g. Monday 9-11AM, Wednesday 9-11AM and Friday 9-11AM).

Errors

HTTP/1.1 error 404 Not Found - No menu with that ID exists