NAV Navbar
shell
  • Introduction
  • GraphQL
  • Authentication
  • Analytics
  • Container Sizes
  • Containers
  • Current User
  • Custom Containers
  • Custom Item Types
  • Custom Items
  • Custom Menus
  • Custom Sections
  • Errors
  • Events
  • Insights
  • Items
  • Locations
  • Menu Announcements
  • Menu History
  • Menus
  • Sections
  • Social Announcements
  • Status
  • Changelog
  • 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.

    GraphQL

    Check out our new GraphQL API Explorer

    https://business.untappd.com/graphi

    GraphQL is actively being used in many parts of Untappd For Business, including the Menu Builder and the UTFB Mobile App.

    Note: The GraphQL API uses the same authentication mechanism as the REST API.

    GraphQL Endpoint (POST):

    https://business.untappd.com/graphql
    

    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/api_tokens.


    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/api_tokens.

    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 "https://business.untappd.com/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.

    List all container sizes

    Request:

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

    Returns JSON structured like this:

    {
      "container_sizes": [
        {
          "id": 1,
          "name": "Draft",
          "position": 1,
          "created_at": "2016-04-07T14:26:31Z",
          "updated_at": "2016-04-07T14:26:31Z"
        },
        {
          "id": 2,
          "name": "Can",
          "position": 2,
          "created_at": "2016-04-07T14:26:31Z",
          "updated_at": "2016-04-07T14:26:31Z"
        },
        {
          "id": 3,
          "name": "Bottle",
          "position": 3,
          "created_at": "2016-04-07T14:26:31Z",
          "updated_at": "2016-04-07T14:26:31Z"
        },
        {
          "id": 4,
          "name": "Tallboy",
          "position": 4,
          "created_at": "2016-04-07T14:26:31Z",
          "updated_at": "2016-04-07T14:26:31Z"
        },
        {
          "id": 8,
          "name": "4 Pack",
          "position": 5,
          "created_at": "2016-04-07T14:26:31Z",
          "updated_at": "2016-04-07T14:26:31Z"
        },
        {
          "id": 5,
          "name": "Crowler",
          "position": 6,
          "created_at": "2016-04-07T14:26:31Z",
          "updated_at": "2016-04-07T14:26:31Z"
        },
        {
          "id": 6,
          "name": "32oz Growler",
          "position": 7,
          "created_at": "2016-04-07T14:26:31Z",
          "updated_at": "2016-04-07T14:26:31Z"
        },
        {
          "id": 7,
          "name": "64oz Growler",
          "position": 8,
          "created_at": "2016-04-07T14:26:31Z",
          "updated_at": "2016-04-07T14:26:31Z"
        }
      ]
    }
    

    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

    List all containers

    Returns a list of containers belonging to an item.

    Request:

    curl "https://business.untappd.com/api/v1/items/1/containers" \
      -X GET \
      -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ="
    

    Returns JSON structured like this:

    {
      "containers": [
        {
          "id": 1,
          "item_id": 1,
          "container_size_id": 6,
          "price": "4.00",
          "position": 0,
          "created_at": "2016-06-16T19:54:49Z",
          "updated_at": "2016-06-16T19:54:55Z",
          "container_size": {
            "id": 6,
            "name": "8oz Draft",
            "position": 6,
            "created_at": "2016-06-16T19:30:00.948Z",
            "updated_at": "2016-06-16T19:30:00.948Z",
            "container_size_group_id": 1
          },
          "_track_by": 1
        },
        {
          "id": 2,
          "item_id": 1,
          "container_size_id": 4,
          "price": "3.75",
          "position": 1,
          "created_at": "2016-06-16T19:55:02Z",
          "updated_at": "2016-06-16T19:55:05Z",
          "container_size": {
            "id": 4,
            "name": "6oz Draft",
            "position": 4,
            "created_at": "2016-06-16T19:30:00.940Z",
            "updated_at": "2016-06-16T19:30:00.940Z",
            "container_size_group_id": 1
          },
          "_track_by": 2
        }
      ]
    }
    

    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.

    Create a container

    Add a new container to an item.

    Request:

    curl "https://business.untappd.com/api/v1/items/1/containers" \
      -X POST \
      -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ=" \
      -H "Content-Type: application/json" \
      -d '{ "container": { "container_size_id": 4, "price": 3.99 } }'
    

    Returns JSON structured like this:

    {
      "container": {
        "id": 6,
        "item_id": 1,
        "container_size_id": 4,
        "price": "3.99",
        "position": 0,
        "created_at": "2016-06-20T14:04:05Z",
        "updated_at": "2016-06-20T14:04:05Z",
        "container_size": {
          "id": 4,
          "name": "6oz Draft",
          "position": 4,
          "created_at": "2016-06-16T19:30:00.940Z",
          "updated_at": "2016-06-16T19:30:00.940Z",
          "container_size_group_id": 1
        },
        "_track_by": 6
      }
    }
    

    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 "https://business.untappd.com/api/v1/containers/1" \
      -X GET \
      -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ="
    

    Returns JSON structured like this:

    {
      "container": {
        "id": 1,
        "item_id": 1,
        "container_size_id": 6,
        "price": "4.00",
        "position": 0,
        "created_at": "2016-06-16T19:54:49Z",
        "updated_at": "2016-06-16T19:54:55Z",
        "container_size": {
          "id": 6,
          "name": "8oz Draft",
          "position": 6,
          "created_at": "2016-06-16T19:30:00.948Z",
          "updated_at": "2016-06-16T19:30:00.948Z",
          "container_size_group_id": 1
        },
        "_track_by": 1
      }
    }
    

    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.

    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 "https://business.untappd.com/api/v1/containers/1" \
      -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": 1,
        "item_id": 1,
        "container_size_id": 6,
        "price": "2.99",
        "position": 1,
        "created_at": "2016-06-16T19:54:49Z",
        "updated_at": "2016-06-20T14:16:14Z",
        "container_size": {
          "id": 6,
          "name": "8oz Draft",
          "position": 6,
          "created_at": "2016-06-16T19:30:00.948Z",
          "updated_at": "2016-06-16T19:30:00.948Z",
          "container_size_group_id": 1
        },
        "_track_by": 1
      }
    }
    

    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 "https://business.untappd.com/api/v1/containers/1" \
      -X DELETE \
      -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ="
    

    Returns the deleted container as JSON structured like this:

    {
      "container": {
        "id": 1,
        "item_id": 1,
        "container_size_id": 6,
        "price": "2.99",
        "position": 0,
        "created_at": "2016-06-16T19:54:49Z",
        "updated_at": "2016-06-20T14:16:14Z",
        "container_size": {
          "id": 6,
          "name": "8oz Draft",
          "position": 6,
          "created_at": "2016-06-16T19:30:00.948Z",
          "updated_at": "2016-06-16T19:30:00.948Z",
          "container_size_group_id": 1
        },
        "_track_by": 1
      }
    }
    

    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

    List all custom containers

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

    Request:

    curl "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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

    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 "https://business.untappd.com/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

    List all custom items

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

    Request:

    curl "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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

    List all custom menus

    Returns a list of custom menus belonging to your location.

    Request:

    curl "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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.

    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 "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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

    List all custom sections

    List all the custom sections of a custom menu.

    Request:

    curl "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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.

    Errors

    The Kittn API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Your request sucks
    401 Unauthorized -- Your API key is wrong
    403 Forbidden -- The kitten requested is hidden for administrators only
    404 Not Found -- The specified kitten could not be found
    405 Method Not Allowed -- You tried to access a kitten with an invalid method
    406 Not Acceptable -- You requested a format that isn't json
    410 Gone -- The kitten requested has been removed from our servers
    418 I'm a teapot
    429 Too Many Requests -- You're requesting too many kittens! Slow down!
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- We're temporarially offline for maintanance. Please try again later.

    Events

    List all events

    Returns a list of events belonging to your location.

    Request:

    curl "https://business.untappd.com/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",
          "end_time": "2017-06-30T19:15:00.000Z",
          "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 "https://business.untappd.com/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",
        "end_time": "2017-06-30T19:15:00.000Z",
        "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 "https://business.untappd.com/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",
        "end_time": "2017-06-30T19:15:00.000Z",
        "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 "https://business.untappd.com/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",
        "end_time": 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 "https://business.untappd.com/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",
        "end_time": 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.

    Insights

    Retrieve checkins over time

    Retrieve the number of checkins over time for a location.

    Request defaults to group_by=checkins

    curl "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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

    List all items

    Returns a list of items belonging to a section.

    Request:

    curl "https://business.untappd.com/api/v1/sections/1/items" \
      -X GET \
      -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
    

    Returns JSON structured like this:

    {
      "items": [
        {
          "id": 3,
          "section_id": 1,
          "position": 0,
          "untappd_id": 4473,
          "label_image": "https://untappd.akamaized.net/site/beer_logos/beer-_4473_8122008947804818c90640a06d83.jpeg",
          "brewery_location": "Dublin 8",
          "abv": "4.3",
          "ibu": "45.0",
          "cask": false,
          "nitro": false,
          "tap_number": null,
          "rating": "3.81587",
          "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.\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",
          "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.\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",
          "style": "Stout - Irish Dry",
          "custom_style": null,
          "original_style": "Stout - Irish Dry",
          "brewery": "Guinness",
          "custom_brewery": null,
          "original_brewery": "Guinness",
          "created_at": "2016-11-08T15:02:12Z",
          "updated_at": "2016-11-08T15:02:12Z"
        },
        {
          "id": 2,
          "section_id": 1,
          "position": 1,
          "untappd_id": 19004,
          "label_image": "https://untappd.akamaized.net/site/beer_logos/beer-bostonUtopias.jpg",
          "brewery_location": "Boston, MA",
          "abv": "27.0",
          "ibu": "0.0",
          "cask": false,
          "nitro": false,
          "tap_number": null,
          "rating": "4.47778",
          "in_production": true,
          "untappd_beer_slug": "boston-beer-company-samuel-adams-utopias",
          "untappd_brewery_id": 157,
          "name": "Samuel Adams Utopias",
          "original_name": "Samuel Adams Utopias",
          "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.",
          "custom_description": null,
          "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.",
          "style": "Strong Ale - American",
          "custom_style": null,
          "original_style": "Strong Ale - American",
          "brewery": "Boston Beer Company",
          "custom_brewery": null,
          "original_brewery": "Boston Beer Company",
          "created_at": "2016-11-08T15:01:54Z",
          "updated_at": "2016-11-08T15:01:54Z"
        }
      ]
    }
    

    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.

    Create an item

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

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

    Request:

    curl "https://business.untappd.com/api/v1/sections/1/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": 4,
        "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": false,
        "nitro": false,
        "tap_number": null,
        "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 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.",
        "custom_description": null,
        "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-08T15:08:49Z",
        "updated_at": "2016-11-08T15:08:49Z"
      }
    }
    

    HTTP Request

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

    Query Parameters

    Parameter Validations Required Description
    section_id Integer true The section to add the item to.
    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

    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 "https://business.untappd.com/api/v1/items/4" \
      -X GET \
      -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
    

    Returns JSON structured like this:

    {
      "item": {
        "id": 4,
        "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": false,
        "nitro": false,
        "tap_number": null,
        "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 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.",
        "custom_description": null,
        "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-08T15:08:49Z",
        "updated_at": "2016-11-08T15:08:49Z"
      }
    }
    

    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.

    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 "https://business.untappd.com/api/v1/items/4" \
      -X PATCH \
      -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
      -H "Content-Type: application/json" \
      -d '{ "item": { "cask": true, "description": "All the rest...", "tap_number": 1, "brewery": "Russian River Brewing Co." } }'
    

    Returns JSON structured like this:

    {
      "item": {
        "id": 4,
        "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-08T15:08:49Z",
        "updated_at": "2016-11-08T16:18:51Z"
      }
    }
    

    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 "https://business.untappd.com/api/v1/items/4" \
      -X DELETE \
      -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
    

    Returns the deleted item as JSON structured like this:

    {
      "item": {
        "id": 4,
        "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-08T15:08:49Z",
        "updated_at": "2016-11-08T16:18:51Z"
      }
    }
    

    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 "https://business.untappd.com/api/v1/sections/1/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 "https://business.untappd.com/api/v1/items/2/move" \
      -X PATCH \
      -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
      -H "Content-Type: application/json" \
      -d '{ "item": { "section_id": 3 } }'
    

    Returns JSON structured like this:

    {
      "item": {
        "id": 2,
        "section_id": 3,
        "position": 0,
        "untappd_id": 19004,
        "label_image": "https://untappd.akamaized.net/site/beer_logos/beer-bostonUtopias.jpg",
        "brewery_location": "Boston, MA",
        "abv": "27.0",
        "ibu": "0.0",
        "cask": false,
        "nitro": false,
        "tap_number": null,
        "rating": "4.47778",
        "in_production": true,
        "untappd_beer_slug": "boston-beer-company-samuel-adams-utopias",
        "untappd_brewery_id": 157,
        "name": "Samuel Adams Utopias",
        "original_name": "Samuel Adams Utopias",
        "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.",
        "custom_description": null,
        "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.",
        "style": "Strong Ale - American",
        "custom_style": null,
        "original_style": "Strong Ale - American",
        "brewery": "Boston Beer Company",
        "custom_brewery": null,
        "original_brewery": "Boston Beer Company",
        "created_at": "2016-11-08T15:01:54Z",
        "updated_at": "2016-11-08T16:25:35Z"
      }
    }
    

    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 "https://business.untappd.com/api/v1/items/search?q=pbr" \
      -X GET \
      -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
    

    Returns JSON structured like this:

    {
      "items": [
        {
          "id": null,
          "section_id": null,
          "position": 0,
          "untappd_id": 3883,
          "label_image": "https://untappd.akamaized.net/site/beer_logos/beer-3883_a0aa4_sm.jpeg",
          "brewery_location": null,
          "abv": "4.6",
          "ibu": null,
          "cask": false,
          "nitro": false,
          "tap_number": null,
          "rating": null,
          "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": null,
          "custom_description": null,
          "original_description": null,
          "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": null,
          "updated_at": null
        },
        {
          "id": null,
          "section_id": null,
          "position": 0,
          "untappd_id": 3884,
          "label_image": "https://untappd.akamaized.net/site/beer_logos/beer-PabstBlueRibbonLight_3884.jpeg",
          "brewery_location": null,
          "abv": "4.19",
          "ibu": null,
          "cask": false,
          "nitro": false,
          "tap_number": null,
          "rating": null,
          "in_production": true,
          "untappd_beer_slug": "pabst-brewing-company-pabst-blue-ribbon-light",
          "untappd_brewery_id": 963,
          "name": "Pabst Blue Ribbon Light",
          "original_name": "Pabst Blue Ribbon Light",
          "custom_name": null,
          "description": null,
          "custom_description": null,
          "original_description": null,
          "style": "Lager - American Light",
          "custom_style": null,
          "original_style": "Lager - American Light",
          "brewery": "Pabst Brewing Company",
          "custom_brewery": null,
          "original_brewery": "Pabst Brewing Company",
          "created_at": null,
          "updated_at": null
        },
        {
          "id": null,
          "section_id": null,
          "position": 0,
          "untappd_id": 407497,
          "label_image": "https://untappd.akamaized.net/site/beer_logos/beer-_407497_sm_cc8e22fe9e89e8db21eef386d4800e.jpeg",
          "brewery_location": null,
          "abv": "5.4",
          "ibu": null,
          "cask": false,
          "nitro": false,
          "tap_number": null,
          "rating": null,
          "in_production": true,
          "untappd_beer_slug": "barley-browns-beer-point-blank-red",
          "untappd_brewery_id": 7046,
          "name": "Point Blank Red",
          "original_name": "Point Blank Red",
          "custom_name": null,
          "description": null,
          "custom_description": null,
          "original_description": null,
          "style": "Red Ale - American Amber / Red",
          "custom_style": null,
          "original_style": "Red Ale - American Amber / Red",
          "brewery": "Barley Brown's Beer",
          "custom_brewery": null,
          "original_brewery": "Barley Brown's Beer",
          "created_at": null,
          "updated_at": 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 "https://business.untappd.com/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 "https://business.untappd.com/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": 3,
          "section_id": 1,
          "position": 0,
          "untappd_id": 4473,
          "label_image": "https://untappd.akamaized.net/site/beer_logos/beer-_4473_8122008947804818c90640a06d83.jpeg",
          "brewery_location": "Dublin 8",
          "abv": "4.3",
          "ibu": "45.0",
          "cask": false,
          "nitro": false,
          "tap_number": null,
          "rating": "3.81587",
          "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.\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",
          "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.\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",
          "style": "Stout - Irish Dry",
          "custom_style": null,
          "original_style": "Stout - Irish Dry",
          "brewery": "Guinness",
          "custom_brewery": null,
          "original_brewery": "Guinness",
          "created_at": "2016-11-08T15:02:12Z",
          "updated_at": "2016-11-08T15:02:12Z"
        },
        {
          "id": 2,
          "section_id": 1,
          "position": 1,
          "untappd_id": 19004,
          "label_image": "https://untappd.akamaized.net/site/beer_logos/beer-bostonUtopias.jpg",
          "brewery_location": "Boston, MA",
          "abv": "27.0",
          "ibu": "0.0",
          "cask": false,
          "nitro": false,
          "tap_number": null,
          "rating": "4.47778",
          "in_production": true,
          "untappd_beer_slug": "boston-beer-company-samuel-adams-utopias",
          "untappd_brewery_id": 157,
          "name": "Samuel Adams Utopias",
          "original_name": "Samuel Adams Utopias",
          "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.",
          "custom_description": null,
          "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.",
          "style": "Strong Ale - American",
          "custom_style": null,
          "original_style": "Strong Ale - American",
          "brewery": "Boston Beer Company",
          "custom_brewery": null,
          "original_brewery": "Boston Beer Company",
          "created_at": "2016-11-08T15:01:54Z",
          "updated_at": "2016-11-08T16:28:30Z"
        }
      ]
    }
    

    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 "https://business.untappd.com/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",
          "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

    Menu Announcements

    List all menu announcements

    Returns a list of menu announcements belonging to your location.

    Request:

    curl "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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: <https://business.untappd.com/api/v1/locations/3/historical_items?page=2>; rel="last", <https://business.untappd.com/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 "https://business.untappd.com/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 "https://business.untappd.com/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

    List all menus

    Returns a list of menus belonging to your location.

    Request:

    curl "https://business.untappd.com/api/v1/locations/3/menus" \
      -X GET \
      -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
    

    Returns JSON structured like this:

    {
      "menus": [
        {
          "id": 1,
          "location_id": 3,
          "uuid": "98e37027-3f8e-45c7-b9a0-4984128be836",
          "unpublished": true,
          "name": "Draft Beer List",
          "description": "All the draft beers.",
          "footer": "Heavy vs. Light or Good vs. Evil? You Decide.",
          "created_at": "2016-06-16T19:53:37Z",
          "updated_at": "2016-06-16T19:57:33Z",
          "published_at_embed": null,
          "published_at_untappd": null,
          "published_at_facebook": null,
          "position": 0
        }
      ]
    }
    

    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.

    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 "https://business.untappd.com/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",
                      "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
                    }
                  ]
                },
                {
                  "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",
                      "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
                    }
                  ]
                }
              ]
            }
          ],
          "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 "https://business.untappd.com/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",
                      "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
                    }
                  ]
                },
                {
                  "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",
                      "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
                    }
                  ]
                }
              ]
            }
          ],
          "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 location to update menu positions for.
    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 "https://business.untappd.com/api/v1/locations/3/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": 1,
        "location_id": 3,
        "uuid": "98e37027-3f8e-45c7-b9a0-4984128be836",
        "unpublished": true,
        "name": "Draft Beer List",
        "description": null,
        "footer": null,
        "created_at": "2016-06-16T19:53:37Z",
        "updated_at": "2016-06-16T19:57:33Z",
        "published_at_embed": null,
        "published_at_untappd": null,
        "published_at_facebook": null,
        "position": 0
      }
    }
    

    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 "https://business.untappd.com/api/v1/menus/1" \
      -X GET \
      -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
    

    Returns JSON structured like this:

    {
      "menu": {
        "id": 1,
        "location_id": 3,
        "uuid": "98e37027-3f8e-45c7-b9a0-4984128be836",
        "unpublished": true,
        "name": "Draft Beer List",
        "description": "All the draft beers.",
        "footer": "Heavy vs. Light or Good vs. Evil? You Decide.",
        "created_at": "2016-06-16T19:53:37Z",
        "updated_at": "2016-06-16T19:57:33Z",
        "published_at_embed": null,
        "published_at_untappd": null,
        "published_at_facebook": null,
        "position": 0
      }
    }
    

    Or...

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

    curl "https://business.untappd.com/api/v1/menus/3?full=true" \
      -X GET \
      -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
    

    Returns JSON structured like this:

    {
      "menu": {
        "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:02:49Z",
        "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:02:49Z",
            "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:02:49Z",
                "containers": [
                  {
                    "id": 13,
                    "item_id": 10,
                    "container_size_id": 5,
                    "price": "3.99",
                    "position": 0,
                    "created_at": "2016-11-08T17:02:49Z",
                    "updated_at": "2016-11-08T17:02:49Z",
                    "container_size": {
                      "id": 5,
                      "name": "Crowler",
                      "position": 101,
                      "created_at": "2016-03-01T15:36:26Z",
                      "updated_at": "2016-08-24T20:55:13Z"
                    },
                    "_track_by": 13
                  }
                ]
              },
              {
                "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:02:49Z",
                "containers": [
                  {
                    "id": 14,
                    "item_id": 11,
                    "container_size_id": 5,
                    "price": "3.99",
                    "position": 0,
                    "created_at": "2016-11-08T17:02:49Z",
                    "updated_at": "2016-11-08T17:02:49Z",
                    "container_size": {
                      "id": 5,
                      "name": "Crowler",
                      "position": 101,
                      "created_at": "2016-03-01T15:36:26Z",
                      "updated_at": "2016-08-24T20:55:13Z"
                    },
                    "_track_by": 14
                  }
                ]
              }
            ]
          }
        ],
        "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

    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.

    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 "https://business.untappd.com/api/v1/menus/1" \
      -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": 1,
        "location_id": 3,
        "uuid": "98e37027-3f8e-45c7-b9a0-4984128be836",
        "unpublished": true,
        "name": "Super Awesome Draft Beer List",
        "description": "All the draft beers.",
        "footer": "Heavy vs. Light or Good vs. Evil? You Decide.",
        "created_at": "2016-06-16T19:53:37Z",
        "updated_at": "2016-06-17T14:07:48Z",
        "column_formatting": "column_formatting_single_column",
        "published_at_embed": null,
        "published_at_untappd": null,
        "published_at_facebook": null,
        "position": 0
      }
    }
    

    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 "https://business.untappd.com/api/v1/menus/1" \
      -X DELETE \
      -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
    

    Returns the deleted menu as JSON structured like this:

    {
      "menu": {
        "id": 1,
        "location_id": 3,
        "uuid": "98e37027-3f8e-45c7-b9a0-4984128be836",
        "unpublished": true,
        "name": "Super Awesome Draft Beer List",
        "description": "All the draft beers.",
        "footer": "Heavy vs. Light or Good vs. Evil? You Decide.",
        "created_at": "2016-06-16T19:53:37Z",
        "updated_at": "2016-06-17T14:07:48Z",
        "column_formatting": "column_formatting_single_column",
        "published_at_embed": null,
        "published_at_untappd": null,
        "published_at_facebook": null,
        "position": 0
      }
    }
    

    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.

    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 "https://business.untappd.com/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 Objects. All the menus for a location must be passed as a batch to be update atomically. Unexpected behavior may result otherwise.
    id Integer true The 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 "https://business.untappd.com/api/v1/locations/3/menus/publish_all" \
      -X POST \
      -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
    

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

    {
      "menus": [
        {
          "id": 1,
          "location_id": 3,
          "uuid": "98e37027-3f8e-45c7-b9a0-4984128be836",
          "unpublished": false,
          "name": "Super Awesome Draft Beer List",
          "description": "All the draft beers.",
          "footer": "Heavy vs. Light or Good vs. Evil? You Decide.",
          "created_at": "2016-06-16T19:53:37Z",
          "updated_at": "2016-06-17T14:34:11Z",
          "published_at_embed": null,
          "published_at_untappd": null,
          "published_at_facebook": null,
          "position": 1
        },
        {
          "id": 3,
          "location_id": 3,
          "uuid": "1b11b983-d90d-40bf-afc6-a5d55ab3e5f9",
          "unpublished": false,
          "name": "Three Commas",
          "description": null,
          "footer": null,
          "created_at": "2016-06-17T13:41:36Z",
          "updated_at": "2016-06-17T14:34:11Z",
          "published_at_embed": null,
          "published_at_untappd": null,
          "published_at_facebook": null,
          "position": 0
        }
      ]
    }
    

    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 "https://business.untappd.com/api/v1/menus/1/publish" \
      -X POST \
      -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
    

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

    {
      "menu": {
        "id": 1,
        "location_id": 3,
        "uuid": "98e37027-3f8e-45c7-b9a0-4984128be836",
        "unpublished": false,
        "name": "Super Awesome Draft Beer List",
        "description": "All the draft beers.",
        "footer": "Heavy vs. Light or Good vs. Evil? You Decide.",
        "created_at": "2016-06-16T19:53:37Z",
        "updated_at": "2016-06-17T14:39:29Z",
        "published_at_embed": null,
        "published_at_untappd": null,
        "published_at_facebook": null,
        "position": 0
      }
    }
    

    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 "https://business.untappd.com/api/v1/menus/1/unpublish" \
      -X POST \
      -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
    

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

    {
      "menu": {
        "id": 1,
        "location_id": 3,
        "uuid": "98e37027-3f8e-45c7-b9a0-4984128be836",
        "unpublished": true,
        "name": "Super Awesome Draft Beer List",
        "description": "All the draft beers.",
        "footer": "Heavy vs. Light or Good vs. Evil? You Decide.",
        "created_at": "2016-06-16T19:53:37Z",
        "updated_at": "2016-06-17T15:00:42Z",
        "published_at_embed": null,
        "published_at_untappd": null,
        "published_at_facebook": null,
        "position": 0
      }
    }
    

    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 "https://business.untappd.com/api/v1/menus/1/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

    List all sections

    List all the sections of a menu.

    Request:

    curl "https://business.untappd.com/api/v1/menus/1/sections?include_on_deck_section=true" \
      -X GET \
      -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286S2t5cTE2dWtORHVtbzRUV3QzTF8="
    

    Returns JSON structured like this:

    {
      "sections": [
        {
          "id": 1,
          "menu_id": 1,
          "position": 0,
          "name": "Heavy",
          "description": "All our heavy draft beers.",
          "type":"Section",
          "created_at": "2016-06-16T19:53:37Z",
          "updated_at": "2016-06-16T19:55:48Z"
        },
        {
          "id": 2,
          "menu_id": 1,
          "position": 1,
          "name": "Light",
          "description": "All our light beers.",
          "type":"Section",
          "created_at": "2016-06-16T19:55:58Z",
          "updated_at": "2016-06-16T19:56:40Z"
        },
        {
          "id": 3,
          "menu_id": 1,
          "position": 0,
          "name": "On Deck",
          "description": "",
          "type": "OnDeckSection",
          "created_at": "2016-06-16T19:53:37Z",
          "updated_at": "2016-06-16T19:55:48Z"
        }
      ]
    }
    

    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.

    Create a section

    Creates a new section belonging to a menu.

    Request:

    curl "https://business.untappd.com/api/v1/menus/1/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": 6,
        "menu_id": 1,
        "position": 2,
        "name": "Other beers",
        "description": "Our beers that are not dark or light.",
        "created_at": "2016-06-17T15:09:40Z",
        "updated_at": "2016-06-17T15:09:40Z"
      }
    }
    

    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 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 "https://business.untappd.com/api/v1/sections/6" \
      -X GET \
      -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286S2t5cTE2dWtORHVtbzRUV3QzTF8="
    

    Returns JSON structured like this:

    {
      "section": {
        "id": 6,
        "menu_id": 1,
        "position": 2,
        "name": "Other beers",
        "description": "Our beers that are not dark or light.",
        "created_at": "2016-06-17T15:09:40Z",
        "updated_at": "2016-06-17T15:09:40Z"
      }
    }
    

    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.

    Update a section

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

    Request:

    curl "https://business.untappd.com/api/v1/sections/6" \
      -X PATCH \
      -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286S2t5cTE2dWtORHVtbzRUV3QzTF8=" \
      -H "Content-Type: application/json" \
      -d '{ "section": { "description": "All the rest..." } }'
    

    Returns JSON structured like this:

    {
      "section": {
        "id": 6,
        "menu_id": 1,
        "position": 2,
        "name": "Other beers",
        "description": "All the rest...",
        "type":"Section",
        "created_at": "2016-06-17T15:09:40Z",
        "updated_at": "2016-06-17T15:18:30Z"
      }
    }
    

    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 "https://business.untappd.com/api/v1/sections/6" \
      -X DELETE \
      -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286S2t5cTE2dWtORHVtbzRUV3QzTF8="
    

    Returns the deleted section as JSON structured like this:

    {
      "section": {
        "id": 6,
        "menu_id": 1,
        "position": 2,
        "name": "Other beers",
        "description": "All the rest...",
        "created_at": "2016-06-17T15:09:40Z",
        "updated_at": "2016-06-17T15:18:30Z"
      }
    }
    

    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 "https://business.untappd.com/api/v1/menus/1/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 "https://business.untappd.com/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 "https://business.untappd.com/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"
      }
    }
    

    HTTP Request

    POST 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.
    content String true The main content for the announcement. ex. "Join us for happy hour at 3pm!"
    image_remote_url String false A url to an image for the announcement.
    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.
    post_to_facebook Boolean false Indicates that the announcement should be posted to Facebook.
    post_to_twitter Boolean false Indicates that the announcement should be posted to Twitter.

    Cancel a social announcement

    Permanently deletes a social announcement. It cannot be undone.

    Request:

    curl "https://business.untappd.com/api/v1/social_announcements/4" \
      -X DELETE \
      -H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286VUJnelJtUnpLZl9YUTZ5RHV0Qko="
    

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

    {
      "social_announcement": {
        "id": 4,
        "location_id": 3,
        "created_at": "2016-10-12T15:03:29Z",
        "updated_at": "2016-10-12T15:17:15Z",
        "content": "This is an announcement that goes out once per week.",
        "period": "weekly",
        "canceled": true,
        "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/7dcaf01a343b9f100417c791efcbfa25eea4d470.?1476284609",
        "image_updated_at": "2016-10-12T15:03:29Z"
      }
    }
    

    HTTP Request

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

    Query Parameters

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

    Status

    A simple endpoint that returns 200 OK if the api is working.

    Returns JSON structured like this:

    { "status": "OK" }
    

    HTTP Request

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

    Changelog

    All notable changes to this API will be documented in this file.

    2017-10-12

    Added:

    2016-11-22

    Added:

    2016-11-16

    Added:

    2016-11-15

    Added:

    Changed:

    2016-11-08

    Added:

    Changed: