Add or update list rows
/lists/{id}/rowsAdds 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
datakey holding an object, the row's values are read from that object and its other top-level keys are dropped; an integersource_rowreplaces the row's position inproblems[].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 | required | Bearer <key>. A btk_live_… or btk_test_… key. |
Content-Type | string | required | application/json |
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | integer | required | 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
ListRowsUpsertRequest · application/json · required
Only rows is read; other top-level keys are ignored.
rowsarray of objectrequiredmin items 1max items 5001–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) andsource_row(an integer that replaces the row's position inproblems[].row). String values can be up to 2,000 characters; a longer value does not fail the request, and that row is rejected inproblemsas<column>:too_long.Child attributes
dataobjectOptional. 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_rowintegerOptional. Replaces the row's position in
problems[].row.
Example
{
"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. | 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_idintegerrequiredreceivedintegerrequiredRows in your request.
addedintegerrequiredNew keys.
updatedintegerrequiredExisting keys whose data (or status) changed.
unchangedintegerrequiredExisting keys sent with identical data.
rejectedintegerrequiredRows not written. Details (first 50) in
problems.deduplicatedintegerrequiredValid 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.
problemsarray of ListRowProblemrequiredmax items 50Child attributes
rowintegerrequired1-based position in your
rows, or the row's own integersource_rowwhen it sends one.keystring | nullrequiredThe cleaned row key, when it could be read.
reasonstringrequired
Example: result
{
"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
Example: invalid_list_id
{
"error": "invalid_list_id"
}Example: rows_required
{
"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
Example: missing_api_key
{
"error": "missing_api_key",
"message": "Authorization: Bearer btk_… required"
}Example: invalid_api_key
{
"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
Example: insufficient_scope
{
"error": "insufficient_scope",
"required": "lists:write"
}Example: partner_api_disabled
{
"error": "partner_api_disabled"
}Example: partner_lists_disabled
{
"error": "partner_lists_disabled",
"message": "Custom Lists is not enabled for this account."
}Example: list_api_disabled
{
"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
Example: list_not_found
{
"error": "list_not_found"
}405 The HTTP method is not supported on this path.
Schema: Error
Example: method_not_allowed
{
"error": "method_not_allowed"
}409 The list has no valid columns yet.
Schema: Error
Example: list_not_ready
{
"error": "list_not_ready",
"message": "This list has no valid columns yet."
}413 More than 500 rows.
Schema: Error
Example: too_many_rows
{
"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.
Headers
| Name | Type | Description |
|---|---|---|
Retry-After | integer | Seconds to wait before retrying (at least 1). |
Schema: Error
Example: partner_rate_limited
{
"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
Example: upstream_error
{
"error": "upstream_error"
}Example: request_refused
{
"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
| Name | Type | Description |
|---|---|---|
Retry-After | integer | Seconds to wait before retrying. |
Schema: Error
Example: auth_unavailable
{
"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
{
"error": "FEATURE_GATE_UNAVAILABLE",
"retryable": true,
"retry_after_seconds": 5
}Example: FEATURE_GATE_UNAVAILABLE_bare
{
"error": "FEATURE_GATE_UNAVAILABLE"
}#Code samples
Set BETTERTICKETS_API_KEY on your server. Never send a key from a browser.
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":""}]}'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();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
$ch = curl_init('https://app.bettertickets.com/api/partner/v1/lists/4001/rows');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => '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);