# 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": "<code>", "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).
