TallymarkTallymark
Log inGet started for free

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.

View as Markdown

The client object

  • Name
    id
    Type
    string
    Description

    Example: 0abcDEF1234567890xyzAB.

  • Name
    name
    Type
    string
  • Name
    emails
    Type
    array of string
    Description

    Min 1 items.

  • Name
    address
    Type
    string or null
  • Name
    currency
    Type
    string
    Description

    Three-letter currency code, in lowercase. Example: usd.

  • Name
    language
    Type
    string
    Description

    Two-letter language code, in lowercase. One of da, en, fr, de, it, no, pt, es.

  • Name
    default_payment_method_id
    Type
    string or null
    Description

    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.

  • Name
    created_at
    Type
    timestamp
    Description

    Date and time in UTC. Example: 2024-06-15T12:00:00.000000Z.

  • Name
    updated_at
    Type
    timestamp
    Description

    Date and time in UTC. Example: 2024-06-15T12:00:00.000000Z.

  • Name
    is_deleted
    Type
    boolean
  • Name
    payment_methods
    Type
    array of object
    Description

    Cards the client saved when paying in the app, newest first. Cards can't be added through the API.

  • Name
    payment_methods[].id
    Type
    string
    Description

    Example: 0abcDEF1234567890xyzAB.

  • Name
    payment_methods[].type
    Type
    string
    Description

    One of card.

  • Name
    payment_methods[].brand
    Type
    string
    Description

    Example: visa.

  • Name
    payment_methods[].last_four
    Type
    string
    Description

    Example: 4242.

  • Name
    payment_methods[].exp_month
    Type
    integer
    Description

    Min 1. Max 12.

  • Name
    payment_methods[].exp_year
    Type
    integer
  • Name
    payment_methods[].is_default
    Type
    boolean
    Description

    True for the card used when paying without a payment_method_id.

  • Name
    payment_methods[].created_at
    Type
    timestamp
    Description

    Date and time in UTC. Example: 2024-06-15T12:00:00.000000Z.

  • Name
    payment_methods[].updated_at
    Type
    timestamp
    Description

    Date and time in UTC. Example: 2024-06-15T12:00:00.000000Z.

The client object

{
  "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
}
GET/clients

List clients

Query parameters

  • Name
    search
    Type
    string
    Description

    Matches name, emails, and address. Not case-sensitive. Example: jane.

  • Name
    limit
    Type
    integer
    Description

    Number of results per page. Default: 10. Min 1. Max 100.

  • Name
    cursor
    Type
    string
    Description

    To get the next page, pass the next_cursor from the previous response.

  • Name
    created_at
    Type
    object
    Description

    Keys gt, gte, lt, lte. Example: created_at[gt]=2024-06-15T12:00:00.000000Z.

  • Name
    updated_at
    Type
    object
    Description

    Keys gt, gte, lt, lte. Example: updated_at[gt]=2024-06-15T12:00:00.000000Z.

Response

Errors

  • Name
    400
    Type
    request_failed
    Description

    Your request could not be processed.

  • Name
    400
    Type
    api_version_unsupported
    Description

    The requested API version is not supported. Current version: 2026-08-21

  • Name
    401
    Type
    api_key_missing
    Description

    The API key is missing.

  • Name
    401
    Type
    api_key_invalid
    Description

    The API key is invalid or has been revoked.

  • Name
    422
    Description

    The request body or query parameters are invalid.

  • Name
    429
    Description

    Too many requests. The limit is 300 requests per 5 minutes.

Request

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

Response

{
  "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
}
POST/clients

Create or update a client

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
    name
    Type
    string
    Required
    required
    Description

    Max length 255.

  • Name
    email
    Type
    string or array of string
    Required
    required
    Description

    One email address, or a list of up to 4. Example: jane@example.com.

  • Name
    address
    Type
    string or null
  • Name
    currency
    Type
    string
    Required
    required
    Description

    Three-letter currency code, in lowercase. Example: usd.

  • Name
    language
    Type
    string
    Required
    required
    Description

    Two-letter language code, in lowercase. One of da, en, fr, de, it, no, pt, es.

Response

Errors

  • Name
    400
    Type
    request_failed
    Description

    Your request could not be processed.

  • Name
    400
    Type
    api_version_unsupported
    Description

    The requested API version is not supported. Current version: 2026-08-21

  • Name
    401
    Type
    api_key_missing
    Description

    The API key is missing.

  • Name
    401
    Type
    api_key_invalid
    Description

    The API key is invalid or has been revoked.

  • Name
    403
    Type
    api_key_read_only
    Description

    This API key is read-only and cannot make write requests.

  • Name
    422
    Description

    The request body or query parameters are invalid.

  • Name
    429
    Description

    Too many requests. The limit is 300 requests per 5 minutes.

Request

POST/clients
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"
}'

Response

{
  "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
}
GET/clients/{id}

Show a client

Path parameters

  • Name
    id
    Type
    string
    Required
    required
    Description

    The client ID. Example: 0abcDEF1234567890xyzAB.

Response

Errors

  • Name
    400
    Type
    request_failed
    Description

    Your request could not be processed.

  • Name
    400
    Type
    api_version_unsupported
    Description

    The requested API version is not supported. Current version: 2026-08-21

  • Name
    401
    Type
    api_key_missing
    Description

    The API key is missing.

  • Name
    401
    Type
    api_key_invalid
    Description

    The API key is invalid or has been revoked.

  • Name
    404
    Description

    The record doesn't exist or was deleted.

  • Name
    429
    Description

    Too many requests. The limit is 300 requests per 5 minutes.

Request

GET/clients/{id}
curl https://api.tallymark.com/clients/0abcDEF1234567890xyzAB \
  -H "Authorization: Bearer $TALLYMARK_API_KEY"

Response

{
  "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
}
POST/clients/{id}/update

Update a client

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

Path parameters

  • Name
    id
    Type
    string
    Required
    required
    Description

    The client ID. Example: 0abcDEF1234567890xyzAB.

Request body

  • Name
    name
    Type
    string
    Description

    Max length 255.

  • Name
    email
    Type
    string or array of string
    Description

    One email address, or a list of up to 4. Example: jane@example.com.

  • Name
    address
    Type
    string or null
  • Name
    currency
    Type
    string
    Description

    Three-letter currency code, in lowercase. Example: usd.

  • Name
    language
    Type
    string
    Description

    Two-letter language code, in lowercase. One of da, en, fr, de, it, no, pt, es.

Response

Errors

  • Name
    400
    Type
    request_failed
    Description

    Your request could not be processed.

  • Name
    400
    Type
    api_version_unsupported
    Description

    The requested API version is not supported. Current version: 2026-08-21

  • Name
    401
    Type
    api_key_missing
    Description

    The API key is missing.

  • Name
    401
    Type
    api_key_invalid
    Description

    The API key is invalid or has been revoked.

  • Name
    403
    Type
    api_key_read_only
    Description

    This API key is read-only and cannot make write requests.

  • Name
    404
    Description

    The record doesn't exist or was deleted.

  • Name
    422
    Description

    The request body or query parameters are invalid.

  • Name
    429
    Description

    Too many requests. The limit is 300 requests per 5 minutes.

Request

POST/clients/{id}/update
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"
}'

Response

{
  "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
}
POST/clients/{id}/delete

Delete a client

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

Path parameters

  • Name
    id
    Type
    string
    Required
    required
    Description

    The client ID. Example: 0abcDEF1234567890xyzAB.

Response

  • Name
    200
    Description

    Deleted client (is_deleted true). Returns a client object.

Errors

  • Name
    400
    Type
    request_failed
    Description

    Your request could not be processed.

  • Name
    400
    Type
    api_version_unsupported
    Description

    The requested API version is not supported. Current version: 2026-08-21

  • Name
    401
    Type
    api_key_missing
    Description

    The API key is missing.

  • Name
    401
    Type
    api_key_invalid
    Description

    The API key is invalid or has been revoked.

  • Name
    403
    Type
    api_key_read_only
    Description

    This API key is read-only and cannot make write requests.

  • Name
    404
    Description

    The record doesn't exist or was deleted.

  • Name
    429
    Description

    Too many requests. The limit is 300 requests per 5 minutes.

Request

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

Response

{
  "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
}
POST/clients/{id}/restore

Restore a deleted client

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

Path parameters

  • Name
    id
    Type
    string
    Required
    required
    Description

    The client ID. Example: 0abcDEF1234567890xyzAB.

Response

  • Name
    200
    Description

    Restored client (is_deleted false). Returns a client object.

Errors

  • Name
    400
    Type
    request_failed
    Description

    Your request could not be processed.

  • Name
    400
    Type
    api_version_unsupported
    Description

    The requested API version is not supported. Current version: 2026-08-21

  • Name
    401
    Type
    api_key_missing
    Description

    The API key is missing.

  • Name
    401
    Type
    api_key_invalid
    Description

    The API key is invalid or has been revoked.

  • Name
    403
    Type
    api_key_read_only
    Description

    This API key is read-only and cannot make write requests.

  • Name
    404
    Description

    The record doesn't exist or was deleted.

  • Name
    429
    Description

    Too many requests. The limit is 300 requests per 5 minutes.

Request

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

Response

{
  "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
}