Expandable Objects

Expandable objects are fields in a Stripe API response that hold an ID by default but can return the full object instead. For example, a charge's customer field is a string like cus_123. If you pass expand[]=customer, Stripe returns the whole customer object in that field.

How expansion works

Add one expand[] parameter for each field you want in full. Use dot notation to reach nested fields. Expansion works on single retrievals and on list endpoints.

For example, you can retrieve a PaymentIntent with expand[]=latest_charge.balance_transaction. One call returns the charge and its balance transaction, which holds the Stripe fee and the net amount.

Why use it

• One expanded request replaces two or three separate calls, which also keeps you further from the rate limit.
• Related data arrives together, so you don't have to join responses by ID.
• Expanding a charge's balance transaction is the standard way to read the fee and net amount.

Limits

Stripe allows up to four levels of expansion in one request. On list endpoints, prefix the field with data, as in expand[]=data.customer. Each expansion makes the response larger and slower, so expand only the fields you use.