# Add or update list rows

`POST /lists/{id}/rows`

- **Full URL:** `https://app.bettertickets.com/api/partner/v1/lists/{id}/rows`
- **Scope required:** `lists:write`
- **Auth:** `Authorization: Bearer <btk_live_… or btk_test_… key>`

Adds or updates 1–500 rows by the list's key column. Test keys write the list's **Staging** rows, live keys **Production** rows. New rows are what the list's automations pick up.

**Row rules:**
- Every row needs the key column. The key is trimmed and lower-cased; at most 255 characters after cleaning.
- Only the list's columns are stored; other keys are ignored, except two reserved keys: if a row has a `data` key holding an object, the row's values are read from that object and its other top-level keys are dropped; an integer `source_row` replaces the row's position in `problems[].row`.
- **An update replaces the row's data**: a column you leave out is stored empty. Send every column each time.
- Cells the organizer edited and locked in BetterTickets keep their value; your value for that column is ignored until the lock is cleared.
- Values are cleaned by column type: email (lower-cased, must be valid), phone (7–15 digits, optional leading `+`), number, date (`2027-01-21`, `1/21/2027`, `Jan 21, 2027`), boolean (`true/false`, `yes/no`, `y/n`, `1/0`), text. Each value at most 2,000 characters. Required columns must have a value.
- The same key twice in one call: the later **valid** row wins (`deduplicated`); a later row that is rejected does not replace an earlier valid one.
- If the list has a status column, a value set as inactive in the list's settings marks the row inactive (it stops driving automations); any other value makes it active again.
- A list holds at most 50,000 rows per data set (Staging and Production each); new keys beyond that are rejected as `list_full`.

Bad rows do not fail the call: they are counted in `rejected` and described (first 50) in `problems`. Safe to repeat.

## Request

### Headers

| Name | Type | Required | Description |
|---|---|---|---|
| `Authorization` | string | Yes | Bearer <key>. A `btk_live_…` or `btk_test_…` key. |
| `Content-Type` | string | Yes | `application/json` |

### Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | integer | Yes | Custom List id (shown in the list's settings). Send plain digits. Other numeric forms, such as `1e1` or `0x10`, may be read as a different list id, so build the path only from the id as shown. (min 1) Example: `4001` |

## Request body

`application/json`, required.

Only `rows` is read; other top-level keys are ignored.

- `rows` (array of object, required, min items 1, max items 500) — 1–500 rows. Each row is an object of column key → value and must contain the list's key column. Reserved keys: `data` (an object; when present, the values are read from it and the other top-level keys are dropped) and `source_row` (an integer that replaces the row's position in `problems[].row`). String values can be up to 2,000 characters; a longer value does not fail the request, and that row is rejected in `problems` as `<column>:too_long`.
  - `data` (object) — Optional. Column key → value. When present, values are read from here and the other top-level keys are dropped. Values inside must be strings, numbers, booleans or null.
  - `source_row` (integer) — Optional. Replaces the row's position in `problems[].row`.

Example:

```json
{
  "rows": [
    {
      "email": "fan@example.com",
      "first_name": "Sam",
      "last_name": "Rivera",
      "tier": "VIP",
      "wristband": "W-1042"
    },
    {
      "email": "kim@example.com",
      "first_name": "Kim",
      "last_name": "Lee",
      "tier": "GA",
      "wristband": ""
    }
  ]
}
```

## Responses

| Status | Meaning | Error codes |
|---|---|---|
| 200 | Rows processed (some may be rejected; check `rejected` and `problems`). | — |
| 400 | Bad list id, or `rows` missing or empty. A bad key inside a row is not a 400: it is reported in the 200 (`rejected`, `problems`). | `invalid_list_id`, `rows_required` |
| 401 | No key, or the key was checked and is unknown, revoked, expired or has the wrong prefix. The same `invalid_api_key` is returned for every kind of bad key. Do not retry it. A temporary problem checking the key answers `503 auth_unavailable` instead. Repeated requests with a missing or invalid key from one IP address are answered `429 partner_rate_limited` instead of `401`. | `missing_api_key`, `invalid_api_key` |
| 403 | The key lacks the required scope, API access or Custom Lists is off for the account, or API Access is off for this list. | `insufficient_scope`, `partner_api_disabled`, `partner_lists_disabled`, `list_api_disabled` |
| 404 | No such list on your account (or it is archived). | `list_not_found` |
| 405 | The HTTP method is not supported on this path. | `method_not_allowed` |
| 409 | The list has no valid columns yet. | `list_not_ready` |
| 413 | More than 500 rows. | `too_many_rows` |
| 429 | Too many requests from this key or from your IP address, or repeated requests with a missing or invalid key from one IP address (answered `429` instead of `401`). Wait `Retry-After` seconds. See [Rate Limits](https://docs.bettertickets.com/rate-limits). | `partner_rate_limited` |
| 502 | `upstream_error`: BetterTickets could not complete the call; retry with backoff and a small cap on attempts. `request_refused`: the call was refused for an unlisted reason; do not retry the same request, and contact BetterTickets if it persists. `request_refused` can also arrive with a 4xx status; branch on `error`, not only on the status. | `upstream_error`, `request_refused` |
| 503 | BetterTickets could not check the key (`auth_unavailable`) or confirm the account's settings (`FEATURE_GATE_UNAVAILABLE`) for a moment. Safe to retry after `Retry-After` seconds; if the header is missing, wait 5 seconds. Retrying `auth_unavailable` faster than `Retry-After` gets `429 partner_rate_limited`. On Custom Lists calls, `FEATURE_GATE_UNAVAILABLE` can also arrive as a bare `{ "error": "FEATURE_GATE_UNAVAILABLE" }` with no `Retry-After`, `retryable` or `retry_after_seconds`; wait 5 seconds before retrying. | `auth_unavailable`, `FEATURE_GATE_UNAVAILABLE` |

### 200

Rows processed (some may be rejected; check `rejected` and `problems`).

Schema `ListRowsUpsertResponse`:

- `list_id` (integer, required)
- `received` (integer, required) — Rows in your request.
- `added` (integer, required) — New keys.
- `updated` (integer, required) — Existing keys whose data (or status) changed.
- `unchanged` (integer, required) — Existing keys sent with identical data.
- `rejected` (integer, required) — Rows not written. Details (first 50) in `problems`.
- `deduplicated` (integer, required) — Valid rows dropped because a later valid row in the same request had the same key (the later one wins). A rejected row never replaces an earlier valid one.
- `problems` (array of ListRowProblem, required, max items 50)
  - `row` (integer, required) — 1-based position in your `rows`, or the row's own integer `source_row` when it sends one.
  - `key` (string | null, required) — The cleaned row key, when it could be read.
  - `reason` (string, required)

Example `result`:

```json
{
  "list_id": 4001,
  "received": 2,
  "added": 1,
  "updated": 0,
  "unchanged": 0,
  "rejected": 1,
  "deduplicated": 0,
  "problems": [
    {
      "row": 2,
      "key": "kim@example.com",
      "reason": "wristband:required"
    }
  ]
}
```

### 400

Bad list id, or `rows` missing or empty. A bad key inside a row is not a 400: it is reported in the 200 (`rejected`, `problems`).

Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)).

Example `invalid_list_id`:

```json
{
  "error": "invalid_list_id"
}
```

Example `rows_required`:

```json
{
  "error": "rows_required",
  "message": "Send {\"rows\": [...]} with 1-500 rows."
}
```

### 401

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

Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)).

Example `missing_api_key`:

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

Example `invalid_api_key`:

```json
{
  "error": "invalid_api_key"
}
```

### 403

The key lacks the required scope, API access or Custom Lists is off for the account, or API Access is off for this list.

Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)).

Example `insufficient_scope`:

```json
{
  "error": "insufficient_scope",
  "required": "lists:write"
}
```

Example `partner_api_disabled`:

```json
{
  "error": "partner_api_disabled"
}
```

Example `partner_lists_disabled`:

```json
{
  "error": "partner_lists_disabled",
  "message": "Custom Lists is not enabled for this account."
}
```

Example `list_api_disabled`:

```json
{
  "error": "list_api_disabled",
  "message": "API access is turned off for this list. Turn it on in the list settings."
}
```

### 404

No such list on your account (or it is archived).

Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)).

Example `list_not_found`:

```json
{
  "error": "list_not_found"
}
```

### 405

The HTTP method is not supported on this path.

Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)).

Example `method_not_allowed`:

```json
{
  "error": "method_not_allowed"
}
```

### 409

The list has no valid columns yet.

Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)).

Example `list_not_ready`:

```json
{
  "error": "list_not_ready",
  "message": "This list has no valid columns yet."
}
```

### 413

More than 500 rows.

Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)).

Example `too_many_rows`:

```json
{
  "error": "too_many_rows",
  "message": "Send at most 500 rows per call.",
  "max_rows": 500
}
```

### 429

Too many requests from this key or from your IP address, or repeated requests with a missing or invalid key from one IP address (answered `429` instead of `401`). Wait `Retry-After` seconds. See [Rate Limits](https://docs.bettertickets.com/rate-limits).

Headers:

- `Retry-After` (integer) — Seconds to wait before retrying (at least 1).

Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)).

Example `partner_rate_limited`:

```json
{
  "error": "partner_rate_limited",
  "message": "Too many Partner API requests. Slow down and retry after Retry-After seconds.",
  "retry_after_seconds": 42
}
```

### 502

`upstream_error`: BetterTickets could not complete the call; retry with backoff and a small cap on attempts. `request_refused`: the call was refused for an unlisted reason; do not retry the same request, and contact BetterTickets if it persists. `request_refused` can also arrive with a 4xx status; branch on `error`, not only on the status.

Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)).

Example `upstream_error`:

```json
{
  "error": "upstream_error"
}
```

Example `request_refused`:

```json
{
  "error": "request_refused"
}
```

### 503

BetterTickets could not check the key (`auth_unavailable`) or confirm the account's settings (`FEATURE_GATE_UNAVAILABLE`) for a moment. Safe to retry after `Retry-After` seconds; if the header is missing, wait 5 seconds. Retrying `auth_unavailable` faster than `Retry-After` gets `429 partner_rate_limited`. On Custom Lists calls, `FEATURE_GATE_UNAVAILABLE` can also arrive as a bare `{ "error": "FEATURE_GATE_UNAVAILABLE" }` with no `Retry-After`, `retryable` or `retry_after_seconds`; wait 5 seconds before retrying.

Headers:

- `Retry-After` (integer) — Seconds to wait before retrying.

Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)).

Example `auth_unavailable`:

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

Example `FEATURE_GATE_UNAVAILABLE`:

```json
{
  "error": "FEATURE_GATE_UNAVAILABLE",
  "retryable": true,
  "retry_after_seconds": 5
}
```

Example `FEATURE_GATE_UNAVAILABLE_bare`:

```json
{
  "error": "FEATURE_GATE_UNAVAILABLE"
}
```

## Code samples

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

### cURL

```bash
curl -X POST "https://app.bettertickets.com/api/partner/v1/lists/4001/rows" \
  -H "Authorization: Bearer $BETTERTICKETS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rows":[{"email":"fan@example.com","first_name":"Sam","last_name":"Rivera","tier":"VIP","wristband":"W-1042"},{"email":"kim@example.com","first_name":"Kim","last_name":"Lee","tier":"GA","wristband":""}]}'
```

### Node.js

```js
async function main() {
  const res = await fetch('https://app.bettertickets.com/api/partner/v1/lists/4001/rows', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.BETTERTICKETS_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      "rows": [
        {
          "email": "fan@example.com",
          "first_name": "Sam",
          "last_name": "Rivera",
          "tier": "VIP",
          "wristband": "W-1042"
        },
        {
          "email": "kim@example.com",
          "first_name": "Kim",
          "last_name": "Lee",
          "tier": "GA",
          "wristband": ""
        }
      ]
    }),
  });

  // Error pages from a proxy may not be JSON, so parse defensively.
  const text = await res.text();
  let data = {};
  try { data = text ? JSON.parse(text) : {}; } catch { data = {}; }
  if (!res.ok) {
    // Branch on data.error, e.g. "partner_rate_limited"
    throw new Error(`${res.status} ${data.error || 'unknown'}`);
  }
  console.log(data);
}

main();
```

### Python

```python
import os
import requests

res = requests.request(
    "POST",
    "https://app.bettertickets.com/api/partner/v1/lists/4001/rows",
    headers={"Authorization": f"Bearer {os.environ['BETTERTICKETS_API_KEY']}"},
    json={
        "rows": [
            {
                "email": "fan@example.com",
                "first_name": "Sam",
                "last_name": "Rivera",
                "tier": "VIP",
                "wristband": "W-1042"
            },
            {
                "email": "kim@example.com",
                "first_name": "Kim",
                "last_name": "Lee",
                "tier": "GA",
                "wristband": ""
            }
        ]
    },
    timeout=30,
)
is_json = res.headers.get("content-type", "").startswith("application/json")
data = res.json() if is_json else {}
if not res.ok:
    # Branch on data["error"], e.g. "partner_rate_limited"
    raise RuntimeError(f"{res.status_code} {data.get('error')}")
print(data)
```

### PHP

```php
<?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);
```
