{
  "openapi": "3.1.0",
  "info": {
    "title": "BetterTickets API",
    "version": "1.0.1",
    "description": "Read your BetterTickets events, ticket types and live availability, and read and update rows of your Custom Lists, from your own server.\n\n- **Base URL:** `https://app.bettertickets.com/api/partner/v1` (the same for test and live keys).\n- **Auth:** `Authorization: Bearer <key>` with a `btk_live_` or `btk_test_` key.\n- **Format:** JSON in and out. Responses to supported methods carry `Cache-Control: no-store`; do not cache any response.\n- **Server-to-server only.** The API does not allow browser (CORS) requests. Never put a key in a web page or mobile app.\n\n**Typical flow:** `GET /events` → `GET /events/{id}/locations` (pick a ticket type) → `GET /locations/{id}/availability` before you sell.\n\n## Authentication\n\nAsk your BetterTickets contact for an API key. Send it as a Bearer token:\n\n```\nAuthorization: Bearer btk_live_…\n```\n\n- Keys start with `btk_live_` (live) or `btk_test_` (test). Anything else is refused.\n- A key belongs to one BetterTickets account and only ever sees that account's data.\n- The full key is shown once, when it is issued. Keep it in a secret store and never commit it.\n- `401 invalid_api_key` always means the key was checked and refused. If BetterTickets cannot check a key for a moment, the call answers `503 auth_unavailable` with `Retry-After` instead.\n\n## Scopes\n\nEach operation lists the scope it needs in `x-required-scope`. A key without it gets `403 insufficient_scope`, with `required` naming the scope.\n\n| Scope | Allows |\n|---|---|\n| `events:read` | `GET /events`, `GET /events/{id}`, `GET /events/{id}/locations`, `GET /locations/{id}/availability`. Every key has it. |\n| `lists:read` | `GET /lists/{id}/rows` |\n| `lists:write` | `POST /lists/{id}/rows` |\n\nList scopes are added to a key on request; ask your BetterTickets contact.\n\n## Account Access\n\n- API access must be turned on for your account; otherwise every call answers `403 partner_api_disabled`.\n- 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`).\n- 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.\n\n## Rate Limits\n\nBy default a key can make about **20 GET** and **10 POST** requests per minute. All requests from one IP address, across all keys, are also limited to about **60 GET** and **30 POST** per minute.\n\nOver a limit you get `429 partner_rate_limited` with a `Retry-After` header (seconds) and the same value in `retry_after_seconds`. Repeated requests with a missing or invalid key from one IP address are also answered `429 partner_rate_limited` instead of `401`. Treat the limits as a ceiling, not a guaranteed quota, and ask your BetterTickets contact if you need more. While the key check is unavailable (`503 auth_unavailable`), wait `Retry-After` seconds between attempts; retrying faster gets `429 partner_rate_limited`.\n\n## Test Mode\n\n- `btk_test_` keys see the same live events, ticket types and availability as live keys. Test events are not returned by any operation: `GET /events` leaves them out, `GET /events/{id}` and `GET /events/{id}/locations` answer `404 event_not_found`, and `GET /locations/{id}/availability` answers `404 location_not_found`.\n- Custom List reads and writes with a test key use the list's **Staging** rows; live keys use **Production** rows.\n\n## Limits\n\n| What | Limit |\n|---|---|\n| Rows per `POST /lists/{id}/rows` | 500 (`413 too_many_rows` above) |\n| List cell value | 2,000 characters |\n| List row key (after cleaning) | 255 characters |\n| Rows per list | 50,000 per data set (Staging and Production each); new keys beyond that are rejected as `list_full` |\n\n## Timestamps\n\n| Field | Format |\n|---|---|\n| List row `added_at`, `updated_at` | Epoch milliseconds (integer) |\n| Event `date`, `absolute_time`, `doors_time` | Text as entered for the event; the format is not normalized |\n\n## Errors\n\nEvery error has the same JSON shape:\n\n```json\n{ \"error\": \"list_api_disabled\", \"message\": \"API access is turned off for this list. Turn it on in the list settings.\" }\n```\n\n| Field | Meaning |\n|---|---|\n| `error` | Stable machine code. Branch on this. |\n| `message` | Human text. May change; not always present. |\n| other fields | Some errors add fields; see the `Error` schema. |\n\n**Retrying:**\n\n| `error` | Retry? | How |\n|---|---|---|\n| `partner_rate_limited` (429) | Yes | Wait `Retry-After` seconds, then retry one request at a time. |\n| `auth_unavailable` (503) | Yes | Wait `Retry-After` seconds (5) between attempts; retrying faster gets `429 partner_rate_limited`. |\n| `FEATURE_GATE_UNAVAILABLE` (503) | Yes | Wait `Retry-After` seconds; 5 if the header is missing. |\n| `upstream_error` (502) | Yes | Exponential backoff with jitter and a small cap on attempts. |\n| Any `500` | Yes | An unexpected error; the body may not follow the error shape. Exponential backoff with a small cap on attempts. |\n| `request_refused` (502 or 4xx) | No | Do not retry the same request; contact BetterTickets if it persists. |\n| Any other 4xx | No | Fix the request, the key or the account settings first. |\n\nAn authenticated call with an unsupported HTTP method returns `405 method_not_allowed`.\n"
  },
  "servers": [
    {
      "url": "https://app.bettertickets.com/api/partner/v1",
      "description": "Production. Test keys (`btk_test_…`) use this same URL."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Events",
      "description": "Your account's events and their ticket types. Read-only."
    },
    {
      "name": "Availability",
      "description": "Live availability of a ticket type. Read-only; nothing is reserved."
    },
    {
      "name": "Custom Lists",
      "description": "Read and add or update rows of your Custom Lists. Needs Custom Lists on your account and API Access on the list."
    }
  ],
  "paths": {
    "/events": {
      "get": {
        "operationId": "listEvents",
        "tags": [
          "Events"
        ],
        "summary": "List events",
        "description": "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).\n\n`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.",
        "x-required-scope": "events:read",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "description": "Page number: a whole number of 1 or more, as plain digits. Anything else answers `400 invalid_page`. An empty value uses the default.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "description": "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.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 20
            }
          },
          {
            "name": "venue_id",
            "in": "query",
            "description": "Only events at this venue. Plain digits; anything else answers `400 invalid_venue_id`.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "example": 3001
            }
          },
          {
            "name": "from_date",
            "in": "query",
            "description": "Only events on or after this date (`YYYY-MM-DD`).",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2027-07-01"
          },
          {
            "name": "to_date",
            "in": "query",
            "description": "Only events on or before this date (`YYYY-MM-DD`, whole day included).",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2027-07-31"
          },
          {
            "name": "search",
            "in": "query",
            "description": "Text contained in the event name, artist or venue name.",
            "schema": {
              "type": "string",
              "example": "festival"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of events.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventPage"
                },
                "examples": {
                  "page": {
                    "value": {
                      "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": {
            "description": "`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.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_page": {
                    "value": {
                      "error": "invalid_page",
                      "message": "page must be a whole number of 1 or more"
                    }
                  },
                  "invalid_per_page": {
                    "value": {
                      "error": "invalid_per_page",
                      "message": "per_page must be a whole number of 1 or more"
                    }
                  },
                  "invalid_venue_id": {
                    "value": {
                      "error": "invalid_venue_id",
                      "message": "venue_id must be a whole number"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The key lacks the required scope, or API access is off for the account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_scope": {
                    "value": {
                      "error": "insufficient_scope",
                      "required": "events:read"
                    }
                  },
                  "partner_api_disabled": {
                    "value": {
                      "error": "partner_api_disabled"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "description": "BetterTickets could not load the data. Retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "upstream_error": {
                    "value": {
                      "error": "upstream_error"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/events/{id}": {
      "get": {
        "operationId": "getEvent",
        "tags": [
          "Events"
        ],
        "summary": "Get one event",
        "description": "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).\n\n`locations` lists **every** ticket type of the event, including ones that are switched off. Sell from `GET /events/{id}/locations` instead.",
        "x-required-scope": "events:read",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventRef"
          }
        ],
        "responses": {
          "200": {
            "description": "The event.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Event"
                },
                "examples": {
                  "event": {
                    "value": {
                      "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": {
            "description": "The reference is neither a number nor a valid `concert_sku` (for example it contains `/`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_event_id": {
                    "value": {
                      "error": "invalid_event_id"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The key lacks the required scope, or API access is off for the account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_scope": {
                    "value": {
                      "error": "insufficient_scope",
                      "required": "events:read"
                    }
                  },
                  "partner_api_disabled": {
                    "value": {
                      "error": "partner_api_disabled"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such event on your account, a test event, or an event whose sales have closed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "event_not_found": {
                    "value": {
                      "error": "event_not_found"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "409": {
            "description": "The `concert_sku` matches more than one event on your account. Use the numeric id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "ambiguous_concert_sku": {
                    "value": {
                      "error": "ambiguous_concert_sku"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "description": "BetterTickets could not load the data. Retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "upstream_error": {
                    "value": {
                      "error": "upstream_error"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/events/{id}/locations": {
      "get": {
        "operationId": "listEventLocations",
        "tags": [
          "Events"
        ],
        "summary": "List an event's ticket types",
        "description": "The active ticket types of one event, in display order, with prices in cents and live availability. Only numeric event ids are accepted.\n\nA ticket type can be listed here and still not be for sale; check `can_fulfill` on `GET /locations/{id}/availability` before selling.",
        "x-required-scope": "events:read",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventId"
          }
        ],
        "responses": {
          "200": {
            "description": "Ticket types.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LocationList"
                },
                "examples": {
                  "locations": {
                    "value": {
                      "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": {
            "description": "The id is not plain digits of 1 or more (for example `5.0`, `1e1`, or a `concert_sku`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_event_id": {
                    "value": {
                      "error": "invalid_event_id"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The key lacks the required scope, or API access is off for the account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_scope": {
                    "value": {
                      "error": "insufficient_scope",
                      "required": "events:read"
                    }
                  },
                  "partner_api_disabled": {
                    "value": {
                      "error": "partner_api_disabled"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such event on your account, a test event, or an event whose sales have closed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "event_not_found": {
                    "value": {
                      "error": "event_not_found"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "description": "BetterTickets could not load the data. Retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "upstream_error": {
                    "value": {
                      "error": "upstream_error"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/locations/{id}/availability": {
      "get": {
        "operationId": "getLocationAvailability",
        "tags": [
          "Availability"
        ],
        "summary": "Get live availability of a ticket type",
        "description": "Tickets left for one ticket type. Read-only: nothing is reserved.",
        "x-required-scope": "events:read",
        "parameters": [
          {
            "$ref": "#/components/parameters/LocationId"
          },
          {
            "name": "requested_quantity",
            "in": "query",
            "description": "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.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            },
            "example": 2
          }
        ],
        "responses": {
          "200": {
            "description": "Availability.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Availability"
                },
                "examples": {
                  "limited": {
                    "value": {
                      "location_id": 2001,
                      "event_id": 1001,
                      "effective_available": 1184,
                      "available_quantity": 1188,
                      "can_fulfill": true
                    }
                  },
                  "unlimited": {
                    "value": {
                      "location_id": 2002,
                      "event_id": 1001,
                      "effective_available": -1,
                      "available_quantity": -1,
                      "can_fulfill": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The id is not plain digits of 1 or more (for example `5.0` or `1e1`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_location_id": {
                    "value": {
                      "error": "invalid_location_id"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The key lacks the required scope, or API access is off for the account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_scope": {
                    "value": {
                      "error": "insufficient_scope",
                      "required": "events:read"
                    }
                  },
                  "partner_api_disabled": {
                    "value": {
                      "error": "partner_api_disabled"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "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.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "location_not_found": {
                    "value": {
                      "error": "location_not_found"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "description": "BetterTickets could not load the data. Retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "upstream_error": {
                    "value": {
                      "error": "upstream_error"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/lists/{id}/rows": {
      "get": {
        "operationId": "lookupListRow",
        "tags": [
          "Custom Lists"
        ],
        "summary": "Look up one list row by key",
        "description": "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.\n\n`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.\n\n**Key cleaning.** `key` is cleaned the same way imported keys are, by the key column's type:\n\n| Key column type | Cleaning |\n|---|---|\n| Any | Trimmed and lower-cased |\n| Email | Must be a valid email address |\n| Phone | Spaces, parentheses, dots and dashes removed; 7–15 digits with an optional leading `+` must remain (`(555) 010-1234` finds `5550101234`) |\n| Date | `2027-01-21`, `1/21/2027` or `Jan 21, 2027` |\n\nA 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.\"\n",
        "x-required-scope": "lists:read",
        "parameters": [
          {
            "$ref": "#/components/parameters/ListId"
          },
          {
            "name": "key",
            "in": "query",
            "required": true,
            "description": "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).",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 2000
            },
            "example": "fan@example.com"
          }
        ],
        "responses": {
          "200": {
            "description": "The row.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListRowLookupResponse"
                },
                "examples": {
                  "row": {
                    "value": {
                      "list_id": 4001,
                      "row": {
                        "row_key": "fan@example.com",
                        "added_at": 1795456800000,
                        "updated_at": 1795460400000,
                        "data": {
                          "email": "fan@example.com",
                          "tier": "VIP"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad list id or key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_list_id": {
                    "value": {
                      "error": "invalid_list_id"
                    }
                  },
                  "missing_key": {
                    "summary": "No key, a blank key, or a key over 2,000 characters.",
                    "value": {
                      "error": "invalid_key",
                      "message": "Pass ?key=<value of the list key column>."
                    }
                  },
                  "invalid_key": {
                    "summary": "The key does not fit the key column type, or is over 255 characters after cleaning.",
                    "value": {
                      "error": "invalid_key",
                      "message": "The key does not match the type of the list key column."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The key lacks the required scope, API access or Custom Lists is off for the account, or API Access is off for this list.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_scope": {
                    "value": {
                      "error": "insufficient_scope",
                      "required": "lists:read"
                    }
                  },
                  "partner_api_disabled": {
                    "value": {
                      "error": "partner_api_disabled"
                    }
                  },
                  "partner_lists_disabled": {
                    "value": {
                      "error": "partner_lists_disabled",
                      "message": "Custom Lists is not enabled for this account."
                    }
                  },
                  "list_api_disabled": {
                    "value": {
                      "error": "list_api_disabled",
                      "message": "API access is turned off for this list. Turn it on in the list settings."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such list on your account (or it is archived), or no active row with that key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "list_not_found": {
                    "value": {
                      "error": "list_not_found"
                    }
                  },
                  "row_not_found": {
                    "value": {
                      "error": "row_not_found"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "description": "`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.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "upstream_error": {
                    "value": {
                      "error": "upstream_error"
                    }
                  },
                  "request_refused": {
                    "value": {
                      "error": "request_refused"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/ListsUnavailable"
          }
        }
      },
      "post": {
        "operationId": "upsertListRows",
        "tags": [
          "Custom Lists"
        ],
        "summary": "Add or update list rows",
        "description": "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.\n\n**Row rules:**\n- Every row needs the key column. The key is trimmed and lower-cased; at most 255 characters after cleaning.\n- 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`.\n- **An update replaces the row's data**: a column you leave out is stored empty. Send every column each time.\n- Cells the organizer edited and locked in BetterTickets keep their value; your value for that column is ignored until the lock is cleared.\n- 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.\n- 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.\n- 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.\n- A list holds at most 50,000 rows per data set (Staging and Production each); new keys beyond that are rejected as `list_full`.\n\nBad rows do not fail the call: they are counted in `rejected` and described (first 50) in `problems`. Safe to repeat.\n",
        "x-required-scope": "lists:write",
        "parameters": [
          {
            "$ref": "#/components/parameters/ListId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ListRowsUpsertRequest"
              },
              "examples": {
                "rows": {
                  "value": {
                    "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": {
          "200": {
            "description": "Rows processed (some may be rejected; check `rejected` and `problems`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListRowsUpsertResponse"
                },
                "examples": {
                  "result": {
                    "value": {
                      "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": {
            "description": "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`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_list_id": {
                    "value": {
                      "error": "invalid_list_id"
                    }
                  },
                  "rows_required": {
                    "value": {
                      "error": "rows_required",
                      "message": "Send {\"rows\": [...]} with 1-500 rows."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The key lacks the required scope, API access or Custom Lists is off for the account, or API Access is off for this list.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_scope": {
                    "value": {
                      "error": "insufficient_scope",
                      "required": "lists:write"
                    }
                  },
                  "partner_api_disabled": {
                    "value": {
                      "error": "partner_api_disabled"
                    }
                  },
                  "partner_lists_disabled": {
                    "value": {
                      "error": "partner_lists_disabled",
                      "message": "Custom Lists is not enabled for this account."
                    }
                  },
                  "list_api_disabled": {
                    "value": {
                      "error": "list_api_disabled",
                      "message": "API access is turned off for this list. Turn it on in the list settings."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such list on your account (or it is archived).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "list_not_found": {
                    "value": {
                      "error": "list_not_found"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "409": {
            "description": "The list has no valid columns yet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "list_not_ready": {
                    "value": {
                      "error": "list_not_ready",
                      "message": "This list has no valid columns yet."
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "More than 500 rows.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "too_many_rows": {
                    "value": {
                      "error": "too_many_rows",
                      "message": "Send at most 500 rows per call.",
                      "max_rows": 500
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "description": "`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.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "upstream_error": {
                    "value": {
                      "error": "upstream_error"
                    }
                  },
                  "request_refused": {
                    "value": {
                      "error": "request_refused"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/ListsUnavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "btk_live_… / btk_test_…",
        "description": "API key issued for your BetterTickets account. Server-to-server only."
      }
    },
    "parameters": {
      "EventRef": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "Numeric event id, or the event's `concert_sku` (2–80 characters, matched case-insensitively).",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "examples": {
          "id": {
            "value": "1001"
          },
          "sku": {
            "value": "SRF_07-16-2027"
          }
        }
      },
      "EventId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "Numeric event id, plain digits only (`concert_sku` is not accepted here).",
        "schema": {
          "type": "integer",
          "minimum": 1
        },
        "example": 1001
      },
      "LocationId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "Ticket type (location) id, plain digits only.",
        "schema": {
          "type": "integer",
          "minimum": 1
        },
        "example": 2001
      },
      "ListId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "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.",
        "schema": {
          "type": "integer",
          "minimum": 1
        },
        "example": 4001
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "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`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "missing_api_key": {
                "value": {
                  "error": "missing_api_key",
                  "message": "Authorization: Bearer btk_… required"
                }
              },
              "invalid_api_key": {
                "value": {
                  "error": "invalid_api_key"
                }
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "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": {
            "description": "Seconds to wait before retrying (at least 1).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "partner_rate_limited": {
                "value": {
                  "error": "partner_rate_limited",
                  "message": "Too many Partner API requests. Slow down and retry after Retry-After seconds.",
                  "retry_after_seconds": 42
                }
              }
            }
          }
        }
      },
      "Unavailable": {
        "description": "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": {
            "description": "Seconds to wait before retrying.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "auth_unavailable": {
                "value": {
                  "error": "auth_unavailable",
                  "message": "API key check is temporarily unavailable. Retry after Retry-After seconds.",
                  "retryable": true,
                  "retry_after_seconds": 5
                }
              },
              "FEATURE_GATE_UNAVAILABLE": {
                "value": {
                  "error": "FEATURE_GATE_UNAVAILABLE",
                  "retryable": true,
                  "retry_after_seconds": 5
                }
              }
            }
          }
        }
      },
      "ListsUnavailable": {
        "description": "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": {
            "description": "Seconds to wait before retrying.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "auth_unavailable": {
                "value": {
                  "error": "auth_unavailable",
                  "message": "API key check is temporarily unavailable. Retry after Retry-After seconds.",
                  "retryable": true,
                  "retry_after_seconds": 5
                }
              },
              "FEATURE_GATE_UNAVAILABLE": {
                "value": {
                  "error": "FEATURE_GATE_UNAVAILABLE",
                  "retryable": true,
                  "retry_after_seconds": 5
                }
              },
              "FEATURE_GATE_UNAVAILABLE_bare": {
                "value": {
                  "error": "FEATURE_GATE_UNAVAILABLE"
                }
              }
            }
          }
        }
      },
      "MethodNotAllowed": {
        "description": "The HTTP method is not supported on this path.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "method_not_allowed": {
                "value": {
                  "error": "method_not_allowed"
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Every error has this shape: a stable machine code in `error`, usually a human sentence in `message`, and sometimes extra fields. Branch on `error`, never on `message`.",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Stable error code, e.g. `invalid_api_key`, `event_not_found`."
          },
          "message": {
            "type": "string",
            "description": "Human-readable explanation. Wording may change."
          },
          "required": {
            "type": "string",
            "description": "`insufficient_scope` only: the scope the operation needs."
          },
          "reason": {
            "type": "string",
            "description": "`partner_lists_disabled` only, when present: a short machine-readable reason."
          },
          "retry_after_seconds": {
            "type": "integer",
            "minimum": 1,
            "description": "`partner_rate_limited`, `auth_unavailable` and `FEATURE_GATE_UNAVAILABLE` (when present): seconds to wait. Same value as the `Retry-After` header."
          },
          "retryable": {
            "type": "boolean",
            "description": "`auth_unavailable` and `FEATURE_GATE_UNAVAILABLE` (when present): always `true`."
          },
          "max_rows": {
            "type": "integer",
            "description": "`too_many_rows` only: the per-call row limit (500)."
          }
        },
        "additionalProperties": true
      },
      "Venue": {
        "type": "object",
        "description": "Where the event takes place. 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.",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "address": {
            "type": [
              "string",
              "null"
            ]
          },
          "city": {
            "type": [
              "string",
              "null"
            ]
          },
          "state": {
            "type": [
              "string",
              "null"
            ]
          },
          "zip_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "timezone": {
            "type": [
              "string",
              "null"
            ],
            "description": "IANA time zone name, e.g. `America/Chicago`, when set."
          }
        },
        "additionalProperties": true
      },
      "EventSummaryTicketType": {
        "type": "object",
        "description": "Short form of an active ticket type, as embedded in `GET /events`. For prices and availability use `GET /events/{id}/locations`. 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.",
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "description": "Ticket type (location) id."
          },
          "event_id": {
            "type": "integer"
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": true
      },
      "EventTicketType": {
        "type": "object",
        "description": "A ticket type as embedded in `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.",
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "description": "Ticket type (location) id."
          },
          "event_id": {
            "type": "integer"
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "price": {
            "type": "integer",
            "description": "Price per ticket, in **cents**."
          },
          "available_quantity": {
            "type": "integer",
            "description": "Tickets left; `-1` = unlimited."
          },
          "is_sold_out": {
            "type": "boolean"
          },
          "low_ticket_warning": {
            "type": "boolean",
            "description": "True when only a few tickets are left."
          },
          "is_active": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "False for a ticket type that is switched off."
          }
        },
        "additionalProperties": true
      },
      "EventSummary": {
        "type": "object",
        "description": "An event as listed by `GET /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.",
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "description": "Event id."
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "artist": {
            "type": [
              "string",
              "null"
            ],
            "description": "Headliner or display title. Either `name` or `artist` is always set."
          },
          "date": {
            "type": [
              "string",
              "null"
            ],
            "description": "Event date, typically `YYYY-MM-DD`."
          },
          "absolute_time": {
            "type": [
              "string",
              "null"
            ],
            "description": "Event start time as entered (typically ISO 8601). Always set on listed events."
          },
          "doors_time": {
            "type": [
              "string",
              "null"
            ]
          },
          "concert_sku": {
            "type": [
              "string",
              "null"
            ],
            "description": "The event's reference code. Accepted in place of `id` by `GET /events/{id}`."
          },
          "venue_id": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Venue id; use it with the `venue_id` filter."
          },
          "venue_string": {
            "type": [
              "string",
              "null"
            ],
            "description": "Venue name as text."
          },
          "venue": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Venue"
              },
              {
                "type": "null"
              }
            ]
          },
          "event_image_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "is_sold_out": {
            "type": "boolean",
            "description": "The event is marked sold out."
          },
          "location_count": {
            "type": "integer",
            "description": "Number of active ticket types."
          },
          "locations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventSummaryTicketType"
            }
          }
        },
        "additionalProperties": true
      },
      "Event": {
        "type": "object",
        "description": "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.",
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "description": "Event id."
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "artist": {
            "type": [
              "string",
              "null"
            ],
            "description": "Headliner or display title."
          },
          "date": {
            "type": [
              "string",
              "null"
            ],
            "description": "Event date, typically `YYYY-MM-DD`."
          },
          "absolute_time": {
            "type": [
              "string",
              "null"
            ],
            "description": "Event start time as entered (typically ISO 8601)."
          },
          "doors_time": {
            "type": [
              "string",
              "null"
            ]
          },
          "concert_sku": {
            "type": [
              "string",
              "null"
            ],
            "description": "The event's reference code."
          },
          "venue_id": {
            "type": [
              "integer",
              "null"
            ]
          },
          "venue_string": {
            "type": [
              "string",
              "null"
            ],
            "description": "Venue name as text."
          },
          "venue": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Venue"
              },
              {
                "type": "null"
              }
            ]
          },
          "event_image_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "is_sold_out": {
            "type": "boolean",
            "description": "True when the event is marked sold out or every active ticket type is sold out."
          },
          "low_ticket_warning": {
            "type": "boolean",
            "description": "True when any active ticket type is low."
          },
          "locations": {
            "type": "array",
            "description": "**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.",
            "items": {
              "$ref": "#/components/schemas/EventTicketType"
            }
          }
        },
        "additionalProperties": true
      },
      "EventPage": {
        "type": "object",
        "description": "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.",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventSummary"
            }
          },
          "itemsReceived": {
            "type": "integer",
            "description": "Events on this page."
          },
          "curPage": {
            "type": "integer"
          },
          "nextPage": {
            "type": [
              "integer",
              "null"
            ]
          },
          "prevPage": {
            "type": [
              "integer",
              "null"
            ]
          },
          "itemsTotal": {
            "type": "integer"
          },
          "pageTotal": {
            "type": "integer"
          }
        },
        "additionalProperties": true
      },
      "Location": {
        "type": "object",
        "description": "A **ticket type** (for example GA, VIP, or a pickup stop). Its `id` is the location id used by `GET /locations/{id}/availability`. 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.",
        "required": [
          "id",
          "event_id"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "description": "Ticket type (location) id."
          },
          "event_id": {
            "type": "integer"
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Display name."
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "price": {
            "type": "integer",
            "description": "Price per ticket, in **cents**."
          },
          "available_quantity": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Tickets left after tickets sold; `-1` = unlimited."
          },
          "effective_available": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Tickets left after tickets sold **and** checkouts in progress; `-1` = unlimited. The best \"tickets left\" number."
          },
          "is_sold_out": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "is_effectively_sold_out": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Sold out once checkouts in progress are counted."
          },
          "low_ticket_warning": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "True when only a few tickets are left."
          },
          "address": {
            "type": [
              "string",
              "null"
            ],
            "description": "Street address, for ticket types tied to a place (such as a pickup stop)."
          },
          "city": {
            "type": [
              "string",
              "null"
            ]
          },
          "state": {
            "type": [
              "string",
              "null"
            ]
          },
          "zip_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "image_url": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": true
      },
      "LocationList": {
        "type": "object",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Location"
            }
          }
        },
        "additionalProperties": false
      },
      "Availability": {
        "type": "object",
        "description": "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.",
        "required": [
          "location_id",
          "event_id",
          "effective_available",
          "available_quantity",
          "can_fulfill"
        ],
        "properties": {
          "location_id": {
            "type": "integer"
          },
          "event_id": {
            "type": [
              "integer",
              "null"
            ]
          },
          "effective_available": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Tickets left after tickets sold **and** checkouts in progress. `-1` = unlimited. Use this to show \"tickets left\"."
          },
          "available_quantity": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Tickets left after tickets sold only. `-1` = unlimited."
          },
          "can_fulfill": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "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."
          }
        },
        "additionalProperties": true
      },
      "ListRowLookupResponse": {
        "type": "object",
        "required": [
          "list_id",
          "row"
        ],
        "properties": {
          "list_id": {
            "type": "integer"
          },
          "row": {
            "type": "object",
            "required": [
              "row_key",
              "added_at",
              "updated_at",
              "data"
            ],
            "properties": {
              "row_key": {
                "type": "string",
                "description": "The cleaned key (trimmed, lower-cased)."
              },
              "added_at": {
                "type": "integer",
                "format": "int64",
                "description": "When the row first arrived, epoch milliseconds. Never reset by later writes."
              },
              "updated_at": {
                "type": "integer",
                "format": "int64",
                "description": "Last change, epoch milliseconds."
              },
              "data": {
                "type": "object",
                "additionalProperties": true,
                "description": "Only the columns the list exposes to the API (chosen in the list's settings)."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "ListRowsUpsertRequest": {
        "type": "object",
        "required": [
          "rows"
        ],
        "properties": {
          "rows": {
            "type": "array",
            "minItems": 1,
            "maxItems": 500,
            "description": "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 `<column>:too_long`.",
            "items": {
              "type": "object",
              "additionalProperties": {
                "oneOf": [
                  {
                    "type": "string",
                    "description": "Up to 2,000 characters after trimming. A longer value does not fail the request: that row is rejected and reported in `problems` as `<column>:too_long`."
                  },
                  {
                    "type": "number"
                  },
                  {
                    "type": "boolean"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "properties": {
                "data": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "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": {
                  "type": "integer",
                  "description": "Optional. Replaces the row's position in `problems[].row`."
                }
              }
            }
          }
        },
        "additionalProperties": true,
        "description": "Only `rows` is read; other top-level keys are ignored."
      },
      "ListRowsUpsertResponse": {
        "type": "object",
        "required": [
          "list_id",
          "received",
          "added",
          "updated",
          "unchanged",
          "rejected",
          "deduplicated",
          "problems"
        ],
        "properties": {
          "list_id": {
            "type": "integer"
          },
          "received": {
            "type": "integer",
            "description": "Rows in your request."
          },
          "added": {
            "type": "integer",
            "description": "New keys."
          },
          "updated": {
            "type": "integer",
            "description": "Existing keys whose data (or status) changed."
          },
          "unchanged": {
            "type": "integer",
            "description": "Existing keys sent with identical data."
          },
          "rejected": {
            "type": "integer",
            "description": "Rows not written. Details (first 50) in `problems`."
          },
          "deduplicated": {
            "type": "integer",
            "description": "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": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/ListRowProblem"
            }
          }
        },
        "additionalProperties": false
      },
      "ListRowProblem": {
        "type": "object",
        "description": "A row that was not written. `reason` is one of `invalid_row`, `missing_key`, `key_too_long`, `list_full`, or `<column>:<problem>` 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.",
        "required": [
          "row",
          "key",
          "reason"
        ],
        "properties": {
          "row": {
            "type": "integer",
            "description": "1-based position in your `rows`, or the row's own integer `source_row` when it sends one."
          },
          "key": {
            "type": [
              "string",
              "null"
            ],
            "description": "The cleaned row key, when it could be read."
          },
          "reason": {
            "type": "string"
          }
        },
        "additionalProperties": false
      }
    }
  }
}
