Expandable Objects

Expandable objects are Stripe's way of returning a nested, fully-populated object inside a response instead of just its ID. By default many fields hold only a reference — for example a charge's customer field is a string like cus_123. Passing an expand parameter tells the API to replace that reference with the full object, so you get the data you need in a single request.

How expansion works

Add expand[] entries to a request, naming the fields you want inflated. Stripe supports dot notation to reach nested references and applies expansion to both individual retrievals and list endpoints.

A common example: retrieving a PaymentIntent and expanding its latest charge and the charge's balance transaction in one call, expand[]=latest_charge.balance_transaction, so you see the fee and net amount without a second lookup.

Why it matters

• Fewer round trips. One expanded request replaces two or three sequential calls, which also keeps you further from the rate limit.
• Simpler code. Related data arrives together, so you don't stitch responses back together by ID.
• Cost visibility. Expanding a charge's balance transaction is the standard way to read the Stripe fee and the net amount that lands in your balance.

Limits to keep in mind

Expansion has depth caps — Stripe limits how many levels you can inflate in one request, and list responses can only expand within data. Over-expanding also makes payloads larger and slower, so request only the references you actually consume. For high-volume ingestion, reading events and expanding just the fields your handler needs is usually the leaner path.