Pre-1.0 · one maintainer · Stripe and cards only · no SDKs (client libraries) yet · no production users yet. Docs describe v0.9.1 (29 Oct 2026) · What’s new →

Update customer

PATCH

/v1/customers/{id}

const url = 'http://localhost:8080/v1/customers/example';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"display_name":"example","email":"example","status":"active","dunning_policy_id":"example","additional_emails":["example"]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PATCH \
  --url http://localhost:8080/v1/customers/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "display_name": "example", "email": "example", "status": "active", "dunning_policy_id": "example", "additional_emails": [ "example" ] }'

Changes only the fields you send. An empty display_name or email is ignored, so you cannot clear the email here.

status: archived is refused with 409 invalid_state while the customer has a subscription that still bills. Cancel those subscriptions first. Archiving does not stop dunning on unpaid invoices.
dunning_policy_id set to "" removes the assignment, so the tenant’s default policy applies. A set ID must be a policy in this tenant and mode, or the call returns 404. The change applies to the next dunning run, not to runs already started.
additional_emails replaces the whole CC list; [] clears it. Entries are lowercased, deduplicated, capped at 10 and may not equal the primary email.
A new email that is already on the CC list is refused with 422 unless you send a new additional_emails too. Changing the email resets its bounce state.

Name and email changes are copied to the linked Stripe customer when there is one. A Stripe failure is logged and does not fail the call. The change is written to the audit log (it records that the email changed, not the address).

Authorizations

BearerAuth

Parameters

Path Parameters

required

string

Header Parameters

Idempotency-Key

string

Makes the call safe to retry. Send a unique value (a UUID works) and the same value on every retry. For 24 hours, a repeat with the same key, method, path and body gets the first response again, with an Idempotent-Replayed: true header, instead of running again. The error cases are in docs/api-surface.md. The usage routes do not take it: each usage event carries its own idempotency_key.

Request Body^required

application/json

object

display_name

string

email

string

status

string

Allowed values: active archived

dunning_policy_id

Policy ID, or "" to use the tenant default.

string

additional_emails

Array<string>

<= 10 items

Responses

200

The updated customer.

application/json

object

required

string

external_id

required

string

display_name

required

string

email

string

additional_emails

CC’d on billing documents and billing-state emails (invoice, receipt, dunning, payment failed, credit note) — never on credential-bearing emails (setup links, resets, invites). Normalized to lowercase bare addresses, deduped, capped at 10, never equal to the primary email. Stored encrypted at rest.

Array<string>

<= 10 items

status

required

string

Allowed values: active archived

created_at

required

string format: date-time

test_clock_id

Test clock this customer is pinned to (test mode only). When set, the customer — and any invoices/subscriptions created for it — run on the clock’s simulated time. Empty for live customers. The dashboard reads it to show the “test clock” badge + simulated-time banner on the customer and its invoices.

string

tenant_id

string

email_status

Deliverability of email, learned from bounce and complaint reports.

string

Allowed values: unknown ok bounced complained

email_last_bounced_at

string format: date-time

email_bounce_reason

string

dunning_policy_id

Assigned dunning policy; absent means the tenant default.

string

stripe_customer_id

The Stripe customer. Absent until the first payment-method action.

string

livemode

boolean

updated_at

required

string format: date-time

Example

{
  "id": "hc_cus_42014438d82ddf33",
  "status": "active",
  "email_status": "unknown"
}

400

The body is not valid JSON.

application/json

object

error

object

type

One of invalid_request_error, authentication_error, rate_limit_error or api_error. Every error the API answers has this shape, including an unknown path (404, code route_not_found) and a method the path does not take (405, code method_not_allowed, with an Allow header). The few exceptions are listed in docs/api-surface.md.

string

code

string

message

string

request_id

string

param

The request field the error is about. Sent only when the error names one. A request body may hold only the fields its operation lists, spelled and cased as listed: any other field, or one the server sets (such as id), is refused with 422 and param naming it. An operation with no request body lists no fields: send no body, {} or null. The Stripe and Postmark webhooks and the LiteLLM callback take their sender’s body as it comes.

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}

404

Customer, or the named dunning policy, not found.

application/json

object

error

object

type

string

code

string

message

string

request_id

string

param

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}

409

Archive refused because a subscription still bills (invalid_state).

application/json

object

error

object

type

string

code

string

message

string

request_id

string

param

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}

422

An email or CC entry is invalid (param names the field).

application/json

object

error

object

type

string

code

string

message

string

request_id

string

param

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}

Update customer

Authorizations

Parameters

Path Parameters

Header Parameters

Request Bodyrequired

Responses

200

Example

400

Example

404

Example

409

Example

422

Example

Request Body^required