# BetterTickets API — full documentation > Source: https://docs.bettertickets.com. Generated from the public OpenAPI spec and guides. Base URL `https://app.bettertickets.com/api/partner/v1`. --- # BetterTickets API The BetterTickets API lets your own server read your account's events, ticket types and live availability, and read and update rows of your Custom Lists. It is a small, JSON-over-HTTPS REST API authenticated with a Bearer key. > **Server-to-server only.** Call the API from your backend. Browsers are refused (no CORS), so never put a key in a web page or mobile app. ## Base URL ```text https://app.bettertickets.com/api/partner/v1 ``` Test keys and live keys use the same base URL. See [Test vs Live](https://docs.bettertickets.com/test-vs-live.md). ## Quickstart 1. Ask your BetterTickets contact to turn on API access for your account and issue you an API key. You get a `btk_test_…` key for building and a `btk_live_…` key for production. Until API access is on, every call answers `403 partner_api_disabled`. 2. Put the key in an environment variable on your server. The samples in these docs read it from `BETTERTICKETS_API_KEY`: ```bash export BETTERTICKETS_API_KEY=btk_test_… ``` 3. Send it as a Bearer token and list your events: ```bash curl https://app.bettertickets.com/api/partner/v1/events \ -H "Authorization: Bearer $BETTERTICKETS_API_KEY" ``` A successful call answers `200` with a page of events (shortened; see [List events](https://docs.bettertickets.com/reference/list-events.md) for every field): ```json { "itemsReceived": 1, "curPage": 1, "nextPage": null, "items": [ { "id": 1001, "name": "Summer Roots Festival 2027", "date": "2027-07-16", "is_sold_out": false } ] } ``` 4. Pick an event and list its ticket types. Replace `1001` with an `items[].id` from step 3: ```bash curl https://app.bettertickets.com/api/partner/v1/events/1001/locations \ -H "Authorization: Bearer $BETTERTICKETS_API_KEY" ``` 5. Check live availability right before you sell. Replace `2001` with an `items[].id` from the step 4 response: ```bash curl "https://app.bettertickets.com/api/partner/v1/locations/2001/availability?requested_quantity=2" \ -H "Authorization: Bearer $BETTERTICKETS_API_KEY" ``` ## What you can do | Resource | Operations | Scope | |---|---|---| | [Events](https://docs.bettertickets.com/reference/events.md) | [List events](https://docs.bettertickets.com/reference/list-events.md), [Get one event](https://docs.bettertickets.com/reference/get-event.md), [List an event's ticket types](https://docs.bettertickets.com/reference/list-event-locations.md) | `events:read` | | [Availability](https://docs.bettertickets.com/reference/availability.md) | [Get live availability of a ticket type](https://docs.bettertickets.com/reference/get-location-availability.md) | `events:read` | | [Custom Lists](https://docs.bettertickets.com/reference/custom-lists.md) | [Look up one list row](https://docs.bettertickets.com/reference/lookup-list-row.md), [Add or update list rows](https://docs.bettertickets.com/reference/upsert-list-rows.md) | `lists:read`, `lists:write` | ## Conventions - **JSON in and out.** Send `Content-Type: application/json` on `POST`. Responses are JSON, and responses to supported methods carry `Cache-Control: no-store`. Do not cache any response. - **Money is in cents.** A `price` of `5000` is $50.00. - **`-1` means unlimited** in quantity fields such as `available_quantity` and `effective_available`. - **Ticket types are called locations** in paths and field names. A location is one thing a buyer can pick for an event, for example *GA*, *VIP*, or a pickup stop. - **Timestamps.** List row `added_at` and `updated_at` are epoch milliseconds. Event `date`, `absolute_time` and `doors_time` are text as entered for the event; their format is not normalized. - **Documented fields only.** Responses can contain fields that are not documented here. They are not part of the API, may change or disappear without notice, and must not be relied on. - **Errors** share one shape: `{ "error": "", "message": "…" }`. Branch on `error`. See [Errors](https://docs.bettertickets.com/errors.md). ## Typical flow 1. `GET /events` to find the event (filter by date, venue or text). 2. `GET /events/{id}/locations` to pick a ticket type and read its price. 3. `GET /locations/{id}/availability` right before you sell, to confirm `can_fulfill`. Availability is read-only: nothing is reserved, so check it as close to the sale as you can. ## For AI tools Every page has a Markdown twin at the same path plus `.md`. The whole site is also available as [/llms.txt](https://docs.bettertickets.com/llms.txt) (index) and [/llms-full.txt](https://docs.bettertickets.com/llms-full.txt) (everything in one file), and the spec as [/openapi.json](https://docs.bettertickets.com/openapi.json) (OpenAPI 3.1). --- # Authentication & Keys Every request needs an API key, sent as a Bearer token: ```http GET /api/partner/v1/events HTTP/1.1 Host: app.bettertickets.com Authorization: Bearer btk_live_… ``` ## Getting a key Ask your BetterTickets contact for an API key. - A key belongs to one BetterTickets account and only ever sees that account's data. - Keys start with `btk_live_` (live) or `btk_test_` (test). Anything else is refused. See [Test vs Live](https://docs.bettertickets.com/test-vs-live.md). - The full key is shown once, when it is issued. Store it in a secret manager or an environment variable on your server, and never commit it to source control. - If a key leaks, ask your BetterTickets contact to revoke it and issue a new one. ## Server-to-server only The API is built for your backend. It does not allow cross-origin browser requests (no `Access-Control-Allow-Origin` header), so a browser cannot call it, and a key must never ship in a web page, browser extension or mobile app. For the same reason these docs have **no "Try It" console**. Use the generated cURL, Node, Python or PHP samples on each operation page from your own server or terminal. ## Scopes Each operation needs one scope. A key without it gets `403 insufficient_scope`, and the `required` field names the missing scope. | Scope | Allows | |---|---| | `events:read` | `GET /events`, `GET /events/{id}`, `GET /events/{id}/locations`, `GET /locations/{id}/availability`. Every key has it. | | `lists:read` | `GET /lists/{id}/rows` | | `lists:write` | `POST /lists/{id}/rows` | List scopes are added to a key on request; ask your BetterTickets contact. ```json { "error": "insufficient_scope", "required": "lists:write" } ``` ## Account access - API access must be turned on for your account; otherwise every call answers `403 partner_api_disabled`. - Custom Lists calls also need Custom Lists enabled on your account (`403 partner_lists_disabled`) and **API Access** turned on in that list's settings (`403 list_api_disabled`). See [Custom Lists](https://docs.bettertickets.com/custom-lists.md). - If BetterTickets cannot confirm these settings for a moment, the call answers `503 FEATURE_GATE_UNAVAILABLE`. Wait `Retry-After` seconds (5 if the header is missing) and retry. See [Retrying](https://docs.bettertickets.com/errors#retrying). ## Bad keys A missing key gets `401 missing_api_key`. A key that is unknown, revoked, expired or has the wrong prefix gets the same `401 invalid_api_key` for every case, so you cannot tell them apart from the response. `401 invalid_api_key` always means the key was checked and refused. Do not retry it; ask your BetterTickets contact for a new key. ## When the Key Check Is Unavailable If BetterTickets cannot check your key for a moment, the call answers `503 auth_unavailable` instead of `401`. Your key has not been judged invalid, so retry: ```http HTTP/1.1 503 Service Unavailable Retry-After: 5 Content-Type: application/json { "error": "auth_unavailable", "message": "API key check is temporarily unavailable. Retry after Retry-After seconds.", "retryable": true, "retry_after_seconds": 5 } ``` Wait `Retry-After` seconds between attempts and cap the number of attempts. Retrying faster gets `429 partner_rate_limited`. See [Retrying](https://docs.bettertickets.com/errors#retrying). --- # Test vs Live BetterTickets issues two kinds of key. Both use the same base URL: ```text https://app.bettertickets.com/api/partner/v1 ``` | | `btk_test_…` | `btk_live_…` | |---|---|---| | Events, ticket types, availability | Same live data as a live key (read-only) | Live data | | Test events | Not returned | Not returned | | Custom List reads and writes | The list's **Staging** rows | The list's **Production** rows | | Scopes, rate limits, errors | Same | Same | ## Events and availability Event, ticket type and availability calls are read-only, so a test key simply sees the same live events, prices and availability as a live key. Nothing you read reserves or changes anything. Events marked as test events in BetterTickets are not returned, for either kind of key: | Operation | For a test event | |---|---| | `GET /events` | Not listed | | `GET /events/{id}` | `404 event_not_found` | | `GET /events/{id}/locations` | `404 event_not_found` | | `GET /locations/{id}/availability` | `404 location_not_found` | ## Custom Lists Each Custom List keeps two separate data sets: - **Staging** — read and written by `btk_test_` keys. Use it to build and test your integration. - **Production** — read and written by `btk_live_` keys. These are the rows your live automations use. A list holds at most 50,000 rows per data set. Production reads answer `404 row_not_found` while the list's Production switch is off. ## Going live 1. Build and test against Staging with your `btk_test_` key. 2. Ask your BetterTickets contact for a `btk_live_` key with the same scopes. 3. Swap the key in your server's configuration. No URL changes are needed. --- # Errors Every error has the same JSON shape: ```json { "error": "list_api_disabled", "message": "API access is turned off for this list. Turn it on in the list settings." } ``` | Field | Meaning | |---|---| | `error` | Stable machine code. Branch on this. | | `message` | Human text. May change; not always present. | | `required` | `insufficient_scope` only: the scope the operation needs. | | `retry_after_seconds` | `partner_rate_limited`, `auth_unavailable` and `FEATURE_GATE_UNAVAILABLE` (when present): seconds to wait, the same value as the `Retry-After` header. | | `retryable` | `auth_unavailable` and `FEATURE_GATE_UNAVAILABLE` (when present): always `true`. | | `max_rows` | `too_many_rows` only: the per-call row limit (500). | | `reason` | `partner_lists_disabled` only, when present: a short machine-readable reason. | Branch on `error`, never on `message` or on the HTTP status alone. ## Error codes | Status | `error` | Meaning | Retry? | |---|---|---|---| | 400 | `invalid_page` | `page` is not a whole number of 1 or more. | No | | 400 | `invalid_per_page` | `per_page` is not a whole number of 1 or more. | No | | 400 | `invalid_venue_id` | `venue_id` is not a whole number. | No | | 400 | `invalid_event_id` | The event id (or `concert_sku`) is not valid. `GET /events/{id}/locations` takes plain digits only. | No | | 400 | `invalid_location_id` | The ticket type id is not plain digits of 1 or more. | No | | 400 | `invalid_list_id` | The list id is not a whole number of 1 or more. Send plain digits: other numeric forms, such as `1e1` or `0x10`, may be read as a different list id. | No | | 400 | `invalid_key` | `key` is missing, blank, too long, or does not fit the list's key column type. | No | | 400 | `rows_required` | `rows` is missing or empty. | No | | 401 | `missing_api_key` | No `Authorization: Bearer` header. Repeated from one IP address, answered `429 partner_rate_limited` instead. | No | | 401 | `invalid_api_key` | The key was checked and is unknown, revoked, expired or has the wrong prefix. Repeated from one IP address, answered `429 partner_rate_limited` instead. | No | | 403 | `insufficient_scope` | The key lacks the scope in `required`. | No | | 403 | `partner_api_disabled` | API access is off for your account. | No | | 403 | `partner_lists_disabled` | Custom Lists is not enabled for your account. | No | | 403 | `list_api_disabled` | API Access is off in this list's settings. | No | | 404 | `event_not_found` | No such event on your account, a test event, or sales have closed. | No | | 404 | `location_not_found` | No such ticket type on your account, a ticket type that is not sold on its own, one of a test event, or one whose event's sales have closed. | No | | 404 | `list_not_found` | No such list on your account, or it is archived. | No | | 404 | `row_not_found` | No active row with that key. | No | | 405 | `method_not_allowed` | The HTTP method is not supported on this path. On event and availability paths the key is checked first, so a call without a valid key gets `401` instead. | No | | 409 | `ambiguous_concert_sku` | The `concert_sku` matches more than one event. Use the numeric id. | No | | 409 | `list_not_ready` | The list has no valid columns yet. | No | | 413 | `too_many_rows` | More than 500 rows in one call. | No — split the batch | | 429 | `partner_rate_limited` | Too many requests from this key or from your IP address (see [Rate Limits](https://docs.bettertickets.com/rate-limits.md)), or repeated requests with a missing or invalid key from one IP address. | Yes, after `Retry-After` | | 500 | any | An unexpected error. The body may not follow the error shape. | Yes, with backoff and a small cap | | 502 | `upstream_error` | BetterTickets could not load or save the data. | Yes, with backoff and a small cap | | 502 | `request_refused` | Custom Lists: refused for an unlisted reason. Can also arrive with a 4xx status. | No — contact BetterTickets if it persists | | 503 | `auth_unavailable` | BetterTickets could not check the key for a moment. The key was not judged invalid. | Yes, after `Retry-After` | | 503 | `FEATURE_GATE_UNAVAILABLE` | BetterTickets could not confirm your account's settings for a moment. | Yes, after `Retry-After` | ## Retrying | `error` | Retry? | How | |---|---|---| | `partner_rate_limited` (429) | Yes | Wait `Retry-After` seconds, then retry one request at a time. | | `auth_unavailable` (503) | Yes | Wait `Retry-After` seconds (5) between attempts; retrying faster gets `429 partner_rate_limited`. | | `FEATURE_GATE_UNAVAILABLE` (503) | Yes | Wait `Retry-After` seconds. If the header is missing (Custom Lists calls can answer a bare `{ "error": "FEATURE_GATE_UNAVAILABLE" }`), wait 5 seconds. | | `upstream_error` (502) | Yes | Exponential backoff with jitter and a small cap on attempts. | | Any `500` | Yes | Exponential backoff with a small cap on attempts. | | `request_refused` (502 or 4xx) | No | Do not retry the same request; contact BetterTickets if it persists. | | Any other 4xx | No | Fix the request, the key or the account settings first. | Cap the number of attempts for every retryable error. `401 invalid_api_key` and `404` answers are not temporary: retrying the same request straight away gets the same answer. `POST /lists/{id}/rows` is safe to repeat: sending the same rows again updates them to the same values and reports them as `unchanged`. --- # Rate Limits By default a key can make about: | Requests | Limit | |---|---| | `GET` | **20 per minute** | | `POST` | **10 per minute** | All requests from one IP address, across all keys, are also limited to about **60 `GET`** and **30 `POST`** per minute. If your server uses several keys, plan for the shared IP limit as well as each key's limit. Repeated requests with a missing or invalid key from one IP address are answered `429 partner_rate_limited` instead of `401 missing_api_key` or `401 invalid_api_key`. Fix the key before retrying. Treat the numbers as a ceiling, not a guaranteed quota. If you need more, ask your BetterTickets contact. ## When you hit the limit You get `429 partner_rate_limited` with a `Retry-After` header (in seconds) and the same value in the body: ```http HTTP/1.1 429 Too Many Requests Retry-After: 42 Content-Type: application/json { "error": "partner_rate_limited", "message": "Too many Partner API requests. Slow down and retry after Retry-After seconds.", "retry_after_seconds": 42 } ``` Wait at least `Retry-After` seconds before the next request with that key, or from that IP address. ## Staying under the limit - **Cache event data.** Events and ticket types change rarely. Refresh them every few minutes, not on every page view. - **Check availability only when it matters**, for example right before a sale, rather than polling every ticket type. - **Batch list writes.** `POST /lists/{id}/rows` takes up to 500 rows per call; one call with 500 rows counts as one request. - **Serialize retries.** Do not retry several requests in parallel after a `429`. - **Pace retries of `503 auth_unavailable`.** Wait `Retry-After` seconds between attempts; retrying faster gets `429 partner_rate_limited`. ```js async function call(url, init = {}) { for (let attempt = 0; attempt < 5; attempt++) { const res = await fetch(url, init); if (res.status !== 429) return res; const wait = Number(res.headers.get('Retry-After') || 1); await new Promise((r) => setTimeout(r, wait * 1000)); } throw new Error('Still rate limited after 5 attempts'); } ``` --- # Pagination `GET /events` is the only paginated operation. Other operations return their full result in one response. ## Parameters | Parameter | Default | Notes | |---|---|---| | `page` | `1` | Page number, starting at 1. | | `per_page` | `20` | Events per page. Use 100 or fewer; larger values may be limited in future. | Both must be whole numbers of 1 or more, written as plain digits (`2`, not `2.0`, `+2` or `0x2`). Anything else, or the same parameter sent twice, answers `400`: | Parameter | Error | |---|---| | `page` | `400 invalid_page` | | `per_page` | `400 invalid_per_page` | An empty value (`?page=`) counts as not sent and uses the default. The `venue_id` filter must be plain digits too, or it answers `400 invalid_venue_id`. ```json { "error": "invalid_per_page", "message": "per_page must be a whole number of 1 or more" } ``` Fix the value instead of retrying. ## Response ```json { "itemsReceived": 20, "curPage": 1, "nextPage": 2, "prevPage": null, "itemsTotal": 57, "pageTotal": 3, "items": [ … ] } ``` | Field | Meaning | |---|---| | `items` | The events on this page. | | `itemsReceived` | Number of events on this page. | | `curPage` | This page number. | | `nextPage` | The next page number, or `null` on the last page. | | `prevPage` | The previous page number, or `null` on the first page. | | `itemsTotal` | Events matching your filters across all pages. | | `pageTotal` | Number of pages. | ## Reading every page Follow `nextPage` until it is `null`: ```js const BASE = 'https://app.bettertickets.com/api/partner/v1'; const headers = { Authorization: `Bearer ${process.env.BETTERTICKETS_API_KEY}` }; async function allEvents(filters = {}) { const events = []; let page = 1; while (page) { const qs = new URLSearchParams({ ...filters, page: String(page), per_page: '100' }); const res = await fetch(`${BASE}/events?${qs}`, { headers }); if (!res.ok) throw new Error(`GET /events failed: ${res.status}`); const body = await res.json(); events.push(...body.items); page = body.nextPage; } return events; } ``` ```python import os, requests BASE = "https://app.bettertickets.com/api/partner/v1" HEADERS = {"Authorization": f"Bearer {os.environ['BETTERTICKETS_API_KEY']}"} def all_events(**filters): events, page = [], 1 while page: r = requests.get(f"{BASE}/events", headers=HEADERS, params={**filters, "page": page, "per_page": 100}, timeout=30) r.raise_for_status() body = r.json() events.extend(body["items"]) page = body["nextPage"] return events ``` Events are sorted by date, earliest first. Results can shift between pages if events change while you page, so treat a full sync as a snapshot and de-duplicate by `id`. --- # Custom Lists Custom Lists are tables of people or records in your BetterTickets account, keyed by one column (for example an email address). The API lets your server look up one row by key and add or update rows in batches of up to 500. New rows are what the list's automations pick up. ## Before you start All three must be in place, or the call answers `403`: | Requirement | Error when missing | |---|---| | Custom Lists enabled on your account | `403 partner_lists_disabled` | | **API Access** turned on in the list's settings | `403 list_api_disabled` | | The key has `lists:read` (lookups) or `lists:write` (upserts) | `403 insufficient_scope` | Ask your BetterTickets contact to enable Custom Lists and to add list scopes to your key. The list id is shown in the list's settings. ## Staging and Production Test keys (`btk_test_…`) read and write the list's **Staging** rows. Live keys (`btk_live_…`) read and write **Production** rows. See [Test vs Live](https://docs.bettertickets.com/test-vs-live.md). ## Looking up a row ```bash curl -G https://app.bettertickets.com/api/partner/v1/lists/4001/rows \ --data-urlencode "key=fan@example.com" \ -H "Authorization: Bearer $BETTERTICKETS_API_KEY" ``` URL-encode `key` (for example with `encodeURIComponent`, `URLSearchParams` or `requests` params). Unencoded, a `+` in an email address arrives as a space and the lookup misses. ```json { "list_id": 4001, "row": { "row_key": "fan@example.com", "added_at": 1795456800000, "updated_at": 1795460400000, "data": { "email": "fan@example.com", "tier": "VIP" } } } ``` Only the columns the list exposes to the API are returned in `data`. `404 row_not_found` is returned when there is no active row with that key. Full reference: [Look up one list row](https://docs.bettertickets.com/reference/lookup-list-row.md). ## Adding or updating rows ```bash curl -X POST https://app.bettertickets.com/api/partner/v1/lists/4001/rows \ -H "Authorization: Bearer $BETTERTICKETS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"rows":[{"email":"fan@example.com","first_name":"Sam","tier":"VIP"}]}' ``` The call is an upsert by the list's key column: - **A new key adds a row**; an existing key updates it. - **An update replaces the row's data.** A column you leave out is stored empty, so send every column each time. - **Cells locked in BetterTickets keep their value.** If the organizer edited and locked a cell, your value for that column is ignored until the lock is cleared. - **Only the list's columns are stored**; other keys are ignored. - **The same key twice in one call:** the later *valid* row wins and the earlier one is counted in `deduplicated`. - **Status column:** if the list has one, a value set as inactive in the list's settings marks the row inactive (it stops driving automations); any other value makes it active again. - **Safe to repeat.** Re-sending the same rows reports them as `unchanged`. Full reference: [Add or update list rows](https://docs.bettertickets.com/reference/upsert-list-rows.md). ## Value cleaning Keys and values are cleaned by column type before they are stored or matched. | Column type | Cleaning | |---|---| | Key (any type) | Trimmed and lower-cased; at most 255 characters after cleaning | | Email | Lower-cased; must be a valid email address | | Phone | Spaces, parentheses, dots and dashes removed; 7–15 digits with an optional leading `+` | | Number | Must be a number | | Date | `2027-01-21`, `1/21/2027` or `Jan 21, 2027` | | Boolean | `true/false`, `yes/no`, `y/n`, `1/0` | | Text | Leading and trailing spaces trimmed; blank counts as empty | Every value is at most 2,000 characters. Required columns must have a value. ## Partial success Bad rows do not fail the call. The response counts them in `rejected` and describes the first 50 in `problems`: ```json { "list_id": 4001, "received": 2, "added": 1, "updated": 0, "unchanged": 0, "rejected": 1, "deduplicated": 0, "problems": [{ "row": 2, "key": "kim@example.com", "reason": "wristband:required" }] } ``` `row` is the 1-based position in your `rows` array, or the row's own integer `source_row` if you send one. `reason` is one of `invalid_row`, `missing_key`, `key_too_long`, `list_full`, or `:` where problem is `required`, `too_long`, `not_a_value`, `invalid_email`, `invalid_phone`, `invalid_number`, `invalid_date` or `invalid_boolean`. Other reasons may be added; treat unknown ones as a rejected row. ## Limits | What | Limit | |---|---| | Rows per `POST` | 500 (`413 too_many_rows` above) | | Cell value | 2,000 characters | | Row key after cleaning | 255 characters | | Rows per list | 50,000 per data set (Staging and Production each); new keys beyond that are rejected as `list_full` | --- # Changelog The API is versioned in the path (`/api/partner/v1`). New operations, optional parameters, response fields and error codes can appear within v1, so build your client to ignore fields and error codes it does not know. ## 2026-11-18 Spec version 1.0.1. Clearer errors and stricter checks; nothing was removed. - **Clear `400` errors for bad paging values on `GET /events`.** A `page`, `per_page` or `venue_id` that is not plain digits now answers `400 invalid_page`, `400 invalid_per_page` or `400 invalid_venue_id` instead of `502 upstream_error`. See [Pagination](https://docs.bettertickets.com/pagination.md). - **`404` instead of `502` for events and ticket types that are not available.** - `GET /events/{id}/locations` answers `404 event_not_found` for an event that does not exist or whose sales have closed. - `GET /locations/{id}/availability` answers `404 location_not_found` for a ticket type that does not exist, is not sold on its own, or whose event's sales have closed. - **Test events are hidden everywhere.** `GET /events/{id}/locations` now answers `404 event_not_found` for a test event, like the other event operations. See [Test vs Live](https://docs.bettertickets.com/test-vs-live.md). - **Stricter ids.** `GET /events/{id}/locations` and `GET /locations/{id}/availability` take plain digits only; values such as `5.0` or `1e1` answer `400 invalid_event_id` or `400 invalid_location_id`. - **`401 invalid_api_key` now always means the key was refused.** When BetterTickets cannot check a key for a moment, the call answers `503 auth_unavailable` with `Retry-After: 5` instead of `401`. Wait `Retry-After` seconds between attempts; retrying faster gets `429 partner_rate_limited`. See [Authentication & Keys](https://docs.bettertickets.com/authentication.md). - **Retry hints on `503` errors.** `auth_unavailable` and most `FEATURE_GATE_UNAVAILABLE` answers carry a `Retry-After` header plus `retryable` and `retry_after_seconds` in the body. On Custom Lists calls, `FEATURE_GATE_UNAVAILABLE` can still arrive as a bare `{ "error": "FEATURE_GATE_UNAVAILABLE" }`; when there is no `Retry-After`, wait 5 seconds. See [Retrying](https://docs.bettertickets.com/errors#retrying). - **Event responses contain only the documented fields.** Every documented field is unchanged. - **Rate limits documented in full.** Requests from one IP address, across all keys, are limited to about 60 `GET` and 30 `POST` per minute, and repeated requests with a missing or invalid key from one IP address get `429 partner_rate_limited` instead of `401`. See [Rate Limits](https://docs.bettertickets.com/rate-limits.md). - **Clearer retry guidance.** `request_refused` is not retryable; contact BetterTickets if it persists. An unexpected `500` is retryable with backoff. See [Retrying](https://docs.bettertickets.com/errors#retrying). - **Known issues resolved.** Every item on the former Known Issues list is fixed, and the list has been removed. ## November 2026 - **Published:** public developer docs at docs.bettertickets.com, with a Markdown twin of every page, [/llms.txt](https://docs.bettertickets.com/llms.txt), [/llms-full.txt](https://docs.bettertickets.com/llms-full.txt) and the [OpenAPI 3.1 spec](https://docs.bettertickets.com/openapi.json). - **v1 operations documented:** - `GET /events` - `GET /events/{id}` - `GET /events/{id}/locations` - `GET /locations/{id}/availability` - `GET /lists/{id}/rows` - `POST /lists/{id}/rows` --- # Events Your account's events and their ticket types. Read-only. ## Operations - [`GET /events` — List events](https://docs.bettertickets.com/reference/list-events.md) (scope `events:read`): Lists your account's events that are active, on sale, not test events, and have a title and start time, sorted by date (earliest first). - [`GET /events/{id}` — Get one event](https://docs.bettertickets.com/reference/get-event.md) (scope `events:read`): One event of your account, by numeric id or concert_sku. - [`GET /events/{id}/locations` — List an event's ticket types](https://docs.bettertickets.com/reference/list-event-locations.md) (scope `events:read`): The active ticket types of one event, in display order, with prices in cents and live availability. --- # List events `GET /events` - **Full URL:** `https://app.bettertickets.com/api/partner/v1/events` - **Scope required:** `events:read` - **Auth:** `Authorization: Bearer ` Lists your account's events that are active, on sale, not test events, and have a title and start time, sorted by date (earliest first). `from_date` / `to_date` filter on the event date only. An event can stay listed for up to about an hour after its sales close, while `GET /events/{id}` already answers `404`; check the detail before selling. ## Request ### Headers | Name | Type | Required | Description | |---|---|---|---| | `Authorization` | string | Yes | Bearer . A `btk_live_…` or `btk_test_…` key. | ### Query parameters | Name | Type | Required | Description | |---|---|---|---| | `page` | integer | No | Page number: a whole number of 1 or more, as plain digits. Anything else answers `400 invalid_page`. An empty value uses the default. (min 1, default 1) Example: `1` | | `per_page` | integer | No | Events per page: a whole number of 1 or more, as plain digits. Anything else answers `400 invalid_per_page`. Use 100 or fewer; larger values may be limited in future. An empty value uses the default. (min 1, default 20) Example: `20` | | `venue_id` | integer | No | Only events at this venue. Plain digits; anything else answers `400 invalid_venue_id`. (min 0) Example: `3001` | | `from_date` | string (date) | No | Only events on or after this date (`YYYY-MM-DD`). Example: `2027-07-01` | | `to_date` | string (date) | No | Only events on or before this date (`YYYY-MM-DD`, whole day included). Example: `2027-07-31` | | `search` | string | No | Text contained in the event name, artist or venue name. Example: `festival` | ## Responses | Status | Meaning | Error codes | |---|---|---| | 200 | A page of events. | — | | 400 | `page`, `per_page` or `venue_id` is not plain digits, is below its minimum, or is sent more than once. Fix the value instead of retrying. | `invalid_page`, `invalid_per_page`, `invalid_venue_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`. | `missing_api_key`, `invalid_api_key` | | 403 | The key lacks the required scope, or API access is off for the account. | `insufficient_scope`, `partner_api_disabled` | | 405 | The HTTP method is not supported on this path. | `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](https://docs.bettertickets.com/rate-limits). | `partner_rate_limited` | | 502 | BetterTickets could not load the data. Retry later. | `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`. | `auth_unavailable`, `FEATURE_GATE_UNAVAILABLE` | ### 200 A page of events. Schema `EventPage`: One page of events. Only the fields below are documented. Responses can contain other fields; they are not part of the API, may change or disappear without notice, and must not be relied on. - `items` (array of EventSummary, required) - `id` (integer, required) — Event id. - `name` (string | null) - `artist` (string | null) — Headliner or display title. Either `name` or `artist` is always set. - `date` (string | null) — Event date, typically `YYYY-MM-DD`. - `absolute_time` (string | null) — Event start time as entered (typically ISO 8601). Always set on listed events. - `doors_time` (string | null) - `concert_sku` (string | null) — The event's reference code. Accepted in place of `id` by `GET /events/{id}`. - `venue_id` (integer | null) — Venue id; use it with the `venue_id` filter. - `venue_string` (string | null) — Venue name as text. - `venue` (Venue | null) - `id` (integer) - `name` (string | null) - `address` (string | null) - `city` (string | null) - `state` (string | null) - `zip_code` (string | null) - `timezone` (string | null) — IANA time zone name, e.g. `America/Chicago`, when set. - `event_image_url` (string | null) - `is_sold_out` (boolean) — The event is marked sold out. - `location_count` (integer) — Number of active ticket types. - `locations` (array of EventSummaryTicketType) - `id` (integer, required) — Ticket type (location) id. - `event_id` (integer) - `name` (string | null) - `itemsReceived` (integer) — Events on this page. - `curPage` (integer) - `nextPage` (integer | null) - `prevPage` (integer | null) - `itemsTotal` (integer) - `pageTotal` (integer) Example `page`: ```json { "itemsReceived": 1, "curPage": 1, "nextPage": null, "prevPage": null, "itemsTotal": 1, "pageTotal": 1, "items": [ { "id": 1001, "name": "Summer Roots Festival 2027", "artist": "Summer Roots Festival 2027", "date": "2027-07-16", "absolute_time": "2027-07-16T16:00:00-05:00", "doors_time": "3:00 PM", "concert_sku": "SRF_07-16-2027", "venue_id": 3001, "venue_string": "Riverside Park Bandshell", "venue": { "id": 3001, "name": "Riverside Park Bandshell", "address": "100 Example Ave", "city": "Springfield", "state": "IL", "zip_code": "62701", "timezone": "America/Chicago" }, "event_image_url": "https://example.com/images/summer-roots.jpg", "is_sold_out": false, "location_count": 2, "locations": [ { "id": 2001, "event_id": 1001, "name": "GA Weekend" }, { "id": 2002, "event_id": 1001, "name": "VIP Weekend" } ] } ] } ``` ### 400 `page`, `per_page` or `venue_id` is not plain digits, is below its minimum, or is sent more than once. Fix the value instead of retrying. Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). Example `invalid_page`: ```json { "error": "invalid_page", "message": "page must be a whole number of 1 or more" } ``` Example `invalid_per_page`: ```json { "error": "invalid_per_page", "message": "per_page must be a whole number of 1 or more" } ``` Example `invalid_venue_id`: ```json { "error": "invalid_venue_id", "message": "venue_id must be a whole number" } ``` ### 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` (see [Errors](https://docs.bettertickets.com/errors.md)). 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` (see [Errors](https://docs.bettertickets.com/errors.md)). Example `insufficient_scope`: ```json { "error": "insufficient_scope", "required": "events:read" } ``` Example `partner_api_disabled`: ```json { "error": "partner_api_disabled" } ``` ### 405 The HTTP method is not supported on this path. Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). 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](https://docs.bettertickets.com/rate-limits). Headers: - `Retry-After` (integer) — Seconds to wait before retrying (at least 1). Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). 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` (see [Errors](https://docs.bettertickets.com/errors.md)). 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: - `Retry-After` (integer) — Seconds to wait before retrying. Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). 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 ```bash curl "https://app.bettertickets.com/api/partner/v1/events?from_date=2027-07-01&to_date=2027-07-31" \ -H "Authorization: Bearer $BETTERTICKETS_API_KEY" ``` ### Node.js ```js async function main() { const res = await fetch('https://app.bettertickets.com/api/partner/v1/events?from_date=2027-07-01&to_date=2027-07-31', { method: 'GET', headers: { Authorization: `Bearer ${process.env.BETTERTICKETS_API_KEY}`, }, }); // Error pages from a proxy may not be JSON, so parse defensively. const text = await res.text(); let data = {}; try { data = text ? JSON.parse(text) : {}; } catch { data = {}; } if (!res.ok) { // Branch on data.error, e.g. "partner_rate_limited" throw new Error(`${res.status} ${data.error || 'unknown'}`); } console.log(data); } main(); ``` ### Python ```python import os import requests res = requests.request( "GET", "https://app.bettertickets.com/api/partner/v1/events", headers={"Authorization": f"Bearer {os.environ['BETTERTICKETS_API_KEY']}"}, params={"from_date": "2027-07-01", "to_date": "2027-07-31"}, timeout=30, ) is_json = res.headers.get("content-type", "").startswith("application/json") data = res.json() if is_json else {} if not res.ok: # Branch on data["error"], e.g. "partner_rate_limited" raise RuntimeError(f"{res.status_code} {data.get('error')}") print(data) ``` ### PHP ```php 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('BETTERTICKETS_API_KEY'), ], ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); $data = json_decode((string) $body, true) ?? []; if ($status >= 400) { // Branch on $data['error'], e.g. "partner_rate_limited" throw new RuntimeException($status . ' ' . ($data['error'] ?? 'unknown')); } print_r($data); ``` --- # Get one event `GET /events/{id}` - **Full URL:** `https://app.bettertickets.com/api/partner/v1/events/{id}` - **Scope required:** `events:read` - **Auth:** `Authorization: Bearer ` One event of your account, by numeric id or `concert_sku`. Answers `404 event_not_found` for events of other accounts, test events, and events whose sales have closed (inactive, off sale, or past their sales cutoff). `locations` lists **every** ticket type of the event, including ones that are switched off. Sell from `GET /events/{id}/locations` instead. ## Request ### Headers | Name | Type | Required | Description | |---|---|---|---| | `Authorization` | string | Yes | Bearer . A `btk_live_…` or `btk_test_…` key. | ### Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | Yes | Numeric event id, or the event's `concert_sku` (2–80 characters, matched case-insensitively). (min length 1, max length 80) Example: `1001` | ## Responses | Status | Meaning | Error codes | |---|---|---| | 200 | The event. | — | | 400 | The reference is neither a number nor a valid `concert_sku` (for example it contains `/`). | `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`. | `missing_api_key`, `invalid_api_key` | | 403 | The key lacks the required scope, or API access is off for the account. | `insufficient_scope`, `partner_api_disabled` | | 404 | No such event on your account, a test event, or an event whose sales have closed. | `event_not_found` | | 405 | The HTTP method is not supported on this path. | `method_not_allowed` | | 409 | The `concert_sku` matches more than one event on your account. Use the numeric id. | `ambiguous_concert_sku` | | 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](https://docs.bettertickets.com/rate-limits). | `partner_rate_limited` | | 502 | BetterTickets could not load the data. Retry later. | `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`. | `auth_unavailable`, `FEATURE_GATE_UNAVAILABLE` | ### 200 The event. Schema `Event`: One event, as returned by `GET /events/{id}`. Only the fields below are documented. Responses can contain other fields; they are not part of the API, may change or disappear without notice, and must not be relied on. - `id` (integer, required) — Event id. - `name` (string | null) - `artist` (string | null) — Headliner or display title. - `date` (string | null) — Event date, typically `YYYY-MM-DD`. - `absolute_time` (string | null) — Event start time as entered (typically ISO 8601). - `doors_time` (string | null) - `concert_sku` (string | null) — The event's reference code. - `venue_id` (integer | null) - `venue_string` (string | null) — Venue name as text. - `venue` (Venue | null) - `id` (integer) - `name` (string | null) - `address` (string | null) - `city` (string | null) - `state` (string | null) - `zip_code` (string | null) - `timezone` (string | null) — IANA time zone name, e.g. `America/Chicago`, when set. - `event_image_url` (string | null) - `is_sold_out` (boolean) — True when the event is marked sold out or every active ticket type is sold out. - `low_ticket_warning` (boolean) — True when any active ticket type is low. - `locations` (array of EventTicketType) — **Every** ticket type of the event, including ones switched off (`is_active: false`) and ones not sold on their own, sorted by name. Sell from `GET /events/{id}/locations`, not from this list. - `id` (integer, required) — Ticket type (location) id. - `event_id` (integer) - `name` (string | null) - `description` (string | null) - `price` (integer) — Price per ticket, in **cents**. - `available_quantity` (integer) — Tickets left; `-1` = unlimited. - `is_sold_out` (boolean) - `low_ticket_warning` (boolean) — True when only a few tickets are left. - `is_active` (boolean | null) — False for a ticket type that is switched off. Example `event`: ```json { "id": 1001, "name": "Summer Roots Festival 2027", "artist": "Summer Roots Festival 2027", "date": "2027-07-16", "absolute_time": "2027-07-16T16:00:00-05:00", "doors_time": "3:00 PM", "concert_sku": "SRF_07-16-2027", "venue_id": 3001, "venue_string": "Riverside Park Bandshell", "venue": { "id": 3001, "name": "Riverside Park Bandshell", "address": "100 Example Ave", "city": "Springfield", "state": "IL", "zip_code": "62701", "timezone": "America/Chicago" }, "event_image_url": "https://example.com/images/summer-roots.jpg", "is_sold_out": false, "low_ticket_warning": false, "locations": [ { "id": 2001, "event_id": 1001, "name": "GA Weekend", "description": "General admission, both days.", "price": 5000, "available_quantity": 1188, "is_sold_out": false, "low_ticket_warning": false, "is_active": true } ] } ``` ### 400 The reference is neither a number nor a valid `concert_sku` (for example it contains `/`). Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). 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` (see [Errors](https://docs.bettertickets.com/errors.md)). 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` (see [Errors](https://docs.bettertickets.com/errors.md)). 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` (see [Errors](https://docs.bettertickets.com/errors.md)). Example `event_not_found`: ```json { "error": "event_not_found" } ``` ### 405 The HTTP method is not supported on this path. Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). Example `method_not_allowed`: ```json { "error": "method_not_allowed" } ``` ### 409 The `concert_sku` matches more than one event on your account. Use the numeric id. Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). Example `ambiguous_concert_sku`: ```json { "error": "ambiguous_concert_sku" } ``` ### 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](https://docs.bettertickets.com/rate-limits). Headers: - `Retry-After` (integer) — Seconds to wait before retrying (at least 1). Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). 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` (see [Errors](https://docs.bettertickets.com/errors.md)). 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: - `Retry-After` (integer) — Seconds to wait before retrying. Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). 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 ```bash curl "https://app.bettertickets.com/api/partner/v1/events/1001" \ -H "Authorization: Bearer $BETTERTICKETS_API_KEY" ``` ### Node.js ```js async function main() { const res = await fetch('https://app.bettertickets.com/api/partner/v1/events/1001', { method: 'GET', headers: { Authorization: `Bearer ${process.env.BETTERTICKETS_API_KEY}`, }, }); // Error pages from a proxy may not be JSON, so parse defensively. const text = await res.text(); let data = {}; try { data = text ? JSON.parse(text) : {}; } catch { data = {}; } if (!res.ok) { // Branch on data.error, e.g. "partner_rate_limited" throw new Error(`${res.status} ${data.error || 'unknown'}`); } console.log(data); } main(); ``` ### Python ```python import os import requests res = requests.request( "GET", "https://app.bettertickets.com/api/partner/v1/events/1001", headers={"Authorization": f"Bearer {os.environ['BETTERTICKETS_API_KEY']}"}, timeout=30, ) is_json = res.headers.get("content-type", "").startswith("application/json") data = res.json() if is_json else {} if not res.ok: # Branch on data["error"], e.g. "partner_rate_limited" raise RuntimeError(f"{res.status_code} {data.get('error')}") print(data) ``` ### PHP ```php 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('BETTERTICKETS_API_KEY'), ], ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); $data = json_decode((string) $body, true) ?? []; if ($status >= 400) { // Branch on $data['error'], e.g. "partner_rate_limited" throw new RuntimeException($status . ' ' . ($data['error'] ?? 'unknown')); } print_r($data); ``` --- # List an event's ticket types `GET /events/{id}/locations` - **Full URL:** `https://app.bettertickets.com/api/partner/v1/events/{id}/locations` - **Scope required:** `events:read` - **Auth:** `Authorization: Bearer ` 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 | Name | Type | Required | Description | |---|---|---|---| | `Authorization` | string | Yes | Bearer . A `btk_live_…` or `btk_test_…` key. | ### Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | integer | Yes | Numeric event id, plain digits only (`concert_sku` is not accepted here). (min 1) Example: `1001` | ## Responses | Status | Meaning | Error codes | |---|---|---| | 200 | Ticket types. | — | | 400 | The id is not plain digits of 1 or more (for example `5.0`, `1e1`, or a `concert_sku`). | `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`. | `missing_api_key`, `invalid_api_key` | | 403 | The key lacks the required scope, or API access is off for the account. | `insufficient_scope`, `partner_api_disabled` | | 404 | No such event on your account, a test event, or an event whose sales have closed. | `event_not_found` | | 405 | The HTTP method is not supported on this path. | `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](https://docs.bettertickets.com/rate-limits). | `partner_rate_limited` | | 502 | BetterTickets could not load the data. Retry later. | `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`. | `auth_unavailable`, `FEATURE_GATE_UNAVAILABLE` | ### 200 Ticket types. Schema `LocationList`: - `items` (array of Location, required) - `id` (integer, required) — Ticket type (location) id. - `event_id` (integer, required) - `name` (string | null) — Display name. - `description` (string | null) - `price` (integer) — Price per ticket, in **cents**. - `available_quantity` (integer | null) — Tickets left after tickets sold; `-1` = unlimited. - `effective_available` (integer | null) — Tickets left after tickets sold **and** checkouts in progress; `-1` = unlimited. The best "tickets left" number. - `is_sold_out` (boolean | null) - `is_effectively_sold_out` (boolean | null) — Sold out once checkouts in progress are counted. - `low_ticket_warning` (boolean | null) — True when only a few tickets are left. - `address` (string | null) — Street address, for ticket types tied to a place (such as a pickup stop). - `city` (string | null) - `state` (string | null) - `zip_code` (string | null) - `image_url` (string | 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` (see [Errors](https://docs.bettertickets.com/errors.md)). 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` (see [Errors](https://docs.bettertickets.com/errors.md)). 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` (see [Errors](https://docs.bettertickets.com/errors.md)). 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` (see [Errors](https://docs.bettertickets.com/errors.md)). Example `event_not_found`: ```json { "error": "event_not_found" } ``` ### 405 The HTTP method is not supported on this path. Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). 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](https://docs.bettertickets.com/rate-limits). Headers: - `Retry-After` (integer) — Seconds to wait before retrying (at least 1). Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). 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` (see [Errors](https://docs.bettertickets.com/errors.md)). 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: - `Retry-After` (integer) — Seconds to wait before retrying. Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). 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 ```bash curl "https://app.bettertickets.com/api/partner/v1/events/1001/locations" \ -H "Authorization: Bearer $BETTERTICKETS_API_KEY" ``` ### Node.js ```js async function main() { const res = await fetch('https://app.bettertickets.com/api/partner/v1/events/1001/locations', { method: 'GET', headers: { Authorization: `Bearer ${process.env.BETTERTICKETS_API_KEY}`, }, }); // Error pages from a proxy may not be JSON, so parse defensively. const text = await res.text(); let data = {}; try { data = text ? JSON.parse(text) : {}; } catch { data = {}; } if (!res.ok) { // Branch on data.error, e.g. "partner_rate_limited" throw new Error(`${res.status} ${data.error || 'unknown'}`); } console.log(data); } main(); ``` ### Python ```python import os import requests res = requests.request( "GET", "https://app.bettertickets.com/api/partner/v1/events/1001/locations", headers={"Authorization": f"Bearer {os.environ['BETTERTICKETS_API_KEY']}"}, timeout=30, ) is_json = res.headers.get("content-type", "").startswith("application/json") data = res.json() if is_json else {} if not res.ok: # Branch on data["error"], e.g. "partner_rate_limited" raise RuntimeError(f"{res.status_code} {data.get('error')}") print(data) ``` ### PHP ```php 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('BETTERTICKETS_API_KEY'), ], ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); $data = json_decode((string) $body, true) ?? []; if ($status >= 400) { // Branch on $data['error'], e.g. "partner_rate_limited" throw new RuntimeException($status . ' ' . ($data['error'] ?? 'unknown')); } print_r($data); ``` --- # Availability Live availability of a ticket type. Read-only; nothing is reserved. ## Operations - [`GET /locations/{id}/availability` — Get live availability of a ticket type](https://docs.bettertickets.com/reference/get-location-availability.md) (scope `events:read`): Tickets left for one ticket type. --- # Get live availability of a ticket type `GET /locations/{id}/availability` - **Full URL:** `https://app.bettertickets.com/api/partner/v1/locations/{id}/availability` - **Scope required:** `events:read` - **Auth:** `Authorization: Bearer ` Tickets left for one ticket type. Read-only: nothing is reserved. ## Request ### Headers | Name | Type | Required | Description | |---|---|---|---| | `Authorization` | string | Yes | Bearer . A `btk_live_…` or `btk_test_…` key. | ### Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | integer | Yes | Ticket type (location) id, plain digits only. (min 1) Example: `2001` | ### Query parameters | Name | Type | Required | Description | |---|---|---|---| | `requested_quantity` | integer | No | Quantity to test `can_fulfill` against. Send a whole number as plain digits. Defaults to 1; a value that cannot be read as a positive whole number is ignored and the default applies. Other numeric forms, such as `2.0` or `1e1`, may be read as numbers. (min 1, default 1) Example: `2` | ## Responses | Status | Meaning | Error codes | |---|---|---| | 200 | Availability. | — | | 400 | The id is not plain digits of 1 or more (for example `5.0` or `1e1`). | `invalid_location_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`. | `missing_api_key`, `invalid_api_key` | | 403 | The key lacks the required scope, or API access is off for the account. | `insufficient_scope`, `partner_api_disabled` | | 404 | No such ticket type on your account, a ticket type that is not sold on its own, one of a test event, or one whose event's sales have closed. | `location_not_found` | | 405 | The HTTP method is not supported on this path. | `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](https://docs.bettertickets.com/rate-limits). | `partner_rate_limited` | | 502 | BetterTickets could not load the data. Retry later. | `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`. | `auth_unavailable`, `FEATURE_GATE_UNAVAILABLE` | ### 200 Availability. Schema `Availability`: Live availability of one ticket type. `-1` in a quantity field means unlimited. Only the fields below are documented. Responses can contain other fields; they are not part of the API, may change or disappear without notice, and must not be relied on. - `location_id` (integer, required) - `event_id` (integer | null, required) - `effective_available` (integer | null, required) — Tickets left after tickets sold **and** checkouts in progress. `-1` = unlimited. Use this to show "tickets left". - `available_quantity` (integer | null, required) — Tickets left after tickets sold only. `-1` = unlimited. - `can_fulfill` (boolean | null, required) — False when `available_quantity` is below `requested_quantity`, or the ticket type is not for sale. It does **not** count checkouts in progress; compare `effective_available` with your quantity for the stricter answer. Example `limited`: ```json { "location_id": 2001, "event_id": 1001, "effective_available": 1184, "available_quantity": 1188, "can_fulfill": true } ``` Example `unlimited`: ```json { "location_id": 2002, "event_id": 1001, "effective_available": -1, "available_quantity": -1, "can_fulfill": true } ``` ### 400 The id is not plain digits of 1 or more (for example `5.0` or `1e1`). Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). Example `invalid_location_id`: ```json { "error": "invalid_location_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` (see [Errors](https://docs.bettertickets.com/errors.md)). 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` (see [Errors](https://docs.bettertickets.com/errors.md)). Example `insufficient_scope`: ```json { "error": "insufficient_scope", "required": "events:read" } ``` Example `partner_api_disabled`: ```json { "error": "partner_api_disabled" } ``` ### 404 No such ticket type on your account, a ticket type that is not sold on its own, one of a test event, or one whose event's sales have closed. Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). Example `location_not_found`: ```json { "error": "location_not_found" } ``` ### 405 The HTTP method is not supported on this path. Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). 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](https://docs.bettertickets.com/rate-limits). Headers: - `Retry-After` (integer) — Seconds to wait before retrying (at least 1). Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). 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` (see [Errors](https://docs.bettertickets.com/errors.md)). 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: - `Retry-After` (integer) — Seconds to wait before retrying. Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). 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 ```bash curl "https://app.bettertickets.com/api/partner/v1/locations/2001/availability?requested_quantity=2" \ -H "Authorization: Bearer $BETTERTICKETS_API_KEY" ``` ### Node.js ```js async function main() { const res = await fetch('https://app.bettertickets.com/api/partner/v1/locations/2001/availability?requested_quantity=2', { method: 'GET', headers: { Authorization: `Bearer ${process.env.BETTERTICKETS_API_KEY}`, }, }); // Error pages from a proxy may not be JSON, so parse defensively. const text = await res.text(); let data = {}; try { data = text ? JSON.parse(text) : {}; } catch { data = {}; } if (!res.ok) { // Branch on data.error, e.g. "partner_rate_limited" throw new Error(`${res.status} ${data.error || 'unknown'}`); } console.log(data); } main(); ``` ### Python ```python import os import requests res = requests.request( "GET", "https://app.bettertickets.com/api/partner/v1/locations/2001/availability", headers={"Authorization": f"Bearer {os.environ['BETTERTICKETS_API_KEY']}"}, params={"requested_quantity": 2}, timeout=30, ) is_json = res.headers.get("content-type", "").startswith("application/json") data = res.json() if is_json else {} if not res.ok: # Branch on data["error"], e.g. "partner_rate_limited" raise RuntimeError(f"{res.status_code} {data.get('error')}") print(data) ``` ### PHP ```php 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('BETTERTICKETS_API_KEY'), ], ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); $data = json_decode((string) $body, true) ?? []; if ($status >= 400) { // Branch on $data['error'], e.g. "partner_rate_limited" throw new RuntimeException($status . ' ' . ($data['error'] ?? 'unknown')); } print_r($data); ``` --- # Custom Lists Read and add or update rows of your Custom Lists. Needs Custom Lists on your account and API Access on the list. ## Operations - [`GET /lists/{id}/rows` — Look up one list row by key](https://docs.bettertickets.com/reference/lookup-list-row.md) (scope `lists:read`): Finds the row whose key column equals key. - [`POST /lists/{id}/rows` — Add or update list rows](https://docs.bettertickets.com/reference/upsert-list-rows.md) (scope `lists:write`): Adds or updates 1–500 rows by the list's key column. --- # Look up one list row by key `GET /lists/{id}/rows` - **Full URL:** `https://app.bettertickets.com/api/partner/v1/lists/{id}/rows` - **Scope required:** `lists:read` - **Auth:** `Authorization: Bearer ` Finds the row whose key column equals `key`. Returns only the columns the list exposes to the API. Test keys read the list's **Staging** rows, live keys **Production** rows. `404 row_not_found` also when the row was removed or is inactive, and for Production reads while the list's Production switch is off. **Key cleaning.** `key` is cleaned the same way imported keys are, by the key column's type: | Key column type | Cleaning | |---|---| | Any | Trimmed and lower-cased | | Email | Must be a valid email address | | Phone | Spaces, parentheses, dots and dashes removed; 7–15 digits with an optional leading `+` must remain (`(555) 010-1234` finds `5550101234`) | | Date | `2027-01-21`, `1/21/2027` or `Jan 21, 2027` | A missing or blank key, or one over 2,000 characters, gets `400 invalid_key` "Pass ?key=…". A key that does not fit the column type, or is over 255 characters after cleaning, gets `400 invalid_key` "The key does not match the type of the list key column." ## Request ### Headers | Name | Type | Required | Description | |---|---|---|---| | `Authorization` | string | Yes | Bearer . A `btk_live_…` or `btk_test_…` key. | ### Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | integer | Yes | Custom List id (shown in the list's settings). Send plain digits. Other numeric forms, such as `1e1` or `0x10`, may be read as a different list id, so build the path only from the id as shown. (min 1) Example: `4001` | ### Query parameters | Name | Type | Required | Description | |---|---|---|---| | `key` | string | Yes | Value of the list's key column. URL-encode it (for example with `encodeURIComponent`, `URLSearchParams` or `requests` params), so `+` and `@` arrive intact. Cleaned before matching (see the operation description). (min length 1, max length 2000) Example: `fan@example.com` | ## Responses | Status | Meaning | Error codes | |---|---|---| | 200 | The row. | — | | 400 | Bad list id or key. | `invalid_list_id`, `invalid_key` | | 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`. | `missing_api_key`, `invalid_api_key` | | 403 | The key lacks the required scope, API access or Custom Lists is off for the account, or API Access is off for this list. | `insufficient_scope`, `partner_api_disabled`, `partner_lists_disabled`, `list_api_disabled` | | 404 | No such list on your account (or it is archived), or no active row with that key. | `list_not_found`, `row_not_found` | | 405 | The HTTP method is not supported on this path. | `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](https://docs.bettertickets.com/rate-limits). | `partner_rate_limited` | | 502 | `upstream_error`: BetterTickets could not complete the call; retry with backoff and a small cap on attempts. `request_refused`: the call was refused for an unlisted reason; do not retry the same request, and contact BetterTickets if it persists. `request_refused` can also arrive with a 4xx status; branch on `error`, not only on the status. | `upstream_error`, `request_refused` | | 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`. On Custom Lists calls, `FEATURE_GATE_UNAVAILABLE` can also arrive as a bare `{ "error": "FEATURE_GATE_UNAVAILABLE" }` with no `Retry-After`, `retryable` or `retry_after_seconds`; wait 5 seconds before retrying. | `auth_unavailable`, `FEATURE_GATE_UNAVAILABLE` | ### 200 The row. Schema `ListRowLookupResponse`: - `list_id` (integer, required) - `row` (object, required) - `row_key` (string, required) — The cleaned key (trimmed, lower-cased). - `added_at` (integer (int64), required) — When the row first arrived, epoch milliseconds. Never reset by later writes. - `updated_at` (integer (int64), required) — Last change, epoch milliseconds. - `data` (object, required) — Only the columns the list exposes to the API (chosen in the list's settings). Example `row`: ```json { "list_id": 4001, "row": { "row_key": "fan@example.com", "added_at": 1795456800000, "updated_at": 1795460400000, "data": { "email": "fan@example.com", "tier": "VIP" } } } ``` ### 400 Bad list id or key. Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). Example `invalid_list_id`: ```json { "error": "invalid_list_id" } ``` Example `missing_key` (No key, a blank key, or a key over 2,000 characters.): ```json { "error": "invalid_key", "message": "Pass ?key=." } ``` Example `invalid_key` (The key does not fit the key column type, or is over 255 characters after cleaning.): ```json { "error": "invalid_key", "message": "The key does not match the type of the list key column." } ``` ### 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` (see [Errors](https://docs.bettertickets.com/errors.md)). 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, API access or Custom Lists is off for the account, or API Access is off for this list. Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). Example `insufficient_scope`: ```json { "error": "insufficient_scope", "required": "lists:read" } ``` Example `partner_api_disabled`: ```json { "error": "partner_api_disabled" } ``` Example `partner_lists_disabled`: ```json { "error": "partner_lists_disabled", "message": "Custom Lists is not enabled for this account." } ``` Example `list_api_disabled`: ```json { "error": "list_api_disabled", "message": "API access is turned off for this list. Turn it on in the list settings." } ``` ### 404 No such list on your account (or it is archived), or no active row with that key. Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). Example `list_not_found`: ```json { "error": "list_not_found" } ``` Example `row_not_found`: ```json { "error": "row_not_found" } ``` ### 405 The HTTP method is not supported on this path. Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). 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](https://docs.bettertickets.com/rate-limits). Headers: - `Retry-After` (integer) — Seconds to wait before retrying (at least 1). Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). 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 `upstream_error`: BetterTickets could not complete the call; retry with backoff and a small cap on attempts. `request_refused`: the call was refused for an unlisted reason; do not retry the same request, and contact BetterTickets if it persists. `request_refused` can also arrive with a 4xx status; branch on `error`, not only on the status. Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). Example `upstream_error`: ```json { "error": "upstream_error" } ``` Example `request_refused`: ```json { "error": "request_refused" } ``` ### 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`. On Custom Lists calls, `FEATURE_GATE_UNAVAILABLE` can also arrive as a bare `{ "error": "FEATURE_GATE_UNAVAILABLE" }` with no `Retry-After`, `retryable` or `retry_after_seconds`; wait 5 seconds before retrying. Headers: - `Retry-After` (integer) — Seconds to wait before retrying. Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). 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 } ``` Example `FEATURE_GATE_UNAVAILABLE_bare`: ```json { "error": "FEATURE_GATE_UNAVAILABLE" } ``` ## Code samples Set `BETTERTICKETS_API_KEY` on your server. Never send a key from a browser. ### cURL ```bash curl "https://app.bettertickets.com/api/partner/v1/lists/4001/rows?key=fan%40example.com" \ -H "Authorization: Bearer $BETTERTICKETS_API_KEY" ``` ### Node.js ```js async function main() { const res = await fetch('https://app.bettertickets.com/api/partner/v1/lists/4001/rows?key=fan%40example.com', { method: 'GET', headers: { Authorization: `Bearer ${process.env.BETTERTICKETS_API_KEY}`, }, }); // Error pages from a proxy may not be JSON, so parse defensively. const text = await res.text(); let data = {}; try { data = text ? JSON.parse(text) : {}; } catch { data = {}; } if (!res.ok) { // Branch on data.error, e.g. "partner_rate_limited" throw new Error(`${res.status} ${data.error || 'unknown'}`); } console.log(data); } main(); ``` ### Python ```python import os import requests res = requests.request( "GET", "https://app.bettertickets.com/api/partner/v1/lists/4001/rows", headers={"Authorization": f"Bearer {os.environ['BETTERTICKETS_API_KEY']}"}, params={"key": "fan@example.com"}, timeout=30, ) is_json = res.headers.get("content-type", "").startswith("application/json") data = res.json() if is_json else {} if not res.ok: # Branch on data["error"], e.g. "partner_rate_limited" raise RuntimeError(f"{res.status_code} {data.get('error')}") print(data) ``` ### PHP ```php 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('BETTERTICKETS_API_KEY'), ], ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); $data = json_decode((string) $body, true) ?? []; if ($status >= 400) { // Branch on $data['error'], e.g. "partner_rate_limited" throw new RuntimeException($status . ' ' . ($data['error'] ?? 'unknown')); } print_r($data); ``` --- # Add or update list rows `POST /lists/{id}/rows` - **Full URL:** `https://app.bettertickets.com/api/partner/v1/lists/{id}/rows` - **Scope required:** `lists:write` - **Auth:** `Authorization: Bearer ` Adds or updates 1–500 rows by the list's key column. Test keys write the list's **Staging** rows, live keys **Production** rows. New rows are what the list's automations pick up. **Row rules:** - Every row needs the key column. The key is trimmed and lower-cased; at most 255 characters after cleaning. - Only the list's columns are stored; other keys are ignored, except two reserved keys: if a row has a `data` key holding an object, the row's values are read from that object and its other top-level keys are dropped; an integer `source_row` replaces the row's position in `problems[].row`. - **An update replaces the row's data**: a column you leave out is stored empty. Send every column each time. - Cells the organizer edited and locked in BetterTickets keep their value; your value for that column is ignored until the lock is cleared. - Values are cleaned by column type: email (lower-cased, must be valid), phone (7–15 digits, optional leading `+`), number, date (`2027-01-21`, `1/21/2027`, `Jan 21, 2027`), boolean (`true/false`, `yes/no`, `y/n`, `1/0`), text. Each value at most 2,000 characters. Required columns must have a value. - The same key twice in one call: the later **valid** row wins (`deduplicated`); a later row that is rejected does not replace an earlier valid one. - If the list has a status column, a value set as inactive in the list's settings marks the row inactive (it stops driving automations); any other value makes it active again. - A list holds at most 50,000 rows per data set (Staging and Production each); new keys beyond that are rejected as `list_full`. Bad rows do not fail the call: they are counted in `rejected` and described (first 50) in `problems`. Safe to repeat. ## Request ### Headers | Name | Type | Required | Description | |---|---|---|---| | `Authorization` | string | Yes | Bearer . A `btk_live_…` or `btk_test_…` key. | | `Content-Type` | string | Yes | `application/json` | ### Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | integer | Yes | Custom List id (shown in the list's settings). Send plain digits. Other numeric forms, such as `1e1` or `0x10`, may be read as a different list id, so build the path only from the id as shown. (min 1) Example: `4001` | ## Request body `application/json`, required. Only `rows` is read; other top-level keys are ignored. - `rows` (array of object, required, min items 1, max items 500) — 1–500 rows. Each row is an object of column key → value and must contain the list's key column. Reserved keys: `data` (an object; when present, the values are read from it and the other top-level keys are dropped) and `source_row` (an integer that replaces the row's position in `problems[].row`). String values can be up to 2,000 characters; a longer value does not fail the request, and that row is rejected in `problems` as `:too_long`. - `data` (object) — Optional. Column key → value. When present, values are read from here and the other top-level keys are dropped. Values inside must be strings, numbers, booleans or null. - `source_row` (integer) — Optional. Replaces the row's position in `problems[].row`. Example: ```json { "rows": [ { "email": "fan@example.com", "first_name": "Sam", "last_name": "Rivera", "tier": "VIP", "wristband": "W-1042" }, { "email": "kim@example.com", "first_name": "Kim", "last_name": "Lee", "tier": "GA", "wristband": "" } ] } ``` ## Responses | Status | Meaning | Error codes | |---|---|---| | 200 | Rows processed (some may be rejected; check `rejected` and `problems`). | — | | 400 | Bad list id, or `rows` missing or empty. A bad key inside a row is not a 400: it is reported in the 200 (`rejected`, `problems`). | `invalid_list_id`, `rows_required` | | 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`. | `missing_api_key`, `invalid_api_key` | | 403 | The key lacks the required scope, API access or Custom Lists is off for the account, or API Access is off for this list. | `insufficient_scope`, `partner_api_disabled`, `partner_lists_disabled`, `list_api_disabled` | | 404 | No such list on your account (or it is archived). | `list_not_found` | | 405 | The HTTP method is not supported on this path. | `method_not_allowed` | | 409 | The list has no valid columns yet. | `list_not_ready` | | 413 | More than 500 rows. | `too_many_rows` | | 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](https://docs.bettertickets.com/rate-limits). | `partner_rate_limited` | | 502 | `upstream_error`: BetterTickets could not complete the call; retry with backoff and a small cap on attempts. `request_refused`: the call was refused for an unlisted reason; do not retry the same request, and contact BetterTickets if it persists. `request_refused` can also arrive with a 4xx status; branch on `error`, not only on the status. | `upstream_error`, `request_refused` | | 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`. On Custom Lists calls, `FEATURE_GATE_UNAVAILABLE` can also arrive as a bare `{ "error": "FEATURE_GATE_UNAVAILABLE" }` with no `Retry-After`, `retryable` or `retry_after_seconds`; wait 5 seconds before retrying. | `auth_unavailable`, `FEATURE_GATE_UNAVAILABLE` | ### 200 Rows processed (some may be rejected; check `rejected` and `problems`). Schema `ListRowsUpsertResponse`: - `list_id` (integer, required) - `received` (integer, required) — Rows in your request. - `added` (integer, required) — New keys. - `updated` (integer, required) — Existing keys whose data (or status) changed. - `unchanged` (integer, required) — Existing keys sent with identical data. - `rejected` (integer, required) — Rows not written. Details (first 50) in `problems`. - `deduplicated` (integer, required) — Valid rows dropped because a later valid row in the same request had the same key (the later one wins). A rejected row never replaces an earlier valid one. - `problems` (array of ListRowProblem, required, max items 50) - `row` (integer, required) — 1-based position in your `rows`, or the row's own integer `source_row` when it sends one. - `key` (string | null, required) — The cleaned row key, when it could be read. - `reason` (string, required) Example `result`: ```json { "list_id": 4001, "received": 2, "added": 1, "updated": 0, "unchanged": 0, "rejected": 1, "deduplicated": 0, "problems": [ { "row": 2, "key": "kim@example.com", "reason": "wristband:required" } ] } ``` ### 400 Bad list id, or `rows` missing or empty. A bad key inside a row is not a 400: it is reported in the 200 (`rejected`, `problems`). Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). Example `invalid_list_id`: ```json { "error": "invalid_list_id" } ``` Example `rows_required`: ```json { "error": "rows_required", "message": "Send {\"rows\": [...]} with 1-500 rows." } ``` ### 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` (see [Errors](https://docs.bettertickets.com/errors.md)). 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, API access or Custom Lists is off for the account, or API Access is off for this list. Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). Example `insufficient_scope`: ```json { "error": "insufficient_scope", "required": "lists:write" } ``` Example `partner_api_disabled`: ```json { "error": "partner_api_disabled" } ``` Example `partner_lists_disabled`: ```json { "error": "partner_lists_disabled", "message": "Custom Lists is not enabled for this account." } ``` Example `list_api_disabled`: ```json { "error": "list_api_disabled", "message": "API access is turned off for this list. Turn it on in the list settings." } ``` ### 404 No such list on your account (or it is archived). Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). Example `list_not_found`: ```json { "error": "list_not_found" } ``` ### 405 The HTTP method is not supported on this path. Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). Example `method_not_allowed`: ```json { "error": "method_not_allowed" } ``` ### 409 The list has no valid columns yet. Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). Example `list_not_ready`: ```json { "error": "list_not_ready", "message": "This list has no valid columns yet." } ``` ### 413 More than 500 rows. Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). Example `too_many_rows`: ```json { "error": "too_many_rows", "message": "Send at most 500 rows per call.", "max_rows": 500 } ``` ### 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](https://docs.bettertickets.com/rate-limits). Headers: - `Retry-After` (integer) — Seconds to wait before retrying (at least 1). Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). 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 `upstream_error`: BetterTickets could not complete the call; retry with backoff and a small cap on attempts. `request_refused`: the call was refused for an unlisted reason; do not retry the same request, and contact BetterTickets if it persists. `request_refused` can also arrive with a 4xx status; branch on `error`, not only on the status. Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). Example `upstream_error`: ```json { "error": "upstream_error" } ``` Example `request_refused`: ```json { "error": "request_refused" } ``` ### 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`. On Custom Lists calls, `FEATURE_GATE_UNAVAILABLE` can also arrive as a bare `{ "error": "FEATURE_GATE_UNAVAILABLE" }` with no `Retry-After`, `retryable` or `retry_after_seconds`; wait 5 seconds before retrying. Headers: - `Retry-After` (integer) — Seconds to wait before retrying. Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)). 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 } ``` Example `FEATURE_GATE_UNAVAILABLE_bare`: ```json { "error": "FEATURE_GATE_UNAVAILABLE" } ``` ## Code samples Set `BETTERTICKETS_API_KEY` on your server. Never send a key from a browser. ### cURL ```bash curl -X POST "https://app.bettertickets.com/api/partner/v1/lists/4001/rows" \ -H "Authorization: Bearer $BETTERTICKETS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"rows":[{"email":"fan@example.com","first_name":"Sam","last_name":"Rivera","tier":"VIP","wristband":"W-1042"},{"email":"kim@example.com","first_name":"Kim","last_name":"Lee","tier":"GA","wristband":""}]}' ``` ### Node.js ```js async function main() { const res = await fetch('https://app.bettertickets.com/api/partner/v1/lists/4001/rows', { method: 'POST', headers: { Authorization: `Bearer ${process.env.BETTERTICKETS_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "rows": [ { "email": "fan@example.com", "first_name": "Sam", "last_name": "Rivera", "tier": "VIP", "wristband": "W-1042" }, { "email": "kim@example.com", "first_name": "Kim", "last_name": "Lee", "tier": "GA", "wristband": "" } ] }), }); // Error pages from a proxy may not be JSON, so parse defensively. const text = await res.text(); let data = {}; try { data = text ? JSON.parse(text) : {}; } catch { data = {}; } if (!res.ok) { // Branch on data.error, e.g. "partner_rate_limited" throw new Error(`${res.status} ${data.error || 'unknown'}`); } console.log(data); } main(); ``` ### Python ```python import os import requests res = requests.request( "POST", "https://app.bettertickets.com/api/partner/v1/lists/4001/rows", headers={"Authorization": f"Bearer {os.environ['BETTERTICKETS_API_KEY']}"}, json={ "rows": [ { "email": "fan@example.com", "first_name": "Sam", "last_name": "Rivera", "tier": "VIP", "wristband": "W-1042" }, { "email": "kim@example.com", "first_name": "Kim", "last_name": "Lee", "tier": "GA", "wristband": "" } ] }, timeout=30, ) is_json = res.headers.get("content-type", "").startswith("application/json") data = res.json() if is_json else {} if not res.ok: # Branch on data["error"], e.g. "partner_rate_limited" raise RuntimeError(f"{res.status_code} {data.get('error')}") print(data) ``` ### PHP ```php 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('BETTERTICKETS_API_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'rows' => [ [ 'email' => 'fan@example.com', 'first_name' => 'Sam', 'last_name' => 'Rivera', 'tier' => 'VIP', 'wristband' => 'W-1042', ], [ 'email' => 'kim@example.com', 'first_name' => 'Kim', 'last_name' => 'Lee', 'tier' => 'GA', 'wristband' => '', ], ], ]), ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); $data = json_decode((string) $body, true) ?? []; if ($status >= 400) { // Branch on $data['error'], e.g. "partner_rate_limited" throw new RuntimeException($status . ' ' . ($data['error'] ?? 'unknown')); } print_r($data); ```