NAV
shell

Introduction

Welcome to the Untappd For Business (UTFB) API! You can use our API to access Untappd For Business API endpoints.

Version - /api/v1

For example: /api/v1/sessions

You must prepend /api/v1 to all the endpoints.

Legacy Menus

What is happening?

Within Untappd for Business there are two types of menus: beer menus and custom menus (food, wine, cocktail items). We are consolidating these separate menu types to allow beer and non-beer items to co-exist within the same menu. As a result of consolidating menu types, the the Custom Menu APIs have been deprecated and all menus will now be able to be accessed from a single set of Menu APIs.

What do I need to do?

Replace any usage you have of Custom Menus, Custom Sections, Custom Items, Custom Containers APIs with Menus, Sections, Items, and Containers APIs.

When does this need to be completed by?

All venues will be migrated to the consolidated menu type by May 31, 2023 at which point custom menus will no longer be updated with changes on Untappd for Business.

How can I do this?

In the next sections you can see all the deprecated endpoints that will eventually be removed and a method for migrating off these endpoints before your venue is migrated to the new consolidated menu type.

Deprecated Endpoints

As of February 2023, all of the following API endpoint are deprecated and will be fully removed in October 2023.

Migration

To help ease the migration from Custom Menus we have introduced a new query parameter, include_legacy, that can be used on select Menu, Section, Item, and Container routes (listed below) when retrieving data. This new param allows you to update your API routes away from the deprecated routes above while still being able to load your custom menus, sections, etc prior to your migration to our consolidated menus system.

Supported Endpoints

Below are the old API endpoints that can be migrated to their equivalent new endpoint using the include_legacy parameter to enable fallback. By passing include_legacy you can tell the new endpoint to continue to load as if you called the old endpoint.

Old Endpoint New Endpoint
List all custom menus ➡️ List all menus
Retrieve a custom menu ➡️ Retrieve a menu
List all custom sections ➡️ List all sections
Retrieve a custom section ➡️ Retrieve a section
List all custom items ➡️ List all items
Retrieve a custom item ➡️ Retrieve an item
List all custom containers ➡️ List all containers
Retrieve a custom container ➡️ Retrieve a container

How include_legacy works

When your venue is migrated to our consolidated menus experience we will migrate all your custom menus into the consolidated system and they will then be available under the regular Menu, Section, Item, and Container endpoints. Each migrated menu will contain a reference to the old custom menu identifier to allow us to load the old data for you during your transition.

When you pass include_legacy to a supported endpoint we will attempt to load data in the following way.

  1. Look for a Menu with an id equal to the id provided
  2. Return the Menu if found
  3. Look for a Menu with a legacy_menu_id equal to the id provided
  4. Return the Menu if found
  5. Look for a CustomMenu with an id equal to the id provided
  6. Return the CustomMenu if found
  7. Return an error if nothing was found

TLS Versions

The Untappd API currently supports only TLS v1.2.

Authentication

To base64 encode your email and API token:

printf [email protected]:MySuperAPIToken123 | base64

Outputs:

bmlja0B1bnRhcHBkLmNvbTpNeVN1cGVyQVBJVG9rZW4xMjM=

All requests to the API require either a read only token or a read & write token.

An API token is essentially your password to the API. The API expects the API Token to be included in all requests in a header that looks like the following:

Authorization: Basic bmlja0B1bnRhcHBkLmNvbTpNeVN1cGVyQVBJVG9rZW4xMjM=

You must replace Authorization: Basic bmlja0B1bnRhcHBkLmNvbTpNeVN1cGVyQVBJVG9rZW4xMjM= with your encoded email and API key.

See: https://en.wikipedia.org/wiki/Basic_access_authentication

You can verify the token by sending a request to the current user endpoint

You can find your tokens under the section titled **"API Access Tokens" at: https://business.untappd.com/account.**

Alternatively, you may use the /sessions routes below to programmatically fetch your API tokens. Please do not hit the /sessions route for every request! We rate limit it so your requests will fail! The POST /sessions route should ideally only ever be used once to initially fetch the token. You can then hard code your API tokens.

API Token Types

There are two types of API tokens.

The Read Only token only allows read access to your data. You cannot modify any of your data using a read only token. Read only tokens should be used in frontend (user facing) applications. For example if you build a custom menu that is embedded on your website. This way you can hard code the token in the web page and not have to worry about a malicious user using your token to change your data.

The Read & Write token allows read and write access to your data. You can modify your data using the read and write token. Read and write tokens should be used only on the backend (non-user facing) integrations. For example if you build an application that works behind the scenes to sync your menus with your point of sale system.

You can find your tokens here: https://business.untappd.com/account.

POST /sessions

To get your API key, use this code:

curl "https://business.untappd.com/api/v1/sessions" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "DrinkMoreBeer"}'

Returns JSON structured like this:

{
  "user": {
    "email": "[email protected]",
    "auth_token": "Rt4688PzSJUSdXZeZLTB",
    "auth_token_read_only": "Kr3514GdHWBYjQBuLHJP"
  }
}

You can get your API key by sending a POST request with a JSON body containing the user's email and password.

The response to the POST request will return the email, auth_token, and auth_token_read_only which must be supplied with every request via the Basic Authorization header.

Reset session

Reset the API key for the currently authorized user.

Request:

curl "https://business.untappd.com/api/v1/sessions" \
  -X DELETE \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="

Returns JSON structured like this:

{ "status": "OK" }

HTTP Request

DELETE https://business.untappd.com/api/v1/sessions

Analytics

Track an event

Track an event for location analytics. These events are aggregated and displayed as part of the analytics dashboard.

If you are building a custom embedded menu on your website using this api then you should hit this endpoint every time your menu is loaded by a visitor of your website to track the menu view.

curl "http://localhost:3000/api/v1/locations/3/analytics?source_name=iPhoneApp" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="

Returns JSON structured like this:

{ "status" : "OK" }

HTTP Request

GET https://business.untappd.com/api/v1/locations/:location_id/analytics

Query Parameters

Parameter Validations Required Description
location_id Integer true The location to record the event for.
source_name Integer true The source of the event. This is used to group and label events on the analytics dashboard.
Defaults to: API.
e.g. API, HomePage, MobileApp

Container Sizes

In order to set a container on an item, you must know the container_size.id.

The index route here will give you all the possible container sizes to present to a user. We use a select field on business.untappd.com.

Container Size Object

Property Type Description
created_at timestamp Time at which the ContainerSize was created. ISO8601 format.
id integer Unique identifier for the ContainerSize
name string Name of the ContainerSize
ounces float Number of ounces the ContainerSize holds
position integer The position of the ContainerSize in the list of ContainerSizes. Positions start at zero and should be contiguous.
updated_at timestamp Time at which the ContainzerSize was last updated. ISO8601 format.

List all container sizes

Request:

curl "http://localhost:3000/api/v1/container_sizes" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="

Returns JSON structured like this:

{
  "container_sizes": [
    {
      "id": 94,
      "name": "1oz Draft",
      "ounces": "1.0",
      "position": 0,
      "created_at": "2016-06-01T16:26:07.206217Z",
      "updated_at": "2017-01-30T16:11:56.740164Z"
    },
    {
      "id": 116,
      "name": "1.5oz Draft",
      "ounces": "1.5",
      "position": 1,
      "created_at": "2016-07-01T19:05:30.941985Z",
      "updated_at": "2017-01-30T16:11:56.538908Z"
    },
    {
      "id": 93,
      "name": "2oz Draft",
      "ounces": "2.0",
      "position": 2,
      "created_at": "2016-06-01T16:26:07.206217Z",
      "updated_at": "2016-07-01T19:36:38.267600Z"
    },
    {
      "id": 127,
      "name": "2.5oz Draft",
      "ounces": "2.5",
      "position": 3,
      "created_at": "2016-07-26T19:30:18.883625Z",
      "updated_at": "2016-08-01T19:43:50.743959Z"
    },
    {
      "id": 34,
      "name": "3oz Draft",
      "ounces": "3.0",
      "position": 4,
      "created_at": "2016-03-01T15:36:26.000000Z",
      "updated_at": "2016-08-01T19:43:50.763425Z"
    }
  ]
}

Returns a list of all container sizes. This list is likely to be added to in the future. A given container size will most likely never be removed.

HTTP Request

GET https://business.untappd.com/api/v1/container_sizes

Containers

Container Object

Property Type Description
_track_by integer
calories integer Number of calories for the Container
container_size_id integer ContainerSize identifier. See: ContainerSize.
container_size ContainerSize The ContainerSize for the Container
created_at timestamp Time at which the Container was created. ISO8601 format.
currency string Currency used for the price of the Container. ISO 4217 3-letter code.
id integer Unique identifier for the Container
item_id integer Item id that the Container belongs to. See Item.
name string Name of the Container
position integer The position of the Container in the list of Containers for the Item. Positions start at zero and should be contiguous.
price float Price for the Container. Currency is determined by the currency property.
updated_at timestamp Time at which the Container was last updated. ISO8601 format.

List all containers

Returns a list of containers belonging to an item.

Request:

curl "http://localhost:3000/api/v1/items/64/containers" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ="

Returns JSON structured like this:

{
  "containers": [
    {
      "id": 118,
      "item_id": 64,
      "container_size_id": 18,
      "price": "7.00",
      "position": 0,
      "container_size": {
        "id": 18,
        "name": "20oz Draft",
        "position": 21,
        "created_at": "2016-03-01T15:36:26.000Z",
        "updated_at": "2016-08-24T20:52:06.390Z",
        "container_size_group_id": 2,
        "ounces": "20.0"
      },
      "created_at": "2023-03-21T13:04:40.317030Z",
      "updated_at": "2023-03-21T13:04:40.317030Z",
      "_track_by": 118,
      "calories": "180.0",
      "name": "20oz Draft",
      "currency": "USD"
    }
  ]
}

HTTP Request

GET https://business.untappd.com/api/v1/items/:item_id/containers

Query Parameters

Parameter Validations Required Description
item_id Integer true The id of the item.
build true or not set false Add a blank container (not yet persisted) to the response. This is useful when you have a reactive frontend that fetches all the containers and provides fields for a new one to be added.
include_legacy Boolean false Enables legacy container fallback. See Legacy Migration

Create a container

Add a new container to an item.

Request:

curl "http://localhost:3000/api/v1/items/64/containers" \
  -X POST \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ=" \
  -H "Content-Type: application/json" \
  -d '{ "container": { "container_size_id": 18, "price": 7.00 } }'

Returns JSON structured like this:

{
  "container": {
    "id": 118,
    "item_id": 64,
    "container_size_id": 18,
    "price": "7.00",
    "position": 0,
    "container_size": {
      "id": 18,
      "name": "20oz Draft",
      "position": 21,
      "created_at": "2016-03-01T15:36:26.000Z",
      "updated_at": "2016-08-24T20:52:06.390Z",
      "container_size_group_id": 2,
      "ounces": "20.0"
    },
    "created_at": "2023-03-21T13:04:40.317030Z",
    "updated_at": "2023-03-21T13:04:40.317030Z",
    "_track_by": 118,
    "calories": "180.0",
    "name": "20oz Draft",
    "currency": "USD"
  }
}

HTTP Request

POST https://business.untappd.com/api/v1/items/:item_id/containers

Query Parameters

Parameter Validations Required Description
item_id Integer true The id of the item.
container_size_id Integer true id of the container size. See: Container Sizes.
price Float true Price of the container size for an item.

Retrieve a container

Retrieve the details of an existing container. You need only supply the unique container identifier that was returned upon container creation.

Request:

curl "http://localhost:3000/api/v1/containers/118" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ="

Returns JSON structured like this:

{
  "container": {
    "id": 118,
    "item_id": 64,
    "container_size_id": 18,
    "price": "7.00",
    "position": 0,
    "container_size": {
      "id": 18,
      "name": "20oz Draft",
      "position": 21,
      "created_at": "2016-03-01T15:36:26.000Z",
      "updated_at": "2016-08-24T20:52:06.390Z",
      "container_size_group_id": 2,
      "ounces": "20.0"
    },
    "created_at": "2023-03-21T13:04:40.317030Z",
    "updated_at": "2023-03-21T13:04:40.317030Z",
    "_track_by": 118,
    "calories": "180.0",
    "name": "20oz Draft",
    "currency": "USD"
  }
}

HTTP Request

GET https://business.untappd.com/api/v1/containers/:id

Query Parameters

Parameter Validations Required Description
id Integer true The id of the container.
include_legacy Boolean false Enables legacy container fallback. See Legacy Migration

Update a container

Updates the specified container by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Request:

curl "http://localhost:3000/api/v1/containers/118" \
  -X PATCH \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ=" \
  -H "Content-Type: application/json" \
  -d '{ "container": { "price": 2.99, "position": 1 } }'

Returns JSON structured like this:

{
  "container": {
    "id": 118,
    "item_id": 64,
    "container_size_id": 18,
    "price": "2.99",
    "position": 1,
    "container_size": {
      "id": 18,
      "name": "20oz Draft",
      "position": 21,
      "created_at": "2016-03-01T15:36:26.000Z",
      "updated_at": "2016-08-24T20:52:06.390Z",
      "container_size_group_id": 2,
      "ounces": "20.0"
    },
    "created_at": "2023-03-21T13:04:40.317030Z",
    "updated_at": "2023-03-21T13:04:40.317030Z",
    "_track_by": 118,
    "calories": "180.0",
    "name": "20oz Draft",
    "currency": "USD"
  }
}

HTTP Request

PUT https://business.untappd.com/api/v1/containers/:id PATCH https://business.untappd.com/api/v1/containers/:id

Query Parameters

Parameter Validations Required Description
id Integer true The id of the container.
container_size_id Integer true id of the container size. See: Container Sizes.
price Integer true Price of the container size for an item.
position Integer false The position of the container in the list of containers for the item. Positions start at zero and should be contiguous.

Delete a container

Permanently deletes a container. It cannot be undone.

Request:

curl "http://localhost:3000/api/v1/containers/118" \
  -X DELETE \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ="

Returns the deleted container as JSON structured like this:

{
  "container": {
    "id": 118,
    "item_id": 64,
    "container_size_id": 18,
    "price": "7.00",
    "position": 0,
    "container_size": {
      "id": 18,
      "name": "20oz Draft",
      "position": 21,
      "created_at": "2016-03-01T15:36:26.000Z",
      "updated_at": "2016-08-24T20:52:06.390Z",
      "container_size_group_id": 2,
      "ounces": "20.0"
    },
    "created_at": "2023-03-21T13:04:40.317030Z",
    "updated_at": "2023-03-21T13:04:40.317030Z",
    "_track_by": 118,
    "calories": "180.0",
    "name": "20oz Draft",
    "currency": "USD"
  }
}

HTTP Request

DELETE https://business.untappd.com/api/v1/containers/:id

Query Parameters

Parameter Validations Required Description
id Integer true The container to be deleted.

Current User

The current user belonging to the auth token.

Returns JSON structured like this:

{
  "current_user": {
    "id": 1,
    "email": "[email protected]",
    "created_at": "2016-01-06T19:12:06Z",
    "updated_at": "2016-06-15T14:16:36Z",
    "role": "owner",
    "admin": false,
    "business_id": 1,
    "untappd_username": "starbuck",
    "name": "Kara"
  }
}

HTTP Request

GET https://business.untappd.com/api/v1/current_user

Custom Containers [Deprecated]

List all custom containers

Returns a list of custom containers belonging to a custom item.

Request:

curl "http://localhost:3000/api/v1/custom_items/2/custom_containers" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ="

Returns JSON structured like this:

{
  "custom_containers": [
    {
      "id": 2,
      "custom_item_id": 2,
      "name": "1 glass",
      "price": "8.95",
      "position": 0,
      "_track_by": 2,
      "created_at": "2016-11-14T16:06:00Z",
      "updated_at": "2016-11-14T16:06:12Z"
    },
    {
      "id": 3,
      "custom_item_id": 2,
      "name": "1 bottle",
      "price": "38.95",
      "position": 1,
      "_track_by": 3,
      "created_at": "2016-11-14T16:06:09Z",
      "updated_at": "2016-11-14T16:06:09Z"
    }
  ]
}

HTTP Request

GET https://business.untappd.com/api/v1/custom_items/:custom_item_id/custom_containers

Query Parameters

Parameter Validations Required Description
item_id Integer true The id of the custom item.
build true or not set false Add a blank custom container (not yet persisted) to the response. This is useful when you have a reactive frontend that fetches all the custom containers and provides fields for a new one to be added.

Create a custom container

Add a new custom container to a custom item.

Request:

curl "http://localhost:3000/api/v1/custom_items/2/custom_containers" \
  -X POST \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ=" \
  -H "Content-Type: application/json" \
  -d '{ "custom_container": { "name": "Tall glass", "price": 5.99 } }'

Returns JSON structured like this:

{
  "custom_container": {
    "id": 4,
    "custom_item_id": 2,
    "name": "Tall glass",
    "price": "5.99",
    "position": 0,
    "_track_by": 4,
    "created_at": "2016-11-14T16:07:01Z",
    "updated_at": "2016-11-14T16:07:01Z"
  }
}

HTTP Request

POST https://business.untappd.com/api/v1/custom_items/:custom_item_id/custom_containers

Query Parameters

Parameter Validations Required Description
custom_item_id Integer true The id of the custom_item.
name String false Name of the custom container.
price Float true Price of the custom container.

Retrieve a custom container

Retrieve the details of an existing custom container. You need only supply the unique custom container identifier that was returned upon custom container creation.

Request:

curl "http://localhost:3000/api/v1/custom_containers/2" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ="

Returns JSON structured like this:

{
  "custom_container": {
    "id": 2,
    "custom_item_id": 2,
    "name": "1 glass",
    "price": "8.95",
    "position": 1,
    "_track_by": 2,
    "created_at": "2016-11-14T16:06:00Z",
    "updated_at": "2016-11-14T16:06:12Z"
  }
}

HTTP Request

GET https://business.untappd.com/api/v1/custom_containers/:id

Query Parameters

Parameter Validations Required Description
id Integer true The id of the custom container.

Update a custom container

Updates the specified custom container by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Request:

curl "http://localhost:3000/api/v1/custom_containers/2" \
  -X PATCH \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ=" \
  -H "Content-Type: application/json" \
  -d '{ "custom_container": { "price": 7.99 } }'

Returns JSON structured like this:

{
  "custom_container": {
    "id": 2,
    "custom_item_id": 2,
    "name": "1 glass",
    "price": "7.99",
    "position": 1,
    "_track_by": 2,
    "created_at": "2016-11-14T16:06:00Z",
    "updated_at": "2016-11-14T16:07:47Z"
  }
}

HTTP Request

PUT https://business.untappd.com/api/v1/custom_containers/:id PATCH https://business.untappd.com/api/v1/custom_containers/:id

Query Parameters

Parameter Validations Required Description
id Integer true The id of the container.
name String false Name of the custom container.
price Float true Price of the custom container.
position Integer false The position of the custom container in the list of custom containers for the custom item. Positions start at zero and should be contiguous.

Delete a custom container

Permanently deletes a custom container. It cannot be undone.

Request:

curl "http://localhost:3000/api/v1/custom_containers/2" \
  -X DELETE \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ="

Returns the deleted custom container as JSON structured like this:

{
  "custom_container": {
    "id": 2,
    "custom_item_id": 2,
    "name": "1 glass",
    "price": "7.99",
    "position": 1,
    "_track_by": 2,
    "created_at": "2016-11-14T16:06:00Z",
    "updated_at": "2016-11-14T16:07:47Z"
  }
}

HTTP Request

DELETE https://business.untappd.com/api/v1/custom_containers/:id

Query Parameters

Parameter Validations Required Description
id Integer true The custom container to be deleted.

Custom Item Types [Deprecated]

In order to set a type on a custom item, you must know the custom_item_type_id from: custom_item_type.id.

The index route here will give you all the possible custom item types to present to a user. We use a select field on business.untappd.com.

List all custom item types

Request:

curl "http://localhost:3000/api/v1/custom_item_types" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="

Returns JSON structured like this:

{
  "custom_item_types": [
    {
      "id": 1,
      "name": "wine",
      "position": 0,
      "created_at": "2016-09-29T16:49:33Z",
      "updated_at": "2016-09-29T16:49:33Z"
    },
    {
      "id": 3,
      "name": "food",
      "position": 1,
      "created_at": "2016-09-29T16:49:33Z",
      "updated_at": "2016-09-29T18:52:01Z"
    },
    {
      "id": 2,
      "name": "cocktail",
      "position": 2,
      "created_at": "2016-09-29T16:49:33Z",
      "updated_at": "2016-09-29T18:52:01Z"
    }
  ]
}

Returns a list of all custom item types. This list is likely to be added to in the future. A given custom item type will most likely never be removed.

HTTP Request

GET https://business.untappd.com/api/v1/custom_item_types

Custom Items [Deprecated]

List all custom items

Returns a list of custom items belonging to a custom section.

Request:

curl "http://localhost:3000/api/v1/custom_sections/1/custom_items" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="

Returns JSON structured like this:

{
  "custom_items": [
    {
      "id": 3,
      "custom_section_id": 1,
      "position": 0,
      "name": "Old Fashioned",
      "description": "Bitters and all.",
      "type": "cocktail",
      "custom_item_type_id": 2,
      "image_url_for_type": "//s3.amazonaws.com/woof.nextglass.co/custom_item_type_images_production/36b7fa2ac48d10381ec79332cb5e5d6ef13e392a-custom-item-type-image.png",
      "created_at": "2016-09-29T17:04:59Z",
      "updated_at": "2016-09-29T18:48:08Z"
    },
    {
      "id": 2,
      "custom_section_id": 1,
      "position": 1,
      "name": "A glass of house red",
      "description": "Made from grapes.",
      "type": "wine",
      "custom_item_type_id": 1,
      "image_url_for_type": "//s3.amazonaws.com/woof.nextglass.co/custom_item_type_images_production/36b7fa2ac48d10381ec79332cb5e5d6ef13e392b-custom-item-type-image.png",
      "created_at": "2016-09-29T17:04:58Z",
      "updated_at": "2016-09-29T18:48:15Z"
    },
    {
      "id": 1,
      "custom_section_id": 1,
      "position": 2,
      "name": "Cheese Platter",
      "description": "Delightful and delicious.",
      "type": "food",
      "custom_item_type_id": 3,
      "image_url_for_type": "//s3.amazonaws.com/woof.nextglass.co/custom_item_type_images_production/36b7fa2ac48d10381ec79332cb5e5d6ef13e392c-custom-item-type-image.png",
      "created_at": "2016-09-29T17:04:56Z",
      "updated_at": "2016-09-29T18:48:19Z"
    }
  ]
}

HTTP Request

GET https://business.untappd.com/api/v1/custom_sections/:custom_section_id/custom_items

Query Parameters

Parameter Validations Required Description
custom_section_id Integer true The section to list the items for.

Create a custom item

Creates a new custom item.

Request:

curl "http://localhost:3000/api/v1/custom_sections/1/custom_items" \
  -X POST \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04=" \
  -H "Content-Type: application/json" \
  -d '{ "custom_item": { "name": "A glass of house red", "description": "Made from grapes.", "custom_item_type_id": 1 } }'

Returns all the items for the section (including the new one) as JSON structured like this:

{
  "custom_item": {
    "id": 2,
    "custom_section_id": 1,
    "position": 1,
    "name": "A glass of house red",
    "description": "Made from grapes.",
    "type": "wine",
    "custom_item_type_id": 1,
    "image_url_for_type": "//s3.amazonaws.com/woof.nextglass.co/custom_item_type_images_production/36b7fa2ac48d10381ec79332cb5e5d6ef13e392b-custom-item-type-image.png",
    "created_at": "2016-09-29T17:04:58Z",
    "updated_at": "2016-09-29T18:48:15Z"
  }
}

HTTP Request

POST https://business.untappd.com/api/v1/custom_sections/:custom_section_id/custom_items

Query Parameters

Parameter Validations Required Description
custom_section_id Integer true The custom section to add the custom item to.
name String false The custom item name.
description String false The custom item description.
type wine/cocktail/food true The custom item type.

Retrieve a custom item

Retrieve the details of an existing custom item. You need only supply the unique custom item identifier that was returned upon custom item creation.

Request:

curl "http://localhost:3000/api/v1/custom_items/2" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="

Returns JSON structured like this:

{
  "custom_item": {
    "id": 2,
    "custom_section_id": 1,
    "position": 1,
    "name": "A glass of house red",
    "description": "Made from grapes.",
    "type": "wine",
    "custom_item_type_id": 1,
    "image_url_for_type": "//s3.amazonaws.com/woof.nextglass.co/custom_item_type_images_production/36b7fa2ac48d10381ec79332cb5e5d6ef13e392b-custom-item-type-image.png",
    "created_at": "2016-09-29T17:04:58Z",
    "updated_at": "2016-09-29T18:48:15Z"
  }
}

HTTP Request

GET https://business.untappd.com/api/v1/custom_items/:id

Query Parameters

Parameter Validations Required Description
id Integer true The id of the custom item.
name String false The custom item name.
description String false The custom item description.
type wine/cocktail/food true The custom item type.

Update a custom item

Updates the specified custom item by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Request:

curl "http://localhost:3000/api/v1/custom_items/2" \
  -X PATCH \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04=" \
  -H "Content-Type: application/json" \
  -d '{ "custom_item": { "name": "Sangria", "description": "Fruit, Sweetened", "custom_item_type_id": 2 } }'

Returns JSON structured like this:

{
  "custom_item": {
    "id": 2,
    "custom_section_id": 1,
    "position": 1,
    "name": "Sangria",
    "description": "Fruit, Sweetened",
    "type": "cocktail",
    "custom_item_type_id": 2,
    "image_url_for_type": "//s3.amazonaws.com/woof.nextglass.co/custom_item_type_images_production/36b7fa2ac48d10381ec79332cb5e5d6ef13e392b-custom-item-type-image.png",
    "created_at": "2016-09-29T17:04:58Z",
    "updated_at": "2016-09-29T19:22:38Z"
  }
}

HTTP Request

PUT https://business.untappd.com/api/v1/custom_items/:id PATCH https://business.untappd.com/api/v1/custom_items/:id

Query Parameters

Parameter Validations Required Description
id Integer true The id of the item.
name String false The custom item name.
description String false The custom item description.
type wine/cocktail/food true The custom item type.

Delete a custom item

Permanently deletes a custom item. It cannot be undone.

Request:

curl "http://localhost:3000/api/v1/custom_items/1" \
  -X DELETE \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="

Returns the deleted custom item as JSON structured like this:

{
  "custom_item": {
    "id": 1,
    "custom_section_id": 1,
    "position": 2,
    "name": "ccccc",
    "description": "c",
    "type": "wine",
    "custom_item_type_id": 1,
    "image_url_for_type": "//s3.amazonaws.com/woof.nextglass.co/custom_item_type_images_production/36b7fa2ac48d10381ec79332cb5e5d6ef13e392c-custom-item-type-image.png",
    "created_at": "2016-09-29T17:04:56Z",
    "updated_at": "2016-09-29T18:48:19Z"
  }
}

HTTP Request

DELETE https://business.untappd.com/api/v1/custom_items/:id

Query Parameters

Parameter Validations Required Description
id Integer true The custom item to be deleted.

Update custom item positions

Set the positions of custom items in a custom section. Custom item positions are used to order the custom items within a custom section of a published custom menu on a page.

Important!: When updating custom item positions, all custom items for the custom section must be passed and the positions must start at zero. Use List all custom items first to get all the custom items for the custom section.

Request:

curl "http://localhost:3000/api/v1/custom_sections/1/custom_items/positions" \
  -X PATCH \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04=" \
  -H "Content-Type: application/json" \
  -d '{ "custom_items": [{ "id": 2, "position": 1 }, { "id": 3, "position": 0 }] }'

Returns JSON structured like this:

{
  "custom_items": [
    {
      "id": 3,
      "position": 0
    },
    {
      "id": 2,
      "position": 1
    }
  ]
}

HTTP Request

PATCH https://business.untappd.com/api/v1/custom_sections/:custom_section_id/custom_items/positions

Query Parameters

Parameter Validations Required Description
custom_section_id Integer true The custom section to update custom item positions for.
custom_items Array true An Array of Objects. All the custom items for a custom section should be passed as a batch to be update atomically. Unexpected behavior may result otherwise.
id Integer true The custom item id to update the position for.
position Integer true The position to set the custom item at. Custom item positions must start at zero.

Move a custom item to another custom section

Move the specified custom item to another custom section.

Request:

curl "http://localhost:3000/api/v1/custom_items/2/move" \
  -X PATCH \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04=" \
  -H "Content-Type: application/json" \
  -d '{ "custom_item": { "custom_section_id": 3 } }'

Returns JSON structured like this:

{
  "custom_item": {
    "id": 2,
    "custom_section_id": 3,
    "position": 0,
    "name": "Sangria",
    "description": "Fruit, Sweetened",
    "type": "cocktail",
    "custom_item_type_id": 2,
    "image_url_for_type": "//s3.amazonaws.com/woof.nextglass.co/custom_item_type_images_production/36b7fa2ac48d10381ec79332cb5e5d6ef13e392b-custom-item-type-image.png",
    "created_at": "2016-09-29T17:04:58Z",
    "updated_at": "2016-09-29T19:25:51Z"
  }
}

HTTP Request

PATCH https://business.untappd.com/api/v1/custom_items/:id/move

Query Parameters

Parameter Validations Required Description
id Integer true The id of the custom item.
custom_section_id Integer true The custom_section_id of the custom section to move the custom item to.

Custom Menus [Deprecated]

List all custom menus

Returns a list of custom menus belonging to your location.

Request:

curl "http://localhost:3000/api/v1/locations/3/custom_menus" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0="

Returns JSON structured like this:

{
  "custom_menus": [
    {
      "id": 1,
      "location_id": 3,
      "name": "Wine selection",
      "description": "",
      "unpublished": true,
      "created_at": "2016-09-26T20:10:37Z",
      "updated_at": "2016-09-26T20:10:37Z",
      "position": 0
    }
  ]
}

HTTP Request

GET https://business.untappd.com/api/v1/locations/:location_id/custom_menus

Query Parameters

Parameter Validations Required Description
location_id Integer true The id of the location.

Create a custom menu

Creates a new custom menu.

Request:

curl "http://localhost:3000/api/v1/locations/3/custom_menus" \
  -X POST \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0=" \
  -H "Content-Type: application/json" \
  -d '{ "custom_menu": { "name": "Wine selection" } }'

Returns JSON structured like this:

{
  "custom_menu": {
    "id": 1,
    "location_id": 3,
    "name": "Wine selection",
    "description": "",
    "unpublished": true,
    "created_at": "2016-09-26T20:10:37Z",
    "updated_at": "2016-09-26T20:10:37Z",
    "position": 0
  }
}

HTTP Request

POST https://business.untappd.com/api/v1/locations/:location_id/custom_menus

Query Parameters

Parameter Validations Required Description
location_id Integer true The id of the location.
name String true The custom menu name.

Retrieve a custom menu

Retrieve the details of an existing custom menu. You need only supply the unique custom menu identifier that was returned upon custom menu creation.

Request:

curl "http://localhost:3000/api/v1/custom_menus/1" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0="

Returns JSON structured like this:

{
  "custom_menu": {
    "id": 1,
    "location_id": 3,
    "name": "Wine selection",
    "description": "",
    "unpublished": true,
    "created_at": "2016-09-26T20:10:37Z",
    "updated_at": "2016-09-26T20:10:37Z",
    "position": 0
  }
}

Or...

To get the full custom menu use the full param with the request:

curl "http://localhost:3000/api/v1/custom_menus/1?full=true" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0="

Returns JSON structured like this:

{
  "custom_menu": {
    "id": 1,
    "location_id": 3,
    "name": "Wine selection",
    "description": "",
    "unpublished": true,
    "created_at": "2016-09-26T20:30:08Z",
    "updated_at": "2016-09-26T20:35:27Z",
    "position": 0,
    "custom_sections": [
      {
        "id": 1,
        "custom_menu_id": 1,
        "position": 0,
        "name": "",
        "description": "",
        "created_at": "2016-09-26T20:30:08Z",
        "updated_at": "2016-09-26T20:30:08Z",
        "custom_items": []
      }
    ]
  }
}

HTTP Request

GET https://business.untappd.com/api/v1/custom_menus/:id

Query Parameters

Parameter Validations Required Description
id Integer true The id of the custom menu.
full true or not set false Returns the entire custom menu tree with custom sections, custom items, and custom containers. Also, enables analytics tracking for the request.
source_name Integer false When full is present in the request params, an optional source_name may be provided to change the recorded source of the request for the analytics dashboard.
Defaults to: API. See: Analytics/Track.

Update a custom menu

Updates the specified custom menu by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Request:

curl "http://localhost:3000/api/v1/custom_menus/1" \
  -X PATCH \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0=" \
  -H "Content-Type: application/json" \
  -d '{ "custom_menu": { "name": "Super Awesome Food Menu" } }'

Returns JSON structured like this:

{
  "custom_menu": {
    "id": 1,
    "location_id": 3,
    "name": "Super Awesome Food Menu",
    "description": "",
    "unpublished": true,
    "created_at": "2016-09-26T20:10:37Z",
    "updated_at": "2016-09-26T20:19:38Z",
    "position": 0
  }
}

HTTP Request

PUT https://business.untappd.com/api/v1/custom_menus/:id PATCH https://business.untappd.com/api/v1/custom_menus/:id

Query Parameters

Parameter Validations Required Description
id Integer true The id of the custom menu.
name String false The custom menu name.
description String false The custom menu description.
footer String false The custom menu footer.

Delete a custom menu

Permanently deletes a custom menu. It cannot be undone. If the custom menu is already published then it will first be unpublished and then deleted.

Request:

curl "http://localhost:3000/api/v1/custom_menus/1" \
  -X DELETE \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0="

Returns the deleted custom menu as JSON structured like this:

{
  "custom_menu": {
    "id": 1,
    "location_id": 3,
    "name": "Super Awesome Food Menu",
    "description": "",
    "unpublished": true,
    "created_at": "2016-09-26T20:10:37Z",
    "updated_at": "2016-09-26T20:20:48Z",
    "position": 0
  }
}

HTTP Request

DELETE https://business.untappd.com/api/v1/custom_menus/:id

Query Parameters

Parameter Validations Required Description
id Integer true The custom menu to be deleted.

Delete Multiple Custom Menus

Permanently deletes custom menus. It cannot be undone. If the custom menus are already published then they will first be unpublished and then deleted.

Request:

curl "http://localhost:3000/api/v1/locations/3/custom_menus" \
  -X DELETE \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [1, 2, 3] }'

Returns JSON structured like this:

{
  "success": true
}

HTTP Request

DELETE https://business.untappd.com/api/v1/locations/:location_id/custom_menus

Query Parameters

Parameter Validations Required Description
location_id Integer true The location to delete custom menus for.
ids Array true An Array of ids. All the custom menu ids for the location to be deleted.

Update custom menu positions

Set the positions of custom menus in a location. Custom menu positions are used to order the published custom menus on a page.

Important!: When updating custom menu positions, all custom menus for the location must be passed and the positions must start at zero. Use List all custom menus first to get all the custom menus for the location.

Request:

curl "http://localhost:3000/api/v1/locations/3/custom_menus/positions" \
  -X PATCH \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0=" \
  -H "Content-Type: application/json" \
  -d '{ "custom_menus": [{ "id": 1, "position": 1 }, { "id": 3, "position": 0 }] }'

Returns JSON structured like this:

{
  "custom_menus": [
    {
      "id": 3,
      "position": 0
    },
    {
      "id": 1,
      "position": 1
    }
  ]
}

HTTP Request

PATCH https://business.untappd.com/api/v1/locations/:location_id/custom_menus/positions

Query Parameters

Parameter Validations Required Description
location_id Integer true The location to update custom menu positions for.
custom_menus Array true An Array of Objects. All the custom menus for a location must be passed as a batch to be update atomically. Unexpected behavior may result otherwise.
id Integer true The custom menu id to update the position for.
position Integer true The position to set the custom menu at. Custom menu positions must start at zero.

Publish all custom menus

Publish all the unpublished custom menus of a location. Any changes to a published custom menu will automatically take effect.

Request:

curl "http://localhost:3000/api/v1/locations/3/custom_menus/publish_all" \
  -X POST \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0="

Returns JSON structured like this (notice unpublished is now set to: false):

{
  "custom_menus": [
    {
      "id": 1,
      "location_id": 3,
      "name": "Super Awesome Food Menu",
      "description": "",
      "unpublished": false,
      "created_at": "2016-09-26T20:10:37Z",
      "updated_at": "2016-09-26T20:20:48Z",
      "position": 0
    },
    {
      "id": 2,
      "location_id": 3,
      "name": "Super Awesome Cocktail Menu",
      "description": "",
      "unpublished": false,
      "created_at": "2016-09-26T20:10:37Z",
      "updated_at": "2016-09-26T20:20:48Z",
      "position": 0
    }
  ]
}

HTTP Request

POST https://business.untappd.com/api/v1/locations/:location_id/custom_menus/publish_all

Query Parameters

Parameter Validations Required Description
location_id Integer true The location.

Publish a custom menu

Publish a custom menu. There is no need to republish a custom menu that has already been published. Any changes to a published custom menu will automatically take effect.

Request:

curl "http://localhost:3000/api/v1/custom_menus/1/publish" \
  -X POST \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0="

Returns JSON structured like this (notice unpublished is now set to: false):

{
  "custom_menu": {
    "id": 1,
    "location_id": 3,
    "name": "Wine selection",
    "description": "",
    "unpublished": false,
    "created_at": "2016-09-26T20:30:08Z",
    "updated_at": "2016-09-26T20:32:44Z",
    "position": 0
  }
}

HTTP Request

POST https://business.untappd.com/api/v1/custom_menus/:id/publish

Query Parameters

Parameter Validations Required Description
id Integer true The custom menu to publish.

Unpublish a custom menu

Unpublish a custom menu.

Request:

curl "http://localhost:3000/api/v1/custom_menus/1/unpublish" \
  -X POST \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0="

Returns JSON structured like this (notice unpublished is now set to: true):

{
  "custom_menu": {
    "id": 1,
    "location_id": 3,
    "name": "Wine selection",
    "description": "",
    "unpublished": true,
    "created_at": "2016-09-26T20:30:08Z",
    "updated_at": "2016-09-26T20:35:27Z",
    "position": 0
  }
}

HTTP Request

POST https://business.untappd.com/api/v1/custom_menus/:id/unpublish

Query Parameters

Parameter Validations Required Description
id Integer true The custom menu to unpublish.

Custom Sections [Deprecated]

List all custom sections

List all the custom sections of a custom menu.

Request:

curl "http://localhost:3000/api/v1/custom_menus/1/custom_sections" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0="

Returns JSON structured like this:

{
  "custom_sections": [
    {
      "id": 1,
      "custom_menu_id": 1,
      "position": 0,
      "name": "Red wines",
      "description": "",
      "created_at": "2016-09-26T20:30:08Z",
      "updated_at": "2016-09-26T20:30:08Z"
    },
    {
      "id": 2,
      "custom_menu_id": 1,
      "position": 1,
      "name": "White wines",
      "description": "",
      "created_at": "2016-09-26T20:46:33Z",
      "updated_at": "2016-09-26T20:46:33Z"
    }
  ]
}

HTTP Request

GET https://business.untappd.com/api/v1/custom_menus/:custom_menu_id/custom_sections

Query Parameters

Parameter Validations Required Description
custom_menu_id Integer true The custom menu to lookup the custom sections for.

Create a custom section

Creates a new custom section belonging to a custom menu.

Request:

curl "http://localhost:3000/api/v1/custom_menus/1/custom_sections" \
  -X POST \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0=" \
  -H "Content-Type: application/json" \
  -d '{ "custom_section": { "name": "Red Wine", "description": "Our red wine selection." } }'

Returns JSON structured like this:

{
  "custom_section": {
    "id": 2,
    "custom_menu_id": 1,
    "position": 1,
    "name": "Red Wine",
    "description": "Our red wine selection.",
    "created_at": "2016-09-26T20:46:33Z",
    "updated_at": "2016-09-26T20:46:33Z"
  }
}

HTTP Request

POST https://business.untappd.com/api/v1/custom_menus/:custom_menu_id/custom_sections

Query Parameters

Parameter Validations Required Description
custom_menu_id Integer true The id of the custom menu.
head true or false true Adds the new custom section to the head of the list of custom sections for this custom menu when head is true. Otherwise the new custom section will be appended to the end.
name String false A name for the new custom section.
description String A description for the new custom section.

Retrieve a custom section

Retrieve the details of an existing custom section. You need only supply the unique custom section identifier that was returned upon custom section creation.

Request:

curl "http://localhost:3000/api/v1/custom_sections/2" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0="

Returns JSON structured like this:

{
  "custom_section": {
    "id": 2,
    "custom_menu_id": 1,
    "position": 1,
    "name": "Other beers",
    "description": "Our beers that are not dark or light.",
    "created_at": "2016-09-26T20:46:33Z",
    "updated_at": "2016-09-26T20:46:33Z"
  }
}

HTTP Request

GET https://business.untappd.com/api/v1/custom_sections/:id

Query Parameters

Parameter Validations Required Description
id Integer true The id of the custom section.

Update a custom section

Updates the specified custom section by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Request:

curl "http://localhost:3000/api/v1/custom_sections/2" \
  -X PATCH \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0=" \
  -H "Content-Type: application/json" \
  -d '{ "custom_section": { "description": "All the rest..." } }'

Returns JSON structured like this:

{
  "custom_section": {
    "id": 2,
    "custom_menu_id": 1,
    "position": 1,
    "name": "Other beers",
    "description": "All the rest...",
    "created_at": "2016-09-26T20:46:33Z",
    "updated_at": "2016-09-27T13:34:27Z"
  }
}

HTTP Request

PUT https://business.untappd.com/api/v1/custom_sections/:id PATCH https://business.untappd.com/api/v1/custom_sections/:id

Query Parameters

Parameter Validations Required Description
id Integer true The id of the section.
name String false The custom section name.
description String false The custom section description.

Delete a custom section

Permanently deletes a custom section. It cannot be undone.

Request:

curl "http://localhost:3000/api/v1/custom_sections/2" \
  -X DELETE \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0="

Returns the deleted custom section as JSON structured like this:

{
  "custom_section": {
    "id": 2,
    "custom_menu_id": 1,
    "position": 1,
    "name": "Other beers",
    "description": "All the rest...",
    "created_at": "2016-09-26T20:46:33Z",
    "updated_at": "2016-09-27T13:34:27Z"
  }
}

HTTP Request

DELETE https://business.untappd.com/api/v1/custom_sections/:id

Query Parameters

Parameter Validations Required Description
id Integer true The id of the custom section.

Update custom section positions

Set the positions of custom sections in a custom menu. Custom section positions are used to order the custom sections of a published custom menu on a page.

Important!: When updating custom section positions, all custom sections for the custom menu must be passed and the positions must start at zero. Use List all custom sections first to get all the custom sections for the custom menu.

Request:

curl "http://localhost:3000/api/v1/custom_menus/1/custom_sections/positions" \
  -X PATCH \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0=" \
  -H "Content-Type: application/json" \
  -d '{ "custom_sections": [{ "id": 1, "position": 1 }, { "id": 2, "position": 0 }] }'

Returns JSON structured like this:

{
  "custom_sections": [
    {
      "id": 2,
      "position": 0
    },
    {
      "id": 1,
      "position": 1
    }
  ]
}

HTTP Request

PATCH https://business.untappd.com/api/v1/custom_menus/:custom_menu_id/custom_sections/positions

Query Parameters

Parameter Validations Required Description
custom_menu_id Integer true The custom menu to update custom section positions for.
custom_sections Array true An Array of Objects. All the custom sections for a custom menu must be passed as a batch to be update atomically. Unexpected behavior may result otherwise.
id Integer true The custom section id to update the position for.
position Integer true The position to set the custom section at. Custom section positions must start at zero.

Events

List all events

Returns a list of events belonging to your location.

Request:

curl "http://localhost:3000/api/v1/locations/3/events" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="

Returns JSON structured like this:

{
  "events": [
    {
      "id": 1,
      "name": "Super fun happy hour",
      "description": "Liquid drinks half off only during happy hour.",
      "place_json": {
        "id": "5cfafd431239a7242f807c60f67c95d7670cb33f",
        "url": "https://maps.google.com/?cid=13931099202030384142",
        "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png",
        "name": "Next Glass",
        "scope": "GOOGLE",
        "types": ["point_of_interest", "establishment"],
        "geometry": {
          "location": {
            "lat": 34.234665,
            "lng": -77.94829399999998
          }
        },
        "place_id": "ChIJ9xKQtMcfqokRDrS_A-o0VcE",
        "vicinity": "21 South Front Street, Wilmington",
        "reference": "CmReAAAAk8lnuukeWe9pdvxdr1GwFtwWZCfR78NpnbUGNarlNoJaVcDSTiWdh57OTpgal6f4i8OktGTjDVHbXxBq9dfgfG3E7esCfV_BR-URXRehDvAxB0F76qLx6e6XfiAJShaREhDvFuIPRvlhQuvn3x0xtakZGhRgRASCIW2rLgn4eUxfN7IIjMLLOw",
        "utc_offset": -240,
        "adr_address": "<span class=\"street-address\">21 S Front St</span>, <span class=\"locality\">Wilmington</span>, <span class=\"region\">NC</span> <span class=\"postal-code\">28401</span>, <span class=\"country-name\">USA</span>",
        "formatted_address": "21 S Front St, Wilmington, NC 28401, USA",
        "html_attributions": [],
        "address_components": [
          {
            "types": ["street_number"],
            "long_name": "21",
            "short_name": "21"
          },
          {
            "types": ["route"],
            "long_name": "South Front Street",
            "short_name": "S Front St"
          },
          {
            "types": ["neighborhood", "political"],
            "long_name": "Historic District",
            "short_name": "Historic District"
          },
          {
            "types": ["locality", "political"],
            "long_name": "Wilmington",
            "short_name": "Wilmington"
          },
          {
            "types": ["administrative_area_level_3", "political"],
            "long_name": "Wilmington",
            "short_name": "Wilmington"
          },
          {
            "types": ["administrative_area_level_2", "political"],
            "long_name": "New Hanover County",
            "short_name": "New Hanover County"
          },
          {
            "types": ["administrative_area_level_1", "political"],
            "long_name": "North Carolina",
            "short_name": "NC"
          },
          {
            "types": ["country", "political"],
            "long_name": "United States",
            "short_name": "US"
          },
          {
            "types": ["postal_code"],
            "long_name": "28401",
            "short_name": "28401"
          }
        ]
      },
      "start_time": "2017-06-30T04:15:00.000Z",
      "start_time_in_zone": "2017-06-30T00:15:00-04:00",
      "end_time": "2017-06-30T19:15:00.000Z",
      "end_time_in_zone": "2017-06-30T15:15:00-04:00",
      "location_id": 3,
      "created_at": "2016-06-20T14:47:33.551Z",
      "updated_at": "2016-06-20T14:59:11.153Z",
      "location_name": "Next Glass",
      "city": "Wilmington",
      "state": "NC",
      "street": "21 S Front St",
      "country": "US",
      "zip": "28401",
      "latitude": "34.234665",
      "longitude": "-77.94829399999998",
      "from_facebook": false,
      "link": "https://nextglass.co"
    }
  ]
}

HTTP Request

GET https://business.untappd.com/api/v1/locations/:location_id/events

Query Parameters

Parameter Validations Required Description
location_id Integer true The id of the location.

Create an event

Creates a new event.

Request:

curl "http://localhost:3000/api/v1/locations/3/events" \
  -X POST \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04=" \
  -H "Content-Type: application/json" \
  -d '{ "event": { "name": "Super fun happy hour", "description": "Liquid drinks half off only during happy hour.", "start_time_date": "2017-06-30", "start_time_time": "12:15", "end_time_date": "2017-06-30", "end_time_time": "15:15" } }'

Returns JSON structured like this:

{
  "event": {
    "id": 3,
    "name": "Super fun happy hour",
    "description": "Liquid drinks half off only during happy hour.",
    "place_json": null,
    "start_time": "2017-06-30T16:15:00.000Z",
    "start_time_in_zone": "2017-06-30T12:15:00-04:00",
    "end_time": "2017-06-30T19:15:00.000Z",
    "end_time_in_zone": "2017-06-30T15:15:00-04:00",
    "location_id": 3,
    "created_at": "2016-06-20T14:55:21.667Z",
    "updated_at": "2016-06-20T14:55:21.667Z",
    "location_name": null,
    "city": null,
    "state": null,
    "street": null,
    "country": null,
    "zip": null,
    "latitude": null,
    "longitude": null,
    "from_facebook": false,
    "link": null
  }
}

HTTP Request

POST https://business.untappd.com/api/v1/locations/:location_id/events

Query Parameters

Parameter Validations Required Description
location_id Integer true The id of the location.
name String true The event name.
description String true The event description.
start_time_date String true The event start date. e.g. 2017-06-30
start_time_time String true The event start time. 24-hour format e.g. 12:15
end_time_date String false The event end date. e.g. 2017-06-30
end_time_time String false The event end time. 24-hour format e.g. 15:15
link String false A url to a web page for the event.
location_name String false The event location. e.g. Next Glass
street String false The event location city. e.g. 21 S Front St.
city String false The event location city. e.g. Wilmington
state String false The event location city. e.g. NC
zip String false The event location city. e.g. 28401
country String false The event location city. e.g. US

Retrieve an event

Retrieve the details of an existing event. You need only supply the unique event identifier that was returned upon event creation.

Request:

curl "http://localhost:3000/api/v1/events/1" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="

Returns JSON structured like this:

{
  "event": {
    "id": 1,
    "name": "Super fun happy hour",
    "description": "Liquid drinks half off only during happy hour.",
    "place_json": {
      "id": "5cfafd431239a7242f807c60f67c95d7670cb33f",
      "url": "https://maps.google.com/?cid=13931099202030384142",
      "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png",
      "name": "Next Glass",
      "scope": "GOOGLE",
      "types": ["point_of_interest", "establishment"],
      "geometry": {
        "location": {
          "lat": 34.234665,
          "lng": -77.94829399999998
        }
      },
      "place_id": "ChIJ9xKQtMcfqokRDrS_A-o0VcE",
      "vicinity": "21 South Front Street, Wilmington",
      "reference": "CmReAAAAk8lnuukeWe9pdvxdr1GwFtwWZCfR78NpnbUGNarlNoJaVcDSTiWdh57OTpgal6f4i8OktGTjDVHbXxBq9dfgfG3E7esCfV_BR-URXRehDvAxB0F76qLx6e6XfiAJShaREhDvFuIPRvlhQuvn3x0xtakZGhRgRASCIW2rLgn4eUxfN7IIjMLLOw",
      "utc_offset": -240,
      "adr_address": "<span class=\"street-address\">21 S Front St</span>, <span class=\"locality\">Wilmington</span>, <span class=\"region\">NC</span> <span class=\"postal-code\">28401</span>, <span class=\"country-name\">USA</span>",
      "formatted_address": "21 S Front St, Wilmington, NC 28401, USA",
      "html_attributions": [],
      "address_components": [
        {
          "types": ["street_number"],
          "long_name": "21",
          "short_name": "21"
        },
        {
          "types": ["route"],
          "long_name": "South Front Street",
          "short_name": "S Front St"
        },
        {
          "types": ["neighborhood", "political"],
          "long_name": "Historic District",
          "short_name": "Historic District"
        },
        {
          "types": ["locality", "political"],
          "long_name": "Wilmington",
          "short_name": "Wilmington"
        },
        {
          "types": ["administrative_area_level_3", "political"],
          "long_name": "Wilmington",
          "short_name": "Wilmington"
        },
        {
          "types": ["administrative_area_level_2", "political"],
          "long_name": "New Hanover County",
          "short_name": "New Hanover County"
        },
        {
          "types": ["administrative_area_level_1", "political"],
          "long_name": "North Carolina",
          "short_name": "NC"
        },
        {
          "types": ["country", "political"],
          "long_name": "United States",
          "short_name": "US"
        },
        {
          "types": ["postal_code"],
          "long_name": "28401",
          "short_name": "28401"
        }
      ]
    },
    "start_time": "2017-06-30T04:15:00.000Z",
    "start_time_in_zone": "2017-06-30T00:15:00-04:00",
    "end_time": "2017-06-30T19:15:00.000Z",
    "end_time_in_zone": "2017-06-30T15:15:00-04:00",
    "location_id": 3,
    "created_at": "2016-06-20T14:47:33.551Z",
    "updated_at": "2016-06-20T14:59:11.153Z",
    "location_name": "Next Glass",
    "city": "Wilmington",
    "state": "NC",
    "street": "21 S Front St",
    "country": "US",
    "zip": "28401",
    "latitude": "34.234665",
    "longitude": "-77.94829399999998",
    "from_facebook": false,
    "link": "https://nextglass.co"
  }
}

HTTP Request

GET https://business.untappd.com/api/v1/events/:id

Query Parameters

Parameter Validations Required Description
id Integer true The id of the event.

Update an event

Updates the specified menu by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Note: start_time_date and start_time_time must be set together. Same thing goes for end_time_date and end_time_time.

Request:

curl "http://localhost:3000/api/v1/events/1" \
  -X PATCH \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04=" \
  -H "Content-Type: application/json" \
  -d '{ "event": { "name": "Super fun happy hour. Changed start time", "start_time_date": "2017-06-30", "start_time_time": "14:15" } }'

Returns JSON structured like this:

{
  "event": {
    "id": 1,
    "name": "Super fun happy hour. Changed start time",
    "description": "Liquid drinks half off only during happy hour.",
    "place_json": {
      "id": "5cfafd431239a7242f807c60f67c95d7670cb33f",
      "url": "https://maps.google.com/?cid=13931099202030384142",
      "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png",
      "name": "Next Glass",
      "scope": "GOOGLE",
      "types": ["point_of_interest", "establishment"],
      "geometry": {
        "location": {
          "lat": 34.234665,
          "lng": -77.94829399999998
        }
      },
      "place_id": "ChIJ9xKQtMcfqokRDrS_A-o0VcE",
      "vicinity": "21 South Front Street, Wilmington",
      "reference": "CmReAAAAk8lnuukeWe9pdvxdr1GwFtwWZCfR78NpnbUGNarlNoJaVcDSTiWdh57OTpgal6f4i8OktGTjDVHbXxBq9dfgfG3E7esCfV_BR-URXRehDvAxB0F76qLx6e6XfiAJShaREhDvFuIPRvlhQuvn3x0xtakZGhRgRASCIW2rLgn4eUxfN7IIjMLLOw",
      "utc_offset": -240,
      "adr_address": "<span class=\"street-address\">21 S Front St</span>, <span class=\"locality\">Wilmington</span>, <span class=\"region\">NC</span> <span class=\"postal-code\">28401</span>, <span class=\"country-name\">USA</span>",
      "formatted_address": "21 S Front St, Wilmington, NC 28401, USA",
      "html_attributions": [],
      "address_components": [
        {
          "types": ["street_number"],
          "long_name": "21",
          "short_name": "21"
        },
        {
          "types": ["route"],
          "long_name": "South Front Street",
          "short_name": "S Front St"
        },
        {
          "types": ["neighborhood", "political"],
          "long_name": "Historic District",
          "short_name": "Historic District"
        },
        {
          "types": ["locality", "political"],
          "long_name": "Wilmington",
          "short_name": "Wilmington"
        },
        {
          "types": ["administrative_area_level_3", "political"],
          "long_name": "Wilmington",
          "short_name": "Wilmington"
        },
        {
          "types": ["administrative_area_level_2", "political"],
          "long_name": "New Hanover County",
          "short_name": "New Hanover County"
        },
        {
          "types": ["administrative_area_level_1", "political"],
          "long_name": "North Carolina",
          "short_name": "NC"
        },
        {
          "types": ["country", "political"],
          "long_name": "United States",
          "short_name": "US"
        },
        {
          "types": ["postal_code"],
          "long_name": "28401",
          "short_name": "28401"
        }
      ]
    },
    "start_time": "2017-06-30T18:15:00.000Z",
    "start_time_in_zone": "2017-06-30T14:15:00-04:00",
    "end_time": null,
    "end_time_in_zone": null,
    "location_id": 3,
    "created_at": "2016-06-20T14:47:33.551Z",
    "updated_at": "2016-06-20T15:06:33.046Z",
    "location_name": "Next Glass",
    "city": "Wilmington",
    "state": "NC",
    "street": "21 S Front St",
    "country": "US",
    "zip": "28401",
    "latitude": "34.234665",
    "longitude": "-77.94829399999998",
    "from_facebook": false,
    "link": "https://nextglass.co"
  }
}

HTTP Request

PUT https://business.untappd.com/api/v1/events/:id
PATCH https://business.untappd.com/api/v1/events/:id

Query Parameters

Parameter Validations Required Description
id Integer true The id of the event.
name String true The event name.
description String true The event description.
start_time_date String true The event start date. e.g. 2017-06-30
start_time_time String true The event start time. 24-hour format e.g. 12:15
end_time_date String false The event end date. e.g. 2017-06-30
end_time_time String false The event end time. 24-hour format e.g. 15:15
link String false A url to a web page for the event.
location_name String false The event location. e.g. Next Glass
street String false The event location city. e.g. 21 S Front St.
city String false The event location city. e.g. Wilmington
state String false The event location city. e.g. NC
zip String false The event location city. e.g. 28401
country String false The event location city. e.g. US

Delete an event

Permanently deletes an event. It cannot be undone.

Request:

curl "http://localhost:3000/api/v1/events/1" \
  -X DELETE \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="

Returns the deleted event as JSON structured like this:

{
  "event": {
    "id": 1,
    "name": "Super fun happy hour. Changed start time",
    "description": "Liquid drinks half off only during happy hour.",
    "place_json": {
      "id": "5cfafd431239a7242f807c60f67c95d7670cb33f",
      "url": "https://maps.google.com/?cid=13931099202030384142",
      "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png",
      "name": "Next Glass",
      "scope": "GOOGLE",
      "types": ["point_of_interest", "establishment"],
      "geometry": {
        "location": {
          "lat": 34.234665,
          "lng": -77.94829399999998
        }
      },
      "place_id": "ChIJ9xKQtMcfqokRDrS_A-o0VcE",
      "vicinity": "21 South Front Street, Wilmington",
      "reference": "CmReAAAAk8lnuukeWe9pdvxdr1GwFtwWZCfR78NpnbUGNarlNoJaVcDSTiWdh57OTpgal6f4i8OktGTjDVHbXxBq9dfgfG3E7esCfV_BR-URXRehDvAxB0F76qLx6e6XfiAJShaREhDvFuIPRvlhQuvn3x0xtakZGhRgRASCIW2rLgn4eUxfN7IIjMLLOw",
      "utc_offset": -240,
      "adr_address": "<span class=\"street-address\">21 S Front St</span>, <span class=\"locality\">Wilmington</span>, <span class=\"region\">NC</span> <span class=\"postal-code\">28401</span>, <span class=\"country-name\">USA</span>",
      "formatted_address": "21 S Front St, Wilmington, NC 28401, USA",
      "html_attributions": [],
      "address_components": [
        {
          "types": ["street_number"],
          "long_name": "21",
          "short_name": "21"
        },
        {
          "types": ["route"],
          "long_name": "South Front Street",
          "short_name": "S Front St"
        },
        {
          "types": ["neighborhood", "political"],
          "long_name": "Historic District",
          "short_name": "Historic District"
        },
        {
          "types": ["locality", "political"],
          "long_name": "Wilmington",
          "short_name": "Wilmington"
        },
        {
          "types": ["administrative_area_level_3", "political"],
          "long_name": "Wilmington",
          "short_name": "Wilmington"
        },
        {
          "types": ["administrative_area_level_2", "political"],
          "long_name": "New Hanover County",
          "short_name": "New Hanover County"
        },
        {
          "types": ["administrative_area_level_1", "political"],
          "long_name": "North Carolina",
          "short_name": "NC"
        },
        {
          "types": ["country", "political"],
          "long_name": "United States",
          "short_name": "US"
        },
        {
          "types": ["postal_code"],
          "long_name": "28401",
          "short_name": "28401"
        }
      ]
    },
    "start_time": "2017-06-30T18:15:00.000Z",
    "start_time_in_zone": "2017-06-30T14:15:00-04:00",
    "end_time": null,
    "end_time_in_zone": null,
    "location_id": 3,
    "created_at": "2016-06-20T14:47:33.551Z",
    "updated_at": "2016-06-20T15:06:33.046Z",
    "location_name": "Next Glass",
    "city": "Wilmington",
    "state": "NC",
    "street": "21 S Front St",
    "country": "US",
    "zip": "28401",
    "latitude": "34.234665",
    "longitude": "-77.94829399999998",
    "from_facebook": false,
    "link": "https://nextglass.co"
  }
}

HTTP Request

DELETE https://business.untappd.com/api/v1/events/:id

Query Parameters

Parameter Validations Required Description
id Integer true The event to be deleted.

Hours

List hours

List the hours associated with a given location.

curl "http://localhost:3000/api/v1/locations/2/hours" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="

Returns JSON structured like this:

{
  "hours": [
    {
      "id": 8,
      "always_open": false,
      "closed": false,
      "open_at": "2000-01-01T08:00:00.000Z",
      "close_at": "2000-01-01T18:00:00.000Z",
      "day": "monday",
      "location_id": 2,
      "created_at": "2020-08-13T17:50:20.225Z",
      "updated_at": "2020-08-13T17:50:20.225Z"
    },
    {
      "id": 9,
      "always_open": false,
      "closed": false,
      "open_at": "2000-01-01T08:00:00.000Z",
      "close_at": "2000-01-01T18:00:00.000Z",
      "day": "tuesday",
      "location_id": 2,
      "created_at": "2020-08-13T17:50:20.228Z",
      "updated_at": "2020-08-13T17:50:20.228Z"
    },
    {
      "id": 10,
      "always_open": false,
      "closed": false,
      "open_at": "2000-01-01T08:00:00.000Z",
      "close_at": "2000-01-01T18:00:00.000Z",
      "day": "wednesday",
      "location_id": 2,
      "created_at": "2020-08-13T17:50:20.230Z",
      "updated_at": "2020-08-13T17:50:20.230Z"
    },
    {
      "id": 11,
      "always_open": false,
      "closed": false,
      "open_at": "2000-01-01T08:00:00.000Z",
      "close_at": "2000-01-01T18:00:00.000Z",
      "day": "thursday",
      "location_id": 2,
      "created_at": "2020-08-13T17:50:20.233Z",
      "updated_at": "2020-08-13T17:50:20.233Z"
    },
    {
      "id": 12,
      "always_open": false,
      "closed": false,
      "open_at": "2000-01-01T08:00:00.000Z",
      "close_at": "2000-01-01T18:00:00.000Z",
      "day": "friday",
      "location_id": 2,
      "created_at": "2020-08-13T17:50:20.235Z",
      "updated_at": "2020-08-13T17:50:20.235Z"
    },
    {
      "id": 13,
      "always_open": false,
      "closed": false,
      "open_at": "2000-01-01T08:00:00.000Z",
      "close_at": "2000-01-01T18:00:00.000Z",
      "day": "saturday",
      "location_id": 2,
      "created_at": "2020-08-13T17:50:20.237Z",
      "updated_at": "2020-08-13T17:50:20.237Z"
    },
    {
      "id": 14,
      "always_open": false,
      "closed": false,
      "open_at": "2000-01-01T08:00:00.000Z",
      "close_at": "2000-01-01T18:00:00.000Z",
      "day": "sunday",
      "location_id": 2,
      "created_at": "2020-08-13T17:50:20.240Z",
      "updated_at": "2020-08-13T17:50:20.240Z"
    }
  ]
}

HTTP Request

GET https://business.untappd.com/api/v1/locations/:id/hours

Query Parameters

Parameter Validations Required Description
id Integer true The id of the location.

Update hours

Updates the specified location's hours by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Request:

curl "http://localhost:3000/api/v1/locations/2/hours" \
  -X PATCH \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04=" \
  -H "Content-Type: application/json" \
  -d '{ "hours": [ { "id": 8, "closed: 0, open_at: "2020-08-13T20:07:48.112Z" } ] }'

Returns JSON structured like this:

{
  "hours": [
    {
      "id": 8,
      "always_open": false,
      "closed": false,
      "open_at": "2020-08-13T20:07:48.112Z",
      "close_at": null,
      "day": "monday",
      "location_id": 2,
      "created_at": "2020-08-13T17:50:20.225Z",
      "updated_at": "2020-08-13T20:08:16.248Z"
    },
    {
      "id": 9,
      "always_open": false,
      "closed": false,
      "open_at": "2000-01-01T08:00:00.000Z",
      "close_at": "2000-01-01T18:00:00.000Z",
      "day": "tuesday",
      "location_id": 2,
      "created_at": "2020-08-13T17:50:20.228Z",
      "updated_at": "2020-08-13T17:50:20.228Z"
    },
    {
      "id": 10,
      "always_open": false,
      "closed": false,
      "open_at": "2000-01-01T08:00:00.000Z",
      "close_at": "2000-01-01T18:00:00.000Z",
      "day": "wednesday",
      "location_id": 2,
      "created_at": "2020-08-13T17:50:20.230Z",
      "updated_at": "2020-08-13T17:50:20.230Z"
    },
    {
      "id": 11,
      "always_open": false,
      "closed": false,
      "open_at": "2000-01-01T08:00:00.000Z",
      "close_at": "2000-01-01T18:00:00.000Z",
      "day": "thursday",
      "location_id": 2,
      "created_at": "2020-08-13T17:50:20.233Z",
      "updated_at": "2020-08-13T17:50:20.233Z"
    },
    {
      "id": 12,
      "always_open": false,
      "closed": false,
      "open_at": "2000-01-01T08:00:00.000Z",
      "close_at": "2000-01-01T18:00:00.000Z",
      "day": "friday",
      "location_id": 2,
      "created_at": "2020-08-13T17:50:20.235Z",
      "updated_at": "2020-08-13T17:50:20.235Z"
    },
    {
      "id": 13,
      "always_open": false,
      "closed": false,
      "open_at": "2000-01-01T08:00:00.000Z",
      "close_at": "2000-01-01T18:00:00.000Z",
      "day": "saturday",
      "location_id": 2,
      "created_at": "2020-08-13T17:50:20.237Z",
      "updated_at": "2020-08-13T17:50:20.237Z"
    },
    {
      "id": 14,
      "always_open": false,
      "closed": false,
      "open_at": "2000-01-01T08:00:00.000Z",
      "close_at": "2000-01-01T18:00:00.000Z",
      "day": "sunday",
      "location_id": 2,
      "created_at": "2020-08-13T17:50:20.240Z",
      "updated_at": "2020-08-13T17:50:20.240Z"
    }
  ]
}

HTTP Request

PUT https://business.untappd.com/api/v1/locations/:location_id/hours
PATCH https://business.untappd.com/api/v1/locations/:location_id/hours

Query Parameters

Parameter Validations Required Description
location_id Integer true The id of the location.
id Integer true The id of the hour.
always_open Boolean false Whether the location is always open.
closed Boolean false Whether the location is closed.
open_at DateTime false The location's opening hour
close_at DateTime false The location's closing hour

Insights

Retrieve checkins over time

Retrieve the number of checkins over time for a location.

Request defaults to group_by=checkins

curl "http://localhost:3000/api/v1/locations/3/insights/checkins_over_time" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="

Returns JSON structured like this:

{
  "insights": {
    "checkins": {
      "count": 7,
      "items": [
        {
          "date": "2016-06-14",
          "checkins": 0,
          "distinct_users": 0
        },
        {
          "date": "2016-06-15",
          "checkins": 2,
          "distinct_users": 1
        },
        {
          "date": "2016-06-16",
          "checkins": 2,
          "distinct_users": 2
        },
        {
          "date": "2016-06-17",
          "checkins": 7,
          "distinct_users": 5
        },
        {
          "date": "2016-06-18",
          "checkins": 0,
          "distinct_users": 0
        },
        {
          "date": "2016-06-19",
          "checkins": 0,
          "distinct_users": 0
        },
        {
          "date": "2016-06-20",
          "checkins": 0,
          "distinct_users": 0
        }
      ]
    },
    "time_taken": 0.017
  }
}

The group_by param will return differently structured JSON depending on the value passed.

Request with group_by=gender

curl "http://localhost:3000/api/v1/locations/3/insights/checkins_over_time?group_by=gender" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="

Response

{
  "insights": {
    "user_gender": [
      {
        "gender": "Male",
        "count": 7
      },
      {
        "gender": "Female",
        "count": 4
      },
      {
        "gender": "N/A",
        "count": 0
      }
    ],
    "time_taken": 0.011
  }
}

Request with group_by=ages

curl "http://localhost:3000/api/v1/locations/3/insights/checkins_over_time?group_by=ages" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="

Response

{
  "insights": {
    "user_ages": {
      "data": {
        "19-21": 0,
        "22-25": 0,
        "26-30": 9,
        "31-40": 1,
        "41-50": 0,
        "51-60": 1,
        "61+": 0
      },
      "total": 11
    },
    "time_taken": 0.014
  }
}

Request with group_by=daily

curl "http://localhost:3000/api/v1/locations/3/insights/checkins_over_time?group_by=daily" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="

Response

{
  "insights": {
    "daily_data": [
      {
        "day": "Monday",
        "distinct_users": 0
      },
      {
        "day": "Tuesday",
        "distinct_users": 0
      },
      {
        "day": "Wednesday",
        "distinct_users": 1
      },
      {
        "day": "Thursday",
        "distinct_users": 2
      },
      {
        "day": "Friday",
        "distinct_users": 5
      },
      {
        "day": "Saturday",
        "distinct_users": 0
      },
      {
        "day": "Sunday",
        "distinct_users": 0
      }
    ],
    "time_taken": 0.007
  }
}

HTTP Request

GET https://business.untappd.com/api/v1/locations/:location_id/insights/checkins_over_time

Query Parameters

Parameter Validations Required Description
location_id Integer true The location to query checkins for.
group_by Must be one of:
· checkins
· gender
· ages
· daily		 false Groups the checkins over time by the given value.
Defaults to: checkins.
num_days Must be one of:
·1
·7
·30
·90
·180		 false The number of days to query the data for.
Defaults to: 7.
tz_offset Integer false The timezone to query the data for (in hours).
Defaults to location timezone.
e.g. -5

Retrieve menu views over time

Retrieve the number of menu views over time for a location.

curl "http://localhost:3000/api/v1/locations/3/insights/menu_views_over_time?num_days=90" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="

Returns JSON structured like this:

{
  "total_menu_views": 149,
  "menu_views": [
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-03-22T04:00:00.000Z",
        "end": "2016-03-23T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-03-23T04:00:00.000Z",
        "end": "2016-03-24T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-03-24T04:00:00.000Z",
        "end": "2016-03-25T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-03-25T04:00:00.000Z",
        "end": "2016-03-26T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-03-26T04:00:00.000Z",
        "end": "2016-03-27T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-03-27T04:00:00.000Z",
        "end": "2016-03-28T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-03-28T04:00:00.000Z",
        "end": "2016-03-29T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-03-29T04:00:00.000Z",
        "end": "2016-03-30T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-03-30T04:00:00.000Z",
        "end": "2016-03-31T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-03-31T04:00:00.000Z",
        "end": "2016-04-01T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 1
        }
      ],
      "timeframe": {
        "start": "2016-04-01T04:00:00.000Z",
        "end": "2016-04-02T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-02T04:00:00.000Z",
        "end": "2016-04-03T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-03T04:00:00.000Z",
        "end": "2016-04-04T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-04T04:00:00.000Z",
        "end": "2016-04-05T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-05T04:00:00.000Z",
        "end": "2016-04-06T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-06T04:00:00.000Z",
        "end": "2016-04-07T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 1
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-07T04:00:00.000Z",
        "end": "2016-04-08T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-08T04:00:00.000Z",
        "end": "2016-04-09T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-09T04:00:00.000Z",
        "end": "2016-04-10T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-10T04:00:00.000Z",
        "end": "2016-04-11T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-11T04:00:00.000Z",
        "end": "2016-04-12T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-12T04:00:00.000Z",
        "end": "2016-04-13T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-13T04:00:00.000Z",
        "end": "2016-04-14T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-14T04:00:00.000Z",
        "end": "2016-04-15T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-15T04:00:00.000Z",
        "end": "2016-04-16T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-16T04:00:00.000Z",
        "end": "2016-04-17T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-17T04:00:00.000Z",
        "end": "2016-04-18T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-18T04:00:00.000Z",
        "end": "2016-04-19T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-19T04:00:00.000Z",
        "end": "2016-04-20T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-20T04:00:00.000Z",
        "end": "2016-04-21T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-21T04:00:00.000Z",
        "end": "2016-04-22T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-22T04:00:00.000Z",
        "end": "2016-04-23T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-23T04:00:00.000Z",
        "end": "2016-04-24T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-24T04:00:00.000Z",
        "end": "2016-04-25T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-25T04:00:00.000Z",
        "end": "2016-04-26T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-26T04:00:00.000Z",
        "end": "2016-04-27T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-27T04:00:00.000Z",
        "end": "2016-04-28T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-28T04:00:00.000Z",
        "end": "2016-04-29T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-29T04:00:00.000Z",
        "end": "2016-04-30T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-04-30T04:00:00.000Z",
        "end": "2016-05-01T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-01T04:00:00.000Z",
        "end": "2016-05-02T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-02T04:00:00.000Z",
        "end": "2016-05-03T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-03T04:00:00.000Z",
        "end": "2016-05-04T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 24
        }
      ],
      "timeframe": {
        "start": "2016-05-04T04:00:00.000Z",
        "end": "2016-05-05T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-05T04:00:00.000Z",
        "end": "2016-05-06T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-06T04:00:00.000Z",
        "end": "2016-05-07T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-07T04:00:00.000Z",
        "end": "2016-05-08T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-08T04:00:00.000Z",
        "end": "2016-05-09T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-09T04:00:00.000Z",
        "end": "2016-05-10T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-10T04:00:00.000Z",
        "end": "2016-05-11T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-11T04:00:00.000Z",
        "end": "2016-05-12T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-12T04:00:00.000Z",
        "end": "2016-05-13T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-13T04:00:00.000Z",
        "end": "2016-05-14T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-14T04:00:00.000Z",
        "end": "2016-05-15T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-15T04:00:00.000Z",
        "end": "2016-05-16T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 32
        }
      ],
      "timeframe": {
        "start": "2016-05-16T04:00:00.000Z",
        "end": "2016-05-17T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 27
        }
      ],
      "timeframe": {
        "start": "2016-05-17T04:00:00.000Z",
        "end": "2016-05-18T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 64
        }
      ],
      "timeframe": {
        "start": "2016-05-18T04:00:00.000Z",
        "end": "2016-05-19T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-19T04:00:00.000Z",
        "end": "2016-05-20T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-20T04:00:00.000Z",
        "end": "2016-05-21T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-21T04:00:00.000Z",
        "end": "2016-05-22T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-22T04:00:00.000Z",
        "end": "2016-05-23T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-23T04:00:00.000Z",
        "end": "2016-05-24T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-24T04:00:00.000Z",
        "end": "2016-05-25T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-25T04:00:00.000Z",
        "end": "2016-05-26T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-26T04:00:00.000Z",
        "end": "2016-05-27T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-27T04:00:00.000Z",
        "end": "2016-05-28T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-28T04:00:00.000Z",
        "end": "2016-05-29T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-29T04:00:00.000Z",
        "end": "2016-05-30T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-30T04:00:00.000Z",
        "end": "2016-05-31T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-05-31T04:00:00.000Z",
        "end": "2016-06-01T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-06-01T04:00:00.000Z",
        "end": "2016-06-02T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-06-02T04:00:00.000Z",
        "end": "2016-06-03T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-06-03T04:00:00.000Z",
        "end": "2016-06-04T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-06-04T04:00:00.000Z",
        "end": "2016-06-05T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-06-05T04:00:00.000Z",
        "end": "2016-06-06T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-06-06T04:00:00.000Z",
        "end": "2016-06-07T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-06-07T04:00:00.000Z",
        "end": "2016-06-08T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-06-08T04:00:00.000Z",
        "end": "2016-06-09T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-06-09T04:00:00.000Z",
        "end": "2016-06-10T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-06-10T04:00:00.000Z",
        "end": "2016-06-11T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-06-11T04:00:00.000Z",
        "end": "2016-06-12T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-06-12T04:00:00.000Z",
        "end": "2016-06-13T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-06-13T04:00:00.000Z",
        "end": "2016-06-14T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-06-14T04:00:00.000Z",
        "end": "2016-06-15T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-06-15T04:00:00.000Z",
        "end": "2016-06-16T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-06-16T04:00:00.000Z",
        "end": "2016-06-17T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-06-17T04:00:00.000Z",
        "end": "2016-06-18T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-06-18T04:00:00.000Z",
        "end": "2016-06-19T04:00:00.000Z"
      }
    },
    {
      "value": [
        {
          "source": "API",
          "result": 0
        },
        {
          "source": "website",
          "result": 0
        }
      ],
      "timeframe": {
        "start": "2016-06-19T04:00:00.000Z",
        "end": "2016-06-20T04:00:00.000Z"
      }
    }
  ]
}

HTTP Request

GET https://business.untappd.com/api/v1/locations/:location_id/insights/menu_views_over_time

Query Parameters

Parameter Validations Required Description
location_id Integer true The location to query checkins for.
num_days Must be one of:
·1
·7
·30
·90
·180		 false The number of days to query the data for.
Defaults to: 7.
tz_offset Integer false The timezone to query the data for (in seconds).
Defaults to location timezone.
e.g. -18000

Retrieve stats for a location

Retrieve the stats for a location. The response includes properties that don't have a time range, i.e. total checkins for the location.

curl "http://localhost:3000/api/v1/locations/3/insights/stats" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="

Returns JSON structured like this:

{
  "insights": {
    "subscribes": {
      "all": 10,
      "beers": 0,
      "events": 0
    },
    "stats": {
      "total_checkins": 291,
      "total_users": 31
    },
    "time_taken": 0.009
  }
}

HTTP Request

GET https://business.untappd.com/api/v1/locations/:location_id/insights/stats

Query Parameters

Parameter Validations Required Description
location_id Integer true The location to query the stats for.

Retrieve subscribes over time

Retrieve the subscribes over time for a location.

curl "http://localhost:3000/api/v1/locations/3/insights/subscribes_over_time?num_days=30" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="

Returns JSON structured like this:

{
  "insights": {
    "date_range": "2016-05-21 11:47:44",
    "subscribes": {
      "all": 2,
      "beers": 0,
      "events": 0
    },
    "time_taken": 0.007
  }
}

HTTP Request

GET https://business.untappd.com/api/v1/locations/:location_id/insights/subscribes_over_time

Query Parameters

Parameter Validations Required Description
location_id Integer true The location to query the subscribes for.
num_days Must be one of:
·1
·7
·30
·90
·180		 false The number of days to query the data for.
Defaults to: 7.
tz_offset Integer false The timezone to query the data for (in hours).
Defaults to location timezone.
e.g. -5

Retrieve top beers

Retrieve the top beers and top nearby beers over time for a location.

curl "http://localhost:3000/api/v1/locations/3/insights/top_beers" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="

Returns JSON structured like this:

{
  "insights": {
    "top_beers": [
      {
        "recent_created_at": "Sat, 18 Jun 2016 00:30:15 +0000",
        "total_count": 4,
        "total_users": 3,
        "beer": {
          "bid": 3963,
          "beer_name": "Festina Peche",
          "beer_label": "https://untappd.akamaized.net/site/beer_logos/beer-3963_54433_sm.jpeg",
          "beer_abv": 4.5,
          "beer_ibu": 8,
          "beer_slug": "dogfish-head-craft-brewery-festina-peche",
          "beer_description": "A refreshing neo-BerlinerWeisse fermented with honest-to-goodness peaches to (get this!) 4.5% abv! Because extreme beers don't have to be extremely boozy! Available in 4-pack and draft during the sweaty months.",
          "is_in_production": 1,
          "beer_style_id": 171,
          "beer_style": "Berliner Weisse",
          "auth_rating": 0,
          "wish_list": false,
          "beer_active": 1,
          "rating_score": 3.481,
          "rating_count": 66387
        },
        "brewery": {
          "brewery_id": 459,
          "brewery_name": "Dogfish Head Craft Brewery",
          "brewery_slug": "dogfish-head-craft-brewery",
          "brewery_label": "https://untappd.akamaized.net/site/brewery_logos/brewery-459_b3e4d.jpeg",
          "country_name": "United States",
          "contact": {
            "twitter": "dogfishbeer",
            "facebook": "http://www.facebook.com/dogfishheadbeer",
            "url": "http://www.dogfish.com/"
          },
          "location": {
            "brewery_city": "Milton",
            "brewery_state": "DE",
            "lat": 38.7776,
            "lng": -75.3099
          },
          "brewery_active": 1
        }
      },
      {
        "recent_created_at": "Fri, 17 Jun 2016 21:29:41 +0000",
        "total_count": 2,
        "total_users": 2,
        "beer": {
          "bid": 846311,
          "beer_name": "The Guilty Party",
          "beer_label": "https://untappd.akamaized.net/site/beer_logos/beer-846311_5904a_sm.jpeg",
          "beer_abv": 5.1,
          "beer_ibu": 37,
          "beer_slug": "gibb-s-hundred-brewing-company-the-guilty-party",
          "beer_description": "This charmingly drinkable brew is a pleasure to share with friends old and new. Pleasingly full-bodied, it achieves a nice balance of caramelly, nutty, biscuity maltiness, and smooth but assertive bitterness. The premium English and Belgian malt comes through nicely in the nose, along with floral Indie Golding hops, and a wonderful fruitiness from the traditional English yeast.",
          "is_in_production": 1,
          "beer_style_id": 92,
          "beer_style": "Extra Special / Strong Bitter",
          "auth_rating": 0,
          "wish_list": false,
          "beer_active": 1,
          "rating_score": 3.643,
          "rating_count": 1603
        },
        "brewery": {
          "brewery_id": 128514,
          "brewery_name": "Gibb's Hundred Brewing Company",
          "brewery_slug": "gibb-s-hundred-brewing-company",
          "brewery_label": "https://untappd.akamaized.net/site/brewery_logos/brewery-128514_37810.jpeg",
          "country_name": "United States",
          "contact": {
            "twitter": "GibbsHundred",
            "facebook": "https://www.facebook.com/gibbshundred",
            "url": "www.gibbshundred.com"
          },
          "location": {
            "brewery_city": "Greensboro",
            "brewery_state": "NC",
            "lat": 36.0658,
            "lng": -79.7918
          },
          "brewery_active": 1
        }
      },
      {
        "recent_created_at": "Thu, 16 Jun 2016 16:47:14 +0000",
        "total_count": 2,
        "total_users": 2,
        "beer": {
          "bid": 752597,
          "beer_name": "Pleasure Island Pilsner",
          "beer_label": "https://untappd.akamaized.net/site/assets/images/temp/badge-beer-default.png",
          "beer_abv": 5,
          "beer_ibu": 30,
          "beer_slug": "good-hops-brewing-pleasure-island-pilsner",
          "beer_description": "",
          "is_in_production": 1,
          "beer_style_id": 39,
          "beer_style": "Pilsner - Other",
          "auth_rating": 0,
          "wish_list": false,
          "beer_active": 1,
          "rating_score": 3.223,
          "rating_count": 299
        },
        "brewery": {
          "brewery_id": 138065,
          "brewery_name": "Good Hops Brewing",
          "brewery_slug": "good-hops-brewing",
          "brewery_label": "https://untappd.akamaized.net/site/brewery_logos/brewery-138065_c5ded.jpeg",
          "country_name": "United States",
          "contact": {
            "twitter": "goodhopsbrewing",
            "facebook": "https://www.facebook.com/pages/Good-Hops-Brewing-LLC/218556831654670",
            "url": "http://www.goodhopsbrewing.com/"
          },
          "location": {
            "brewery_city": "Carolina Beach",
            "brewery_state": "NC",
            "lat": 34.0413,
            "lng": -77.9046
          },
          "brewery_active": 1
        }
      },
      {
        "recent_created_at": "Fri, 17 Jun 2016 20:30:51 +0000",
        "total_count": 1,
        "total_users": 1,
        "beer": {
          "bid": 1543818,
          "beer_name": "Stone Citrusy Wit",
          "beer_label": "https://untappd.akamaized.net/site/beer_logos/beer-1543818_c35ad_sm.jpeg",
          "beer_abv": 5.3,
          "beer_ibu": 35,
          "beer_slug": "stone-brewing-stone-citrusy-wit",
          "beer_description": "When it comes to our beers and the ingredients we use, we give a wit. So rather than spinning just the same fruit wheel of the classic orange peel, we punched up our wit with the dynamic duo of tangerine and kaffir lime leaf. The fruit-forward aromatics and flavors are perfectly balanced, so you don’t have to bother adding a slice (or leaf) to the rim of your glass. Even with this lack of unnecessary garnish, you won’t find an absence of intense fruit. In fact, each dryly refreshing, citrusy sip of this coriander-spiced, tangerine-infused, Mandarina Bavaria-hopped creation will satisfy even the most hardcore fan.",
          "is_in_production": 1,
          "beer_style_id": 83,
          "beer_style": "Witbier",
          "auth_rating": 0,
          "wish_list": false,
          "beer_active": 1,
          "rating_score": 3.53,
          "rating_count": 6547
        },
        "brewery": {
          "brewery_id": 1204,
          "brewery_name": "Stone Brewing",
          "brewery_slug": "stone-brewing",
          "brewery_label": "https://untappd.akamaized.net/site/brewery_logos/brewery-1204_23541.jpeg",
          "country_name": "United States",
          "contact": {
            "twitter": "StoneBrewingCo",
            "facebook": "http://www.facebook.com/StoneBrewingCo",
            "url": "http://www.stonebrewing.com/"
          },
          "location": {
            "brewery_city": "Escondido",
            "brewery_state": "CA",
            "lat": 33.1157,
            "lng": -117.12
          },
          "brewery_active": 1
        }
      },
      {
        "recent_created_at": "Fri, 17 Jun 2016 23:14:11 +0000",
        "total_count": 1,
        "total_users": 1,
        "beer": {
          "bid": 561943,
          "beer_name": "Viking Fraoch Scottish Sour",
          "beer_label": "https://untappd.akamaized.net/site/beer_logos/beer-561943_d13a0_sm.jpeg",
          "beer_abv": 5,
          "beer_ibu": 0,
          "beer_slug": "d9-brewing-company-viking-fraoch-scottish-sour",
          "beer_description": "Viking Fraoch Scottish Sour is the first Fanatical Ale in our Ancient Sour Series.  Viking Fraoch (Fraoch is Scandinavian for Heather, a flower native to that area) is a 4,000 year old Viking Heather Flower Ale combined with an 18th Century Scottish Ale that is spontaneously soured with a rich brown hue, balanced tartness and hint of heather flowers. Flavors of caramel, bold tartness and ripe stone fruit give way to lingering flowers and clean, crisp mouthfeel.",
          "is_in_production": 1,
          "beer_style_id": 70,
          "beer_style": "Sour Ale",
          "auth_rating": 0,
          "wish_list": false,
          "beer_active": 1,
          "rating_score": 3.86,
          "rating_count": 5097
        },
        "brewery": {
          "brewery_id": 67113,
          "brewery_name": "D9 Brewing Company",
          "brewery_slug": "d9-brewing-company",
          "brewery_label": "https://untappd.akamaized.net/site/brewery_logos/brewery-district9brewingcompany_67113.jpeg",
          "country_name": "United States",
          "contact": {
            "twitter": "D9Brewing",
            "facebook": "http://facebook.com/d9brewing",
            "url": "http://www.d9brewing.com"
          },
          "location": {
            "brewery_city": "Cornelius",
            "brewery_state": "NC",
            "lat": 35.4584,
            "lng": -80.8539
          },
          "brewery_active": 1
        }
      },
      {
        "recent_created_at": "Fri, 17 Jun 2016 21:28:02 +0000",
        "total_count": 1,
        "total_users": 1,
        "beer": {
          "bid": 210218,
          "beer_name": "Apple Ale",
          "beer_label": "https://untappd.akamaized.net/site/beer_logos/beer-210218_d71b7_sm.jpeg",
          "beer_abv": 5,
          "beer_ibu": 0,
          "beer_slug": "redd-s-brewing-company-apple-ale",
          "beer_description": "Redd’s Apple Ale is an apple flavored golden ale with low malty and bitterness cues. With a crisp clean finish that allows the natural apple flavor to come through, this ale is for those times when you are looking to try something different.",
          "is_in_production": 1,
          "beer_style_id": 21,
          "beer_style": "Fruit Beer",
          "auth_rating": 0,
          "wish_list": false,
          "beer_active": 1,
          "rating_score": 3.113,
          "rating_count": 60658
        },
        "brewery": {
          "brewery_id": 36153,
          "brewery_name": "Redd's Brewing Company",
          "brewery_slug": "redds-brewing-company",
          "brewery_label": "https://untappd.akamaized.net/site/brewery_logos/brewery-ReddsBrewingCompany_36153_7d340.jpeg",
          "country_name": "United States",
          "contact": {
            "twitter": "ReddsAppleAle",
            "facebook": "https://www.facebook.com/reddsappleale",
            "url": "http://www.reddsapple.com"
          },
          "location": {
            "brewery_city": "Milwaukee",
            "brewery_state": "WI",
            "lat": 43.0389,
            "lng": -87.9065
          },
          "brewery_active": 1
        }
      }
    ],
    "top_nearby_beers": [
      {
        "beer": {
          "bid": 49166,
          "beer_name": "Port City IPA",
          "beer_label": "https://untappd.akamaized.net/site/beer_logos/beer-_49166_883830a37f4eaf609a5c87a54b5d.jpeg",
          "beer_abv": 6.1,
          "beer_ibu": 0,
          "beer_slug": "front-street-brewery-nc-port-city-ipa",
          "beer_description": "",
          "is_in_production": 1,
          "beer_style_id": 128,
          "beer_style": "IPA - American",
          "auth_rating": 0,
          "wish_list": false,
          "beer_active": 1
        },
        "brewery": {
          "brewery_id": 559,
          "brewery_name": "Front Street Brewery (NC)",
          "brewery_slug": "front-street-brewery-nc",
          "brewery_label": "https://untappd.akamaized.net/site/brewery_logos/brewery-FrontStreetBreweryNC_559.jpeg",
          "country_name": "United States",
          "contact": {
            "twitter": "FrontStreetBrew",
            "facebook": "http://www.facebook.com/FrontStreetBrewery",
            "url": "http://frontstreetbrewery.com"
          },
          "location": {
            "brewery_city": "Wilmington",
            "brewery_state": "NC",
            "lat": 34.2358,
            "lng": -77.9491
          },
          "brewery_active": 1
        },
        "total_users": 31
      },
      {
        "beer": {
          "bid": 8905,
          "beer_name": "Sexual Chocolate (Bourbon Barrel Aged)",
          "beer_label": "https://untappd.akamaized.net/site/beer_logos/beer-800268_54a99_sm.jpeg",
          "beer_abv": 9.75,
          "beer_ibu": 85,
          "beer_slug": "foothills-brewing-sexual-chocolate-bourbon-barrel-aged",
          "beer_description": "A barrel-aged cocoa infused Imperial Stout. Opaque black in color with a dark brown head. Big chocolate aroma with notes of espresso, blackstrap molasses, dark sweet toffee and dark fruit. Smooth dark chocolate backbone with complex notes of coffee, dark toffee and dark fruit.",
          "is_in_production": 1,
          "beer_style_id": 86,
          "beer_style": "Stout - American Imperial / Double",
          "auth_rating": 0,
          "wish_list": false,
          "beer_active": 1
        },
        "brewery": {
          "brewery_id": 543,
          "brewery_name": "Foothills Brewing",
          "brewery_slug": "foothills-brewing",
          "brewery_label": "https://untappd.akamaized.net/site/brewery_logos/brewery-FoothillsBrewing_543.jpeg",
          "country_name": "United States",
          "contact": {
            "twitter": "FoothillsBeer",
            "facebook": "http://www.facebook.com/foothills.brewing",
            "url": "http://www.foothillsbrewing.com/"
          },
          "location": {
            "brewery_city": "Winston-Salem",
            "brewery_state": "NC",
            "lat": 36.0973,
            "lng": -80.2509
          },
          "brewery_active": 1
        },
        "total_users": 27
      },
      {
        "beer": {
          "bid": 125297,
          "beer_name": "Amberjack ESB",
          "beer_label": "https://untappd.akamaized.net/site/beer_logos/beer-_125297_e0fe653089ba588e5d3617d7e5ca.jpeg",
          "beer_abv": 4.5,
          "beer_ibu": 0,
          "beer_slug": "front-street-brewery-nc-amberjack-esb",
          "beer_description": "A traditional English Ale.  ESB stands for Extra Special Bitter.  The English’s idea of bitter is very different than ours.  This beer does not have much upfront bitterness.  It focuses more on hop flavor and aroma.  East Kent Goldings hops give this beer a nice earthy aroma and flavor.  English Crystal malt give this ale a nice amber color and a touch of caramel flavor. ",
          "is_in_production": 1,
          "beer_style_id": 92,
          "beer_style": "Extra Special / Strong Bitter",
          "auth_rating": 0,
          "wish_list": false,
          "beer_active": 1
        },
        "brewery": {
          "brewery_id": 559,
          "brewery_name": "Front Street Brewery (NC)",
          "brewery_slug": "front-street-brewery-nc",
          "brewery_label": "https://untappd.akamaized.net/site/brewery_logos/brewery-FrontStreetBreweryNC_559.jpeg",
          "country_name": "United States",
          "contact": {
            "twitter": "FrontStreetBrew",
            "facebook": "http://www.facebook.com/FrontStreetBrewery",
            "url": "http://frontstreetbrewery.com"
          },
          "location": {
            "brewery_city": "Wilmington",
            "brewery_state": "NC",
            "lat": 34.2358,
            "lng": -77.9491
          },
          "brewery_active": 1
        },
        "total_users": 26
      },
      {
        "beer": {
          "bid": 49653,
          "beer_name": "Coastal Kolsch",
          "beer_label": "https://untappd.akamaized.net/site/beer_logos/beer-_49653_fa9f65c91c163fa7a4a8dcca22f5.jpeg",
          "beer_abv": 4.8,
          "beer_ibu": 0,
          "beer_slug": "front-street-brewery-nc-coastal-kolsch",
          "beer_description": "Unfiltered ",
          "is_in_production": 1,
          "beer_style_id": 30,
          "beer_style": "Kölsch",
          "auth_rating": 0,
          "wish_list": false,
          "beer_active": 1
        },
        "brewery": {
          "brewery_id": 559,
          "brewery_name": "Front Street Brewery (NC)",
          "brewery_slug": "front-street-brewery-nc",
          "brewery_label": "https://untappd.akamaized.net/site/brewery_logos/brewery-FrontStreetBreweryNC_559.jpeg",
          "country_name": "United States",
          "contact": {
            "twitter": "FrontStreetBrew",
            "facebook": "http://www.facebook.com/FrontStreetBrewery",
            "url": "http://frontstreetbrewery.com"
          },
          "location": {
            "brewery_city": "Wilmington",
            "brewery_state": "NC",
            "lat": 34.2358,
            "lng": -77.9491
          },
          "brewery_active": 1
        },
        "total_users": 24
      },
      {
        "beer": {
          "bid": 27490,
          "beer_name": "Riptide Raspberry Ale",
          "beer_label": "https://untappd.akamaized.net/site/beer_logos/beer-_27490_de5d725d6ddcfbb2cc6d56f8c0ce.jpeg",
          "beer_abv": 4.7,
          "beer_ibu": 0,
          "beer_slug": "front-street-brewery-nc-riptide-raspberry-ale",
          "beer_description": "American Wheat Ale made with all natural raspberry puree for a delicious, subtly sweet flavor. A Front Street favorite! Light bodied and delicately hopped. ",
          "is_in_production": 1,
          "beer_style_id": 60,
          "beer_style": "Red Ale - American Amber / Red",
          "auth_rating": 0,
          "wish_list": false,
          "beer_active": 1
        },
        "brewery": {
          "brewery_id": 559,
          "brewery_name": "Front Street Brewery (NC)",
          "brewery_slug": "front-street-brewery-nc",
          "brewery_label": "https://untappd.akamaized.net/site/brewery_logos/brewery-FrontStreetBreweryNC_559.jpeg",
          "country_name": "United States",
          "contact": {
            "twitter": "FrontStreetBrew",
            "facebook": "http://www.facebook.com/FrontStreetBrewery",
            "url": "http://frontstreetbrewery.com"
          },
          "location": {
            "brewery_city": "Wilmington",
            "brewery_state": "NC",
            "lat": 34.2358,
            "lng": -77.9491
          },
          "brewery_active": 1
        },
        "total_users": 19
      }
    ]
  }
}

HTTP Request

GET https://business.untappd.com/api/v1/locations/:location_id/insights/top_beers

Query Parameters

Parameter Validations Required Description
location_id Integer true The location to query the top beers for.
num_days Must be one of:
·1
·7
·30		 false The number of days to query the data for.
Defaults to: 7.
tz_offset Integer false The timezone to query the data for (in hours).
Defaults to location timezone.
e.g. -5

Items

Item Object

Property Type Description
calories integer Number of calories for the Item. To specify the calories for a specific Container size see Container.
created_at timestamp Time at which the Item was created. ISO8601 format.
custom_label_image url URL for the user uploaded label image for the Item.
custom_label_image_filename string Filename for the user uploaded label image.
custom_label_image_thumb url URL for the thumbnail version of the user uploaded label image.
default_image url URL for the default image for the Item.
description string Description of the Item.
id integer Unique identifier for the Item.
label_image url URL of the label image for the Item.
label_image_hd url URL of the HD version of the label image for the item. Only beer types have HD versions of the label. For all other types, this will be the same as label_image.
label_image_thumb url URL of the thumbnail version of the label image for the item. Thumbnail images are 100x100.
name string Name of the Item.
position integer The position of the Item in the list of Items for the Section. Positions start at zero and should be contiguous.
section_id integer Section id that the Item belongs to. See Section.
tap_number string Tap number set for the Item.
type string One of beer, cocktail, flight, food, merchandise, miscellaneous, non_alcoholic, spirit, or wine.
updated_at timestamp Time at which the Item was last updated. ISO8601 format.

Beer Item Object

Property Type Description
abv float Alcohol By Volume for the Beer.
brewery string Name of the brewery.
brewery_country string Country of the brewery.
brewery_location string Location of the brewery.
cask boolean Indicates if the Beer is poured from a cask.
custom_abv float Customized abv
custom_brewery string Customized brewery
custom_calories integer Customized calories
custom_description string Customized description
custom_ibu float Customized ibu
custom_name string Customized name
custom_style string Customized style
ibu float International Bitterness Units for the Beer.
in_production boolean Indicates if this Beer is still in production or not.
local boolean Indicates if this Beer is local.
nitro boolean Indicates if this Beer is a nitro pour.
original_abv float Original abv as defined by Untappd.
original_brewery string Original brewery as defined by Untappd.
original_calories integer Original calories as defined by Untappd.
original_description string Original description as defined by Untappd.
original_ibu float Original ibu as defined by Untappd.
original_label_image url Original label_image as defined by Untappd.
original_label_image_hd url Original label_image_hd as defined by Untappd.
original_name string Original name as defined by Untappd.
original_style string Original style as defined by Untappd.
rating float Untappd rating for the Item. rating is on a scale from 0.0 to 5.0 inclusive.
rating_count integer Number of rating the Item has received on Untappd.
style string Style for the Beer.
untappd_beer_slug string Untappd unique URL slug for the beer.
untappd_brewery_id integer Untappd identifier for the brewery.
untappd_id integer Untappd identifier for the beer.

Spirit Item Object

Property Type Description
abv float Alcohol By Volume for the Spirit.
category string The type of Spirit e.g. Gin
location string Location that the Spirit is from.
producer string The producer of the Spirit.
vintage string Year or age of the Spirit.

Wine Item Object

Property Type Description
abv float Alcohol By Volume for the Wine.
category string Category refers the grapes used in this wine e.g. Cabernet Sauvignon
characteristics string Characteristics used to describe this wine e.g. Red - Savory and Classic
location string Location that the Wine is from.
producer string The producer of the Wine.
vintage string Year that the Wine was produced.

Item Full Object

The full Item object can be returned by passing full=true when retieving a Menu. This will return the entire menu tree including all Sections, Items, and Containers. The following properties will be available in addition to the properties in the regular Item object

Property Type Description
containers array An array of Containers for the Item

List all items

Returns a list of items belonging to a section.

Request:

curl "http://localhost:3000/api/v1/sections/10/items" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="

Returns JSON structured like this:

{
  "items": [
    {
      "id": 64,
      "section_id": 10,
      "position": 0,
      "untappd_id": 4473,
      "label_image": "https://beer.untappd.com/labels/4473",
      "label_image_hd": "https://beer.untappd.com/labels/4473?size=hd",
      "label_image_thumb": "https://beer.untappd.com/labels/4473",
      "original_label_image": "https://beer.untappd.com/labels/4473",
      "original_label_image_hd": "https://beer.untappd.com/labels/4473?size=hd",
      "custom_label_image": null,
      "custom_label_image_thumb": null,
      "custom_label_image_filename": null,
      "brewery_location": "Dublin, County Dublin",
      "cask": false,
      "nitro": true,
      "local": false,
      "tap_number": "1",
      "rating": "3.76886",
      "rating_count": 801407,
      "in_production": true,
      "untappd_beer_slug": "guinness-guinness-draught",
      "untappd_brewery_id": 49,
      "name": "Guinness Draught",
      "original_name": "Guinness Draught",
      "custom_name": null,
      "description": "Swirling clouds tumble as the storm begins to calm. Settle. Breathe in the moment, then break through the smooth, light head to the bittersweet reward.\r\n\r\nUnmistakeably GUINNESS, from the first velvet sip to the last, lingering drop. And every deep-dark satisfying mouthful in between.\r\n\r\nPure beauty. Pure GUINNESS.\r\n\r\nGuinness Draught is sold in kegs, widget cans, and bottles. The ABV varies from 4.1 to 4.3%.\r\n\r\nGuinness Extra Cold is the exact same beer only served through a super cooler at 3.5 °C",
      "custom_description": null,
      "original_description": "Swirling clouds tumble as the storm begins to calm. Settle. Breathe in the moment, then break through the smooth, light head to the bittersweet reward.\r\n\r\nUnmistakeably GUINNESS, from the first velvet sip to the last, lingering drop. And every deep-dark satisfying mouthful in between.\r\n\r\nPure beauty. Pure GUINNESS.\r\n\r\nGuinness Draught is sold in kegs, widget cans, and bottles. The ABV varies from 4.1 to 4.3%.\r\n\r\nGuinness Extra Cold is the exact same beer only served through a super cooler at 3.5 °C",
      "style": "Stout - Irish Dry",
      "custom_style": null,
      "original_style": "Stout - Irish Dry",
      "brewery": "Guinness",
      "brewery_country": "Ireland",
      "custom_brewery": null,
      "original_brewery": "Guinness",
      "calories": "125",
      "custom_calories": null,
      "original_calories": "125",
      "abv": "4.2",
      "custom_abv": null,
      "original_abv": "4.2",
      "ibu": "45.0",
      "custom_ibu": null,
      "original_ibu": "45.0",
      "created_at": "2023-03-21T13:01:26.220225Z",
      "updated_at": "2023-03-21T13:04:40.327469Z",
      "type": "beer",
      "default_image": "https://assets.untappd.com/site/assets/images/temp/badge-beer-default.png",
      "producer": null,
      "vintage": null,
      "characteristics": null,
      "category": null,
      "location": null
    },
    {
      "id": 65,
      "section_id": 10,
      "position": 1,
      "untappd_id": null,
      "label_image": "https://www.wine-searcher.com/images/labels/19/94/10531994.jpg?width=50&height=50&fit=bounds&canvas=50,50",
      "label_image_hd": "https://s3.amazonaws.com/woof.nextglass.co/default/wine.svg",
      "label_image_thumb": "https://www.wine-searcher.com/images/labels/19/94/10531994.jpg?width=50&height=50&fit=bounds&canvas=50,50",
      "original_label_image": "https://beer.untappd.com/labels/",
      "original_label_image_hd": "https://beer.untappd.com/labels/?size=hd",
      "custom_label_image": null,
      "custom_label_image_thumb": null,
      "custom_label_image_filename": null,
      "brewery_location": null,
      "cask": false,
      "nitro": false,
      "local": false,
      "tap_number": null,
      "rating": null,
      "rating_count": null,
      "in_production": null,
      "untappd_beer_slug": null,
      "untappd_brewery_id": null,
      "name": "Bodegas Campo Viejo Tempranillo",
      "original_name": null,
      "custom_name": null,
      "description": "A cherry red colour suggests a vibrant Tempranillo wine. On the nose, the rich aromas have a pronounced intensity with an initial scent of ripe fruits followed by gentle sweet notes of vanilla and spices. On the palate, it is perfumed, soft and fresh with a long finish.",
      "custom_description": "A cherry red colour suggests a vibrant Tempranillo wine. On the nose, the rich aromas have a pronounced intensity with an initial scent of ripe fruits followed by gentle sweet notes of vanilla and spices. On the palate, it is perfumed, soft and fresh with a long finish.",
      "original_description": null,
      "style": null,
      "custom_style": null,
      "original_style": null,
      "brewery": null,
      "brewery_country": null,
      "custom_brewery": null,
      "original_brewery": null,
      "calories": null,
      "custom_calories": null,
      "original_calories": null,
      "abv": "13.5",
      "custom_abv": null,
      "original_abv": null,
      "ibu": null,
      "custom_ibu": null,
      "original_ibu": null,
      "created_at": "2023-03-21T13:02:01.593381Z",
      "updated_at": "2023-03-21T13:05:28.545371Z",
      "type": "wine",
      "default_image": "https://s3.amazonaws.com/woof.nextglass.co/default/wine.svg",
      "producer": "Bodegas Campo Viejo",
      "vintage": null,
      "characteristics": "Red - Savory and Classic",
      "category": "Tempranillo",
      "location": "Rioja, Spain"
    },
    {
      "id": 66,
      "section_id": 10,
      "position": 2,
      "untappd_id": null,
      "label_image": "https://www.wine-searcher.com/images/labels/36/77/10143677.jpg?width=50&height=50&fit=bounds&canvas=50,50",
      "label_image_hd": "https://s3.amazonaws.com/woof.nextglass.co/default/spirit.svg",
      "label_image_thumb": "https://www.wine-searcher.com/images/labels/36/77/10143677.jpg?width=50&height=50&fit=bounds&canvas=50,50",
      "original_label_image": "https://beer.untappd.com/labels/",
      "original_label_image_hd": "https://beer.untappd.com/labels/?size=hd",
      "custom_label_image": null,
      "custom_label_image_thumb": null,
      "custom_label_image_filename": null,
      "brewery_location": null,
      "cask": false,
      "nitro": false,
      "local": false,
      "tap_number": null,
      "rating": null,
      "rating_count": null,
      "in_production": null,
      "untappd_beer_slug": null,
      "untappd_brewery_id": null,
      "name": "The Kraken Black Spiced Rum",
      "original_name": null,
      "custom_name": null,
      "description": "One of the fastest growing rum brands, The Kraken® is the world’s first black spiced rum, housed in an iconic bottle. Taste the flavors of cinnamon, vanilla, and nutmeg and experience its magic. The Kraken® Original is 94 proof. It has a distinct aroma of caramel, toffee and spice with flavors of cinnamon and vanilla and a lingering spicy finish. (47% ABV - 94 proof) The Kraken®, blended with secret spices, is perfect to spice up classics and new favorite cocktails or as a shot.",
      "custom_description": "One of the fastest growing rum brands, The Kraken® is the world’s first black spiced rum, housed in an iconic bottle. Taste the flavors of cinnamon, vanilla, and nutmeg and experience its magic. The Kraken® Original is 94 proof. It has a distinct aroma of caramel, toffee and spice with flavors of cinnamon and vanilla and a lingering spicy finish. (47% ABV - 94 proof) The Kraken®, blended with secret spices, is perfect to spice up classics and new favorite cocktails or as a shot.",
      "original_description": null,
      "style": null,
      "custom_style": null,
      "original_style": null,
      "brewery": null,
      "brewery_country": null,
      "custom_brewery": null,
      "original_brewery": null,
      "calories": null,
      "custom_calories": null,
      "original_calories": null,
      "abv": "35.0",
      "custom_abv": null,
      "original_abv": null,
      "ibu": null,
      "custom_ibu": null,
      "original_ibu": null,
      "created_at": "2023-03-21T13:02:51.158417Z",
      "updated_at": "2023-03-21T13:06:38.052956Z",
      "type": "spirit",
      "default_image": "https://s3.amazonaws.com/woof.nextglass.co/default/spirit.svg",
      "producer": "The Kraken",
      "vintage": null,
      "characteristics": null,
      "category": "Rum - Liqueur - Flavored",
      "location": "Caribbean, Rest of World"
    }
  ]
}

HTTP Request

GET https://business.untappd.com/api/v1/sections/:section_id/items

Query Parameters

Parameter Validations Required Description
section_id Integer true The section to list the items for.
include_legacy Boolean false Enables legacy item fallback. See Legacy Migration

Create an item

Creates a new item

Request:

curl "http://localhost:3000/api/v1/sections/10/items" \
  -X POST \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
  -H "Content-Type: application/json" \
  -d '{ "untappd_id": 4499 }'

Returns all the items for the section (including the new one) as JSON structured like this:

{
  "item": {
    "id": 68,
    "section_id": 10,
    "position": 0,
    "untappd_id": 4499,
    "label_image": "https://beer.untappd.com/labels/4499",
    "label_image_hd": "https://beer.untappd.com/labels/4499?size=hd",
    "label_image_thumb": "https://beer.untappd.com/labels/4499",
    "original_label_image": "https://beer.untappd.com/labels/4499",
    "original_label_image_hd": "https://beer.untappd.com/labels/4499?size=hd",
    "custom_label_image": null,
    "custom_label_image_thumb": null,
    "custom_label_image_filename": null,
    "brewery_location": "Windsor, CA",
    "cask": false,
    "nitro": false,
    "local": false,
    "tap_number": null,
    "rating": "4.5019",
    "rating_count": 275355,
    "in_production": true,
    "untappd_beer_slug": "russian-river-brewing-company-pliny-the-elder",
    "untappd_brewery_id": 5143,
    "name": "Pliny the Elder",
    "original_name": "Pliny the Elder",
    "custom_name": null,
    "description": "PLINY THE ELDER -  (Double IPA)  Brewed with Amarillo, Centennial, CTZ, Cascade, Warrior, and Simcoe hops.  Well-balanced with malt, hops, and alcohol.  Slightly bitter with aromas of citrus, pine, and floral. ",
    "custom_description": null,
    "original_description": "PLINY THE ELDER -  (Double IPA)  Brewed with Amarillo, Centennial, CTZ, Cascade, Warrior, and Simcoe hops.  Well-balanced with malt, hops, and alcohol.  Slightly bitter with aromas of citrus, pine, and floral. ",
    "style": "IPA - Imperial / Double",
    "custom_style": null,
    "original_style": "IPA - Imperial / Double",
    "brewery": "Russian River Brewing Company",
    "brewery_country": "United States",
    "custom_brewery": null,
    "original_brewery": "Russian River Brewing Company",
    "calories": "240",
    "custom_calories": null,
    "original_calories": "240",
    "abv": "8.0",
    "custom_abv": null,
    "original_abv": "8.0",
    "ibu": "100.0",
    "custom_ibu": null,
    "original_ibu": "100.0",
    "created_at": "2023-03-21T14:07:14.266113Z",
    "updated_at": "2023-03-21T14:07:14.266113Z",
    "type": "beer",
    "default_image": "https://assets.untappd.com/site/assets/images/temp/badge-beer-default.png",
    "producer": null,
    "vintage": null,
    "characteristics": null,
    "category": null,
    "location": null
  }
}

HTTP Request

POST https://business.untappd.com/api/v1/sections/:section_id/items

Parameters

Parameter Type Required Description
section_id Integer true The section to add the item to.
type String true One of beer, cocktail, flight, food, merchandise, miscellaneous, non_alcoholic, spirit, wine

Beer Parameters

The data for the item is automatically populated from the beer database.

Note: This type will accept an array of integers for untappd_id to batch add multiple items at once.

Parameter Type Required Description
untappd_id Integer or Array[Integer] true A single ID or an array of IDs. untappd_id is the Untappd ID for a given item in the beer database. This is different from an Item ID. e.g. item.untappd_id != item.id

Spirit Parameters

Parameter Type Required Description
abv float false Alcohol By Volume for the Spirit.
calories integer false Number of calories for the Spirit.
category string false The type of Spirit e.g. Gin
description string false Description of the Spirit.
location string false Location that the Spirit is from.
name string false Name of the Spirit.
producer string false The producer of the Spirit.
tap_number string false Tap number for the Spirit.
vintage string false Year or age of the Spirit.

Wine Parameters

Property Type Required Description
abv float false Alcohol By Volume for the Wine.
calories integer false Number of calories for the Wine.
category string false Category refers the grapes used in this wine e.g. Cabernet Sauvignon
characteristics string false Characteristics used to describe this wine e.g. Red - Savory and Classic
description string false Description of the Wine.
location string false Location that the Wine is from.
name string false Name of the Wine.
producer string false The producer of the Wine.
tap_number string false Tap number for the Wine.
vintage string false Year that the Wine was produced.

Cocktail/Flight/Food/NonAlcoholic Parameters

Property Type Required Description
calories integer false Number of calories for the Item.
description string false Description of the Item.
name string false Name of the Item.
tap_number string false Tap number for the Item.

Miscellaneous Parameters

Property Type Required Description
description string false Description of the Item.
name string false Name of the Item.
tap_number string false Tap number for the Item.

Merchandise Parameters

Property Type Required Description
description string false Description of the Item.
name string false Name of the Item.

Retrieve an item

Retrieve the details of an existing item. You need only supply the unique item identifier that was returned upon item creation.

Request:

curl "http://localhost:3000/api/v1/items/64" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="

Returns JSON structured like this:

{
  "item": {
    "id": 64,
    "section_id": 10,
    "position": 1,
    "untappd_id": 4473,
    "label_image": "https://beer.untappd.com/labels/4473",
    "label_image_hd": "https://beer.untappd.com/labels/4473?size=hd",
    "label_image_thumb": "https://beer.untappd.com/labels/4473",
    "original_label_image": "https://beer.untappd.com/labels/4473",
    "original_label_image_hd": "https://beer.untappd.com/labels/4473?size=hd",
    "custom_label_image": null,
    "custom_label_image_thumb": null,
    "custom_label_image_filename": null,
    "brewery_location": "Dublin, County Dublin",
    "cask": false,
    "nitro": true,
    "local": false,
    "tap_number": "1",
    "rating": "3.76886",
    "rating_count": 801407,
    "in_production": true,
    "untappd_beer_slug": "guinness-guinness-draught",
    "untappd_brewery_id": 49,
    "name": "Guinness Draught",
    "original_name": "Guinness Draught",
    "custom_name": null,
    "description": "Swirling clouds tumble as the storm begins to calm. Settle. Breathe in the moment, then break through the smooth, light head to the bittersweet reward.\r\n\r\nUnmistakeably GUINNESS, from the first velvet sip to the last, lingering drop. And every deep-dark satisfying mouthful in between.\r\n\r\nPure beauty. Pure GUINNESS.\r\n\r\nGuinness Draught is sold in kegs, widget cans, and bottles. The ABV varies from 4.1 to 4.3%.\r\n\r\nGuinness Extra Cold is the exact same beer only served through a super cooler at 3.5 °C",
    "custom_description": null,
    "original_description": "Swirling clouds tumble as the storm begins to calm. Settle. Breathe in the moment, then break through the smooth, light head to the bittersweet reward.\r\n\r\nUnmistakeably GUINNESS, from the first velvet sip to the last, lingering drop. And every deep-dark satisfying mouthful in between.\r\n\r\nPure beauty. Pure GUINNESS.\r\n\r\nGuinness Draught is sold in kegs, widget cans, and bottles. The ABV varies from 4.1 to 4.3%.\r\n\r\nGuinness Extra Cold is the exact same beer only served through a super cooler at 3.5 °C",
    "style": "Stout - Irish Dry",
    "custom_style": null,
    "original_style": "Stout - Irish Dry",
    "brewery": "Guinness",
    "brewery_country": "Ireland",
    "custom_brewery": null,
    "original_brewery": "Guinness",
    "calories": "125",
    "custom_calories": null,
    "original_calories": "125",
    "abv": "4.2",
    "custom_abv": null,
    "original_abv": "4.2",
    "ibu": "45.0",
    "custom_ibu": null,
    "original_ibu": "45.0",
    "created_at": "2023-03-21T13:01:26.220225Z",
    "updated_at": "2023-03-21T14:07:14.275910Z",
    "type": "beer",
    "default_image": "https://assets.untappd.com/site/assets/images/temp/badge-beer-default.png",
    "producer": null,
    "vintage": null,
    "characteristics": null,
    "category": null,
    "location": null
  }
}

HTTP Request

GET https://business.untappd.com/api/v1/items/:id

Query Parameters

Parameter Validations Required Description
id Integer true The id of the item.
include_legacy Boolean false Enables legacy item fallback. See Legacy Migration

Update an item

Updates the specified item by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Request:

curl "http://localhost:3000/api/v1/items/68" \
  -X PATCH \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
  -H "Content-Type: application/json" \
  -d '{ "item": { "cask": true, "tap_number": 1, "brewery": "Russian River Brewing Co." } }'

Returns JSON structured like this:

{
  "item": {
    "id": 68,
    "section_id": 10,
    "position": 0,
    "untappd_id": 4499,
    "label_image": "https://beer.untappd.com/labels/4499",
    "label_image_hd": "https://beer.untappd.com/labels/4499?size=hd",
    "label_image_thumb": "https://beer.untappd.com/labels/4499",
    "original_label_image": "https://beer.untappd.com/labels/4499",
    "original_label_image_hd": "https://beer.untappd.com/labels/4499?size=hd",
    "custom_label_image": null,
    "custom_label_image_thumb": null,
    "custom_label_image_filename": null,
    "brewery_location": "Windsor, CA",
    "cask": true,
    "nitro": false,
    "local": false,
    "tap_number": "1",
    "rating": "4.5019",
    "rating_count": 275355,
    "in_production": true,
    "untappd_beer_slug": "russian-river-brewing-company-pliny-the-elder",
    "untappd_brewery_id": 5143,
    "name": "Pliny the Elder",
    "original_name": "Pliny the Elder",
    "custom_name": null,
    "description": "PLINY THE ELDER -  (Double IPA)  Brewed with Amarillo, Centennial, CTZ, Cascade, Warrior, and Simcoe hops.  Well-balanced with malt, hops, and alcohol.  Slightly bitter with aromas of citrus, pine, and floral. ",
    "custom_description": null,
    "original_description": "PLINY THE ELDER -  (Double IPA)  Brewed with Amarillo, Centennial, CTZ, Cascade, Warrior, and Simcoe hops.  Well-balanced with malt, hops, and alcohol.  Slightly bitter with aromas of citrus, pine, and floral. ",
    "style": "IPA - Imperial / Double",
    "custom_style": null,
    "original_style": "IPA - Imperial / Double",
    "brewery": "Russian River Brewing Co.",
    "brewery_country": "United States",
    "custom_brewery": "Russian River Brewing Co.",
    "original_brewery": "Russian River Brewing Company",
    "calories": "240",
    "custom_calories": null,
    "original_calories": "240",
    "abv": "8.0",
    "custom_abv": null,
    "original_abv": "8.0",
    "ibu": "100.0",
    "custom_ibu": null,
    "original_ibu": "100.0",
    "created_at": "2023-03-21T14:07:14.266113Z",
    "updated_at": "2023-03-21T14:10:11.540401Z",
    "type": "beer",
    "default_image": "https://assets.untappd.com/site/assets/images/temp/badge-beer-default.png",
    "producer": null,
    "vintage": null,
    "characteristics": null,
    "category": null,
    "location": null
  }
}

HTTP Request

PUT https://business.untappd.com/api/v1/items/:id PATCH https://business.untappd.com/api/v1/items/:id

Query Parameters

Parameter Validations Required Description
id Integer true The id of the item.
cask true/false false Is the item designated cask?
nitro true/false false Is the item designated nitro?
tap_number String false A tap description for the item. e.g. Could be 2 or B.
description String false A custom description for the item. If custom_description is null, menus will display the original_description.
name String false A custom name for the item. If custom_name is null, menus will display the original_name.
style String false A custom style for the item. If custom_style is null, menus will display the original_style.
brewery String false A custom brewery for the item. If custom_brewery is null, menus will display the original_brewery.

Delete an item

Permanently deletes an item. It cannot be undone.

Request:

curl "http://localhost:3000/api/v1/items/68" \
  -X DELETE \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="

Returns the deleted item as JSON structured like this:

{
  "item": {
    "id": 68,
    "section_id": 10,
    "position": 0,
    "untappd_id": 4499,
    "label_image": "https://beer.untappd.com/labels/4499",
    "label_image_hd": "https://beer.untappd.com/labels/4499?size=hd",
    "label_image_thumb": "https://beer.untappd.com/labels/4499",
    "original_label_image": "https://beer.untappd.com/labels/4499",
    "original_label_image_hd": "https://beer.untappd.com/labels/4499?size=hd",
    "custom_label_image": null,
    "custom_label_image_thumb": null,
    "custom_label_image_filename": null,
    "brewery_location": "Windsor, CA",
    "cask": true,
    "nitro": false,
    "local": false,
    "tap_number": "1",
    "rating": "4.5019",
    "rating_count": 275355,
    "in_production": true,
    "untappd_beer_slug": "russian-river-brewing-company-pliny-the-elder",
    "untappd_brewery_id": 5143,
    "name": "Pliny the Elder",
    "original_name": "Pliny the Elder",
    "custom_name": null,
    "description": "PLINY THE ELDER -  (Double IPA)  Brewed with Amarillo, Centennial, CTZ, Cascade, Warrior, and Simcoe hops.  Well-balanced with malt, hops, and alcohol.  Slightly bitter with aromas of citrus, pine, and floral. ",
    "custom_description": null,
    "original_description": "PLINY THE ELDER -  (Double IPA)  Brewed with Amarillo, Centennial, CTZ, Cascade, Warrior, and Simcoe hops.  Well-balanced with malt, hops, and alcohol.  Slightly bitter with aromas of citrus, pine, and floral. ",
    "style": "IPA - Imperial / Double",
    "custom_style": null,
    "original_style": "IPA - Imperial / Double",
    "brewery": "Russian River Brewing Co.",
    "brewery_country": "United States",
    "custom_brewery": "Russian River Brewing Co.",
    "original_brewery": "Russian River Brewing Company",
    "calories": "240",
    "custom_calories": null,
    "original_calories": "240",
    "abv": "8.0",
    "custom_abv": null,
    "original_abv": "8.0",
    "ibu": "100.0",
    "custom_ibu": null,
    "original_ibu": "100.0",
    "created_at": "2023-03-21T14:07:14.266113Z",
    "updated_at": "2023-03-21T14:10:11.540401Z",
    "type": "beer",
    "default_image": "https://assets.untappd.com/site/assets/images/temp/badge-beer-default.png",
    "producer": null,
    "vintage": null,
    "characteristics": null,
    "category": null,
    "location": null
  }
}

HTTP Request

DELETE https://business.untappd.com/api/v1/items/:id

Query Parameters

Parameter Validations Required Description
id Integer true The item to be deleted.

Update item positions

Set the positions of items in a section. Item positions are used to order the items within a section of a published menu on a page.

Important!: When updating item positions, all items for the section must be passed and the positions must start at zero. Use List all items first to get all the items for the section.

Request:

curl "http://localhost:3000/api/v1/sections/10/items/positions" \
  -X PATCH \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
  -H "Content-Type: application/json" \
  -d '{ "items": [{ "id": 1, "position": 1 }, { "id": 2, "position": 0 }] }'

Returns JSON structured like this:

{
  "items": [
    {
      "id": 2,
      "position": 0
    },
    {
      "id": 1,
      "position": 1
    }
  ]
}

HTTP Request

PATCH https://business.untappd.com/api/v1/sections/:section_id/items/positions

Query Parameters

Parameter Validations Required Description
section_id Integer true The section to update item positions for.
items Array true An Array of Objects. All the items for a section should be passed as a batch to be update atomically. Unexpected behavior may result otherwise.
id Integer true The item id to update the position for.
position Integer true The position to set the item at. Item positions must start at zero.

Move an item to another section

Move the specified item to another section.

Request:

curl "http://localhost:3000/api/v1/items/64/move" \
  -X PATCH \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
  -H "Content-Type: application/json" \
  -d '{ "item": { "section_id": 3 } }'

Returns JSON structured like this:

{
  "item": {
    "id": 67,
    "section_id": 10,
    "position": 0,
    "untappd_id": 9681,
    "label_image": "https://beer.untappd.com/labels/9681",
    "label_image_hd": "https://beer.untappd.com/labels/9681?size=hd",
    "label_image_thumb": "https://beer.untappd.com/labels/9681",
    "original_label_image": "https://beer.untappd.com/labels/9681",
    "original_label_image_hd": "https://beer.untappd.com/labels/9681?size=hd",
    "custom_label_image": null,
    "custom_label_image_thumb": null,
    "custom_label_image_filename": null,
    "brewery_location": "Grand Rapids, MI",
    "cask": false,
    "nitro": false,
    "local": false,
    "tap_number": null,
    "rating": "4.38633",
    "rating_count": 224308,
    "in_production": true,
    "untappd_beer_slug": "founders-brewing-co-kentucky-breakfast-stout-kbs",
    "untappd_brewery_id": 549,
    "name": "Kentucky Breakfast Stout (KBS)",
    "original_name": "Kentucky Breakfast Stout (KBS)",
    "custom_name": null,
    "description": "This beer taught us that patience truly is a virtue. KBS is a big imperial stout brewed with a massive amount of coffee and chocolate and then bourbon barrel-aged to perfection. Incredibly silky and full-bodied with notes of vanilla, cocoa, roasted coffee and charred oak.",
    "custom_description": null,
    "original_description": "This beer taught us that patience truly is a virtue. KBS is a big imperial stout brewed with a massive amount of coffee and chocolate and then bourbon barrel-aged to perfection. Incredibly silky and full-bodied with notes of vanilla, cocoa, roasted coffee and charred oak.",
    "style": "Stout - Imperial / Double Coffee",
    "custom_style": null,
    "original_style": "Stout - Imperial / Double Coffee",
    "brewery": "Founders Brewing Co.",
    "brewery_country": "United States",
    "custom_brewery": null,
    "original_brewery": "Founders Brewing Co.",
    "calories": "340",
    "custom_calories": null,
    "original_calories": "340",
    "abv": "12.0",
    "custom_abv": null,
    "original_abv": "12.0",
    "ibu": "70.0",
    "custom_ibu": null,
    "original_ibu": "70.0",
    "created_at": "2023-03-21T14:14:17.526349Z",
    "updated_at": "2023-03-21T14:14:17.526936Z",
    "type": "beer",
    "default_image": "https://assets.untappd.com/site/assets/images/temp/badge-beer-default.png",
    "producer": null,
    "vintage": null,
    "characteristics": null,
    "category": null,
    "location": null
  }
}

HTTP Request

PATCH https://business.untappd.com/api/v1/items/:id/move

Query Parameters

Parameter Validations Required Description
id Integer true The id of the item.
section_id Integer true The section_id of the section to move the item to.

Search for item

Search the Untappd beer database for an item.

This is the route that might be used to first find an item to add before calling Create an item with the untappd_id.

Request:

curl "http://localhost:3000/api/v1/items/search?q=pbr" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="

Returns JSON structured like this:

{
  "items": [
    {
      "id": null,
      "section_id": null,
      "position": null,
      "untappd_id": 3883,
      "label_image": "https://beer.untappd.com/labels/3883",
      "label_image_hd": "https://beer.untappd.com/labels/3883?size=hd",
      "label_image_thumb": "https://beer.untappd.com/labels/3883",
      "original_label_image": "https://beer.untappd.com/labels/3883",
      "original_label_image_hd": "https://beer.untappd.com/labels/3883?size=hd",
      "custom_label_image": null,
      "custom_label_image_thumb": null,
      "custom_label_image_filename": null,
      "brewery_location": "San Antonio, TX",
      "cask": false,
      "nitro": false,
      "local": false,
      "tap_number": null,
      "rating": "2.83077",
      "rating_count": 379754,
      "in_production": true,
      "untappd_beer_slug": "pabst-brewing-company-pabst-blue-ribbon",
      "untappd_brewery_id": 963,
      "name": "Pabst Blue Ribbon",
      "original_name": "Pabst Blue Ribbon",
      "custom_name": null,
      "description": "This is the original Pabst Blue Ribbon Beer. Nature's choicest products provide its prized flavor. Only the finest of hops and grains are used. Selected as America's Best in 1893.",
      "custom_description": null,
      "original_description": "This is the original Pabst Blue Ribbon Beer. Nature's choicest products provide its prized flavor. Only the finest of hops and grains are used. Selected as America's Best in 1893.",
      "style": "Lager - American",
      "custom_style": null,
      "original_style": "Lager - American",
      "brewery": "Pabst Brewing Company",
      "brewery_country": "United States",
      "custom_brewery": null,
      "original_brewery": "Pabst Brewing Company",
      "calories": "140",
      "custom_calories": null,
      "original_calories": "140",
      "abv": "4.8",
      "custom_abv": null,
      "original_abv": "4.8",
      "ibu": "10.0",
      "custom_ibu": null,
      "original_ibu": "10.0",
      "created_at": null,
      "updated_at": null,
      "type": "beer",
      "default_image": "https://assets.untappd.com/site/assets/images/temp/badge-beer-default.png",
      "producer": null,
      "vintage": null,
      "characteristics": null,
      "category": null,
      "location": null
    },
    {
      "id": null,
      "section_id": null,
      "position": null,
      "untappd_id": 3396518,
      "label_image": "https://beer.untappd.com/labels/3396518",
      "label_image_hd": "https://beer.untappd.com/labels/3396518?size=hd",
      "label_image_thumb": "https://beer.untappd.com/labels/3396518",
      "original_label_image": "https://beer.untappd.com/labels/3396518",
      "original_label_image_hd": "https://beer.untappd.com/labels/3396518?size=hd",
      "custom_label_image": null,
      "custom_label_image_thumb": null,
      "custom_label_image_filename": null,
      "brewery_location": "San Antonio, TX",
      "cask": false,
      "nitro": false,
      "local": false,
      "tap_number": null,
      "rating": "3.90427",
      "rating_count": 45210,
      "in_production": true,
      "untappd_beer_slug": "pabst-brewing-company-pabst-blue-ribbon-hard-coffee",
      "untappd_brewery_id": 963,
      "name": "Pabst Blue Ribbon Hard Coffee",
      "original_name": "Pabst Blue Ribbon Hard Coffee",
      "custom_name": null,
      "description": "Coffee flavored malt beverage. ",
      "custom_description": null,
      "original_description": "Coffee flavored malt beverage. ",
      "style": "Flavored Malt Beverage",
      "custom_style": null,
      "original_style": "Flavored Malt Beverage",
      "brewery": "Pabst Brewing Company",
      "brewery_country": "United States",
      "custom_brewery": null,
      "original_brewery": "Pabst Brewing Company",
      "calories": "150",
      "custom_calories": null,
      "original_calories": "150",
      "abv": "5.0",
      "custom_abv": null,
      "original_abv": "5.0",
      "ibu": "0.0",
      "custom_ibu": null,
      "original_ibu": "0.0",
      "created_at": null,
      "updated_at": null,
      "type": "beer",
      "default_image": "https://assets.untappd.com/site/assets/images/temp/badge-beer-default.png",
      "producer": null,
      "vintage": null,
      "characteristics": null,
      "category": null,
      "location": null
    },
    {
      "id": null,
      "section_id": null,
      "position": null,
      "untappd_id": 3099757,
      "label_image": "https://beer.untappd.com/labels/3099757",
      "label_image_hd": "https://beer.untappd.com/labels/3099757?size=hd",
      "label_image_thumb": "https://beer.untappd.com/labels/3099757",
      "original_label_image": "https://beer.untappd.com/labels/3099757",
      "original_label_image_hd": "https://beer.untappd.com/labels/3099757?size=hd",
      "custom_label_image": null,
      "custom_label_image_thumb": null,
      "custom_label_image_filename": null,
      "brewery_location": "San Antonio, TX",
      "cask": false,
      "nitro": false,
      "local": false,
      "tap_number": null,
      "rating": "3.11095",
      "rating_count": 6662,
      "in_production": true,
      "untappd_beer_slug": "pabst-brewing-company-pabst-blue-ribbon-extra",
      "untappd_brewery_id": 963,
      "name": "Pabst Blue Ribbon Extra",
      "original_name": "Pabst Blue Ribbon Extra",
      "custom_name": null,
      "description": "",
      "custom_description": null,
      "original_description": "",
      "style": "Lager - American",
      "custom_style": null,
      "original_style": "Lager - American",
      "brewery": "Pabst Brewing Company",
      "brewery_country": "United States",
      "custom_brewery": null,
      "original_brewery": "Pabst Brewing Company",
      "calories": "195",
      "custom_calories": null,
      "original_calories": "195",
      "abv": "6.5",
      "custom_abv": null,
      "original_abv": "6.5",
      "ibu": "0.0",
      "custom_ibu": null,
      "original_ibu": "0.0",
      "created_at": null,
      "updated_at": null,
      "type": "beer",
      "default_image": "https://assets.untappd.com/site/assets/images/temp/badge-beer-default.png",
      "producer": null,
      "vintage": null,
      "characteristics": null,
      "category": null,
      "location": null
    }
  ]
}

HTTP Request

GET https://business.untappd.com/api/v1/items/search

Query Parameters

Parameter Validations Required Description
q String true The query string used to search for an item.

Share an item

Share an item to Twitter or Facebook.

Request:

curl "http://localhost:3000/api/v1/items/2/share?social_channel=twitter" \
  -X POST \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="

Response is a 200 OK http status code with an empty object json if there are no errors:

{}

If the social channel is not linked on the user's profile you will get a response like this:

{
  "error": {
    "status": 400,
    "title": "social channel not linked",
    "detail": "The social channel is not linked. The user must link their twitter account before utilizing it.",
    "code": "Errors::SocialChannelNotLinkedError",
    "social_channel": "twitter",
    "item_id": 2,
    "redirect_to": "/locations/3/social"
  }
}

HTTP Request

POST https://business.untappd.com/api/v1/items/:item_id/share

Query Parameters

Parameter Validations Required Description
item_id String true The item to share.
social_channel facebook/twitter true The social channel to share to.

Sort items

Sort the items in a section by the sorter method. This sort is persistent; --it will set the position property on each item.

Request:

curl "http://localhost:3000/api/v1/sections/1/items/sort?sort_by=alphabetically" \
  -X PATCH \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="

Response is all the items for the section with updated and sorted position:

{
  "items": [
    {
      "id": 65,
      "section_id": 10,
      "position": 0,
      "untappd_id": null,
      "label_image": "https://www.wine-searcher.com/images/labels/19/94/10531994.jpg?width=50&height=50&fit=bounds&canvas=50,50",
      "label_image_hd": "https://s3.amazonaws.com/woof.nextglass.co/default/wine.svg",
      "label_image_thumb": "https://www.wine-searcher.com/images/labels/19/94/10531994.jpg?width=50&height=50&fit=bounds&canvas=50,50",
      "original_label_image": "https://beer.untappd.com/labels/",
      "original_label_image_hd": "https://beer.untappd.com/labels/?size=hd",
      "custom_label_image": null,
      "custom_label_image_thumb": null,
      "custom_label_image_filename": null,
      "brewery_location": null,
      "cask": false,
      "nitro": false,
      "local": false,
      "tap_number": null,
      "rating": null,
      "rating_count": null,
      "in_production": null,
      "untappd_beer_slug": null,
      "untappd_brewery_id": null,
      "name": "Bodegas Campo Viejo Tempranillo",
      "original_name": null,
      "custom_name": null,
      "description": "A cherry red colour suggests a vibrant Tempranillo wine. On the nose, the rich aromas have a pronounced intensity with an initial scent of ripe fruits followed by gentle sweet notes of vanilla and spices. On the palate, it is perfumed, soft and fresh with a long finish.",
      "custom_description": "A cherry red colour suggests a vibrant Tempranillo wine. On the nose, the rich aromas have a pronounced intensity with an initial scent of ripe fruits followed by gentle sweet notes of vanilla and spices. On the palate, it is perfumed, soft and fresh with a long finish.",
      "original_description": null,
      "style": null,
      "custom_style": null,
      "original_style": null,
      "brewery": null,
      "brewery_country": null,
      "custom_brewery": null,
      "original_brewery": null,
      "calories": null,
      "custom_calories": null,
      "original_calories": null,
      "abv": "13.5",
      "custom_abv": null,
      "original_abv": null,
      "ibu": null,
      "custom_ibu": null,
      "original_ibu": null,
      "created_at": "2023-03-21T13:02:01.593381Z",
      "updated_at": "2023-03-21T14:14:17.533411Z",
      "type": "wine",
      "default_image": "https://s3.amazonaws.com/woof.nextglass.co/default/wine.svg",
      "producer": "Bodegas Campo Viejo",
      "vintage": null,
      "characteristics": "Red - Savory and Classic",
      "category": "Tempranillo",
      "location": "Rioja, Spain"
    },
    {
      "id": 64,
      "section_id": 10,
      "position": 1,
      "untappd_id": 4473,
      "label_image": "https://beer.untappd.com/labels/4473",
      "label_image_hd": "https://beer.untappd.com/labels/4473?size=hd",
      "label_image_thumb": "https://beer.untappd.com/labels/4473",
      "original_label_image": "https://beer.untappd.com/labels/4473",
      "original_label_image_hd": "https://beer.untappd.com/labels/4473?size=hd",
      "custom_label_image": null,
      "custom_label_image_thumb": null,
      "custom_label_image_filename": null,
      "brewery_location": "Dublin, County Dublin",
      "cask": false,
      "nitro": true,
      "local": false,
      "tap_number": "1",
      "rating": "3.76886",
      "rating_count": 801407,
      "in_production": true,
      "untappd_beer_slug": "guinness-guinness-draught",
      "untappd_brewery_id": 49,
      "name": "Guinness Draught",
      "original_name": "Guinness Draught",
      "custom_name": null,
      "description": "Swirling clouds tumble as the storm begins to calm. Settle. Breathe in the moment, then break through the smooth, light head to the bittersweet reward.\r\n\r\nUnmistakeably GUINNESS, from the first velvet sip to the last, lingering drop. And every deep-dark satisfying mouthful in between.\r\n\r\nPure beauty. Pure GUINNESS.\r\n\r\nGuinness Draught is sold in kegs, widget cans, and bottles. The ABV varies from 4.1 to 4.3%.\r\n\r\nGuinness Extra Cold is the exact same beer only served through a super cooler at 3.5 °C",
      "custom_description": null,
      "original_description": "Swirling clouds tumble as the storm begins to calm. Settle. Breathe in the moment, then break through the smooth, light head to the bittersweet reward.\r\n\r\nUnmistakeably GUINNESS, from the first velvet sip to the last, lingering drop. And every deep-dark satisfying mouthful in between.\r\n\r\nPure beauty. Pure GUINNESS.\r\n\r\nGuinness Draught is sold in kegs, widget cans, and bottles. The ABV varies from 4.1 to 4.3%.\r\n\r\nGuinness Extra Cold is the exact same beer only served through a super cooler at 3.5 °C",
      "style": "Stout - Irish Dry",
      "custom_style": null,
      "original_style": "Stout - Irish Dry",
      "brewery": "Guinness",
      "brewery_country": "Ireland",
      "custom_brewery": null,
      "original_brewery": "Guinness",
      "calories": "125",
      "custom_calories": null,
      "original_calories": "125",
      "abv": "4.2",
      "custom_abv": null,
      "original_abv": "4.2",
      "ibu": "45.0",
      "custom_ibu": null,
      "original_ibu": "45.0",
      "created_at": "2023-03-21T13:01:26.220225Z",
      "updated_at": "2023-03-21T14:14:17.533411Z",
      "type": "beer",
      "default_image": "https://assets.untappd.com/site/assets/images/temp/badge-beer-default.png",
      "producer": null,
      "vintage": null,
      "characteristics": null,
      "category": null,
      "location": null
    }
  ]
}

HTTP Request

PATCH https://business.untappd.com/api/v1/sections/:section_id/items/sort

Query Parameters

Parameter Validations Required Description
section_id String true The section to sort items for.
sort_by String true The method by which to sort the items.

Note: When ordering items with the same brewery, sort_by: brewery will first sort alphabetically by brewery then will fall back to sorting alphabetically by item name.

Sorter Methods

sort_by Description
tap_number Sort by Tap Number
alphabetically A-Z
reverse_alphabetically Z-A
brewery A-Z
style A-Z
abv 0-100
reverse_abv 100-0

Locations

List all locations

List the locations belonging to the currently authorized user.

curl "http://localhost:3000/api/v1/locations" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="

Returns JSON structured like this:

{
  "locations": [
    {
      "id": 3,
      "name": "Pied Piper",
      "formatted_address": "21 S Front St, Wilmington, NC 28401, USA",
      "full_address": "21 S Front St, , Wilmington, North Carolina, 28401, United States",
      "address1": "21 S Front St",
      "address2": "",
      "city": "Wilmington",
      "postcode": "28401",
      "region": "North Carolina",
      "country": "United States",
      "latitude": "34.2346553",
      "longitude": "-77.9482581",
      "website": "http://business.untappd.com",
      "contact_email": "[email protected]",
      "phone": "910-333-1245",
      "untappd_venue_id": 4174364,
      "created_at": "2016-06-16T19:29:59Z",
      "updated_at": "2016-06-16T19:50:32Z",
      "business_id": 3,
      "cross_streets": "",
      "neighborhood": "Downtown Wilmington",
      "timezone": "Eastern Time (US & Canada)",
      "tz_offset": -4,
      "directions": "Turn right at the fork.",
      "description": "Erlich Bachman's Incubator (A.K.A his House)",
      "in_business_since": 2021,
      "number_of_taps": null,
      "food_served": "food_served_yes",
      "growler_filling_station": "growler_filling_station_no",
      "crowler_filling_station": "crowler_filling_station_no",
      "kegs": "kegs_yes",
      "hours": [
        {
          "id": 1,
          "always_open": false,
          "closed": false,
          "open_at": "2000-01-01T08:00:00.000Z",
          "close_at": "2000-01-01T18:00:00.000Z",
          "day": "monday",
          "location_id": 3,
          "created_at": "2020-02-17T20:16:23.508Z",
          "updated_at": "2020-02-17T20:16:23.508Z"
        },
        {
          "id": 2,
          "always_open": false,
          "closed": false,
          "open_at": "2000-01-01T08:00:00.000Z",
          "close_at": "2000-01-01T18:00:00.000Z",
          "day": "tuesday",
          "location_id": 3,
          "created_at": "2020-02-17T20:16:23.511Z",
          "updated_at": "2020-02-17T20:16:23.511Z"
        },
        {
          "id": 3,
          "always_open": false,
          "closed": false,
          "open_at": "2000-01-01T08:00:00.000Z",
          "close_at": "2000-01-01T18:00:00.000Z",
          "day": "wednesday",
          "location_id": 3,
          "created_at": "2020-02-17T20:16:23.615Z",
          "updated_at": "2020-02-17T20:16:23.615Z"
        },
        {
          "id": 4,
          "always_open": false,
          "closed": false,
          "open_at": "2000-01-01T08:00:00.000Z",
          "close_at": "2000-01-01T18:00:00.000Z",
          "day": "thursday",
          "location_id": 3,
          "created_at": "2020-02-17T20:16:23.617Z",
          "updated_at": "2020-02-17T20:16:23.617Z"
        },
        {
          "id": 5,
          "always_open": false,
          "closed": false,
          "open_at": "2000-01-01T08:00:00.000Z",
          "close_at": "2000-01-01T18:00:00.000Z",
          "day": "friday",
          "location_id": 3,
          "created_at": "2020-02-17T20:16:23.619Z",
          "updated_at": "2020-02-17T20:16:23.619Z"
        },
        {
          "id": 6,
          "always_open": false,
          "closed": false,
          "open_at": "2000-01-01T08:00:00.000Z",
          "close_at": "2000-01-01T18:00:00.000Z",
          "day": "saturday",
          "location_id": 3,
          "created_at": "2020-02-17T20:16:23.621Z",
          "updated_at": "2020-02-17T20:16:23.621Z"
        },
        {
          "id": 7,
          "always_open": false,
          "closed": false,
          "open_at": "2000-01-01T08:00:00.000Z",
          "close_at": "2000-01-01T18:00:00.000Z",
          "day": "sunday",
          "location_id": 3,
          "created_at": "2020-02-17T20:16:23.623Z",
          "updated_at": "2020-02-17T20:16:23.623Z"
        }
      ],
      "nitro_on_tap": "nitro_on_tap_no",
      "cask_on_tap": "cask_on_tap_no",
      "serve_wine": "serve_wine_yes",
      "serve_cocktails": "serve_cocktails_yes",
      "serve_liquor": "serve_liquor_yes",
      "outdoor_seating": "outdoor_seating_yes",
      "pet_friendly": "pet_friendly_yes",
      "contact_name": "Starbuck",
      "contact_phone": "(910) 333 - 1245",
      "published_at_untappd": null,
      "published_at_embed": null,
      "published_at_facebook": null,
      "published_count": 0,
      "currency": "USD",
      "currency_symbol": "$",
      "suspended": false,
      "accepted_payment_types": [
        "visa",
        "master_card",
        "american_express",
        "discover",
        "check"
      ],
      "twitter_linked": false,
      "facebook_post_page": false,
      "facebook_menu_page": false,
      "country_name": "United States",
      "website_url": "http://business.untappd.com"
    }
  ]
}

HTTP Request

GET https://business.untappd.com/api/v1/locations

Retrieve a location

Retrieve the information of an existing location. You need only supply the unique location identifier.

curl "http://localhost:3000/api/v1/locations/1234" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="

Returns JSON structured like this:

{
  "location": {
    "id": 1234,
    "name": "Deadpool's Pizza & Pint ",
    "formatted_address": "21 S Front St, Wilmington, NC 28401, USA",
    "full_address": "21 S Front St, , Wilmington, North Carolina, 28401, US",
    "address1": "21 S Front St",
    "address2": "",
    "city": "Wilmington",
    "postcode": "28401",
    "region": "North Carolina",
    "country": "US",
    "latitude": "34.2346598",
    "longitude": "-77.9482096",
    "website": "business.untappd.com",
    "contact_email": "[email protected]",
    "phone": "910 292 4336",
    "untappd_venue_id": 8943870,
    "created_at": "2019-05-13T18:10:26.419925Z",
    "updated_at": "2020-08-12T01:50:15.296375Z",
    "cross_streets": null,
    "neighborhood": null,
    "timezone": "Eastern Time (US & Canada)",
    "tz_offset": -4,
    "directions": null,
    "description": null,
    "in_business_since": null,
    "number_of_taps": null,
    "food_served": "unknown",
    "growler_filling_station": "unknown",
    "hours": [
      {
        "id": 181211,
        "always_open": false,
        "closed": false,
        "open_at": "2000-01-01T08:00:00.000Z",
        "close_at": "2000-01-01T18:00:00.000Z",
        "day": "monday",
        "location_id": 25592,
        "created_at": "2019-05-13T18:10:26.443Z",
        "updated_at": "2019-05-13T18:10:26.443Z"
      },
      {
        "id": 181212,
        "always_open": false,
        "closed": false,
        "open_at": "2000-01-01T08:00:00.000Z",
        "close_at": "2000-01-01T18:00:00.000Z",
        "day": "tuesday",
        "location_id": 25592,
        "created_at": "2019-05-13T18:10:26.446Z",
        "updated_at": "2019-05-13T18:10:26.446Z"
      },
      {
        "id": 181213,
        "always_open": false,
        "closed": false,
        "open_at": "2000-01-01T08:00:00.000Z",
        "close_at": "2000-01-01T18:00:00.000Z",
        "day": "wednesday",
        "location_id": 25592,
        "created_at": "2019-05-13T18:10:26.448Z",
        "updated_at": "2019-05-13T18:10:26.448Z"
      },
      {
        "id": 181214,
        "always_open": false,
        "closed": false,
        "open_at": "2000-01-01T08:00:00.000Z",
        "close_at": "2000-01-01T18:00:00.000Z",
        "day": "thursday",
        "location_id": 25592,
        "created_at": "2019-05-13T18:10:26.451Z",
        "updated_at": "2019-05-13T18:10:26.451Z"
      },
      {
        "id": 181215,
        "always_open": false,
        "closed": false,
        "open_at": "2000-01-01T08:00:00.000Z",
        "close_at": "2000-01-01T18:00:00.000Z",
        "day": "friday",
        "location_id": 25592,
        "created_at": "2019-05-13T18:10:26.453Z",
        "updated_at": "2019-05-13T18:10:26.453Z"
      },
      {
        "id": 181216,
        "always_open": false,
        "closed": false,
        "open_at": "2000-01-01T08:00:00.000Z",
        "close_at": "2000-01-01T18:00:00.000Z",
        "day": "saturday",
        "location_id": 25592,
        "created_at": "2019-05-13T18:10:26.456Z",
        "updated_at": "2019-05-13T18:10:26.456Z"
      },
      {
        "id": 181217,
        "always_open": false,
        "closed": false,
        "open_at": "2000-01-01T08:00:00.000Z",
        "close_at": "2000-01-01T18:00:00.000Z",
        "day": "sunday",
        "location_id": 25592,
        "created_at": "2019-05-13T18:10:26.458Z",
        "updated_at": "2019-05-13T18:10:26.458Z"
      }
    ],
    "crowler_filling_station": "unknown",
    "kegs": "unknown",
    "nitro_on_tap": "unknown",
    "cask_on_tap": "unknown",
    "serve_wine": "unknown",
    "serve_cocktails": "unknown",
    "serve_liquor": "unknown",
    "outdoor_seating": "unknown",
    "pet_friendly": "unknown",
    "child_friendly": "unknown",
    "smoke_friendly": "unknown",
    "contact_name": "Edward",
    "contact_phone": "910 292 4336",
    "published_at_untappd": "2020-08-04T23:03:01.721599Z",
    "published_at_embed": "2020-08-12T01:51:00.431259Z",
    "published_at_facebook": "2020-08-12T01:51:00.431259Z",
    "published_count": 3,
    "currency": "USD",
    "currency_symbol": "$",
    "accepted_payment_types": [],
    "twitter_linked": false,
    "facebook_post_page": false,
    "facebook_menu_page": false,
    "country_name": "United States of America",
    "website_url": "http://business.untappd.com",
    "mailing_address1": null,
    "mailing_address2": null,
    "mailing_city": null,
    "mailing_postcode": null,
    "mailing_region": null,
    "mailing_country": null
  }
}

HTTP Request

GET https://business.untappd.com/api/v1/locations/:id

Query Parameters

Parameter Validations Required Description
id Integer true The id of the location.

Update a location

Updates the specified location by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Request:

curl "http://localhost:3000/api/v1/locations/1" \
  -X PATCH \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04=" \
  -H "Content-Type: application/json" \
  -d '{ "location": { "mailing_address1": "123 Bourbon St" } }'

Returns JSON structured like this:

{
  "location": {
    "id": 1,
    "name": "Pizzas & Pints",
    "country": "US",
    "address1": "21 S Front St",
    "city": "Wilmington",
    "region": "North Carolina",
    "timezone": "Eastern Time (US & Canada)",
    "untappd_venue_id": 8943870,
    "in_business_since": null,
    "number_of_taps": null,
    "address2": "",
    "postcode": "28401",
    "latitude": "34.2346598",
    "longitude": "-77.9482096",
    "website": "business.untappd.com",
    "contact_email": "[email protected]",
    "phone": "910 292 4336",
    "created_at": "2019-05-13T18:10:26.419Z",
    "updated_at": "2020-08-12T14:11:23.037Z",
    "cross_streets": null,
    "neighborhood": null,
    "directions": null,
    "description": null,
    "food_served": "unknown",
    "growler_filling_station": "unknown",
    "crowler_filling_station": "unknown",
    "kegs": "unknown",
    "nitro_on_tap": "unknown",
    "cask_on_tap": "unknown",
    "serve_wine": "unknown",
    "serve_cocktails": "unknown",
    "outdoor_seating": "unknown",
    "pet_friendly": "unknown",
    "facebook_menu_page_id": null,
    "facebook_menu_page_name": null,
    "facebook_menu_page_access_token": null,
    "facebook_post_page_id": null,
    "facebook_post_page_name": null,
    "facebook_post_page_access_token": null,
    "twitter_id": null,
    "twitter_access_token": null,
    "twitter_access_token_secret": null,
    "twitter_username": null,
    "logo_file_name": null,
    "logo_content_type": null,
    "logo_file_size": null,
    "logo_updated_at": null,
    "display_logo_on_menu": true,
    "contact_name": "Thor",
    "contact_phone": "910 292 4336",
    "published_at_untappd": "2020-08-04T23:03:01.721Z",
    "serve_liquor": "unknown",
    "currency": "USD",
    "child_friendly": "unknown",
    "formatted_address": "21 S Front St, Wilmington, NC 28401, USA",
    "published_at_embed": "2020-08-12T01:51:00.431Z",
    "published_at_facebook": "2020-08-12T01:51:00.431Z",
    "pushed_untappd_at": "2020-08-12T01:51:00.431Z",
    "pushed_embed_at": "2020-08-12T01:51:00.431Z",
    "pushed_facebook_at": "2020-08-12T01:51:00.431Z",
    "untappd_venue_access_token": "EE1A0A290BCA3AFE0DD8279BCE680214D52F8AF8",
    "automatic_facebook_event_sync": false,
    "digital_board_last_loaded_at": "2020-08-11T20:16:09.935Z",
    "website_embed_last_seen_at": null,
    "menu_last_updated_at": "2020-08-04T23:02:43.464Z",
    "digital_board_version": 2,
    "needs_touch": null,
    "print_version": 2,
    "business_type": "bar",
    "first_publish_at": "2019-06-24T17:43:06.390Z",
    "festival_start_on": null,
    "festival_end_on": null,
    "organization_id": null,
    "mailing_address1": "123 Bourbon St",
    "mailing_address2": null,
    "mailing_city": null,
    "mailing_postcode": null,
    "mailing_region": null,
    "mailing_country": null,
    "smoke_friendly": "unknown"
  },
  "errors": null
}

HTTP Request

PUT https://business.untappd.com/api/v1/locations/:id PATCH https://business.untappd.com/api/v1/locations/:id

Query Parameters

Parameter Validations Required Description
id Integer true The id of the location.
mailing_address1 String false The location mailing street address.
mailing_address2 String false The location mailing address (PO Box, Apt, Ste, etc.)
mailing_city String false The location mailing city
mailing_postcode String false The location mailing postcode
mailing_region String false The location mailing state/region
mailing_country String false The location mailing country

Update a location's details

Updates the specified location's details by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Request:

curl "http://localhost:3000/api/v1/locations/1/details" \
  -X PATCH \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04=" \
  -H "Content-Type: application/json" \
  -d '{ "currency": "USD", "description": "We really like beer here!", "nitro_on_tap": 1, "categories": ["55a59bace4b013909087cb36"] }'

Returns JSON structured like this:

{
  "location": {
    "id": 1,
    "name": "Pizzas & Pints",
    "country": "US",
    "address1": "21 S Front St",
    "city": "Wilmington",
    "region": "North Carolina",
    "timezone": "Eastern Time (US & Canada)",
    "untappd_venue_id": 8943870,
    "in_business_since": null,
    "number_of_taps": null,
    "address2": "",
    "postcode": "28401",
    "latitude": "34.2346598",
    "longitude": "-77.9482096",
    "website": "business.untappd.com",
    "contact_email": "[email protected]",
    "phone": "910 292 4336",
    "created_at": "2019-05-13T18:10:26.419Z",
    "updated_at": "2020-08-12T14:11:23.037Z",
    "cross_streets": null,
    "neighborhood": null,
    "directions": null,
    "description": "We really like beer here!",
    "food_served": "unknown",
    "growler_filling_station": "unknown",
    "crowler_filling_station": "unknown",
    "kegs": "unknown",
    "nitro_on_tap": "yes",
    "cask_on_tap": "unknown",
    "serve_wine": "unknown",
    "serve_cocktails": "unknown",
    "outdoor_seating": "unknown",
    "pet_friendly": "unknown",
    "facebook_menu_page_id": null,
    "facebook_menu_page_name": null,
    "facebook_menu_page_access_token": null,
    "facebook_post_page_id": null,
    "facebook_post_page_name": null,
    "facebook_post_page_access_token": null,
    "twitter_id": null,
    "twitter_access_token": null,
    "twitter_access_token_secret": null,
    "twitter_username": null,
    "logo_file_name": null,
    "logo_content_type": null,
    "logo_file_size": null,
    "logo_updated_at": null,
    "display_logo_on_menu": true,
    "contact_name": "Thor",
    "contact_phone": "910 292 4336",
    "published_at_untappd": "2020-08-04T23:03:01.721Z",
    "serve_liquor": "unknown",
    "currency": "USD",
    "child_friendly": "unknown",
    "formatted_address": "21 S Front St, Wilmington, NC 28401, USA",
    "published_at_embed": "2020-08-12T01:51:00.431Z",
    "published_at_facebook": "2020-08-12T01:51:00.431Z",
    "pushed_untappd_at": "2020-08-12T01:51:00.431Z",
    "pushed_embed_at": "2020-08-12T01:51:00.431Z",
    "pushed_facebook_at": "2020-08-12T01:51:00.431Z",
    "untappd_venue_access_token": "EE1A0A290BCA3AFE0DD8279BCE680214D52F8AF8",
    "automatic_facebook_event_sync": false,
    "digital_board_last_loaded_at": "2020-08-11T20:16:09.935Z",
    "website_embed_last_seen_at": null,
    "menu_last_updated_at": "2020-08-04T23:02:43.464Z",
    "digital_board_version": 2,
    "needs_touch": null,
    "print_version": 2,
    "business_type": "bar",
    "first_publish_at": "2019-06-24T17:43:06.390Z",
    "festival_start_on": null,
    "festival_end_on": null,
    "organization_id": null,
    "mailing_address1": "123 Bourbon St",
    "mailing_address2": null,
    "mailing_city": null,
    "mailing_postcode": null,
    "mailing_region": null,
    "mailing_country": null,
    "smoke_friendly": "unknown"
  },
  "errors": null
}

HTTP Request

PUT https://business.untappd.com/api/v1/locations/:id/details PATCH https://business.untappd.com/api/v1/locations/:id/details

Query Parameters

Parameter Validations Required Description
id Integer true The id of the location.
timezone String false The location timezone.
currency String false The location accepted currency
description String false The location description
food_served String false The food served at the location
growler_filling_station String false Whether the location fills growlers
crowler_filling_station String false Whether the location fills crowlers
kegs String false Whether the location carries kegs
nitro_on_tap String false Whether the location has nitro on tap
cask_on_tap String false Whether the location has casks on tap
serve_wine String false Whether the location serves wine
serve_liquor String false Whether the location serves liquor
serve_cocktails String false Whether the location serves cocktails
categories String[] false The location categories; minimum 1 required, maximum 4 allowed. Passing an empty array will not add or remove any existing categories.
accepted_payment_types String[] false The location accepted payment types

Menu Announcements

List all menu announcements

Returns a list of menu announcements belonging to your location.

Request:

curl "http://localhost:3000/api/v1/locations/3/menu_announcements" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286VUJnelJtUnpLZl9YUTZ5RHV0Qko="

Returns JSON structured like this:

{
  "menu_announcements": {
    "current": [
      {
        "id": 1,
        "location_id": 3,
        "created_at": "2016-10-12T13:08:57Z",
        "updated_at": "2016-10-12T13:08:57Z",
        "content": "This is an announcement that goes out immediately.",
        "period": "now",
        "canceled": false,
        "next_publish_at": null,
        "last_published_at": "2016-10-12T13:08:57Z",
        "type": "MenuAnnouncement",
        "post_to_facebook": false,
        "post_to_twitter": false,
        "display_on_embed_menu": true,
        "display_on_print_menu": false,
        "display_on_digital_board": false
      }
    ],
    "upcoming": [
      {
        "id": 2,
        "location_id": 3,
        "created_at": "2016-10-12T13:27:27Z",
        "updated_at": "2016-10-12T13:27:27Z",
        "content": "This is an announcement that goes out immediately.",
        "period": "once",
        "canceled": false,
        "next_publish_at": "2016-10-15T17:21:51Z",
        "last_published_at": null,
        "type": "MenuAnnouncement",
        "post_to_facebook": false,
        "post_to_twitter": false,
        "display_on_embed_menu": true,
        "display_on_print_menu": false,
        "display_on_digital_board": false
      }
    ],
    "weekly": [
      {
        "id": 3,
        "location_id": 3,
        "created_at": "2016-10-12T13:28:07Z",
        "updated_at": "2016-10-12T13:28:07Z",
        "content": "This is an announcement that goes out immediately.",
        "period": "weekly",
        "canceled": false,
        "next_publish_at": "2016-11-15T18:21:51Z",
        "last_published_at": null,
        "type": "MenuAnnouncement",
        "post_to_facebook": false,
        "post_to_twitter": false,
        "display_on_embed_menu": true,
        "display_on_print_menu": false,
        "display_on_digital_board": false
      }
    ]
  }
}

HTTP Request

GET https://business.untappd.com/api/v1/locations/:location_id/menu_announcements

Query Parameters

Parameter Validations Required Description
location_id Integer true The id of the location.

Create a menu announcement

Creates a new menu announcement.

Request:

curl "http://localhost:3000/api/v1/locations/3/menu_announcements" \
  -X POST \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286VUJnelJtUnpLZl9YUTZ5RHV0Qko=" \
  -H "Content-Type: application/json" \
  -d '{ "menu_announcement": { "content": "This is an announcement that goes out once per week.", "period": "weekly", "next_publish_at": "2016-11-15T13:21:51Z", "display_on_embed_menu": true } }'

Returns JSON structured like this:

{
  "menu_announcement": {
    "id": 3,
    "location_id": 3,
    "created_at": "2016-10-12T13:28:07Z",
    "updated_at": "2016-10-12T13:28:07Z",
    "content": "This is an announcement that goes out once per week.",
    "period": "weekly",
    "canceled": false,
    "next_publish_at": "2016-11-15T18:21:51Z",
    "last_published_at": null,
    "type": "MenuAnnouncement",
    "post_to_facebook": false,
    "post_to_twitter": false,
    "display_on_embed_menu": true,
    "display_on_print_menu": false,
    "display_on_digital_board": false
  }
}

HTTP Request

POST https://business.untappd.com/api/v1/locations/:location_id/menu_announcements

Query Parameters

Parameter Validations Required Description
location_id Integer true The id of the location.
content String true The main content for the announcement. ex. "Join us for happy hour at 3pm!"
next_publish_at String true The date and time the announcement should be published at. Date time format must be iso8601. Not necessary when supplying period=now.
period String now / once / weekly true When the announcement should be posted. "now" posts the announcement immediately once. "once" posts the announcement at a future time. "weekly" is a reoccurring announcement that will post every week at the given next_publish_at date and time.
display_on_embed_menu Boolean false Indicates that the announcement should be displayed on the embedded menus.
display_on_print_menu Boolean false Indicates that the announcement should be displayed on the print menus.
display_on_digital_board Boolean false Indicates that the announcement should be displayed on the digital boards.

Cancel a menu announcement

Permanently deletes a menu announcement. It cannot be undone.

Request:

curl "http://localhost:3000/api/v1/menu_announcements/1" \
  -X DELETE \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286VUJnelJtUnpLZl9YUTZ5RHV0Qko="

Returns the canceled menu announcement as JSON structured like this. Notice canceled is now true.):

{
  "menu_announcement": {
    "id": 1,
    "location_id": 3,
    "created_at": "2016-10-12T13:08:57Z",
    "updated_at": "2016-10-12T13:57:13Z",
    "content": "This is an announcement that goes out immediately.",
    "period": "now",
    "canceled": true,
    "next_publish_at": null,
    "last_published_at": "2016-10-12T13:08:57Z",
    "type": "MenuAnnouncement",
    "post_to_facebook": false,
    "post_to_twitter": false,
    "display_on_embed_menu": true,
    "display_on_print_menu": false,
    "display_on_digital_board": false
  }
}

HTTP Request

DELETE https://business.untappd.com/api/v1/menu_announcements/:id

Query Parameters

Parameter Validations Required Description
id Integer true The menu announcement to be canceled.

Menu History

Menu history, or more accurately Item history, is useful for restoring items that were previously on a menu but have since been removed.

List historical items

Returns a list of historical items.

Request:

curl --include "http://localhost:3000/api/v1/locations/3/historical_items" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="

'curl --include' switch will display the response http headers:

HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Link: <http://localhost:3000/api/v1/locations/3/historical_items?page=2>; rel="last", <http://localhost:3000/api/v1/locations/3/historical_items?page=2>; rel="next"
Per-Page: 14
Total: 15
Content-Type: application/json; charset=utf-8
ETag: W/"d4882f3a872691d58dce3658c3250d40"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: d5c4f589-7ef4-4cb1-a050-44e34f851625
X-Runtime: 0.051484
Vary: Origin
Transfer-Encoding: chunked

Returns JSON structured like this:

{
  "historical_items": [
    {
      "id": 4,
      "location_id": 3,
      "item": {
        "id": 2,
        "abv": "27.0",
        "ibu": "0.0",
        "cask": false,
        "name": "Samuel Adams Utopias",
        "nitro": false,
        "style": "Strong Ale - American",
        "rating": "4.47778",
        "brewery": "Boston Beer Company",
        "position": 0,
        "containers": [
          {
            "table": {
              "id": 1,
              "price": "15.99",
              "position": 0,
              "item_id": 2,
              "_track_by": 1,
              "created_at": "2016-11-08T16:31:11Z",
              "updated_at": "2016-11-08T16:31:26Z",
              "container_size": {
                "table": {
                  "id": 12,
                  "name": "8oz Draft",
                  "position": 10,
                  "created_at": "2016-03-01T15:36:26Z",
                  "updated_at": "2016-08-24T20:52:06Z"
                },
                "modifiable": true
              },
              "container_size_id": 12
            },
            "modifiable": true
          },
          {
            "table": {
              "id": 2,
              "price": "18.99",
              "position": 1,
              "item_id": 2,
              "_track_by": 2,
              "created_at": "2016-11-08T16:31:34Z",
              "updated_at": "2016-11-08T16:31:38Z",
              "container_size": {
                "table": {
                  "id": 16,
                  "name": "16oz Draft",
                  "position": 18,
                  "created_at": "2016-03-01T15:36:26Z",
                  "updated_at": "2016-08-24T20:52:06Z"
                },
                "modifiable": true
              },
              "container_size_id": 16
            },
            "modifiable": true
          }
        ],
        "created_at": "2016-11-08T15:01:54Z",
        "section_id": 1,
        "tap_number": null,
        "untappd_id": 19004,
        "updated_at": "2016-11-08T16:31:38Z",
        "custom_name": null,
        "description": "Truly the epitome of brewing's two thousand year evolution, Samuel Adams Utopias® offers a flavor not just unlike any other beer but unlike any other beverage in the world. Each release is a blend of batches, some having been aged up to 16 years in the barrel room of our Boston Brewery, in a variety of woods. We aged a portion of the beer in hand-selected, single-use bourbon casks from the award-winning Buffalo Trace Distillery. Some of the latest batches also spent time in Portuguese muscatel finishing casks, as well as sherry, brandy and Cognac casks. This flavorful, slightly fruity brew has a sweet, malty flavor that is reminiscent of a deep, rich vintage port, fine cognac or aged sherry.",
        "label_image": "https://untappd.akamaized.net/site/beer_logos/beer-bostonUtopias.jpg",
        "custom_style": null,
        "in_production": true,
        "original_name": "Samuel Adams Utopias",
        "custom_brewery": null,
        "original_style": "Strong Ale - American",
        "brewery_location": "Boston, MA",
        "original_brewery": "Boston Beer Company",
        "untappd_beer_slug": "boston-beer-company-samuel-adams-utopias",
        "custom_description": null,
        "untappd_brewery_id": 157,
        "original_description": "Truly the epitome of brewing's two thousand year evolution, Samuel Adams Utopias® offers a flavor not just unlike any other beer but unlike any other beverage in the world. Each release is a blend of batches, some having been aged up to 16 years in the barrel room of our Boston Brewery, in a variety of woods. We aged a portion of the beer in hand-selected, single-use bourbon casks from the award-winning Buffalo Trace Distillery. Some of the latest batches also spent time in Portuguese muscatel finishing casks, as well as sherry, brandy and Cognac casks. This flavorful, slightly fruity brew has a sweet, malty flavor that is reminiscent of a deep, rich vintage port, fine cognac or aged sherry."
      },
      "added_at": "2016-11-08T15:01:54Z",
      "changed_at": "2016-11-08T16:31:41Z",
      "change_type": "change_type_removed",
      "created_at": "2016-11-08T16:31:41Z",
      "updated_at": "2016-11-08T16:31:41Z"
    },
    {
      "id": 3,
      "location_id": 3,
      "item": {
        "id": 3,
        "abv": "4.3",
        "ibu": "45.0",
        "cask": false,
        "name": "Guinness Draught",
        "nitro": false,
        "style": "Stout - Irish Dry",
        "rating": "3.81587",
        "brewery": "Guinness",
        "position": 0,
        "containers": [],
        "created_at": "2016-11-08T15:02:12Z",
        "section_id": 1,
        "tap_number": null,
        "untappd_id": 4473,
        "updated_at": "2016-11-08T15:02:12Z",
        "custom_name": null,
        "description": "Swirling clouds tumble as the storm begins to calm. Settle. Breathe in the moment, then break through the smooth, light head to the bittersweet reward.\n\nUnmistakeably GUINNESS, from the first velvet sip to the last, lingering drop. And every deep-dark satisfying mouthful in between.\n\nPure beauty. Pure GUINNESS.\n\nGuinness Draught is sold in kegs, widget cans, and bottles. The ABV varies from 4.1 to 4.3%.\n\nGuinness Extra Cold is the exact same beer only served through a super cooler at 3.5 °C",
        "label_image": "https://untappd.akamaized.net/site/beer_logos/beer-_4473_8122008947804818c90640a06d83.jpeg",
        "custom_style": null,
        "in_production": true,
        "original_name": "Guinness Draught",
        "custom_brewery": null,
        "original_style": "Stout - Irish Dry",
        "brewery_location": "Dublin 8",
        "original_brewery": "Guinness",
        "untappd_beer_slug": "guinness-guinness-draught",
        "custom_description": null,
        "untappd_brewery_id": 49,
        "original_description": "Swirling clouds tumble as the storm begins to calm. Settle. Breathe in the moment, then break through the smooth, light head to the bittersweet reward.\n\nUnmistakeably GUINNESS, from the first velvet sip to the last, lingering drop. And every deep-dark satisfying mouthful in between.\n\nPure beauty. Pure GUINNESS.\n\nGuinness Draught is sold in kegs, widget cans, and bottles. The ABV varies from 4.1 to 4.3%.\n\nGuinness Extra Cold is the exact same beer only served through a super cooler at 3.5 °C"
      },
      "added_at": "2016-11-08T15:02:12Z",
      "changed_at": "2016-11-08T16:31:07Z",
      "change_type": "change_type_removed",
      "created_at": "2016-11-08T16:31:07Z",
      "updated_at": "2016-11-08T16:31:07Z"
    },
    {
      "id": 2,
      "location_id": 3,
      "item": {
        "id": 4,
        "abv": "8.0",
        "ibu": "100.0",
        "cask": true,
        "name": "Pliny the Elder",
        "nitro": false,
        "style": "IPA - Imperial / Double",
        "rating": "4.5657",
        "brewery": "Russian River Brewing Co.",
        "position": 0,
        "containers": [],
        "created_at": "2016-11-08T15:08:49Z",
        "section_id": 1,
        "tap_number": "1",
        "untappd_id": 4499,
        "updated_at": "2016-11-08T16:18:51Z",
        "custom_name": null,
        "description": "All the rest...",
        "label_image": "https://untappd.akamaized.net/site/beer_logos/beer-4499_dc04a_sm.jpeg",
        "custom_style": null,
        "in_production": true,
        "original_name": "Pliny the Elder",
        "custom_brewery": "Russian River Brewing Co.",
        "original_style": "IPA - Imperial / Double",
        "brewery_location": "Santa Rosa, CA",
        "original_brewery": "Russian River Brewing Company",
        "untappd_beer_slug": "russian-river-brewing-company-pliny-the-elder",
        "custom_description": "All the rest...",
        "untappd_brewery_id": 5143,
        "original_description": "A true leader in the hop-wars of the west coast, Pliny the Elder hits you over the head with hoppy bitterness and manages to smooth the rough edges out enough to become an enjoyable brew."
      },
      "added_at": "2016-11-08T15:08:49Z",
      "changed_at": "2016-11-08T16:22:53Z",
      "change_type": "change_type_removed",
      "created_at": "2016-11-08T16:22:53Z",
      "updated_at": "2016-11-08T16:22:53Z"
    },
    {
      "id": 1,
      "location_id": 3,
      "item": {
        "id": 1,
        "abv": "4.6",
        "ibu": "0.0",
        "cask": false,
        "name": "Pabst Blue Ribbon",
        "nitro": false,
        "style": "Lager - North American Adjunct",
        "rating": "2.7616",
        "brewery": "Pabst Brewing Company",
        "position": 0,
        "containers": [],
        "created_at": "2016-11-07T19:09:47Z",
        "section_id": 1,
        "tap_number": null,
        "untappd_id": 3883,
        "updated_at": "2016-11-07T19:18:59Z",
        "custom_name": null,
        "description": "This is the original Pabst Blue Ribbon Beer. Nature's choicest products provide its prized flavor. Only the finest of hops and grains are used. Selected as America's Best in 1893.",
        "label_image": "https://untappd.akamaized.net/site/beer_logos/beer-3883_a0aa4_sm.jpeg",
        "custom_style": null,
        "in_production": true,
        "original_name": "Pabst Blue Ribbon",
        "custom_brewery": null,
        "original_style": "Lager - North American Adjunct",
        "brewery_location": "Woodridge, IL",
        "original_brewery": "Pabst Brewing Company",
        "untappd_beer_slug": "pabst-brewing-company-pabst-blue-ribbon",
        "custom_description": null,
        "untappd_brewery_id": 963,
        "original_description": "This is the original Pabst Blue Ribbon Beer. Nature's choicest products provide its prized flavor. Only the finest of hops and grains are used. Selected as America's Best in 1893."
      },
      "added_at": "2016-11-07T19:09:47Z",
      "changed_at": "2016-11-08T15:01:50Z",
      "change_type": "change_type_removed",
      "created_at": "2016-11-08T15:01:50Z",
      "updated_at": "2016-11-08T15:01:50Z"
    }
  ]
}

HTTP Request

GET https://business.untappd.com/api/v1/locations/:location_id/historical_items?page=:page_number

Query Parameters

Parameter Validations Required Description
location_id Integer true The id of the location to retrieve historical items for.
page Integer false The page number to to view. Only 14 results are returned per page. Pagination information will be the Link header as specified by RFC-5988. See the header output to the right.
q String false A query param to search for historical items by name. ie. ?q=blue would return a list including the beer "Labatt Blue".

Restore a historical item

When an item is removed from a menu it becomes a historical item. You can use the restore route to put a historical item back onto a menu.

The response is a newly created item (based on the historical item) to the specified section.

Request:

curl "http://localhost:3000/api/v1/historical_items/2/restore" \
  -X POST \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
  -H "Content-Type: application/json" \
  -d '{"section_id": 1}'

Returns JSON structured like this:

{
  "item": {
    "id": 5,
    "section_id": 1,
    "position": 0,
    "untappd_id": 4499,
    "label_image": "https://untappd.akamaized.net/site/beer_logos/beer-4499_dc04a_sm.jpeg",
    "brewery_location": "Santa Rosa, CA",
    "abv": "8.0",
    "ibu": "100.0",
    "cask": true,
    "nitro": false,
    "tap_number": "1",
    "rating": "4.5657",
    "in_production": true,
    "untappd_beer_slug": "russian-river-brewing-company-pliny-the-elder",
    "untappd_brewery_id": 5143,
    "name": "Pliny the Elder",
    "original_name": "Pliny the Elder",
    "custom_name": null,
    "description": "All the rest...",
    "custom_description": "All the rest...",
    "original_description": "A true leader in the hop-wars of the west coast, Pliny the Elder hits you over the head with hoppy bitterness and manages to smooth the rough edges out enough to become an enjoyable brew.",
    "style": "IPA - Imperial / Double",
    "custom_style": null,
    "original_style": "IPA - Imperial / Double",
    "brewery": "Russian River Brewing Co.",
    "custom_brewery": "Russian River Brewing Co.",
    "original_brewery": "Russian River Brewing Company",
    "created_at": "2016-11-08T16:34:04Z",
    "updated_at": "2016-11-08T16:34:04Z"
  }
}

HTTP Request

POST https://business.untappd.com/api/v1/historical_items/:id/restore

Query Parameters

Parameter Validations Required Description
id Integer true The id of the historical item to be restored.
section_id Integer true The id of an existing section to which the item will be restored.

Delete a historical item

Permanently deletes a historical item from the Menu History. It cannot be undone.

Request:

curl "http://localhost:3000/api/v1/historical_items/1" \
  -X DELETE \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="

Returns the deleted item as JSON structured like this:

{
  "historical_item": {
    "id": 1,
    "location_id": 3,
    "item": {
      "id": 1,
      "abv": "4.6",
      "ibu": "0.0",
      "cask": false,
      "name": "Pabst Blue Ribbon",
      "nitro": false,
      "style": "Lager - North American Adjunct",
      "rating": "2.7616",
      "brewery": "Pabst Brewing Company",
      "position": 0,
      "containers": [],
      "created_at": "2016-11-07T19:09:47Z",
      "section_id": 1,
      "tap_number": null,
      "untappd_id": 3883,
      "updated_at": "2016-11-07T19:18:59Z",
      "custom_name": null,
      "description": "This is the original Pabst Blue Ribbon Beer. Nature's choicest products provide its prized flavor. Only the finest of hops and grains are used. Selected as America's Best in 1893.",
      "label_image": "https://untappd.akamaized.net/site/beer_logos/beer-3883_a0aa4_sm.jpeg",
      "custom_style": null,
      "in_production": true,
      "original_name": "Pabst Blue Ribbon",
      "custom_brewery": null,
      "original_style": "Lager - North American Adjunct",
      "brewery_location": "Woodridge, IL",
      "original_brewery": "Pabst Brewing Company",
      "untappd_beer_slug": "pabst-brewing-company-pabst-blue-ribbon",
      "custom_description": null,
      "untappd_brewery_id": 963,
      "original_description": "This is the original Pabst Blue Ribbon Beer. Nature's choicest products provide its prized flavor. Only the finest of hops and grains are used. Selected as America's Best in 1893."
    },
    "added_at": "2016-11-07T19:09:47Z",
    "changed_at": "2016-11-08T15:01:50Z",
    "change_type": "change_type_removed",
    "created_at": "2016-11-08T15:01:50Z",
    "updated_at": "2016-11-08T15:01:50Z"
  }
}

HTTP Request

DELETE https://business.untappd.com/api/v1/historical_items/:id

Query Parameters

Parameter Validations Required Description
id Integer true The id of the historical item to be deleted.

Menus

Property Type Description
created_at timestamp Time at which the Menu was created. ISO8601 format.
description string Description of the Menu
draft boolean If the Menu is in a draft status. deprecated
footer string Footer text that is displayed in the footer of the Menu. deprecated
id integer Unique identifier for the Menu
location_id integer Location id that the Menu belongs to
name string Name of the Menu
position integer The position of the Menu in the list of Menus for the Location. Positions start at zero and should be contiguous.
push_notification_frequency string One of real_time, daily, or weekly read only
show_price_on_untappd boolean Whether price information should be shown on the Untappd App.
unpublished boolean Indicates if the Menu is in an unpublished state. Unpublished menus are hidden from the public.
updated_at timestamp Time at which the Menu was last updated. ISO8601 format.
uuid string A unique identifier for the Menu read only

The full Menu object can be returned by passing full=true when retieving a Menu. This will return the entire menu tree including all Sections, Items,and Containers. The following properties will be available in addition to the properties in the regular Menu object

Property Type Description
sections array An array of Sections for the Menu
on_deck_section Sections The OnDeckSection for the Menu

List all menus

Returns a list of menus belonging to your location.

Request:

curl "http://localhost:3000/api/v1/locations/5/menus" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="

Returns JSON structured like this:

{
  "menus": [
    {
      "id": 5,
      "location_id": 5,
      "uuid": "f181f982-42bf-414b-be9a-d13406e5be0b",
      "name": "Beverages",
      "description": "Grab something to drink while you're here.",
      "footer": null,
      "draft": false,
      "unpublished": false,
      "position": 0,
      "show_price_on_untappd": true,
      "push_notification_frequency": "real_time",
      "created_at": "2023-03-21T12:48:57.545101Z",
      "updated_at": "2023-03-21T13:32:55.043263Z"
    }
  ]
}

HTTP Request

GET https://business.untappd.com/api/v1/locations/:location_id/menus

Query Parameters

Parameter Validations Required Description
location_id Integer true The id of the location.
include_legacy Boolean false Enables legacy menu fallback. See Legacy Migration

Create/Update multiple menus

Create/Update (upsert) multiple menus in a single request. A menu with an id will be updated. A menu without an id will be created as a new menu.

The same thing goes for the sections. A section with an id will be updated. A section without an id will be created as a new section.

Important! Any existing sections, items, and/or containers not provided will be deleted. This is essentially a hard reset from the current menu data to the data in the request.

Also, note that menus in our system default to unpublished: true ie. "not published". If you would like your menu to be published out to our publishers (including your website's embedded menus) you must set unpublished: false in the request; as it is in the example to the right.

Note: If your request takes longer than 30 seconds to process you will receive "Request Timeout" as a response. If this is the case, try using the background form parameter.

Request:

curl "http://localhost:3000/api/v1/locations/3/menus" \
  -X PUT \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
  -H "Content-Type: application/json" \
  -d '{"menus":[{"unpublished":false,"name":"Draft Beer List","description":"All the draft beers.","footer":"Heavy vs. Light or Good vs. Evil? You Decide.","sections":[{"name":"Other beers","description":"Our beers that are not dark or light.","items":[{"untappd_id":4499,"cask":true,"nitro":false,"description":"A custom item description","tap_number":4,"containers":[{"container_size_id":6,"price":3.99}]},{"untappd_id":3883,"cask":false,"nitro":true,"description":"A PBR beer","tap_number":5,"containers":[{"container_size_id":6,"price":3.99}]}]}]}]}'

Returns JSON structured like this:

{
  "menus": [
    {
      "id": 3,
      "location_id": 3,
      "uuid": "c2402f2e-90e5-40cd-a455-68e45cf7f70c",
      "name": "Draft Beer List",
      "description": "All the draft beers.",
      "footer": "Heavy vs. Light or Good vs. Evil? You Decide.",
      "draft": false,
      "unpublished": false,
      "position": 0,
      "show_price_on_untappd": true,
      "push_notification_frequency": "real_time",
      "created_at": "2016-11-08T16:59:05Z",
      "updated_at": "2016-11-08T16:59:05Z",
      "sections": [
        {
          "id": 7,
          "menu_id": 3,
          "position": 0,
          "name": "Other beers",
          "description": "Our beers that are not dark or light.",
          "type": "Section",
          "created_at": "2016-11-08T16:59:05Z",
          "updated_at": "2016-11-08T16:59:05Z",
          "items": [
            {
              "id": 10,
              "section_id": 7,
              "position": 0,
              "untappd_id": 4499,
              "label_image": "https://untappd.akamaized.net/site/beer_logos/beer-4499_dc04a_sm.jpeg",
              "brewery_location": "Santa Rosa, CA",
              "abv": "8.0",
              "ibu": "100.0",
              "cask": true,
              "nitro": false,
              "tap_number": "4",
              "rating": "4.5657",
              "in_production": true,
              "untappd_beer_slug": "russian-river-brewing-company-pliny-the-elder",
              "untappd_brewery_id": 5143,
              "name": "Pliny the Elder",
              "original_name": "Pliny the Elder",
              "custom_name": null,
              "description": "A custom item description",
              "custom_description": "A custom item description",
              "original_description": "A true leader in the hop-wars of the west coast, Pliny the Elder hits you over the head with hoppy bitterness and manages to smooth the rough edges out enough to become an enjoyable brew.",
              "style": "IPA - Imperial / Double",
              "custom_style": null,
              "original_style": "IPA - Imperial / Double",
              "brewery": "Russian River Brewing Company",
              "custom_brewery": null,
              "original_brewery": "Russian River Brewing Company",
              "created_at": "2016-11-08T16:59:05Z",
              "updated_at": "2016-11-08T16:59:05Z",
              "containers": [
                {
                  "id": 9,
                  "item_id": 10,
                  "container_size_id": 6,
                  "price": "3.99",
                  "currency": "USD",
                  "position": 0,
                  "created_at": "2016-11-08T16:59:05Z",
                  "updated_at": "2016-11-08T16:59:05Z",
                  "container_size": {
                    "id": 6,
                    "name": "32oz Growler",
                    "position": 96,
                    "created_at": "2016-03-01T15:36:26Z",
                    "updated_at": "2016-08-24T20:55:13Z"
                  },
                  "_track_by": 9
                }
              ],
              "type": "beer",
              "default_image": "https://untappd.akamaized.net/site/assets/images/temp/badge-beer-default.png"
            },
            {
              "id": 11,
              "section_id": 7,
              "position": 1,
              "untappd_id": 3883,
              "label_image": "https://untappd.akamaized.net/site/beer_logos/beer-3883_a0aa4_sm.jpeg",
              "brewery_location": "Woodridge, IL",
              "abv": "4.6",
              "ibu": "0.0",
              "cask": false,
              "nitro": true,
              "tap_number": "5",
              "rating": "2.76162",
              "in_production": true,
              "untappd_beer_slug": "pabst-brewing-company-pabst-blue-ribbon",
              "untappd_brewery_id": 963,
              "name": "Pabst Blue Ribbon",
              "original_name": "Pabst Blue Ribbon",
              "custom_name": null,
              "description": "A PBR beer",
              "custom_description": "A PBR beer",
              "original_description": "This is the original Pabst Blue Ribbon Beer. Nature's choicest products provide its prized flavor. Only the finest of hops and grains are used. Selected as America's Best in 1893.",
              "style": "Lager - North American Adjunct",
              "custom_style": null,
              "original_style": "Lager - North American Adjunct",
              "brewery": "Pabst Brewing Company",
              "custom_brewery": null,
              "original_brewery": "Pabst Brewing Company",
              "created_at": "2016-11-08T16:59:05Z",
              "updated_at": "2016-11-08T16:59:05Z",
              "containers": [
                {
                  "id": 10,
                  "item_id": 11,
                  "container_size_id": 6,
                  "price": "3.99",
                  "currency": "USD",
                  "position": 0,
                  "created_at": "2016-11-08T16:59:05Z",
                  "updated_at": "2016-11-08T16:59:05Z",
                  "container_size": {
                    "id": 6,
                    "name": "32oz Growler",
                    "position": 96,
                    "created_at": "2016-03-01T15:36:26Z",
                    "updated_at": "2016-08-24T20:55:13Z"
                  },
                  "_track_by": 10
                }
              ],
              "type": "beer",
              "default_image": "https://untappd.akamaized.net/site/assets/images/temp/badge-beer-default.png"
            }
          ]
        }
      ],
      "on_deck_section": {
        "id": 8,
        "menu_id": 3,
        "position": 0,
        "name": "On Deck",
        "description": "",
        "type": "OnDeckSection",
        "created_at": "2016-11-08T16:59:05Z",
        "updated_at": "2016-11-08T16:59:05Z",
        "public": false,
        "items": []
      }
    }
  ]
}

An example of using this route to update the previously created data looks like the following:

Request:

curl "http://localhost:3000/api/v1/locations/3/menus" \
  -X PUT \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
  -H "Content-Type: application/json" \
  -d '{"menus":[{"id":3, "unpublished":false,"name":"A different menu name","description":"A menu description","footer":"a footer for the menu","sections":[{"id":7, "name":"A section name","description":"A section description.","items":[{"untappd_id":4499,"cask":true,"nitro":false,"description":"A custom item description","tap_number":4,"containers":[{"container_size_id":5,"price":3.99}]},{"untappd_id":3883,"cask":false,"nitro":true,"description":"A PBR beer","tap_number":5,"containers":[{"container_size_id":5,"price":3.99}]}]}]}]}'

Returns JSON structured like this:

{
  "menus": [
    {
      "id": 3,
      "location_id": 3,
      "uuid": "c2402f2e-90e5-40cd-a455-68e45cf7f70c",
      "name": "A different menu name",
      "description": "A menu description",
      "footer": "a footer for the menu",
      "draft": false,
      "unpublished": false,
      "position": 0,
      "show_price_on_untappd": true,
      "push_notification_frequency": "real_time",
      "created_at": "2016-11-08T16:59:05Z",
      "updated_at": "2016-11-08T17:01:20Z",
      "sections": [
        {
          "id": 7,
          "menu_id": 3,
          "position": 0,
          "name": "A section name",
          "description": "A section description.",
          "type": "Section",
          "created_at": "2016-11-08T16:59:05Z",
          "updated_at": "2016-11-08T17:01:20Z",
          "items": [
            {
              "id": 10,
              "section_id": 7,
              "position": 0,
              "untappd_id": 4499,
              "label_image": "https://untappd.akamaized.net/site/beer_logos/beer-4499_dc04a_sm.jpeg",
              "brewery_location": "Santa Rosa, CA",
              "abv": "8.0",
              "ibu": "100.0",
              "cask": true,
              "nitro": false,
              "tap_number": "4",
              "rating": "4.5657",
              "in_production": true,
              "untappd_beer_slug": "russian-river-brewing-company-pliny-the-elder",
              "untappd_brewery_id": 5143,
              "name": "Pliny the Elder",
              "original_name": "Pliny the Elder",
              "custom_name": null,
              "description": "A custom item description",
              "custom_description": "A custom item description",
              "original_description": "A true leader in the hop-wars of the west coast, Pliny the Elder hits you over the head with hoppy bitterness and manages to smooth the rough edges out enough to become an enjoyable brew.",
              "style": "IPA - Imperial / Double",
              "custom_style": null,
              "original_style": "IPA - Imperial / Double",
              "brewery": "Russian River Brewing Company",
              "custom_brewery": null,
              "original_brewery": "Russian River Brewing Company",
              "created_at": "2016-11-08T16:59:05Z",
              "updated_at": "2016-11-08T17:01:20Z",
              "containers": [
                {
                  "id": 11,
                  "item_id": 10,
                  "container_size_id": 5,
                  "price": "3.99",
                  "currency": "USD",
                  "position": 0,
                  "created_at": "2016-11-08T17:01:20Z",
                  "updated_at": "2016-11-08T17:01:20Z",
                  "container_size": {
                    "id": 5,
                    "name": "Crowler",
                    "position": 101,
                    "created_at": "2016-03-01T15:36:26Z",
                    "updated_at": "2016-08-24T20:55:13Z"
                  },
                  "_track_by": 11
                }
              ],
              "type": "beer",
              "default_image": "https://untappd.akamaized.net/site/assets/images/temp/badge-beer-default.png"
            },
            {
              "id": 11,
              "section_id": 7,
              "position": 1,
              "untappd_id": 3883,
              "label_image": "https://untappd.akamaized.net/site/beer_logos/beer-3883_a0aa4_sm.jpeg",
              "brewery_location": "Woodridge, IL",
              "abv": "4.6",
              "ibu": "0.0",
              "cask": false,
              "nitro": true,
              "tap_number": "5",
              "rating": "2.76162",
              "in_production": true,
              "untappd_beer_slug": "pabst-brewing-company-pabst-blue-ribbon",
              "untappd_brewery_id": 963,
              "name": "Pabst Blue Ribbon",
              "original_name": "Pabst Blue Ribbon",
              "custom_name": null,
              "description": "A PBR beer",
              "custom_description": "A PBR beer",
              "original_description": "This is the original Pabst Blue Ribbon Beer. Nature's choicest products provide its prized flavor. Only the finest of hops and grains are used. Selected as America's Best in 1893.",
              "style": "Lager - North American Adjunct",
              "custom_style": null,
              "original_style": "Lager - North American Adjunct",
              "brewery": "Pabst Brewing Company",
              "custom_brewery": null,
              "original_brewery": "Pabst Brewing Company",
              "created_at": "2016-11-08T16:59:05Z",
              "updated_at": "2016-11-08T17:01:20Z",
              "containers": [
                {
                  "id": 12,
                  "item_id": 11,
                  "container_size_id": 5,
                  "price": "3.99",
                  "currency": "USD",
                  "position": 0,
                  "created_at": "2016-11-08T17:01:20Z",
                  "updated_at": "2016-11-08T17:01:20Z",
                  "container_size": {
                    "id": 5,
                    "name": "Crowler",
                    "position": 101,
                    "created_at": "2016-03-01T15:36:26Z",
                    "updated_at": "2016-08-24T20:55:13Z"
                  },
                  "_track_by": 12
                }
              ],
              "type": "beer",
              "default_image": "https://untappd.akamaized.net/site/assets/images/temp/badge-beer-default.png"
            }
          ]
        }
      ],
      "on_deck_section": {
        "id": 8,
        "menu_id": 3,
        "position": 0,
        "name": "On Deck",
        "description": "",
        "type": "OnDeckSection",
        "created_at": "2016-11-08T16:59:05Z",
        "updated_at": "2016-11-08T16:59:05Z",
        "public": false,
        "items": []
      }
    }
  ]
}

HTTP Request

PUT https://business.untappd.com/api/v1/locations/:location_id/menus

Query Parameters

Parameter Validations Required Description
location_id Integer true The id of the Location.
menus Array true An Array of Objects. Any menus without an id will be created. Any menus with an id will be updated. Any existing menus not provided will remain unchanged.
sections Array true An Array of Objects. Any sections without an id will be created. Any sections with an id will be updated. Any existing sections not provided for the given menu will be removed.
items Array true An Array of Objects. Items are updated by untappd_id. Any items with an untappd_id will be updated. Any existing items not provided for the given section will be removed.
containers Array true An Array of Objects. Existing containers are removed and any provided containers will be created.
background String false Only use this if your payload is extremely large (ie. 1000 menu items) and you are receiving "Request Timeout". If background is set, the bulk upsert will be performed in a background job with the value of background used as the JSON payload. ie: { "background": "{\"menus\": [{\"id\": 1}]}" }. Note: the value of background must be a stringified version of the JSON payload. We do this for performance reasons.
callback_url String false A valid url starting with either https:// or http:// that will be POSTed to with the response when using background. ie. http://example.com/background_job_complete. The Content-Type of the callback request will be: application/json. Note: The response from your server at the callback_url must be an HTTP 200 status code. Any other status code or failure will cause the callback to be retried for about a month using exponential backoff.

Create a menu

Creates a new menu.

Request:

curl "http://localhost:3000/api/v1/locations/5/menus" \
  -X POST \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
  -H "Content-Type: application/json" \
  -d '{ "menu": { "name": "Draft Beer List" } }'

Returns JSON structured like this:

{
  "menu": {
    "id": 5,
    "location_id": 5,
    "uuid": "f181f982-42bf-414b-be9a-d13406e5be0b",
    "name": "Draft Beer List",
    "description": null,
    "footer": null,
    "draft": true,
    "unpublished": true,
    "position": 0,
    "show_price_on_untappd": true,
    "push_notification_frequency": "real_time",
    "created_at": "2023-03-21T12:48:57.545101Z",
    "updated_at": "2023-03-21T13:32:55.043263Z"
  }
}

HTTP Request

POST https://business.untappd.com/api/v1/locations/:location_id/menus

Query Parameters

Parameter Validations Required Description
location_id Integer true The id of the location.
name String true The menu name.

Retrieve a menu

Retrieve the details of an existing menu. You need only supply the unique menu identifier that was returned upon menu creation.

Request:

curl "http://localhost:3000/api/v1/menus/5" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="

Returns JSON structured like this:

{
  "menu": {
    "id": 5,
    "location_id": 5,
    "uuid": "f181f982-42bf-414b-be9a-d13406e5be0b",
    "name": "Beverages",
    "description": "Grab something to drink while you're here.",
    "footer": null,
    "draft": false,
    "unpublished": false,
    "position": 0,
    "show_price_on_untappd": true,
    "push_notification_frequency": "real_time",
    "created_at": "2023-03-21T12:48:57.545101Z",
    "updated_at": "2023-03-21T13:32:55.043263Z"
  }
}

Or...

To get the full menu use the full param with the request:

curl "http://localhost:3000/api/v1/menus/5?full=true" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="

Returns JSON structured like this:

{
  "menu": {
    "id": 5,
    "location_id": 5,
    "uuid": "f181f982-42bf-414b-be9a-d13406e5be0b",
    "name": "Beverages",
    "description": "Grab something to drink while you're here.",
    "footer": null,
    "draft": false,
    "unpublished": false,
    "position": 0,
    "show_price_on_untappd": true,
    "push_notification_frequency": "real_time",
    "created_at": "2023-03-21T12:48:57.545101Z",
    "updated_at": "2023-03-21T18:02:42.836010Z",
    "sections": [
      {
        "id": 10,
        "menu_id": 5,
        "position": 0,
        "name": "Alcoholic Drinks",
        "description": "Escape from a hard day with something alcoholic!",
        "type": "Section",
        "public": true,
        "created_at": "2023-03-21T12:48:57.552844Z",
        "updated_at": "2023-03-21T17:52:55.087976Z",
        "items": [
          {
            "id": 65,
            "section_id": 10,
            "position": 0,
            "untappd_id": null,
            "label_image": "https://www.wine-searcher.com/images/labels/19/94/10531994.jpg?width=50&height=50&fit=bounds&canvas=50,50",
            "label_image_hd": "https://s3.amazonaws.com/woof.nextglass.co/default/wine.svg",
            "label_image_thumb": "https://www.wine-searcher.com/images/labels/19/94/10531994.jpg?width=50&height=50&fit=bounds&canvas=50,50",
            "original_label_image": "https://beer.untappd.com/labels/",
            "original_label_image_hd": "https://beer.untappd.com/labels/?size=hd",
            "custom_label_image": null,
            "custom_label_image_thumb": null,
            "custom_label_image_filename": null,
            "brewery_location": null,
            "cask": false,
            "nitro": false,
            "local": false,
            "tap_number": null,
            "rating": null,
            "rating_count": null,
            "in_production": null,
            "untappd_beer_slug": null,
            "untappd_brewery_id": null,
            "name": "Bodegas Campo Viejo Tempranillo",
            "original_name": null,
            "custom_name": null,
            "description": "A cherry red colour suggests a vibrant Tempranillo wine. On the nose, the rich aromas have a pronounced intensity with an initial scent of ripe fruits followed by gentle sweet notes of vanilla and spices. On the palate, it is perfumed, soft and fresh with a long finish.",
            "custom_description": "A cherry red colour suggests a vibrant Tempranillo wine. On the nose, the rich aromas have a pronounced intensity with an initial scent of ripe fruits followed by gentle sweet notes of vanilla and spices. On the palate, it is perfumed, soft and fresh with a long finish.",
            "original_description": null,
            "style": null,
            "custom_style": null,
            "original_style": null,
            "brewery": null,
            "brewery_country": null,
            "custom_brewery": null,
            "original_brewery": null,
            "calories": null,
            "custom_calories": null,
            "original_calories": null,
            "abv": "13.5",
            "custom_abv": null,
            "original_abv": null,
            "ibu": null,
            "custom_ibu": null,
            "original_ibu": null,
            "created_at": "2023-03-21T13:02:01.593381Z",
            "updated_at": "2023-03-21T14:14:17.533411Z",
            "type": "wine",
            "default_image": "https://s3.amazonaws.com/woof.nextglass.co/default/wine.svg",
            "producer": "Bodegas Campo Viejo",
            "vintage": null,
            "characteristics": "Red - Savory and Classic",
            "category": "Tempranillo",
            "location": "Rioja, Spain",
            "containers": [
              {
                "id": 119,
                "item_id": 65,
                "container_size_id": "",
                "price": "8.00",
                "position": 0,
                "container_size": null,
                "created_at": "2023-03-21T13:05:28.537922Z",
                "updated_at": "2023-03-21T13:05:28.537922Z",
                "_track_by": 119,
                "calories": null,
                "name": "Glass",
                "currency": "USD"
              }
            ]
          },
          {
            "id": 64,
            "section_id": 10,
            "position": 1,
            "untappd_id": 4473,
            "label_image": "https://beer.untappd.com/labels/4473",
            "label_image_hd": "https://beer.untappd.com/labels/4473?size=hd",
            "label_image_thumb": "https://beer.untappd.com/labels/4473",
            "original_label_image": "https://beer.untappd.com/labels/4473",
            "original_label_image_hd": "https://beer.untappd.com/labels/4473?size=hd",
            "custom_label_image": null,
            "custom_label_image_thumb": null,
            "custom_label_image_filename": null,
            "brewery_location": "Dublin, County Dublin",
            "cask": false,
            "nitro": true,
            "local": false,
            "tap_number": "1",
            "rating": "3.76886",
            "rating_count": 801407,
            "in_production": true,
            "untappd_beer_slug": "guinness-guinness-draught",
            "untappd_brewery_id": 49,
            "name": "Guinness Draught",
            "original_name": "Guinness Draught",
            "custom_name": null,
            "description": "Swirling clouds tumble as the storm begins to calm. Settle. Breathe in the moment, then break through the smooth, light head to the bittersweet reward.\r\n\r\nUnmistakeably GUINNESS, from the first velvet sip to the last, lingering drop. And every deep-dark satisfying mouthful in between.\r\n\r\nPure beauty. Pure GUINNESS.\r\n\r\nGuinness Draught is sold in kegs, widget cans, and bottles. The ABV varies from 4.1 to 4.3%.\r\n\r\nGuinness Extra Cold is the exact same beer only served through a super cooler at 3.5 °C",
            "custom_description": null,
            "original_description": "Swirling clouds tumble as the storm begins to calm. Settle. Breathe in the moment, then break through the smooth, light head to the bittersweet reward.\r\n\r\nUnmistakeably GUINNESS, from the first velvet sip to the last, lingering drop. And every deep-dark satisfying mouthful in between.\r\n\r\nPure beauty. Pure GUINNESS.\r\n\r\nGuinness Draught is sold in kegs, widget cans, and bottles. The ABV varies from 4.1 to 4.3%.\r\n\r\nGuinness Extra Cold is the exact same beer only served through a super cooler at 3.5 °C",
            "style": "Stout - Irish Dry",
            "custom_style": null,
            "original_style": "Stout - Irish Dry",
            "brewery": "Guinness",
            "brewery_country": "Ireland",
            "custom_brewery": null,
            "original_brewery": "Guinness",
            "calories": "125",
            "custom_calories": null,
            "original_calories": "125",
            "abv": "4.2",
            "custom_abv": null,
            "original_abv": "4.2",
            "ibu": "45.0",
            "custom_ibu": null,
            "original_ibu": "45.0",
            "created_at": "2023-03-21T13:01:26.220225Z",
            "updated_at": "2023-03-21T14:14:17.533411Z",
            "type": "beer",
            "default_image": "https://assets.untappd.com/site/assets/images/temp/badge-beer-default.png",
            "producer": null,
            "vintage": null,
            "characteristics": null,
            "category": null,
            "location": null,
            "containers": [
              {
                "id": 118,
                "item_id": 64,
                "container_size_id": 18,
                "price": "7.00",
                "position": 0,
                "container_size": {
                  "id": 18,
                  "name": "20oz Draft",
                  "ounces": "20.0",
                  "position": 21,
                  "created_at": "2016-03-01T15:36:26.000000Z",
                  "updated_at": "2016-08-24T20:52:06.390485Z"
                },
                "created_at": "2023-03-21T13:04:40.317030Z",
                "updated_at": "2023-03-21T13:04:40.317030Z",
                "_track_by": 118,
                "calories": "180.0",
                "name": "20oz Draft",
                "currency": "USD"
              }
            ]
          },
          {
            "id": 67,
            "section_id": 10,
            "position": 2,
            "untappd_id": 9681,
            "label_image": "https://beer.untappd.com/labels/9681",
            "label_image_hd": "https://beer.untappd.com/labels/9681?size=hd",
            "label_image_thumb": "https://beer.untappd.com/labels/9681",
            "original_label_image": "https://beer.untappd.com/labels/9681",
            "original_label_image_hd": "https://beer.untappd.com/labels/9681?size=hd",
            "custom_label_image": null,
            "custom_label_image_thumb": null,
            "custom_label_image_filename": null,
            "brewery_location": "Grand Rapids, MI",
            "cask": false,
            "nitro": false,
            "local": false,
            "tap_number": null,
            "rating": "4.38633",
            "rating_count": 224308,
            "in_production": true,
            "untappd_beer_slug": "founders-brewing-co-kentucky-breakfast-stout-kbs",
            "untappd_brewery_id": 549,
            "name": "Kentucky Breakfast Stout (KBS)",
            "original_name": "Kentucky Breakfast Stout (KBS)",
            "custom_name": null,
            "description": "This beer taught us that patience truly is a virtue. KBS is a big imperial stout brewed with a massive amount of coffee and chocolate and then bourbon barrel-aged to perfection. Incredibly silky and full-bodied with notes of vanilla, cocoa, roasted coffee and charred oak.",
            "custom_description": null,
            "original_description": "This beer taught us that patience truly is a virtue. KBS is a big imperial stout brewed with a massive amount of coffee and chocolate and then bourbon barrel-aged to perfection. Incredibly silky and full-bodied with notes of vanilla, cocoa, roasted coffee and charred oak.",
            "style": "Stout - Imperial / Double Coffee",
            "custom_style": null,
            "original_style": "Stout - Imperial / Double Coffee",
            "brewery": "Founders Brewing Co.",
            "brewery_country": "United States",
            "custom_brewery": null,
            "original_brewery": "Founders Brewing Co.",
            "calories": "340",
            "custom_calories": null,
            "original_calories": "340",
            "abv": "12.0",
            "custom_abv": null,
            "original_abv": "12.0",
            "ibu": "70.0",
            "custom_ibu": null,
            "original_ibu": "70.0",
            "created_at": "2023-03-21T14:14:17.526349Z",
            "updated_at": "2023-03-21T14:14:17.526936Z",
            "type": "beer",
            "default_image": "https://assets.untappd.com/site/assets/images/temp/badge-beer-default.png",
            "producer": null,
            "vintage": null,
            "characteristics": null,
            "category": null,
            "location": null,
            "containers": []
          },
          {
            "id": 66,
            "section_id": 10,
            "position": 3,
            "untappd_id": null,
            "label_image": "https://www.wine-searcher.com/images/labels/36/77/10143677.jpg?width=50&height=50&fit=bounds&canvas=50,50",
            "label_image_hd": "https://s3.amazonaws.com/woof.nextglass.co/default/spirit.svg",
            "label_image_thumb": "https://www.wine-searcher.com/images/labels/36/77/10143677.jpg?width=50&height=50&fit=bounds&canvas=50,50",
            "original_label_image": "https://beer.untappd.com/labels/",
            "original_label_image_hd": "https://beer.untappd.com/labels/?size=hd",
            "custom_label_image": null,
            "custom_label_image_thumb": null,
            "custom_label_image_filename": null,
            "brewery_location": null,
            "cask": false,
            "nitro": false,
            "local": false,
            "tap_number": null,
            "rating": null,
            "rating_count": null,
            "in_production": null,
            "untappd_beer_slug": null,
            "untappd_brewery_id": null,
            "name": "The Kraken Black Spiced Rum",
            "original_name": null,
            "custom_name": null,
            "description": "One of the fastest growing rum brands, The Kraken® is the world’s first black spiced rum, housed in an iconic bottle. Taste the flavors of cinnamon, vanilla, and nutmeg and experience its magic. The Kraken® Original is 94 proof. It has a distinct aroma of caramel, toffee and spice with flavors of cinnamon and vanilla and a lingering spicy finish. (47% ABV - 94 proof) The Kraken®, blended with secret spices, is perfect to spice up classics and new favorite cocktails or as a shot.",
            "custom_description": "One of the fastest growing rum brands, The Kraken® is the world’s first black spiced rum, housed in an iconic bottle. Taste the flavors of cinnamon, vanilla, and nutmeg and experience its magic. The Kraken® Original is 94 proof. It has a distinct aroma of caramel, toffee and spice with flavors of cinnamon and vanilla and a lingering spicy finish. (47% ABV - 94 proof) The Kraken®, blended with secret spices, is perfect to spice up classics and new favorite cocktails or as a shot.",
            "original_description": null,
            "style": null,
            "custom_style": null,
            "original_style": null,
            "brewery": null,
            "brewery_country": null,
            "custom_brewery": null,
            "original_brewery": null,
            "calories": null,
            "custom_calories": null,
            "original_calories": null,
            "abv": "35.0",
            "custom_abv": null,
            "original_abv": null,
            "ibu": null,
            "custom_ibu": null,
            "original_ibu": null,
            "created_at": "2023-03-21T13:02:51.158417Z",
            "updated_at": "2023-03-21T14:14:17.533411Z",
            "type": "spirit",
            "default_image": "https://s3.amazonaws.com/woof.nextglass.co/default/spirit.svg",
            "producer": "The Kraken",
            "vintage": null,
            "characteristics": null,
            "category": "Rum - Liqueur - Flavored",
            "location": "Caribbean, Rest of World",
            "containers": [
              {
                "id": 120,
                "item_id": 66,
                "container_size_id": "",
                "price": "3.50",
                "position": 0,
                "container_size": null,
                "created_at": "2023-03-21T13:06:38.039237Z",
                "updated_at": "2023-03-21T13:06:38.039237Z",
                "_track_by": 120,
                "calories": null,
                "name": "Shot",
                "currency": "USD"
              }
            ]
          }
        ]
      }
    ],
    "on_deck_section": {
      "id": 9,
      "menu_id": 5,
      "position": 0,
      "name": "On Deck",
      "description": "",
      "type": "OnDeckSection",
      "public": true,
      "created_at": "2023-03-21T12:48:57.548359Z",
      "updated_at": "2023-03-21T14:14:17.542020Z",
      "items": []
    }
  }
}

HTTP Request

GET https://business.untappd.com/api/v1/menus/:id

Query Parameters

Parameter Validations Required Description
id Integer true The id of the menu.
full true or not set false Returns the entire menu tree with sections, items, containers and container sizes. Also, enables analytics tracking for the request.
source_name Integer false When full is present in the request params, an optional source_name may be provided to change the recorded source of the request for the analytics dashboard.
Defaults to: API. See: Analytics/Track.
include_legacy Boolean false Enables legacy menu fallback. See Legacy Migration

Update a menu

Updates the specified menu by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Request:

curl "http://localhost:3000/api/v1/menus/5" \
  -X PATCH \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
  -H "Content-Type: application/json" \
  -d '{ "menu": { "name": "Super Awesome Draft Beer List" } }'

Returns JSON structured like this:

{
  "menu": {
    "id": 5,
    "location_id": 5,
    "uuid": "f181f982-42bf-414b-be9a-d13406e5be0b",
    "name": "Super Awesome Draft Beer List",
    "description": "Grab something to drink while you're here.",
    "footer": null,
    "draft": false,
    "unpublished": false,
    "position": 0,
    "show_price_on_untappd": true,
    "push_notification_frequency": "real_time",
    "created_at": "2023-03-21T12:48:57.545101Z",
    "updated_at": "2023-03-21T13:32:55.043263Z"
  }
}

HTTP Request

PUT https://business.untappd.com/api/v1/menus/:id PATCH https://business.untappd.com/api/v1/menus/:id

Query Parameters

Parameter Validations Required Description
id Integer true The id of the menu.
name String false The menu name.
description String false The menu description.
footer String false The menu footer.

Delete a menu

Permanently deletes a menu. It cannot be undone. If the menu is already published then it will first be unpublished and then deleted.

Request:

curl "http://localhost:3000/api/v1/menus/5" \
  -X DELETE \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="

Returns the deleted menu as JSON structured like this:

{
  "menu": {
    "id": 5,
    "location_id": 5,
    "uuid": "f181f982-42bf-414b-be9a-d13406e5be0b",
    "name": "Beverages",
    "description": "Grab something to drink while you're here.",
    "footer": null,
    "draft": false,
    "unpublished": false,
    "position": 0,
    "show_price_on_untappd": true,
    "push_notification_frequency": "real_time",
    "created_at": "2023-03-21T12:48:57.545101Z",
    "updated_at": "2023-03-21T13:32:55.043263Z"
  }
}

HTTP Request

DELETE https://business.untappd.com/api/v1/menus/:id

Query Parameters

Parameter Validations Required Description
id Integer true The menu to be deleted.

Delete Multiple Menus

Permanently deletes menus. It cannot be undone. If the menus are already published then they will first be unpublished and then deleted.

Request:

curl "http://localhost:3000/api/v1/locations/5/menus" \
  -X DELETE \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [1, 2, 3] }'

Returns JSON structured like this:

{
  "success": true
}

HTTP Request

DELETE https://business.untappd.com/api/v1/locations/:location_id/menus

Query Parameters

Parameter Validations Required Description
location_id Integer true The location to delete menus for.
ids Array true An Array of ids. All the menu ids for the location to be deleted.

Update menu positions

Set the positions of menus in a location. Menu positions are used to order the published menus on a page.

Important!: When updating menu positions, all menus for the location must be passed and the positions must start at zero. Use List all menus first to get all the menus for the location.

Request:

curl "http://localhost:3000/api/v1/locations/3/menus/positions" \
  -X PATCH \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
  -H "Content-Type: application/json" \
  -d '{ "menus": [{ "id": 1, "position": 1 }, { "id": 3, "position": 0 }] }'

Returns JSON structured like this:

{
  "menus": [
    {
      "id": 3,
      "position": 0
    },
    {
      "id": 1,
      "position": 1
    }
  ]
}

HTTP Request

PATCH https://business.untappd.com/api/v1/locations/:location_id/menus/positions

Query Parameters

Parameter Validations Required Description
location_id Integer true The location to update menu positions for.
menus Array true An Array of Menu Position Objects. All the menus for a location must be passed as a batch to be update atomically. Unexpected behavior may result otherwise.
Property Type Required Description
id integer true Menu id to update the position for.
position integer true The position to set the menu at. Menu positions must start at zero.

Publish all menus

Publish all the unpublished menus of a location. Any changes to a published menu will automatically take effect.

Request:

curl "http://localhost:3000/api/v1/locations/5/menus/publish_all" \
  -X POST \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="

Returns JSON structured like this (notice unpublished is now set to: false):

{
  "menus": [
    {
      "id": 5,
      "location_id": 5,
      "uuid": "f181f982-42bf-414b-be9a-d13406e5be0b",
      "name": "Beverages",
      "description": "Grab something to drink while you're here.",
      "footer": null,
      "draft": false,
      "unpublished": false,
      "position": 0,
      "show_price_on_untappd": true,
      "push_notification_frequency": "real_time",
      "created_at": "2023-03-21T12:48:57.545101Z",
      "updated_at": "2023-03-21T13:32:55.043263Z"
    },
    {
      "id": 6,
      "location_id": 5,
      "uuid": "f181f982-42bf-414b-be9a-d13406e5be0b",
      "name": "Super Awesome Draft Beer List",
      "description": "All the draft beers.",
      "footer": null,
      "draft": false,
      "unpublished": false,
      "position": 1,
      "show_price_on_untappd": true,
      "push_notification_frequency": "real_time",
      "created_at": "2023-03-21T12:48:57.545101Z",
      "updated_at": "2023-03-21T13:32:55.043263Z"
    }
  ]
}

HTTP Request

POST https://business.untappd.com/api/v1/locations/:location_id/menus/publish_all

Query Parameters

Parameter Validations Required Description
location_id Integer true The location.

Publish a menu

Publish a menu. There is no need to republish a menu that has already been published. Any changes to a published menu will automatically take effect.

Request:

curl "http://localhost:3000/api/v1/menus/5/publish" \
  -X POST \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="

Returns JSON structured like this (notice unpublished is now set to: false):

{
  "menu": {
    "id": 5,
    "location_id": 5,
    "uuid": "f181f982-42bf-414b-be9a-d13406e5be0b",
    "name": "Beverages",
    "description": "Grab something to drink while you're here.",
    "footer": null,
    "draft": false,
    "unpublished": false,
    "position": 0,
    "show_price_on_untappd": true,
    "push_notification_frequency": "real_time",
    "created_at": "2023-03-21T12:48:57.545101Z",
    "updated_at": "2023-03-21T13:32:55.043263Z"
  }
}

HTTP Request

POST https://business.untappd.com/api/v1/menus/:id/publish

Query Parameters

Parameter Validations Required Description
id Integer true The menu to publish.

Unpublish a menu

Unpublish a menu.

Request:

curl "http://localhost:3000/api/v1/menus/5/unpublish" \
  -X POST \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="

Returns JSON structured like this (notice unpublished is now set to: true):

{
  "menu": {
    "id": 5,
    "location_id": 5,
    "uuid": "f181f982-42bf-414b-be9a-d13406e5be0b",
    "name": "Beverages",
    "description": "Grab something to drink while you're here.",
    "footer": null,
    "draft": true,
    "unpublished": true,
    "position": 0,
    "show_price_on_untappd": true,
    "push_notification_frequency": "real_time",
    "created_at": "2023-03-21T12:48:57.545101Z",
    "updated_at": "2023-03-21T13:32:55.043263Z"
  }
}

HTTP Request

POST https://business.untappd.com/api/v1/menus/:id/unpublish

Query Parameters

Parameter Validations Required Description
id Integer true The menu to unpublish.

Untappd Item Exists

Returns true or false depending on if an untappd item exists in any section in a menu.

Request:

curl "http://localhost:3000/api/v1/menus/5/untappd_item_exists/4099?is_nitro=true" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="

Returns JSON structured like this:

{
  "untappd_id": 4099,
  "exists": true
}

HTTP Request

GET https://business.untappd.com/api/v1/menus/:menu_id/untappd_item_exists/:untappd_id

Query Parameters

Parameter Validations Required Description
menu_id Integer true The id of the menu.
untappd_id Integer true The id of the untappd item.
is_nitro Boolean false "true", "1" - "false", "0"
is_cask Boolean false "true", "1" - "false", "0"

Sections

Section Object

Property Type Description
created_at timestamp Time at which the Section was created. ISO8601 format.
description string Description of the Section
id integer Unique identifier for the Section
menu_id integer Menu id that the Section belongs to. See Menu.
name string Name of the Section
position integer The position of the Section in the list of Sections for the Menu. Positions start at zero and should be contiguous.
public boolean If the Section is visible to the public. Controls visibility within the Untappd App when displaying menus.
type string One of Section or OnDeckSection
updated_at timestamp Time at which this Section was last updated. ISO8601 format.

Section Full Object

The full Section object can be returned by passing full=true when retieving a Menu. This will return the entire menu tree including all Sections, Items, and Containers. The following properties will be available in addition to the properties in the regular Section object

Property Type Description
items array An array of Items for the Section

List all sections

List all the sections of a menu.

Request:

curl "http://localhost:3000/api/v1/menus/5/sections?include_on_deck_section=true" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286S2t5cTE2dWtORHVtbzRUV3QzTF8="

Returns JSON structured like this:

{
  "sections": [
    {
      "id": 10,
      "menu_id": 5,
      "position": 0,
      "name": "Alcoholic",
      "description": "Escape from a hard day with something alcoholic!",
      "type": "Section",
      "public": true,
      "created_at": "2023-03-21T12:48:57.552844Z",
      "updated_at": "2023-03-21T14:17:37.727172Z"
    },
    {
      "id": 9,
      "menu_id": 5,
      "position": 0,
      "name": "On Deck",
      "description": "",
      "type": "OnDeckSection",
      "public": true,
      "created_at": "2023-03-21T12:48:57.548359Z",
      "updated_at": "2023-03-21T14:14:17.542020Z"
    }
  ]
}

HTTP Request

GET https://business.untappd.com/api/v1/menus/:menu_id/sections

Query Parameters

Parameter Validations Required Description
menu_id Integer true The menu to lookup the sections for.
include_on_deck_section true of false false When set to true will return the section with type OnDeckSection for the menu.
include_legacy Boolean false Enables legacy section fallback. See Legacy Migration

Create a section

Creates a new section belonging to a menu.

Request:

curl "http://localhost:3000/api/v1/menus/5/sections" \
  -X POST \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286S2t5cTE2dWtORHVtbzRUV3QzTF8=" \
  -H "Content-Type: application/json" \
  -d '{ "section": { "name": "Other beers", "description": "Our beers that are not dark or light." } }'

Returns JSON structured like this:

{
  "section": {
    "id": 16,
    "menu_id": 5,
    "position": 2,
    "name": "Other beers",
    "description": "Our beers that are not dark or light.",
    "created_at": "2023-03-21T17:50:55.954Z",
    "updated_at": "2023-03-21T17:50:55.954Z",
    "public": true,
    "items_count": 0
  }
}

HTTP Request

POST https://business.untappd.com/api/v1/menus/:menu_id/sections

Query Parameters

Parameter Validations Required Description
menu_id Integer true The id of the menu.
head true or false true Adds the new section to the head of the list of sections for this menu when head is true. Otherwise the new section will be appended to the end.
name String false A name for the new section.
description String false A description for the new section.

Retrieve a section

Retrieve the details of an existing section. You need only supply the unique section identifier that was returned upon section creation.

Request:

curl "http://localhost:3000/api/v1/sections/10" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286S2t5cTE2dWtORHVtbzRUV3QzTF8="

Returns JSON structured like this:

{
  "section": {
    "id": 10,
    "menu_id": 5,
    "position": 0,
    "name": "Alcoholic",
    "description": "Escape from a hard day with something alcoholic!",
    "type": "Section",
    "public": true,
    "created_at": "2023-03-21T12:48:57.552844Z",
    "updated_at": "2023-03-21T14:17:37.727172Z"
  }
}

HTTP Request

GET https://business.untappd.com/api/v1/sections/:id

Query Parameters

Parameter Validations Required Description
id Integer true The id of the section.
include_legacy Boolean false Enables legacy section fallback. See Legacy Migration

Update a section

Updates the specified section by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Note: This endpoint does not currently support updating On Deck sections. Instead, you can perform actions on an On Deck section by doing the following:

Request:

curl "http://localhost:3000/api/v1/sections/10" \
  -X PATCH \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286S2t5cTE2dWtORHVtbzRUV3QzTF8=" \
  -H "Content-Type: application/json" \
  -d '{ "section": { "name": "Alcoholic Drinks" } }'

Returns JSON structured like this:

{
  "section": {
    "name": "Alcoholic Drinks",
    "id": 10,
    "menu_id": 5,
    "position": 0,
    "description": "Escape from a hard day with something alcoholic!",
    "created_at": "2023-03-21T12:48:57.552Z",
    "updated_at": "2023-03-21T17:52:55.087Z",
    "public": true,
    "items_count": 4
  }
}

HTTP Request

PUT https://business.untappd.com/api/v1/sections/:id

PATCH https://business.untappd.com/api/v1/sections/:id

Query Parameters

Parameter Validations Required Description
id Integer true The id of the section.
name String false The section name.
description String false The section description. Note: This parameter is not available for OnDeckSection.

Delete a section

Permanently deletes a section. It cannot be undone.

Request:

curl "http://localhost:3000/api/v1/sections/15" \
  -X DELETE \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286S2t5cTE2dWtORHVtbzRUV3QzTF8="

Returns the deleted section as JSON structured like this:

{
  "section": {
    "id": 15,
    "menu_id": 5,
    "position": 1,
    "name": "Other Beers",
    "description": "",
    "created_at": "2023-03-21T17:50:32.209Z",
    "updated_at": "2023-03-21T17:50:32.209Z",
    "public": true,
    "items_count": 0
  }
}

HTTP Request

DELETE https://business.untappd.com/api/v1/sections/:id

Query Parameters

Parameter Validations Required Description
id Integer true The id of the section.

Update section positions

Set the positions of sections in a menu. Section positions are used to order the sections of a published menu on a page.

Important!: When updating section positions, all sections for the menu must be passed and the positions must start at zero. Use List all sections first to get all the sections for the menu.

Request:

curl "http://localhost:3000/api/v1/menus/10/sections/positions" \
  -X PATCH \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286S2t5cTE2dWtORHVtbzRUV3QzTF8=" \
  -H "Content-Type: application/json" \
  -d '{ "sections": [{ "id": 1, "position": 1 }, { "id": 2, "position": 0 }] }'

Returns JSON structured like this:

{
  "sections": [
    {
      "id": 2,
      "position": 0
    },
    {
      "id": 1,
      "position": 1
    }
  ]
}

HTTP Request

PATCH https://business.untappd.com/api/v1/menus/:menu_id/sections/positions

Query Parameters

Parameter Validations Required Description
menu_id Integer true The menu to update section positions for.
sections Array true An Array of Objects. All the sections for a menu must be passed as a batch to be update atomically. Unexpected behavior may result otherwise.
id Integer true The section id to update the position for.
position Integer true The position to set the section at. Section positions must start at zero.

Social Announcements

List all social announcements

Returns a list of social announcements belonging to your location.

Request:

curl "http://localhost:3000/api/v1/locations/3/social_announcements" \
  -X GET \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286VUJnelJtUnpLZl9YUTZ5RHV0Qko="

Returns JSON structured like this:

{
  "social_announcements": {
    "upcoming": [
      {
        "id": 7,
        "location_id": 3,
        "created_at": "2016-10-12T15:17:38Z",
        "updated_at": "2016-10-12T15:17:38Z",
        "content": "This is an announcement that goes out once per week.",
        "period": "once",
        "canceled": false,
        "next_publish_at": "2016-11-15T18:21:51Z",
        "last_published_at": null,
        "type": "SocialAnnouncement",
        "post_to_facebook": false,
        "post_to_twitter": true,
        "display_on_embed_menu": false,
        "display_on_print_menu": false,
        "display_on_digital_board": false,
        "image_url": "https://s3.amazonaws.com/woof-announcements.nextglass.co/65e518beb4fe8ecee7a3e6c2e078723e75cdf889.svg?1476285458",
        "image_updated_at": "2016-10-12T15:17:38Z"
      }
    ],
    "weekly": [
      {
        "id": 6,
        "location_id": 3,
        "created_at": "2016-10-12T15:09:07Z",
        "updated_at": "2016-10-12T15:09:07Z",
        "content": "This is an announcement that goes out once per week.",
        "period": "weekly",
        "canceled": false,
        "next_publish_at": "2016-11-15T18:21:51Z",
        "last_published_at": null,
        "type": "SocialAnnouncement",
        "post_to_facebook": false,
        "post_to_twitter": true,
        "display_on_embed_menu": false,
        "display_on_print_menu": false,
        "display_on_digital_board": false,
        "image_url": "https://s3.amazonaws.com/woof-announcements.nextglass.co/240322ed5b0b074f4cbbd596c5080ef438f9d719.svg?1476284947",
        "image_updated_at": "2016-10-12T15:09:07Z"
      }
    ]
  }
}

HTTP Request

GET https://business.untappd.com/api/v1/locations/:location_id/social_announcements

Query Parameters

Parameter Validations Required Description
location_id Integer true The id of the location.

Create a social announcement

Creates a new social announcement.

Request:

curl "http://localhost:3000/api/v1/locations/3/social_announcements" \
  -X POST \
  -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286VUJnelJtUnpLZl9YUTZ5RHV0Qko=" \
  -H "Content-Type: application/json" \
  -d '{ "social_announcement": { "content": "This is an announcement that goes out once per week.", "period": "weekly", "next_publish_at": "2016-11-15T13:21:51Z", "post_to_twitter": true, "image_remote_url": "https://d2q2v9tznh5hzu.cloudfront.net/assets/untappd-logo-a7618c61b0c901c636054446ebe4a19687b132cd98188bb8c33e20cf5294ec83.svg" } }'

Returns JSON structured like this:

{
  "social_announcement": {
    "id": 6,
    "location_id": 3,
    "created_at": "2016-10-12T15:09:07Z",
    "updated_at": "2016-10-12T15:09:07Z",
    "content": "This is an announcement that goes out once per week.",
    "period": "weekly",
    "canceled": false,
    "next_publish_at": "2016-11-15T18:21:51Z",
    "last_published_at": null,
    "type": "SocialAnnouncement",
    "post_to_facebook": false,
    "post_to_twitter": true,
    "display_on_embed_menu": false,
    "display_on_print_menu": false,
    "display_on_digital_board": false,
    "image_url": "https://s3.amazonaws.com/woof-announcements.nextglass.co/240322ed5b0b074f4cbbd596c5080ef438f9d719.svg?1476284947",
    "image_updated_at": "2016-10-12T15:09:07Z"
  }
}