Clients

The customers and members you invoice.

Operations

Create a client

Required on create: client_type (client or member), name, country (ISO 3166-1 alpha-2), currency, locale, and collection_method. client_number is never accepted — it is auto-generated. As a create it takes an Idempotency-Key.

curl -X POST https://billey.nl/api/v1/clients \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "client_type": "client",
    "name": "Example Client B.V.",
    "email": "billing@example.nl",
    "country": "NL",
    "currency": "EUR",
    "locale": "nl",
    "collection_method": "invoice"
  }'

{
  "data": {
    "id": 7,
    "client_number": "2026-0007",
    "client_type": "client",
    "name": "Example Client B.V.",
    "email": "billing@example.nl",
    "country": "NL",
    "currency": "EUR",
    "locale": "nl",
    "collection_method": "invoice",
    "created_at": "2026-07-21T10:15:30Z"
  }
}

When collection_method is direct_debit, an iban and mandate_date are required.

Update a client

PATCH is a partial merge — send only what changes (see PATCH behaviour). Touching any of collection_method, iban, or mandate_date validates the resulting record, so switching to direct_debit without an IBAN on file fails.

Delete a client

DELETE soft-deletes the client and returns 204. It is refused with 409 if the client has accounting history (a non-draft invoice) or still-live references (quotes, recurring schedules); the client's own draft invoices cascade.

See the OpenAPI spec for the full field list.