The Stripe Customers API lets you create, update and retrieve customers and their related subscriptions, invoices, and payment methods. This is the human-friendly guide to the API.
The most common operations people perform with customers in the Stripe API.
| Action | HTTP Method | Endpoint |
|---|---|---|
|
Create a Customer
|
POST
|
/v1/customers
|
|
Update a Customer
|
POST
|
/v1/customers/:id
|
|
Retrieve a Customer
|
GET
|
/v1/customers/:id
|
|
List All Customers
|
GET
|
/v1/customers
|
|
Search Customers
|
GET
|
/v1/customers/search
|
|
Delete a Customer
|
DELETE
|
/v1/customers/:id
|
Customers are identified by a unique ID that starts with cus_. You need this ID in order to
get, update, or delete a customer. These operations are performed using
the HTTP methods GET, POST, and
DELETE on the same endpoint.
The customer ID is part of the URL.
When creating a customer, you typically provide an email address and name. Optionally, you can set additional information like address, phone number, payment methods, and metadata for storing custom data.
If you don't have the ID of a customer, you can search for customers by email, name, or other properties using the search endpoint.
The 10 most important properties a customer can have in the Stripe API. Some properties are required, some are optional, and some are read-only. Show all properties Only show essential properties
| Field Name | Type | Short Description |
|---|---|---|
| id | string | Unique identifier for the customer |
| string | Customer's email address | |
| name | string | Customer's full name or business name |
| description | string | Arbitrary description for the customer |
| phone | string | Customer's phone number |
| address | object | Customer's address information |
| shipping | object | Customer's shipping address |
| created | timestamp | Time when the customer was created |
| balance | integer | Current balance of the customer in cents |
| metadata | object | Set of key-value pairs for storing additional information |
| object | string | String representing the object's type. Always "customer" |
| cash_balance | object | Customer's cash balance, if enabled |
| currency | string | Three-letter ISO currency code |
| default_source | string | ID of the default payment source |
| delinquent | boolean | Whether the customer is delinquent on payments |
| discount | object | Current discount applied to the customer |
| invoice_credit_balance | object | Customer's current credit balance |
| invoice_prefix | string | Prefix for invoice numbers for this customer |
| invoice_settings | object | Customer's invoice settings |
| livemode | boolean | Whether this is a live mode or test mode object |
| next_invoice_sequence | integer | Sequence number for the next invoice |
| preferred_locales | array | Customer's preferred languages |
| sources | object | Customer's payment sources |
| subscriptions | object | Customer's current subscriptions |
| tax | object | Tax details for the customer |
| tax_exempt | string | Tax exemption status: "none", "exempt", or "reverse" |
| tax_ids | object | Customer's tax IDs |
| test_clock | string | ID of the test clock for this customer |
Did you know that deleting a customer also cancels all their subscriptions? Or that customer IDs are permanent and can't be reused? Here are some common pitfalls and gotchas when working with customers in the Stripe API.
Customer IDs like cus_1234567890 are permanent and cannot be changed or reused. Once a customer is deleted, their ID cannot be assigned to a new customer.
When you delete a customer, all their active subscriptions are immediately canceled. Consider pausing or updating subscriptions instead of deleting the customer.
Stripe doesn't enforce email uniqueness across customers. You can have multiple customers with the same email address, so implement your own uniqueness checks if needed.
Customer balance is always in the smallest currency unit (cents for USD). A balance of 1000 means $10.00, not $1000.00.
Metadata can have up to 50 keys, with key names up to 40 characters and values up to 500 characters. Exceeding these limits will cause API errors.
Setting a default_source doesn't automatically charge the customer. It's only used when creating charges or subscriptions without specifying a payment method.
For tax calculations, you may need to provide customer address information. Missing address data can cause tax calculation failures in some jurisdictions.
Customer search is not available in all regions and has rate limits. For high-volume lookups, consider maintaining your own customer index.
