BillKit/DocsConsole
Customers

Retrieve a customer

Fetches one customer by id, including their country, VAT status and the test clock they are attached to.

GET/v1/customers/{customer_id}
Operation get_customer·Scope customers:read·OpenAPI v1.1.0

Parameters

ParameterDescription
customer_idstring · pathrequiredId of the customer, which starts cus_.

Returns

The customer object. A customer belonging to the other mode, or to another account, is a 404 rather than a 403, so no id existence leaks across tenants.

Deleted and purged customers are a 404 here too. Their invoices and payments still resolve; the customer itself stops being readable.

Test it

Compare the response against the same record in the console under Customers. The two views are the same row.

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:read scope.
404No such object in this account and mode.
429Rate limited. Retry-After says when to try again.
500Something failed on BillKit's side (type: api_error). Retry with the same Idempotency-Key.
503Temporarily unable to serve. reason says whether the request was attempted.
Request · curl
curl -X GET https://api.billkit.eu/v1/customers/cus_9XKp2vQ1 \
  -H "Authorization: Bearer $BILLKIT_API_KEY"
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
}