Show Menu

Provider Enablement / Endpoints

Show Menu

Our menu structure attempts to make it easy to represent almost any menu cleanly within the LevelUp format, with a limited amount of translation/manipulation. Ascribing to this format makes it seamless for LevelUp to feature your merchants ordering experience in the LevelUp, a merchant-specific app we power, or any of our partner apps such as Chase Pay.

LevelUp’s menu structure affords you a lot of flexibility in terms of how you choose to represent a menu, and what information you include such as images and nutritional info. If you have specific questions about how to best represent your menu, please email developer@thelevelup.com and we’ll provide advice.

Request Endpoint

GET /locations/:provider_location_id/menu

Example Response Body

{
  "menu": {
    "allows_special_instructions": true,
    "special_instructions_character_limit": 100,
    "provider_id": "35c5e14a-2dc4-4972-8f1a-151b428495d9",
    "name": "Octoburgers_menu",
    "updated_at": "2016-05-31T16:07:55-04:00",
    "option_groups": [
      {
        "option_group": {
          "provider_id": "c9f34ae3-03e7-48d3-b8e3-d47a669d4c4b",
          "universal_id": "c9f34ae3-03e7-48d3-uid",
          "name": "Bun",
          "minimum_choices": 1,
          "maximum_choices": 1,
          "display_order": 1,
          "options": [
            {
              "option": {
                "metadata": {
                  "integration_id_needed_for_validation": "1111",
                  "integration_id_needed_for_submission": "2222",
                  "integration_special_key": "aaaa"
                },
                "provider_id": "8ff532bf-c3db-4e2e-be3c-fe246be60f94",
                "universal_id": "8ff532bf-c3db-4e2e-uid",
                "name": "White",
                "display_order": 1,
                "image": "http://i.imgur.com/KTNsrtb.jpg",
                "price": 0,
                "tax_rate": 0.0725
              }
            },
            {
              "option": {
                "provider_id": "38ff254b-4785-41d5-854d-ed7b1f1a62a6",
                "universal_id": "38ff254b-4785-41d5-uid",
                "name": "Whole Wheat",
                "display_order": 2,
                "image": "http://i.imgur.com/KTNsftb.jpg",
                "price": 0,
                "tax_rate": 0.0675
              }
            },
            {
              "option": {
                "provider_id": "3bc422c8-f199-4006-91e1-1fa4a067dab4",
                "universal_id": "3bc422c8-f199-4006-uid",
                "name": "Portobello Mushroom",
                "display_order": 3,
                "image": null,
                "price": 299,
                "tax_rate": 0.0625
              }
            },
            {
              "option": {
                "provider_id": "359972a7-63ee-4c45-ad36-88a3e2efa0b1",
                "universal_id": "359972a7-63ee-4c45-uid",
                "name": "Soft Pretzel",
                "display_order": 4,
                "image": null,
                "price": 349,
                "tax_rate": 0.0775
              }
            }
          ],
          "defaults": [
            "8ff532bf-c3db-4e2e-be3c-fe246be60f94"
          ]
        }
      },
      {
        "option_group": {
          "provider_id": "ccc9e5b7-0b98-4e1e-bb83-887625989c4e",
          "universal_id": "ccc9e5b7-0b98-4e1e-uid",
          "name": "Patties",
          "minimum_choices": 1,
          "maximum_choices": 1,
          "display_order": 2,
          "options": [
            {
              "option": {
                "provider_id": "b86dac3e-f192-4b0b-a085-64f6b5d9ef8a",
                "universal_id": "b86dac3e-f192-4b0b-uid",
                "name": "The Lone Patty",
                "image": null,
                "price": 0,
                "tax_rate": 0.0675
              }
            },
            {
              "option": {
                "provider_id": "6282c5ad-e912-4772-86e5-70aff4b09365",
                "universal_id": "6282c5ad-e912-uid",
                "name": "Double the Patty, Double the Fun",
                "image": null,
                "price": 100,
                "tax_rate": 0.0555
              }
            },
            {
              "option": {
                "provider_id": "12ceb592-1a81-46b4-9464-9ba7d190e20f",
                "universal_id": "12ceb592-1a81-46b-uid",
                "name": "Three's a Crowded Burger",
                "image": null,
                "price": 200,
                "tax_rate": 0.0675
              }
            },
            {
              "option": {
                "provider_id": "10887107-a0e8-4f76-a371-c819bff8622d",
                "universal_id": "10887107-a0e8-4f76-uid",
                "name": "The Octopatty",
                "image": null,
                "price": 800,
                "tax_rate": 0.0615
              }
            }
          ],
          "defaults": [
            "b86dac3e-f192-4b0b-a085-64f6b5d9ef8a"
          ]
        }
      },
      {
        "option_group": {
          "provider_id": "8708454a-f7a9-47ee-b20b-92e97d30928sd9",
          "universal_id": "8708454a-f7a9-47e-uid",
          "name": "Toppings",
          "minimum_choices": 1,
          "maximum_choices": 5,
          "minimum_unique_choices": 1,
          "maximum_unique_choices": 3,
          "display_order": 3,
          "options": [
            {
              "option": {
                "provider_id": "b44e3e11-3a9d-41af-8351-a7d7252485ca",
                "universal_id": "b44e3e11-3a9d-41a",
                "name": "Alfalfa Sprouts",
                "image": null,
                "price": 49,
                "tax_rate": 0.06
              }
            },
            {
              "option": {
                "provider_id": "c1881fac-b3b0-4cf8-84a0-838aafd03d55",
                "universal_id": "c1881fac-b3b0-4cf8",
                "name": "American Cheese",
                "image": null,
                "price": 0,
                "tax_rate": 0.0425
              }
            },
            {
              "option": {
                "provider_id": "364779b8-5b4b-4849-ad51-debefc41f29b",
                "universal_id": "364779b8-5b4b-4849-uid",
                "name": "Avocado",
                "image": null,
                "price": 49,
                "tax_rate": 0.00
              }
            },
            {
              "option": {
                "provider_id": "c3699423-71e7-4a98-8222-d21dadc0d620",
                "universal_id": "c3699423-71e7-4a98-uid",
                "name": "Bacon",
                "image": "http://i.imgur.com/RAg20zt.jpg",
                "price": 49,
                "tax_rate": 0.00
              }
            },
            {
              "option": {
                "provider_id": "d1469214-de87-4ce7-ae16-e5b976d3eb77",
                "universal_id": "1469214-de87-4ce7-uid",
                "name": "Barbecue Sauce",
                "image": "http://i.imgur.com/RAg21zt.jpg",
                "price": 10,
                "tax_rate": 0.025,
                "option_groups": [
                  "8708454a-f7a9-47ee-b20b-92e97da2a3f8"
                ]
              }
            },
            {
              "option": {
                "provider_id": "54552c54-d092-44c6-8870-a50f923c7893",
                "universal_id": "4552c54-d092-44c6-uid",
                "name": "Blue Cheese",
                "image": null,
                "price": 10,
                "tax_rate": 0.00
              }
            },
            {
              "option": {
                "provider_id": "9517433e-327b-4191-a9a9-c3306cdec6ed",
                "universal_id": "9517433e-327b-419-uid",
                "name": "Cheddar Cheese",
                "image": null,
                "price": 0,
                "tax_rate": 0.00
              }
            },
            {
              "option": {
                "provider_id": "bae7ee52-3155-40b4-ad58-ddad55f79e01",
                "universal_id": "e7ee52-3155-40b4-ad5",
                "name": "Fried Egg",
                "image": null,
                "price": 149,
                "tax_rate": 0.025,
                "option_groups": [
                  "8708454a-f7a9-47ee-b20b-92e97da2a3f9"
                ],
                "maximum_quantity": 3,
                "default_quantity": 2
              }
            },
            {
              "option": {
                "provider_id": "3190971a-f9d8-4c5a-8539-dd9a031d467a",
                "universal_id": "90971a-f9d8-4c5a-8539-id",
                "name": "Grilled Bell Peppers",
                "image": null,
                "price": 49,
                "tax_rate": 0.00
              }
            },
            {
              "option": {
                "provider_id": "fe08316d-8d5f-4090-8d85-2ef132cde946",
                "universal_id": "e08316d-8d5f-4090-8d",
                "name": "Grilled Onions",
                "image": null,
                "price": 10,
                "tax_rate": 0.02
              }
            },
            {
              "option": {
                "provider_id": "6bd09baf-9d0e-48cf-89f8-f19cb37bcace",
                "universal_id": "6bd09baf-9d0e-48cf-89f8-uid",
                "name": "Jalapeños",
                "image": null,
                "price": 49,
                "tax_rate": 0.00
              }
            },
            {
              "option": {
                "provider_id": "fadbf878-5692-4db2-92d9-21a007f63876",
                "universal_id": "fadbf878-5692-4db2-uid",
                "name": "Onion Rings",
                "image": null,
                "price": 149,
                "tax_rate": 0.00
              }
            },
            {
              "option": {
                "provider_id": "19f88084-16c9-466a-a835-182272da8a46",
                "universal_id": "9f88084-16c9-466a-a8",
                "name": "Pepper Jack Cheese",
                "image": null,
                "price": 10,
                "tax_rate": 0.00
              }
            }
          ]
        }
      },
      {
        "option_group": {
          "provider_id": "8708454a-f7a9-47ee-b20b-92e97da2a3f8",
          "universal_id": "708454a-f7a9-47ee-b20b-uid",
          "name": "Barbecue Sauce Amount",
          "minimum_choices": 1,
          "maximum_choices": 1,
          "display_type": "text_dropdown",
          "display_order": 4,
          "options": [
            {
              "option": {
                "provider_id": "a7d72524-8351-41af-3a9d-b44e3e1185ca",
                "universal_id": "a7d72524-8351-41af-3a9",
                "name": "Light",
                "image": null,
                "price": 0,
                "tax_rate": 0.00
              }
            },
            {
              "option": {
                "provider_id": "838aafd0-84a0-4cf8-b3b0-c1881fac3d55",
                "universal_id": "afd0-84a0-4cf8-b3b0-c1",
                "name": "Medium",
                "image": null,
                "price": 0,
                "tax_rate": 0.025
              }
            },
            {
              "option": {
                "provider_id": "debefc41-ad51-4849-5b4b-364779b8f29b",
                "universal_id": "fc41-ad51-4849-5b4b-364779b8",
                "name": "Heavy",
                "image": null,
                "price": 49,
                "tax_rate": 0.0775
              }
            }
          ]
        }
      },
      {
        "option_group": {
          "provider_id": "8708454a-f7a9-47ee-b20b-92e97da2a3f9",
          "universal_id": "08454a-f7a9-47ee-b20",
          "name": "Egg Style",
          "minimum_choices": 1,
          "maximum_choices": 1,
          "display_order": 5,
          "options": [
            {
              "option": {
                "provider_id": "a7d72524-8351-41af-3a9d-b44e3e1185ca",
                "universal_id": "2524-8351-41af-3a9d-b",
                "name": "Over Easy",
                "image": null,
                "price": 0,
                "tax_rate": 0.00
              }
            },
            {
              "option": {
                "provider_id": "838aafd0-84a0-4cf8-b3b0-c1881fac3d55",
                "universal_id": "afd0-84a0-4cf8-b3b0-c-uid",
                "name": "Over Medium",
                "image": null,
                "price": 0,
                "tax_rate": 0.0125
              }
            },
            {
              "option": {
                "provider_id": "debefc41-ad51-4849-5b4b-364779b8f29b",
                "universal_id": "efc41-ad51-4849-5b4b-3647",
                "name": "Over Hard",
                "image": null,
                "price": 49,
                "tax_rate": 0.00
              }
            }
          ]
        }
      }
    ],
    "categories": [
      {
        "category": {
          "provider_id": "ce70838c-2333-4d76-8c87-6720e0a24a47",
          "universal_id": "ce70838c-2333-4d76-8c87-uid",
          "name": "Burgers",
          "description": "Meat or veggies, we'll grill it all!",
          "display_order": 1,
          "items": [
            {
              "item": {
                "provider_id": "77080b92-fcf3-4c86-9df8-2f434d17f153",
                "universal_id": "77080b92-fcf3-4c86-9df-uid",
                "name": "The Octoburger",
                "description": "Premium Massachusetts beef fed with South Dakota corn.",
                "display_order": 1,
                "metadata": {
                  "integration_id_for_validation": "123"
                },
                "price": 450,
                "option_groups": [
                  "c9f34ae3-03e7-48d3-b8e3-d47a669d4c4b",
                  "ccc9e5b7-0b98-4e1e-bb83-887625989c4e",
                  "8708454a-f7a9-47ee-b20b-92e97d30928sd9"
                ],
                "image": "http://i.imgur.com/7Dn4Hav.jpg",
                "nutrition": {
                  "calories": 690
                },
                "allows_special_instructions": true,
                "special_instructions_character_limit": 50,
                "maximum_quantity": 5,
                "minimum_quantity": 2,
                "tax_rate": 0.099
              }
            },
            {
              "item": {
                "provider_id": "e9887853-338f-4094-9f69-eaf3b5e69427",
                "universal_id": "887853-338f-4094-9f69-eaf3b5e-uid",
                "name": "The Octoveg",
                "description": "A grilled lentil patty infused with bits of grilled bell pepper.",
                "display_order": 2,
                "nutrition": {
                  "calcium": 20,
                  "caloric_description": "850 cal – 1100 cal",
                  "calories": 690,
                  "calories_from_fat": 100,
                  "cholesterol": 95,
                  "dietary_fiber": 80,
                  "ingredient_description": "Lentils, Grilled Bell Peppers",
                  "protein": 70,
                  "saturated_fat": 60,
                  "serving_size": 10,
                  "sodium": 50,
                  "sugar": 40,
                  "tags": [
                    "Kosher",
                    "Vegan"
                  ],
                  "total_carbohydrate": 90,
                  "trans_fat": 30,
                  "vitamin_a": 25,
                  "vitamin_d": 20
                },
                "price": 450,
                "option_groups": [
                  "c9f34ae3-03e7-48d3-b8e3-d47a669d4c4b",
                  "ccc9e5b7-0b98-4e1e-bb83-887625989c4e",
                  "8708454a-f7a9-47ee-b20b-92e97d30928sd9"
                ],
                "image": "http://i.imgur.com/KTNsrtb.jpg",
                "allows_special_instructions": true,
                "special_instructions_character_limit": 50
              }
            },
            {
              "item": {
                "provider_id": "e9887853-338f-4094-9f69-eaf3b5e69427",
                "universal_id": "887853-338f-4094-9f69-eaf-uid",
                "name": "The Octobreakfast",
                "description": "A breakfast burger made with breakfast and bacon. Served all day on weekends.",
                "display_order": 3,
                "price": 450,
                "option_groups": [
                  "c9f34ae3-03e7-48d3-b8e3-d47a669d4c4b",
                  "ccc9e5b7-0b98-4e1e-bb83-887625989c4e",
                  "8708454a-f7a9-47ee-b20b-92e97d30928sd9"
                ],
                "image": "http://i.imgur.com/XjsqVh.jpg",
                "nutrition": {
                  "calories": 900
                },
                "allows_special_instructions": true,
                "special_instructions_character_limit": 50,
                "timescopes": [
                  {
                    "time_of_day_ends_at" : "12:00",
                    "time_of_day_starts_at" : "7:00",
                    "day_of_week_ends_at" : "Monday",
                    "day_of_week_starts_at" : "Friday",
                    "date_ends_at" : null,
                    "date_starts_at" : null
                  },
                  {
                    "time_of_day_ends_at" : "17:00",
                    "time_of_day_starts_at" : "7:00",
                    "day_of_week_ends_at" : "Saturday",
                    "day_of_week_starts_at" : "Sunday",
                    "date_ends_at" : null,
                    "date_starts_at" : null
                  }
                ]
              }
            }
          ]
        }
      },
      {
        "category": {
          "provider_id": "19bbd685-ddb9-4469-bed2-a33a81aeebb5",
          "universal_id": "9bbd685-ddb9-4469-be-uid",
          "name": "Beer",
          "description": "Quench your burger thirst with an ice-cold beer.",
          "display_order": 2,
          "items": [
            {
              "item": {
                "provider_id": "cc87779f-c32b-422f-9486-77099fd81e1f",
                "universal_id": "c87779f-c32b-422f-948-uid",
                "name": "Guinness",
                "description": "A pint of the classic Irish dry stout.",
                "price": 249,
                "image": "http://i.imgur.com/RAg20zt.jpg",
                "nutrition": {
                  "calories": 210
                },
                "allows_special_instructions": false,
                "special_instructions_character_limit": null
              }
            },
            {
              "item": {
                "provider_id": "9b8b66e8-26a2-4f01-b862-39f109df4686",
                "universal_id": "b66e8-26a2-4f01-b862-39f-uid",
                "name": "Harpoon IPA",
                "description": "It's good stuff.",
                "price": 199,
                "image": "http://i.imgur.com/fZ74WMr.jpg",
                "nutrition": {
                  "calories": 0
                },
                "allows_special_instructions": false,
                "special_instructions_character_limit": null
              }
            }
          ],
          "category_group": "29bfd636-eyb9-7130-bed2-a3ajb5aee44p",
          "timescopes": [
            {
              "time_of_day_ends_at" : "23:00",
              "time_of_day_starts_at" : "17:00",
              "day_of_week_ends_at" : null,
              "day_of_week_starts_at" : null,
              "date_ends_at" : null,
              "date_starts_at" : null
            }
          ]
        }
      },
      {
        "category": {
          "provider_id": "19bbd685-ddb9-4469-bed2-a33a81aeebb5",
          "universal_id": "685-ddb9-4469-bed2-uid",
          "name": "Smoothies",
          "description": "Quench your burger thirst with an ice-cold beer.",
          "display_order": 3,
          "items": [
            {
              "item": {
                "provider_id": "9b8b66e8-ddb9-422f-9486-26a29fd81d4f",
                "universal_id": "b8b66e8-ddb9-422f-9486-26a29fd",
                "name": "Strawberry Banana Smoothie",
                "description": "A tropical mix of fruity goodness.",
                "price": 499,
                "image": "http://i.imgur.com/RAg20zt.jpg",
                "nutrition": {
                  "calories": 210
                },
                "allows_special_instructions": true,
                "special_instructions_character_limit": 75
              }
            }
          ],
          "category_group": "29bfd636-eyb9-7130-bed2-a3ajb5aee44p"
        }
      }
    ],
    "category_groups": [
      {
        "category_group": {
          "provider_id": "29bfd636-eyb9-7130-bed2-a3ajb5aee44p",
          "universal_id": "bfd636-eyb9-7130-bed2-a3ajb-uid",
          "name": "Drinks",
          "description": "They go down smooth.",
          "display_order": 1
        }
      }
    ]
  }
}

Example Response Schema

{
  "type": "object",
  "properties": {
    "menu": {
      "properties": {
        "name": {
          "description": "The title of the menu (e.g. Burger King Summer St)",
          "type": "string"
        },
        "provider_id": {
          "description": "A unique string that identifies the menu",
          "type": "string"
        },
        "allows_special_instructions": {
          "description": "Whether or not a user may input special instructions to be sent along with their order",
          "type": "boolean"
        },
        "special_instructions_character_limit": {
          "description": "The maximum number of characters that the provider accepts for the special instructions (required if allows_special_instructions is true)",
          "type": "number"
        },
        "timescopes": {
          "type": "array",
          "items": {
            "type": "object",
            "title": "timescope",
            "properties": {
              "time_of_day_starts_at": {
                "type": "string"
              },
              "time_of_day_ends_at": {
                "type": "string"
              },
              "day_of_week_starts_at": {
                "type": "string"
              },
              "day_of_week_ends_at": {
                "type": "string"
              },
              "date_starts_at": {
                "type": "string"
              },
              "date_ends_at": {
                "type": "string"
              }
            },
            "dependencies": {
              "time_of_day_ends_at": [
                "time_of_day_starts_at"
              ],
              "time_of_day_starts_at": [
                "time_of_day_ends_at"
              ],
              "day_of_week_ends_at": [
                "day_of_week_starts_at"
              ],
              "day_of_week_starts_at": [
                "day_of_week_ends_at"
              ],
              "date_ends_at": [
                "date_starts_at"
              ],
              "date_starts_at": [
                "date_ends_at"
              ]
            }
          }
        },
        "updated_at": {
          "description": "An iso8601 timestamp representing when the menu was last updated, in UTC",
          "type" : "string"
        },
        "categories": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "category": {
                "description": "A collection of individual items (e.g. Smoothies)",
                "type": "object",
                "properties": {
                  "description": {
                    "description": "A description of the category scraped from the provider",
                    "type": "string"
                  },
                  "display_order": {
                    "description": "Order in which to display the category",
                    "type": "integer"
                  },
                  "name": {
                    "description": "The name of the category (e.g. Smoothies)",
                    "type": "string"
                  },
                  "provider_id": {
                    "description": "A unique ID (or XPath selector) for this element",
                    "type": "string"
                  },
                  "universal_id": {
                    "description": "A unique ID (or XPath selector) for this category across all merchant's locations",
                    "type": "string"
                  },
                  "category_group": {
                    "description": "The id of the category group to which the category belongs",
                    "type": "string"
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "item": {
                          "description": "A specific thing on a menu (e.g. Banana Smoothie)",
                          "type": "object",
                          "properties": {
                            "allows_special_instructions": {
                              "description": "Whether or not a user may input special instructions to be sent along with this specific item",
                              "type": "boolean"
                            },
                            "description": {
                              "description": "A description of the item scraped from the provider",
                              "type": "string"
                            },
                            "display_order": {
                              "description": "Order in which to display the item",
                              "type": "integer"
                            },
                            "image": {
                              "description": "The URL for an image associated with the item",
                              "type": "string"
                            },
                            "maximum_quantity": {
                              "description" :"The maximum number of the item that may be selected. Note that the minimum quantity is always defaulted to zero",
                              "type": "integer"
                            },
                            "metadata": {
                              "description": "Additional data about the item. Any keys prefixed with integration_ will be passed back to the provider during order validation and submission",
                              "type": "object"
                            },
                            "minimum_quantity": {
                              "description": "The minimum quantity of the item that may be selected. Defaults to zero.",
                              "type": "number"
                            },
                            "name": {
                              "description": "The name of the item",
                              "type": "string"
                            },
                            "nutrition": {
                              "description": "Calorie and other nutrition information",
                              "type": "object",
                              "properties": {
                                "calcium": {
                                  "type": "integer",
                                  "description": "Percent daily value of calcium for a menu item"
                                },
                                "caloric_description": {
                                  "type": "string",
                                  "description": "Range of calories for a menu item (e.g. '850 cal - 1100 cal')"
                                },
                                "calories": {
                                  "type": "integer",
                                  "description": "Calories in the menu item"
                                },
                                "calories_from_fat": {
                                  "type": "integer",
                                  "description": "Calories from fat in the menu item"
                                },
                                "cholesterol" : {
                                  "type": "integer",
                                  "description": "Milligrams of cholesterol in the menu item"
                                },
                                "dietary_fiber": {
                                  "type": "integer",
                                  "description": "Grams of dietary fiber in the menu item"
                                },
                                "ingredient_description": {
                                  "type": "string",
                                  "description": "Ingredients in the menu item"
                                },
                                "protein": {
                                  "type": "integer",
                                  "description": "Grams of protein in the menu item"
                                },
                                "saturated_fat": {
                                  "type": "integer",
                                  "description": "Grams of saturated fat in the menu item"
                                },
                                "sodium": {
                                  "type": "integer",
                                  "description": "Milligrams of sodium in the menu item"
                                },
                                "sugar": {
                                  "type": "integer",
                                  "description": "Grams of sugar in the menu item"
                                },
                                "tags": {
                                  "type": "array",
                                  "items": {
                                    "description": "Nutrition tags for the menu item",
                                    "type": "string",
                                    "enum": [
                                      "Egg",
                                      "Fish",
                                      "Gluten",
                                      "Gluten Free",
                                      "Honey",
                                      "Kosher",
                                      "Lactose",
                                      "Milk",
                                      "Peanuts",
                                      "Shellfish",
                                      "Soybeans",
                                      "Spicy",
                                      "Tree Nuts",
                                      "Vegan",
                                      "Vegetarian",
                                      "Wheat"
                                    ]
                                  }
                                },
                                "total_carbohydrates": {
                                  "type": "integer",
                                  "description": "Grams of total carbohydrates in the menu item"
                                },
                                "total_fat": {
                                  "type": "integer",
                                  "description": "Grams of total fat in the menu item"
                                },
                                "trans_fat": {
                                  "type": "integer",
                                  "description": "Grams of trans fat in the menu item"
                                },
                                "vitamin_a": {
                                  "type": "integer",
                                  "description": "Percent daily value of Vitamin A in the menu item"
                                },
                                "vitamin_d": {
                                  "type": "integer",
                                  "description": "Percent daily value of Vitamin D in the menu item"
                                }
                              }
                            },
                            "option_groups": {
                              "type": "array",
                              "items": {
                                "description": "The provider id for an option group that the item includes",
                                "type": "string"
                              }
                            },
                            "price": {
                              "description": "The cost of the item in cents",
                              "type": "number"
                            },
                            "provider_id": {
                              "description": "A unique ID (or XPath selector) for this element",
                              "type": "string"
                            },
                            "universal_id": {
                              "description": "A unique ID (or XPath selector) for this item across all merchant's locations",
                              "type": "string"
                            },
                            "special_instructions_character_limit": {
                              "description": "The maximum number of characters that the provider accepts for the special instructions (required if allows_special_instructions is true)",
                              "type": "number"
                            },
                            "tax_rate": {
                              "description": "The tax rate to be applied to this item",
                              "type": "number"
                            },
                            "timescopes": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "title": "timescope",
                                "properties": {
                                  "time_of_day_starts_at": {
                                    "type": "string"
                                  },
                                  "time_of_day_ends_at": {
                                    "type": "string"
                                  },
                                  "day_of_week_starts_at": {
                                    "type": "string"
                                  },
                                  "day_of_week_ends_at": {
                                    "type": "string"
                                  },
                                  "date_starts_at": {
                                    "type": "string"
                                  },
                                  "date_ends_at": {
                                    "type": "string"
                                  }
                                },
                                "dependencies": {
                                  "time_of_day_ends_at": [
                                    "time_of_day_starts_at"
                                  ],
                                  "time_of_day_starts_at": [
                                    "time_of_day_ends_at"
                                  ],
                                  "day_of_week_ends_at": [
                                    "day_of_week_starts_at"
                                  ],
                                  "day_of_week_starts_at": [
                                    "day_of_week_ends_at"
                                  ],
                                  "date_ends_at": [
                                    "date_starts_at"
                                  ],
                                  "date_starts_at": [
                                    "date_ends_at"
                                  ]
                                }
                              }
                            }
                          },
                          "required" : [
                            "name",
                            "price",
                            "provider_id",
                            "universal_id"
                          ]
                        }
                      },
                      "required": [
                        "item"
                      ]
                    }
                  },
                  "timescopes": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "title": "timescope",
                      "properties": {
                        "time_of_day_starts_at": {
                          "type": "string"
                        },
                        "time_of_day_ends_at": {
                          "type": "string"
                        },
                        "day_of_week_starts_at": {
                          "type": "string"
                        },
                        "day_of_week_ends_at": {
                          "type": "string"
                        },
                        "date_starts_at": {
                          "type": "string"
                        },
                        "date_ends_at": {
                          "type": "string"
                        }
                      },
                      "dependencies": {
                        "time_of_day_ends_at": [
                          "time_of_day_starts_at"
                        ],
                        "time_of_day_starts_at": [
                          "time_of_day_ends_at"
                        ],
                        "day_of_week_ends_at": [
                          "day_of_week_starts_at"
                        ],
                        "day_of_week_starts_at": [
                          "day_of_week_ends_at"
                        ],
                        "date_ends_at": [
                          "date_starts_at"
                        ],
                        "date_starts_at": [
                          "date_ends_at"
                        ]
                      }
                    }
                  }
                },
                "required": [
                  "items",
                  "name",
                  "provider_id",
                  "universal_id"
                ]
              }
            }
          }
        },
        "category_groups": {
          "type": "array",
          "items": {
            "description": "A collection into which a category fits (e.g. Beverages)",
            "type": "object",
            "properties": {
              "category_group": {
                "type": "object",
                "properties": {
                  "description": {
                    "description": "A description of the category group scraped from the provider",
                    "type": "string"
                  },
                  "display_order": {
                    "description": "Order in which to display the category group",
                    "type": "integer"
                  },
                  "name": {
                    "description": "The name of the category group (e.g. Beverages)",
                    "type": "string"
                  },
                  "provider_id": {
                    "description": "A unique ID (or XPath selector) for this element",
                    "type": "string"
                  },
                  "universal_id": {
                    "description": "A unique ID (or XPath selector) for this category group across all merchant's locations",
                    "type": "string"
                  },
                  "timescopes": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "title": "timescope",
                      "properties": {
                        "time_of_day_starts_at": {
                          "type": "string"
                        },
                        "time_of_day_ends_at": {
                          "type": "string"
                        },
                        "day_of_week_starts_at": {
                          "type": "string"
                        },
                        "day_of_week_ends_at": {
                          "type": "string"
                        },
                        "date_starts_at": {
                          "type": "string"
                        },
                        "date_ends_at": {
                          "type": "string"
                        }
                      },
                      "dependencies": {
                        "time_of_day_ends_at": [
                          "time_of_day_starts_at"
                        ],
                        "time_of_day_starts_at": [
                          "time_of_day_ends_at"
                        ],
                        "day_of_week_ends_at": [
                          "day_of_week_starts_at"
                        ],
                        "day_of_week_starts_at": [
                          "day_of_week_ends_at"
                        ],
                        "date_ends_at": [
                          "date_starts_at"
                        ],
                        "date_starts_at": [
                          "date_ends_at"
                        ]
                      }
                    }
                  }
                },
                "required": [
                  "provider_id",
                  "universal_id",
                  "name"
                ]
              }
            }
          }
        },
        "option_groups": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "option_group": {
                "description": "A collection of item options (e.g. Size)",
                "type": "object",
                "properties": {
                  "defaults": {
                    "type": "array",
                    "items": {
                      "description": "The id for an option that is selected by default",
                      "type": "string"
                    }
                  },
                  "display_order": {
                    "description": "Order in which to display the option group",
                    "type": "integer"
                  },
                  "display_type": {
                    "description": "The display type for the option group.",
                    "type": "string",
                    "enum": ["text_dropdown"]
                  },
                  "free_choices": {
                    "description": "The number of options that can be selected without incurring additional charges",
                    "type": "number"
                  },
                  "maximum_choices": {
                    "description": "The maximum number of options from the option group that may be selected",
                    "type": "number"
                  },
                  "maximum_unique_choices": {
                    "description": "The maximum number of unique options from the option group that may be selected",
                    "type": "number"
                  },
                  "minimum_choices": {
                    "description": "The minimum number of options from the option group that may be selected",
                    "type": "number"
                  },
                  "minimum_unique_choices": {
                    "description": "The minimum number of unique options from the option group that may be selected",
                    "type": "number"
                  },
                  "name": {
                    "description": "The name of the option group (e.g. Size)",
                    "type": "string"
                  },
                  "options": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "option": {
                          "description": "A possible option to be applied to a menu item",
                          "type": "object",
                          "properties": {
                            "maximum_quantity": {
                              "description": "The maximum number of the option that may be selected. Note that the minimum quantity is always defaulted to zero",
                              "type": "number"
                            },
                            "default_quantity": {
                              "description": "The default quantity of the option. Defaults to one. Only applicable when a maximum_quantity is given.",
                              "type": "number"
                            },
                            "minimum_quantity": {
                              "description": "The minimum quantity of the option. Defaults to zero.",
                              "type": "number"
                            },
                            "display_order": {
                              "description": "Order in which to display the option",
                              "type": "integer"
                            },
                            "metadata": {
                              "description": "Additional data about the option. Any keys prefixed with 'integration_' will be passed back to the provider during order validation and submission",
                              "type": "object"
                            },
                            "name": {
                              "description": "The name of the option (e.g. 16oz)",
                              "type": "string"
                            },
                            "image": {
                              "description": "The URL for an image associated with the option",
                              "type": "string"
                            },
                            "option_groups": {
                              "type": "array",
                              "items": {
                                "description": "The id for a parent option",
                                "type": "string"
                              }
                            },
                            "price": {
                              "description": "The cost of adding the option in cents",
                              "type": "number"
                            },
                            "provider_id": {
                              "description": "A unique ID (or XPath selector) for this element",
                              "type": "string"
                            },
                            "tax_rate": {
                              "description": "The tax rate to be applied to this option",
                              "type": "number"
                            },
                            "universal_id": {
                              "description": "A unique ID (or XPath selector) for this option across all merchant's locations",
                              "type": "string"
                            },
                            "timescopes": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "title": "timescope",
                                "properties": {
                                  "time_of_day_starts_at": {
                                    "type": "string"
                                  },
                                  "time_of_day_ends_at": {
                                    "type": "string"
                                  },
                                  "day_of_week_starts_at": {
                                    "type": "string"
                                  },
                                  "day_of_week_ends_at": {
                                    "type": "string"
                                  },
                                  "date_starts_at": {
                                    "type": "string"
                                  },
                                  "date_ends_at": {
                                    "type": "string"
                                  }
                                },
                                "dependencies": {
                                  "time_of_day_ends_at": [
                                    "time_of_day_starts_at"
                                  ],
                                  "time_of_day_starts_at": [
                                    "time_of_day_ends_at"
                                  ],
                                  "day_of_week_ends_at": [
                                    "day_of_week_starts_at"
                                  ],
                                  "day_of_week_starts_at": [
                                    "day_of_week_ends_at"
                                  ],
                                  "date_ends_at": [
                                    "date_starts_at"
                                  ],
                                  "date_starts_at": [
                                    "date_ends_at"
                                  ]
                                }
                              }
                            }
                          },
                          "required": [
                            "name",
                            "price",
                            "provider_id",
                            "universal_id"
                          ]
                        }
                      }
                    }
                  },
                  "provider_id": {
                    "description": "A unique ID (or XPath selector) for this option group",
                    "type": "string"
                  },
                  "universal_id": {
                    "description": "A unique ID (or XPath selector) for this option group across all merchant's locations",
                    "type": "string"
                  },
                  "timescopes": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "title": "timescope",
                      "properties": {
                        "time_of_day_starts_at": {
                          "type": "string"
                        },
                        "time_of_day_ends_at": {
                          "type": "string"
                        },
                        "day_of_week_starts_at": {
                          "type": "string"
                        },
                        "day_of_week_ends_at": {
                          "type": "string"
                        },
                        "date_starts_at": {
                          "type": "string"
                        },
                        "date_ends_at": {
                          "type": "string"
                        }
                      },
                      "dependencies": {
                        "time_of_day_ends_at": [
                          "time_of_day_starts_at"
                        ],
                        "time_of_day_starts_at": [
                          "time_of_day_ends_at"
                        ],
                        "day_of_week_ends_at": [
                          "day_of_week_starts_at"
                        ],
                        "day_of_week_starts_at": [
                          "day_of_week_ends_at"
                        ],
                        "date_ends_at": [
                          "date_starts_at"
                        ],
                        "date_starts_at": [
                          "date_ends_at"
                        ]
                      }
                    }
                  },
                  "required": [
                    "name",
                    "options",
                    "provider_id",
                    "universal_id"
                  ]
                }
              }
            },
            "required": [
              "option_group"
            ]
          }
        }
      },
      "required": [
        "allows_special_instructions",
        "categories",
        "name",
        "option_groups",
        "provider_id",
        "universal_id",
        "updated_at"
      ]
    }
  }
}
Name Type Description
menu[provider_id] String A unique string that identifies the menu.
menu[name] String The title of the menu (e.g. Burger King Summer St).
category[provider_id] String A unique string that identifies the category.
category[universal_id] String A unique string that identifies the category across all merchant’s locations.
category[name] String The category’s name.
category[description] String, null The category’s description, if it has one.
category[category_group] String, null The ID of the category’s category group, if it has one.
category[display_order] Integer, null The order in which to display this category
category_group[provider_id] String A unique string that identifies the category group.
category_group[universal_id] String A unique string that identifies the category group across all merchant’s locations.
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, null The order in which to display this category group
item[provider_id] String A unique string that identifies the item.
item[universal_id] String A unique string that identifies the item across all merchant’s locations.
item[name] String The item’s name.
item[description] String, null The item’s description, if it has one.
item[price] 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[image] String, null A URL to the item’s image, if it has one. See the Show Menu Item Image endpoint for details.
item[option_groups] Array of strings The IDs for the option groups that the item includes.
item[nutrition] Object Refer to JSON schema above for full list of allowed keys.
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[display_order] Integer, null The order in which to display this item
item[maximum_quantity] Integer, null The maximum number of the item that may be selected.
item[minimum_quantity] Integer, null The minimum number of the item that may be selected.
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[provider_id] String A unique string that identifies the option group.
option_group[universal_id] String A unique string that identifies the option group across all merchant’s locations.
option_group[name] String The option group’s name.
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[maximum_
unique_choices]
Integer The maximum number of unique options the user must choose for this option group.
option_group[minimum_
choices]
Integer The minimum number of options the user must choose for this option group.
option_group[minimum_
unique_choices]
Integer The minimum number of unique options the user must choose for this option group.
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[defaults] Array of strings 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_group[display_order] Integer, null The order in which to display this option group
option[provider_id] String A unique string that identifies the option.
option[universal_id] String A unique string that identifies the option across all merchant’s locations.
option[name] String The option’s name.
option[option_groups] Array of strings The IDs for the option groups that the parent option includes.
option[image] String, null A URL to the option’s image, if it has one.
option[price] Integer The option’s price in cents, independent of the base price of any associated item. May be zero.
option[tax_rate] Float, null The tax rate to be applied to this option, e.g., 0.099 would mean a 9.9% tax rate on the option.
option[display_order] Integer, null The order in which to display this option
option[maximum_quantity] Integer The maximum number of the option that may be selected.
option[default_quantity] Integer The default number of the option that may be selected. Defaults to one and only applicable when a maximum_quantity is given.
option[minimum_quantity] Integer The minimum number of the option that may be selected.
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.

Our core menu format is comprised of the following entities:

  • General Information: LevelUp requires some top-level information about menus such as whether or not special instructions are allowed on orders and a name for the menu.

  • Categories: A category is a collection of items. I.E. a category like “Smoothies” might contain the following items: “Banana Smoothie”, “Strawberry Coolatta” and “Raspberry Fusion”. All menus have categories. Categories never have a price. Categories may have an optional attribute of a category group.

  • Category Groups: A category group is a collection into which a category fits. I.E. the following categories “Soft Drinks”, “Smoothies” and “Fresh Juices” might all have a category group of “Beverages”. Not all menus have category groups. If a category does not belong to a category group, simply don’t include a category group attribute under the category. Category groups never have a price. If some categories are under a category group and others are not, only fill out the category group attribute for those that have it.

  • Items: An item is a specific thing on a menu, that is included in categories and can have zero, one or many option groups. In the category “Smoothies”, one of the items might be “Banana Smoothie” and it might have options that allow for the customization of certain aspects of that item like “Size”, “Mix-Ins” or “Quantity”. Items always have prices, though the base price of an item might be $0 if the cost is derived entirely from its options. Items either allow for special instructions or don’t. Special instructions can have an optional character limit – if none is available, set the attribute value to null and LevelUp defaults to 120. You may include images for items, as well as nutrition information if available. You may include optional metadata along with each item. Any metadata keys that begin with “integration_” will be passed back on order validate and order submit requests.

  • Option Groups: An option group is a collection of options. Option groups always have a parent entity, that is either an item, or an option in another option group. For example, “Size” would be an option group with a parent that is simply the item “Banana Smoothie” and it contains options underneath it such as “8 oz”, “12 oz” and “16 oz”. Let’s say that if the user selected 16 oz, they also got to pick their cup’s design. That would be yet another option group, this time with a parent being the 16 oz option. I.E. “Cup Design” would be an option group, with a parent entity of “16 oz” and with options of “Toy Story Themed”, “Superman Themed” or “Star Wars Themed”. Option groups never have a price themselves, only the options have a price. Each option group also has validations that need to be gathered from the menu, i.e. “Select only 1” or “Pick at least 3.” or “Pick As Many As You Want, First One Free”, or “Pick at most 3 unique options”. The format for these requirements is described in LevelUp’s JSON menu structure.

  • Nested Options: Please note that LevelUp will return options in a “flattened” fashion in our order validation and order submission requests. So if you believe that a given item will require that options be presented in a nested fashion, you will need to encode that nesting logic into your option ids, using some delimiter such as “:” or “-”. I.E. parentoptiongroup:option_id so that you can parse it back out as needed. You can also include optional metadata along with each item, which can contain the appropriate nesting which we will echo back to you.

  • Options: Options are the items contained within option groups. For example, the options in the option group “Size” would be “8 oz”, “12 oz” and “16 oz”. Options can be the parents of other option groups. Options always have a price, even if that price is $0. When a user is able to select multiple of an option, that option can have a maximum_quantity that indicates the maximum number of that option the user can select. For example, for Dunkin Donuts coffee, the user can elect to add sweetener as an option, and then input the quantity that they want. Additionally, options can also have a default_quantity. For example, when sweetener is added to a medium Dunkin Donuts it comes default with (3) sweetener. When a default_quantity is not given, it will be assumed to be (1). Options have may nutrition information associated with them.

Additional description of certain attributes:

  • Nutrition: This property is optional but should be included whenever possible.

  • Menu Name: You can title your menu name as “Merchant_Name [Provider_Name]”. I.E. “Joe’s Coffee Shop [Revel]”.

  • Timescopes: This is a list of Timescope objects that are applied to the parent menu object. Timescopes are optional, and should not be provided or null if the menu object is always available, or if a Timescope is not determinable. See the “Timescopes and Partially Available Items” sub-section below for a more in-depth description of a Timescope object.

  • Defaults: Defaults should be passed back along with any option_group to let us know which are the options defaulted to true (i.e. preselected) on a given item. LevelUp will display these within our mobile UI as pre-checked and, assuming the user does not uncheck them, echo them back as normally selected options in the validate/submit call.

  • Universal IDs: These IDs should be uniquely defined for each menu component by a merchant/provider across all merchant locations. There is NOT a 1:1 relationship between universal_id & parsed menu components:

    • e.g. a single item or option may be repeated numerous times in our menu such as an item in multiple categories or an option applied to multiple items
    • Jumbo Juicy burger has the same universal_id regardless of how many times it appears in our parsed menu (‘jumbo-juicy-uid’)
  • Metadata: Items and options both include a metadata object which can be used to pass us additional data. The values in a metadata object must only be strings. Any metadata keys prefixed with “integration_” will be returned on order validate and submit requests. This makes metadata especially useful for storing information that is required to select the item or option during order validation or submission, but cannot be included in the provider_id.

  • Other Notes:

    • IDs should, whenever possible, be persistent across menu refreshes.
    • IDs generally only need to be unique enough for you to be able to find the item again, since LevelUp returns item and options with their parent ids (such as categories, category groups or option_groups for options) included in the post. However, we do flatten all options under the top-level item, so if IDs for options are shared within the same item, you will have to make them unique for us.
    • If a category involves catering option, please always leave it out, unless explicitly requested by the merchant to include it within LevelUp. We don’t by default include any catering options.
    • Please be sure to return the categories, items, option groups, options in the order they are listed on the underlying menu. The sequence of things on a menu is something a merchant tends to put a lot of thought into to design it to be best suited for consumer habits. We want to make sure to respect/replicate that.
    • If special instructions are false, character count should be set to null.
    • Option groups have two sets of validations, namely minimum_choices/maximum_choices and minimum_unique_choices/maximum_unique_choices. The former is validated against the total quantity across all options a user selects, with each option defaulting to a quantity of (1). The latter is validated against the unique set of options a user selects for that option group, disregarding option quantities. For example, if for the option group “Select your bagels” a user selects 3x Plain and 3x Blueberry, their choices would be (6) and unique choices (2).
    • If an option group is for text options (e.g., Ketchup: Light, Medium, or Heavy), then set display_type to text_dropdown, which will display the options as a dropdown instead of a radio list.

Timescopes and Partially Available Items:

A Timescope object is used to specify when a menu object is available on the menu and can be ordered. The following menu objects support Timescopes: Categories, category groups, items, options and option groups.

A single object is composed of 3 sets of fields:

  • time_of_day_[starts|ends]_at - String in ISO 8601 Format (h:mm or hh:mm only, do not provide timezone information we assume the implied timezone is specific to that location) representing the hour and minute of a day the item is available. All times should be in the same timezone as the restaurant location. Set to null if available all day.

  • day_of_week_[starts|ends]_at - String (values: “Monday” through “Sunday” only, without the quotes) representing the days of the week, that the item is available. Set to null if available all week.

  • date_[starts|ends]_at - String in ISO 8601 Format (YYYY-MM-DD only) representing the calendar date range that the item is available, inclusive. Set to null if unknown/available all year.

Each set is optional. For example, you can specify time_of_day_starts_at and time_of_day_ends_at without specifying the other sets to indicate the item is available during a certain period of the day, every day of the week, all year.

In the menu JSON each menu object can have a list of Timescope objects associated with it (this list is named “timescopes”). The list format is used to allow multiple availability periods (e.g. Mon 9-11 AM, Wed 9-11AM and Fri 9-11AM) to be specified for a specific object.

Example Timescopes list specifying that a particular breakfast sandwich is only available from 9-1130am on Mon, Wed, Fri:

"timescopes": [
  {
    "time_of_day_ends_at" : "11:30",
    "time_of_day_starts_at" : "9:00",
    "day_of_week_ends_at" : "Monday",
    "day_of_week_starts_at" : "Monday",
    "date_ends_at" : null,
    "date_starts_at" : null
  },
  {
    "time_of_day_ends_at" : "11:30",
    "time_of_day_starts_at" : "9:00",
    "day_of_week_ends_at" : "Wednesday",
    "day_of_week_starts_at" : "Wednesday",
    "date_ends_at" : null,
    "date_starts_at" : null
  },
  {
    "time_of_day_ends_at" : "11:30",
    "time_of_day_starts_at" : "9:00",
    "day_of_week_ends_at" : "Friday",
    "day_of_week_starts_at" : "Friday",
    "date_ends_at" : null,
    "date_starts_at" : null
  }
]