Customer
The Customer entity in Payments.
A Customer represents a buyer (or payer) you transact with. It is the durable identity that owns Payment Instruments, Orders, Subscriptions, and Disputes — every charge in Payments either belongs to a Customer or is created on the fly during checkout (which still creates a Customer behind the scenes). Use a Customer when you need to remember the buyer across sessions: saved cards, recurring billing, refunds against the right account, dispute correlation.
Lifecycle
- Created —
client.createCustomer({ first_name, last_name, email, phone, personal_address })returns aCustomerDatarecord with anid. No webhook fires for creation; the API response is the source of truth. - Used — the
idis passed asidentityIdwhen creating a Payment Instrument, or asidentity_idon a Subscription / Embedded Checkout session. - Updated —
client.updateCustomer(customerId, partial)patches mutable fields. Tags accept arbitrary JSON for your own bookkeeping. - Identity events —
identity.createdandidentity.updatedwebhook events fire when the underlying processor identity changes (typically the same lifecycle, but they are the audit trail you should subscribe to if you mirror customer state into your own database).
Customers are not deleted via the API. To stop charging a Customer, disable their Payment Instruments or cancel their Subscriptions instead.
Relationships
Every Order, Transfer, and Subscription ultimately resolves to a Customer (the payer). A Customer can own many Payment Instruments (cards, bank accounts) and many Wallets (Solana addresses for crypto checkout). Disputes are reachable through the Transfer that was charged on one of the Customer's Payment Instruments.
Fields that matter
id(string) — the canonical Customer ID. Pass this asidentityIdwhen creating a Payment Instrument and asidentity_idfor subscriptions.entity.first_name,entity.last_name,entity.email,entity.phone(string) — buyer contact info. Required at creation.entity.personal_address(Address | null) — used for AVS on card transactions; pass it when you have it.tags(Record<string, string>) — your own metadata (internal user IDs, plan tier, etc.). Searchable; keep keys stable.identity_roles(string[]) — processor-side flags (e.g. whether this identity has merchant capabilities). Read-only.