Customers

A customer is the buyer. They own payment methods, subscriptions, and invoices. Every other monetary object descends from a customer.

Object

{
  "id": "cus_…",
  "object": "customer",
  "email": "ada@example.com",
  "name": "Ada Lovelace",
  "phone": "+14155551212",
  "billing_address": {
    "line1": "100 Market St",
    "line2": null,
    "city": "San Francisco",
    "region": "CA",
    "country": "US",
    "postal_code": "94105"
  },
  "shipping_address": null,
  "default_payment_method_id": "pm_…",
  "currency": "USD",
  "tax_exempt": "none",
  "tax_ids": [
    { "type": "us_ein", "value": "12-3456789", "verified": true }
  ],
  "metadata": { "your_user_id": "u_28471" },
  "external_ids": { "stripe": "cus_…", "your_app": "u_28471" },
  "balance": { "amount": "0.00", "currency": "USD" },
  "delinquent": false,
  "created_at": "2026-05-06T12:34:56Z",
  "updated_at": "2026-05-06T12:34:56Z"
}

Endpoints

Method	Path	What
POST	/v1/customers	Create.
GET	/v1/customers/{id}	Retrieve.
PATCH	/v1/customers/{id}	Update mutable fields.
DELETE	/v1/customers/{id}	Soft-delete.
GET	/v1/customers	List + filter.
POST	/v1/customers/{id}/payment-methods	Attach payment method.
GET	/v1/customers/{id}/payment-methods	List payment methods.
POST	/v1/customers/{id}/tax-ids	Add a tax ID.
DELETE	/v1/customers/{id}/tax-ids/{tax_id}	Remove a tax ID.
POST	/v1/customers/{id}/discounts	Apply a customer-level coupon.
GET	/v1/customers/{id}/subscriptions	List the customer’s subscriptions.
GET	/v1/customers/{id}/invoices	List the customer’s invoices.
GET	/v1/customers/{id}/upcoming-invoice	Preview the next invoice (if any).

Lifecycle

Customers don’t have a state machine. They exist or they’re soft-deleted (deleted_at set; not retrievable by GET, but referenced by their existing invoices).

The delinquent flag is computed: true while any subscription is in past_due or any invoice is in dunning. Use it in your UI to surface a “please update payment method” banner.

Mutable fields

email, name, phone, billing_address, shipping_address, default_payment_method_id, tax_exempt, metadata, external_ids.

Soft delete

DELETE /v1/customers/{id}

The customer is marked deleted. Existing invoices and ledger entries are preserved (financial records are immutable). The customer is excluded from list responses but still resolvable by ID for historical lookups via GET /v1/customers/{id}?include_deleted=true.

A deleted customer can be undeleted within 30 days:

POST /v1/customers/{id}/undelete

After 30 days the email is freed for reuse and the soft-delete becomes permanent.

Webhook events

customer.created, customer.updated, customer.deleted, customer.payment_method_attached, customer.payment_method_detached, customer.tax_id_invalidated.