# Clients

A client is who you bill. Clients are matched by their exact `email`
list: creating a client with the same emails as an existing one
updates it instead.

Deleting a client pauses their active subscriptions; restoring the
client does not resume them. Deleted clients are hidden until you
restore them.

## The client object

- `id` (string): Example: `0abcDEF1234567890xyzAB`.
- `name` (string)
- `emails` (array of string): Min 1 items.
- `address` (string or null)
- `currency` (string): Three-letter currency code, in lowercase. Example: `usd`.
- `language` (string): Two-letter language code, in lowercase. One of `da`, `en`, `fr`, `de`, `it`, `no`, `pt`, `es`.
- `default_payment_method_id` (string or null): The card `POST /invoices/{id}/pay` uses when no `payment_method_id` is sent. Null when the client has no card on file. Example: `0abcDEF1234567890xyzAB`.
- `created_at` (timestamp): Date and time in UTC. Example: `2024-06-15T12:00:00.000000Z`.
- `updated_at` (timestamp): Date and time in UTC. Example: `2024-06-15T12:00:00.000000Z`.
- `is_deleted` (boolean)
- `payment_methods` (array of object): Cards the client saved when paying in the app, newest first. Cards can't be added through the API.
- `payment_methods[].id` (string): Example: `0abcDEF1234567890xyzAB`.
- `payment_methods[].type` (string): One of `card`.
- `payment_methods[].brand` (string): Example: `visa`.
- `payment_methods[].last_four` (string): Example: `4242`.
- `payment_methods[].exp_month` (integer): Min 1. Max 12.
- `payment_methods[].exp_year` (integer)
- `payment_methods[].is_default` (boolean): True for the card used when paying without a `payment_method_id`.
- `payment_methods[].created_at` (timestamp): Date and time in UTC. Example: `2024-06-15T12:00:00.000000Z`.
- `payment_methods[].updated_at` (timestamp): Date and time in UTC. Example: `2024-06-15T12:00:00.000000Z`.

```json
{
  "id": "0abcDEF1234567890xyzAB",
  "name": "Jane Doe",
  "emails": [
    "jane@example.com"
  ],
  "address": "1 Main St",
  "currency": "usd",
  "language": "en",
  "default_payment_method_id": "0abcDEF1234567890xyzAB",
  "payment_methods": [
    {
      "id": "0abcDEF1234567890xyzAB",
      "type": "card",
      "brand": "visa",
      "last_four": "4242",
      "exp_month": 12,
      "exp_year": 2030,
      "is_default": true,
      "created_at": "2024-06-15T12:00:00.000000Z",
      "updated_at": "2024-06-15T12:00:00.000000Z"
    }
  ],
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}
```

## List clients

`GET /clients`

### Query parameters

- `search` (string): Matches name, emails, and address. Not case-sensitive. Example: `jane`.
- `limit` (integer): Number of results per page. Default: `10`. Min 1. Max 100.
- `cursor` (string): To get the next page, pass the `next_cursor` from the previous response.
- `created_at` (object): Keys `gt`, `gte`, `lt`, `lte`. Example: `created_at[gt]=2024-06-15T12:00:00.000000Z`.
- `updated_at` (object): Keys `gt`, `gte`, `lt`, `lte`. Example: `updated_at[gt]=2024-06-15T12:00:00.000000Z`.

### Response

- `200`: Paginated clients. Returns a [paginated list](/docs/pagination) of [client objects](#the-client-object).

### Errors

- `400` `request_failed`: Your request could not be processed.
- `400` `api_version_unsupported`: The requested API version is not supported. Current version: 2026-08-21
- `401` `api_key_missing`: The API key is missing.
- `401` `api_key_invalid`: The API key is invalid or has been revoked.
- `422`: The request body or query parameters are invalid.
- `429`: Too many requests. The limit is 300 requests per 5 minutes.

### Example request

```bash
curl https://api.tallymark.com/clients \
  -H "Authorization: Bearer $TALLYMARK_API_KEY"
```

### Example response

```json
{
  "data": [
    {
      "id": "0abcDEF1234567890xyzAB",
      "name": "Jane Doe",
      "emails": [
        "jane@example.com"
      ],
      "address": "1 Main St",
      "currency": "usd",
      "language": "en",
      "default_payment_method_id": "0abcDEF1234567890xyzAB",
      "payment_methods": [
        {
          "id": "0abcDEF1234567890xyzAB",
          "type": "card",
          "brand": "visa",
          "last_four": "4242",
          "exp_month": 12,
          "exp_year": 2030,
          "is_default": true,
          "created_at": "2024-06-15T12:00:00.000000Z",
          "updated_at": "2024-06-15T12:00:00.000000Z"
        }
      ],
      "created_at": "2024-06-15T12:00:00.000000Z",
      "updated_at": "2024-06-15T12:00:00.000000Z",
      "is_deleted": false
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Create or update a client

`POST /clients`

Creates a client. If a non-deleted client on this account already has
the same `email` list (exact match, same order), that client is
updated instead and 200 is returned; omitted `address` keeps its
current value.

### Request body

- `name` (string, required): Max length 255.
- `email` (string or array of string, required): One email address, or a list of up to 4. Example: `jane@example.com`.
- `address` (string or null)
- `currency` (string, required): Three-letter currency code, in lowercase. Example: `usd`.
- `language` (string, required): Two-letter language code, in lowercase. One of `da`, `en`, `fr`, `de`, `it`, `no`, `pt`, `es`.

### Response

- `200`: Updated client. Returns a [client object](#the-client-object).
- `201`: Created client. Returns a [client object](#the-client-object).

### Errors

- `400` `request_failed`: Your request could not be processed.
- `400` `api_version_unsupported`: The requested API version is not supported. Current version: 2026-08-21
- `401` `api_key_missing`: The API key is missing.
- `401` `api_key_invalid`: The API key is invalid or has been revoked.
- `403` `api_key_read_only`: This API key is read-only and cannot make write requests.
- `422`: The request body or query parameters are invalid.
- `429`: Too many requests. The limit is 300 requests per 5 minutes.

### Example request

```bash
curl -X POST https://api.tallymark.com/clients \
  -H "Authorization: Bearer $TALLYMARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "address": "1 Main St",
  "currency": "usd",
  "language": "en"
}'
```

### Example response

```json
{
  "id": "0abcDEF1234567890xyzAB",
  "name": "Jane Doe",
  "emails": [
    "jane@example.com"
  ],
  "address": "1 Main St",
  "currency": "usd",
  "language": "en",
  "default_payment_method_id": "0abcDEF1234567890xyzAB",
  "payment_methods": [
    {
      "id": "0abcDEF1234567890xyzAB",
      "type": "card",
      "brand": "visa",
      "last_four": "4242",
      "exp_month": 12,
      "exp_year": 2030,
      "is_default": true,
      "created_at": "2024-06-15T12:00:00.000000Z",
      "updated_at": "2024-06-15T12:00:00.000000Z"
    }
  ],
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}
```

## Show a client

`GET /clients/{id}`

### Path parameters

- `id` (string, required): The client ID. Example: `0abcDEF1234567890xyzAB`.

### Response

- `200`: Client. Returns a [client object](#the-client-object).

### Errors

- `400` `request_failed`: Your request could not be processed.
- `400` `api_version_unsupported`: The requested API version is not supported. Current version: 2026-08-21
- `401` `api_key_missing`: The API key is missing.
- `401` `api_key_invalid`: The API key is invalid or has been revoked.
- `404`: The record doesn't exist or was deleted.
- `429`: Too many requests. The limit is 300 requests per 5 minutes.

### Example request

```bash
curl https://api.tallymark.com/clients/0abcDEF1234567890xyzAB \
  -H "Authorization: Bearer $TALLYMARK_API_KEY"
```

### Example response

```json
{
  "id": "0abcDEF1234567890xyzAB",
  "name": "Jane Doe",
  "emails": [
    "jane@example.com"
  ],
  "address": "1 Main St",
  "currency": "usd",
  "language": "en",
  "default_payment_method_id": "0abcDEF1234567890xyzAB",
  "payment_methods": [
    {
      "id": "0abcDEF1234567890xyzAB",
      "type": "card",
      "brand": "visa",
      "last_four": "4242",
      "exp_month": 12,
      "exp_year": 2030,
      "is_default": true,
      "created_at": "2024-06-15T12:00:00.000000Z",
      "updated_at": "2024-06-15T12:00:00.000000Z"
    }
  ],
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}
```

## Update a client

`POST /clients/{id}/update`

Only the fields you send are changed; omitted fields keep their
current value. Send `address: null` to clear the address.

### Path parameters

- `id` (string, required): The client ID. Example: `0abcDEF1234567890xyzAB`.

### Request body

- `name` (string): Max length 255.
- `email` (string or array of string): One email address, or a list of up to 4. Example: `jane@example.com`.
- `address` (string or null)
- `currency` (string): Three-letter currency code, in lowercase. Example: `usd`.
- `language` (string): Two-letter language code, in lowercase. One of `da`, `en`, `fr`, `de`, `it`, `no`, `pt`, `es`.

### Response

- `200`: Updated client. Returns a [client object](#the-client-object).

### Errors

- `400` `request_failed`: Your request could not be processed.
- `400` `api_version_unsupported`: The requested API version is not supported. Current version: 2026-08-21
- `401` `api_key_missing`: The API key is missing.
- `401` `api_key_invalid`: The API key is invalid or has been revoked.
- `403` `api_key_read_only`: This API key is read-only and cannot make write requests.
- `404`: The record doesn't exist or was deleted.
- `422`: The request body or query parameters are invalid.
- `429`: Too many requests. The limit is 300 requests per 5 minutes.

### Example request

```bash
curl -X POST https://api.tallymark.com/clients/0abcDEF1234567890xyzAB/update \
  -H "Authorization: Bearer $TALLYMARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Jane Smith",
  "address": "2 Main St"
}'
```

### Example response

```json
{
  "id": "0abcDEF1234567890xyzAB",
  "name": "Jane Doe",
  "emails": [
    "jane@example.com"
  ],
  "address": "1 Main St",
  "currency": "usd",
  "language": "en",
  "default_payment_method_id": "0abcDEF1234567890xyzAB",
  "payment_methods": [
    {
      "id": "0abcDEF1234567890xyzAB",
      "type": "card",
      "brand": "visa",
      "last_four": "4242",
      "exp_month": 12,
      "exp_year": 2030,
      "is_default": true,
      "created_at": "2024-06-15T12:00:00.000000Z",
      "updated_at": "2024-06-15T12:00:00.000000Z"
    }
  ],
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}
```

## Delete a client

`POST /clients/{id}/delete`

Deletes the client and pauses their active subscriptions. You can
restore the client later.

### Path parameters

- `id` (string, required): The client ID. Example: `0abcDEF1234567890xyzAB`.

### Response

- `200`: Deleted client (`is_deleted` true). Returns a [client object](#the-client-object).

### Errors

- `400` `request_failed`: Your request could not be processed.
- `400` `api_version_unsupported`: The requested API version is not supported. Current version: 2026-08-21
- `401` `api_key_missing`: The API key is missing.
- `401` `api_key_invalid`: The API key is invalid or has been revoked.
- `403` `api_key_read_only`: This API key is read-only and cannot make write requests.
- `404`: The record doesn't exist or was deleted.
- `429`: Too many requests. The limit is 300 requests per 5 minutes.

### Example request

```bash
curl -X POST https://api.tallymark.com/clients/0abcDEF1234567890xyzAB/delete \
  -H "Authorization: Bearer $TALLYMARK_API_KEY"
```

### Example response

```json
{
  "id": "0abcDEF1234567890xyzAB",
  "name": "Jane Doe",
  "emails": [
    "jane@example.com"
  ],
  "address": "1 Main St",
  "currency": "usd",
  "language": "en",
  "default_payment_method_id": "0abcDEF1234567890xyzAB",
  "payment_methods": [
    {
      "id": "0abcDEF1234567890xyzAB",
      "type": "card",
      "brand": "visa",
      "last_four": "4242",
      "exp_month": 12,
      "exp_year": 2030,
      "is_default": true,
      "created_at": "2024-06-15T12:00:00.000000Z",
      "updated_at": "2024-06-15T12:00:00.000000Z"
    }
  ],
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}
```

## Restore a deleted client

`POST /clients/{id}/restore`

Subscriptions paused when the client was deleted stay paused.
Activate them with `POST /subscriptions/{id}/activate`.

### Path parameters

- `id` (string, required): The client ID. Example: `0abcDEF1234567890xyzAB`.

### Response

- `200`: Restored client (`is_deleted` false). Returns a [client object](#the-client-object).

### Errors

- `400` `request_failed`: Your request could not be processed.
- `400` `api_version_unsupported`: The requested API version is not supported. Current version: 2026-08-21
- `401` `api_key_missing`: The API key is missing.
- `401` `api_key_invalid`: The API key is invalid or has been revoked.
- `403` `api_key_read_only`: This API key is read-only and cannot make write requests.
- `404`: The record doesn't exist or was deleted.
- `429`: Too many requests. The limit is 300 requests per 5 minutes.

### Example request

```bash
curl -X POST https://api.tallymark.com/clients/0abcDEF1234567890xyzAB/restore \
  -H "Authorization: Bearer $TALLYMARK_API_KEY"
```

### Example response

```json
{
  "id": "0abcDEF1234567890xyzAB",
  "name": "Jane Doe",
  "emails": [
    "jane@example.com"
  ],
  "address": "1 Main St",
  "currency": "usd",
  "language": "en",
  "default_payment_method_id": "0abcDEF1234567890xyzAB",
  "payment_methods": [
    {
      "id": "0abcDEF1234567890xyzAB",
      "type": "card",
      "brand": "visa",
      "last_four": "4242",
      "exp_month": 12,
      "exp_year": 2030,
      "is_default": true,
      "created_at": "2024-06-15T12:00:00.000000Z",
      "updated_at": "2024-06-15T12:00:00.000000Z"
    }
  ],
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}
```