BillKit/Docs Console
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 · Spec snapshot 2026-09-13

Parameters

ParameterDescription
country_codestring | nulloptionalAt most 2 characters.
emailstring (email) | nulloptionalMust be a valid email address.
metadataobject | nulloptionalAt most 50 keys.
namestring | nulloptionalAt most 255 characters.
test_clockstring | nulloptionalAt 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.

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

Status Cause
401 Missing or invalid API key.
403 Key is missing the customers:write scope.
422 Validation Error
429 Rate limited. Back off and retry.
Request · curl 
curl -X POST https://api.billkit.eu/v1/customers \
  -H "Authorization: Bearer $BILLKIT_SECRET_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": "string"
}
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": "string",
  "vat_number": "string",
  "vat_number_validated": false
}