The Customer object

{
  "id": "cus_01JEXAMPLE2K8V4N9C6M1Q7R",
  "object": "customer",
  "email": "[email protected]",
  "first_name": "Jenny",
  "last_name": "Rosen",
  "phone": "+15555550100",
  "billing_address": null,
  "payment_settings": {
    "default_payment_method": "pm_01JEXAMPLE2K8V4N9C6M1Q7R"
  },
  "metadata": {},
  "deleted": false,
  "livemode": false
}

{
  "id": "cus_01JEXAMPLE2K8V4N9C6M1Q7R",
  "object": "customer",
  "email": "[email protected]",
  "first_name": "Jenny",
  "last_name": "Rosen",
  "phone": "+15555550100",
  "billing_address": null,
  "payment_settings": {
    "default_payment_method": "pm_01JEXAMPLE2K8V4N9C6M1Q7R"
  },
  "metadata": {},
  "deleted": false,
  "livemode": false
}

{
  "id": "cus_01JEXAMPLE2K8V4N9C6M1Q7R",
  "object": "customer",
  "email": "[email protected]",
  "first_name": "Jenny",
  "last_name": "Rosen",
  "phone": "+15555550100",
  "billing_address": null,
  "payment_settings": {
    "default_payment_method": "pm_01JEXAMPLE2K8V4N9C6M1Q7R"
  },
  "metadata": {},
  "deleted": false,
  "livemode": false
}

Customers store buyer identity, contact details, addresses, metadata, and payment settings that can be reused across checkout and support workflows. Use the generated endpoint pages for exact request and response payloads.

Attributes

string

Unique customer identifier (cus_…).

string

Customer email address.

string

Empty string when not set.

string

Empty string when not set.

string

Empty string when not set.

object | null

Billing address; null when not set.

object

Payment configuration stored for the customer.

object

Custom key-value pairs for your use.

boolean

True when the customer has been soft-deleted.

See every field in the response of Retrieve a customer.

Endpoints

Endpoint	Use it for
Create customer	Create a merchant-scoped customer.
List customers	Page through customer records.
Get customer	Retrieve one customer by `cus_` ID.
Update customer	Change contact fields, addresses, or metadata.

Notes

email is required on create. See the create endpoint for optional fields.
billing_address and shipping are optional on create.
On update, omitted address fields are left unchanged. Explicit null clears the nested value when supported by the handler.
Customer list responses include summary data such as payment counts and spend by currency.

Fundamentals

Payments

Checkout

In-person payments

Customers and catalog

Connect

Billing

Webhooks

Attributes

Endpoints

Notes

​Attributes

​Endpoints

​Notes

Attributes

Endpoints

Notes