BetterTicketsAPI Docs

Events

List an event's ticket types

GET/events/{id}/locations
Scope
events:read
Base URL
https://app.bettertickets.com/api/partner/v1
Auth
Bearer API key

The active ticket types of one event, in display order, with prices in cents and live availability. Only numeric event ids are accepted.

A ticket type can be listed here and still not be for sale; check can_fulfill on GET /locations/{id}/availability before selling.

#Request

Headers

NameTypeRequiredDescription
AuthorizationstringrequiredBearer <key>. A btk_live_… or btk_test_… key.

Path parameters

NameTypeRequiredDescription
idintegerrequiredNumeric event id, plain digits only (concert_sku is not accepted here). (min 1) Example: 1001

#Responses

StatusMeaningError codes
200Ticket types.—
400The id is not plain digits of 1 or more (for example 5.0, 1e1, or a concert_sku).invalid_event_id
401No key, or the key was checked and is unknown, revoked, expired or has the wrong prefix. The same invalid_api_key is returned for every kind of bad key. Do not retry it. A temporary problem checking the key answers 503 auth_unavailable instead. Repeated requests with a missing or invalid key from one IP address are answered 429 partner_rate_limited instead of 401.missing_api_key invalid_api_key
403The key lacks the required scope, or API access is off for the account.insufficient_scope partner_api_disabled
404No such event on your account, a test event, or an event whose sales have closed.event_not_found
405The HTTP method is not supported on this path.method_not_allowed
429Too many requests from this key or from your IP address, or repeated requests with a missing or invalid key from one IP address (answered 429 instead of 401). Wait Retry-After seconds. See Rate Limits.partner_rate_limited
502BetterTickets could not load the data. Retry later.upstream_error
503BetterTickets could not check the key (auth_unavailable) or confirm the account's settings (FEATURE_GATE_UNAVAILABLE) for a moment. Safe to retry after Retry-After seconds; if the header is missing, wait 5 seconds. Retrying auth_unavailable faster than Retry-After gets 429 partner_rate_limited.auth_unavailable FEATURE_GATE_UNAVAILABLE

200 Ticket types.

Schema: LocationList

  • itemsarray of Locationrequired
    Child attributes
    • idintegerrequired

      Ticket type (location) id.

    • event_idintegerrequired
    • namestring | null

      Display name.

    • descriptionstring | null
    • priceinteger

      Price per ticket, in cents.

    • available_quantityinteger | null

      Tickets left after tickets sold; -1 = unlimited.

    • effective_availableinteger | null

      Tickets left after tickets sold and checkouts in progress; -1 = unlimited. The best "tickets left" number.

    • is_sold_outboolean | null
    • is_effectively_sold_outboolean | null

      Sold out once checkouts in progress are counted.

    • low_ticket_warningboolean | null

      True when only a few tickets are left.

    • addressstring | null

      Street address, for ticket types tied to a place (such as a pickup stop).

    • citystring | null
    • statestring | null
    • zip_codestring | null
    • image_urlstring | null

Example: locations

JSON
{
  "items": [
    {
      "id": 2001,
      "event_id": 1001,
      "name": "GA Weekend",
      "description": "General admission, both days.",
      "price": 5000,
      "available_quantity": 1188,
      "effective_available": 1184,
      "is_sold_out": false,
      "is_effectively_sold_out": false,
      "low_ticket_warning": false,
      "address": "100 Example Ave",
      "city": "Springfield",
      "state": "IL",
      "zip_code": "62701",
      "image_url": null
    }
  ]
}
400 The id is not plain digits of 1 or more (for example 5.0, 1e1, or a concert_sku).

Schema: Error

Example: invalid_event_id

JSON
{
  "error": "invalid_event_id"
}
401 No key, or the key was checked and is unknown, revoked, expired or has the wrong prefix. The same invalid_api_key is returned for every kind of bad key. Do not retry it. A temporary problem checking the key answers 503 auth_unavailable instead. Repeated requests with a missing or invalid key from one IP address are answered 429 partner_rate_limited instead of 401.

Schema: Error

Example: missing_api_key

JSON
{
  "error": "missing_api_key",
  "message": "Authorization: Bearer btk_… required"
}

Example: invalid_api_key

JSON
{
  "error": "invalid_api_key"
}
403 The key lacks the required scope, or API access is off for the account.

Schema: Error

Example: insufficient_scope

JSON
{
  "error": "insufficient_scope",
  "required": "events:read"
}

Example: partner_api_disabled

JSON
{
  "error": "partner_api_disabled"
}
404 No such event on your account, a test event, or an event whose sales have closed.

Schema: Error

Example: event_not_found

JSON
{
  "error": "event_not_found"
}
405 The HTTP method is not supported on this path.

Schema: Error

Example: method_not_allowed

JSON
{
  "error": "method_not_allowed"
}
429 Too many requests from this key or from your IP address, or repeated requests with a missing or invalid key from one IP address (answered 429 instead of 401). Wait Retry-After seconds. See Rate Limits.

Headers

NameTypeDescription
Retry-AfterintegerSeconds to wait before retrying (at least 1).

Schema: Error

Example: partner_rate_limited

JSON
{
  "error": "partner_rate_limited",
  "message": "Too many Partner API requests. Slow down and retry after Retry-After seconds.",
  "retry_after_seconds": 42
}
502 BetterTickets could not load the data. Retry later.

Schema: Error

Example: upstream_error

JSON
{
  "error": "upstream_error"
}
503 BetterTickets could not check the key (auth_unavailable) or confirm the account's settings (FEATURE_GATE_UNAVAILABLE) for a moment. Safe to retry after Retry-After seconds; if the header is missing, wait 5 seconds. Retrying auth_unavailable faster than Retry-After gets 429 partner_rate_limited.

Headers

NameTypeDescription
Retry-AfterintegerSeconds to wait before retrying.

Schema: Error

Example: auth_unavailable

JSON
{
  "error": "auth_unavailable",
  "message": "API key check is temporarily unavailable. Retry after Retry-After seconds.",
  "retryable": true,
  "retry_after_seconds": 5
}

Example: FEATURE_GATE_UNAVAILABLE

JSON
{
  "error": "FEATURE_GATE_UNAVAILABLE",
  "retryable": true,
  "retry_after_seconds": 5
}

#Code samples

Set BETTERTICKETS_API_KEY on your server. Never send a key from a browser.

cURL
curl "https://app.bettertickets.com/api/partner/v1/events/1001/locations" \
  -H "Authorization: Bearer $BETTERTICKETS_API_KEY"