BillKit/DocsConsole
Customers

Create a customer

Creates the party you bill. Every field is optional, so you can open the record with whatever you know and fill the rest in later.

POST/v1/customers
Operation create_customer·Scope customers:write·OpenAPI v1.1.0

Parameters

ParameterDescription
country_codestring | nulloptionalTwo-letter ISO 3166-1 country code, stored uppercase. Selects the tax rate the customer is charged. When unset, BillKit fills it from the country seen at checkout or on a payment. At most 2 characters.
emailstring (email) | nulloptionalThe customer's email address. Not unique: two customers can share one. Must be a valid email address.
metadataobject | nulloptionalKey-value pairs stored on the customer and returned with it. At most 50 keys.
namestring | nulloptionalThe customer's full name or business name. At most 255 characters.
test_clock_idstring | nulloptionalTest mode only: the test clock to attach the customer to. Refused on a live-mode key. At most 64 characters.

Returns

The created customer. Use metadata to carry your own identifiers so records reconcile without a lookup table.

A customer on its own cannot be charged. Payment needs a mandate, and a mandate comes from Checkout.

test_clock_id attaches the customer to a test clock, and can only be set here. It is a 400 with a live-mode key and a 404 for a clock that does not exist.

BillKit never deduplicates customers by email. Two calls with the same address create two customers. Key on your own identifier and store the returned id.

Test it

Create the customer, then send them through Checkout to attach a mandate and start their first subscription.

Errors

StatusCause
400The request was refused (type: invalid_request_error): a required parameter is missing (parameter_missing), one failed validation (parameter_invalid) or is not one the operation takes (parameter_unknown), and param names it.
401No credential, or one that does not authenticate.
402The account is suspended (tenant_suspended), or the payment provider refused a charge or refund the call made (type: payment_error, code: payment_refused).
403Authenticated, but not allowed: missing scope (insufficient_scope), a key of the wrong mode (mode_mismatch), or a refused origin. Needs the customers:write scope.
404No such object in this account and mode.
409Conflicts with the object's current state (state_conflict, or a more specific code), or an operation still in flight (operation_pending).
413The request body is larger than the API accepts.
429Rate limited. Retry-After says when to try again.
500Something failed on BillKit's side (type: api_error). Retry with the same Idempotency-Key.
502The payment provider failed or did not answer.
503Temporarily unable to serve. reason says whether the request was attempted.
Request · curl
curl -X POST https://api.billkit.eu/v1/customers \
  -H "Authorization: Bearer $BILLKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Request body · every field
{
  "country_code": "NL",
  "email": "ada@example.com",
  "metadata": {
    "key": "value"
  },
  "name": "Ada Lovelace",
  "test_clock_id": "tc_9XKp2vQ1"
}
Response · 200 OK
{
  "country_code": "NL",
  "created": 1789392000,
  "email": "ada@example.com",
  "id": "cus_9XKp2vQ1",
  "livemode": false,
  "metadata": {
    "key": "value"
  },
  "name": "Ada Lovelace",
  "object": "customer",
  "provisional": false,
  "stats": {
    "currency": "EUR",
    "lifetime_cents": 1900,
    "object": "customer.stats",
    "subscription_count": 0
  },
  "test_clock_id": "tc_9XKp2vQ1",
  "vat_number": "string",
  "vat_number_validated": false
}