Expanding nested objects
A response returns related objects as IDs, not as full objects. The expand parameter swaps a named ID for the object it points to, so one request returns the data instead of three.
Read an unexpanded response
{
"id": "pi_3Rsx4dDtWMrPDtgt0mUrePJ9",
"object": "payment_intent",
"amount": 2120,
"customer": "cus_QyJ8bT2vLk9mNp",
"payment_method": "pm_1Rsx4dDtWMrPDtgt"
}
The customer field holds an ID. Feeding that ID to GET /v1/customers/{id} returns the customer, which costs a second request and a second round trip.
Expand the field
Pass expand[] with the field name. Stripe returns the object inline.
curl -s -G https://api.stripe.com/v1/payment_intents/pi_3Rsx4dDtWMrPDtgt0mUrePJ9 \
-u "$STRIPE_SECRET_KEY:" \
-d "expand[]=customer"
{
"id": "pi_3Rsx4dDtWMrPDtgt0mUrePJ9",
"object": "payment_intent",
"customer": {
"id": "cus_QyJ8bT2vLk9mNp",
"object": "customer",
"email": "ada@example.com",
"created": 1735689600
}
}
The ID doesn't disappear. It moves into customer.id, so a client that reads only IDs keeps working after you add the expansion.
Expand more than one level
Dot notation reaches into a nested object. payment_method.card returns the card details inside the payment method.
curl -s -G https://api.stripe.com/v1/payment_intents/pi_3Rsx4dDtWMrPDtgt0mUrePJ9 \
-u "$STRIPE_SECRET_KEY:" \
-d "expand[]=customer" \
-d "expand[]=payment_method.card"
Expansion stops at four levels. Deeper paths return an error, because each level multiplies the work Stripe does per request.
| Request | Result |
|---|---|
expand[]=customer | Full customer object. |
expand[]=payment_method.card | Full card object inside the payment method. |
expand[]=customer.default_source | Full source object on the customer. |
expand[]=customer.default_source.card.fingerprint | Rejected: past the depth limit. |
Decide when to expand
Expansion trades request count for response size and latency.
| Situation | Use expansion |
|---|---|
| Rendering one payment with its customer | Yes. One request beats two. |
| Listing 100 charges for a report | No. The payload grows past the useful size. |
| Checking a single related field | No. Read the field from the related endpoint. |
| Verifying a charge in a webhook handler | Sometimes. Fetch the related object when the handler needs it. |
Expand on a POST as well as a GET. Pass expand[] in the request body to skip a follow-up read after you create an object.
Expand inside a list
The expand[] parameter works on list endpoints. Expanding a related object on a 100-item page repeats that object on every row and inflates the response. Expand a list only when each row needs the nested data.
Attach your own identifiers with metadata
metadata holds key-value pairs that travel with the object. Use it to link a Stripe object to a record in your own database.
curl https://api.stripe.com/v1/payment_intents \
-u "$STRIPE_SECRET_KEY:" \
-d "amount=2120" \
-d "currency=usd" \
-d "metadata[order_id]=ord_8842" \
-d "metadata[tenant]=acme"
{
"id": "pi_3Rsx4dDtWMrPDtgt0mUrePJ9",
"metadata": {
"order_id": "ord_8842",
"tenant": "acme"
}
}
Rules for metadata:
- Limits. An object holds up to 50 keys. A key allows 40 characters and a value allows 500.
- Not for secrets. Stripe staff can read metadata, and it appears in the Dashboard and in exports.
- Empty removes. Send an empty string to delete a key on update.
- Searchable in some places. The Dashboard search reads metadata on many objects, while API list filters don't.
Keep personally identifiable information out of metadata unless your data policy allows it. Customer names, email addresses, and card fragments belong in the fields Stripe provides, not in a free-text store.
Verify the expansion
Send the request twice, once with expand[] and once without, and compare the customer field. The unexpanded response holds a string. The expanded response holds an object with an id key.
curl -s -G https://api.stripe.com/v1/payment_intents/pi_3Rsx4dDtWMrPDtgt0mUrePJ9 \
-u "$STRIPE_SECRET_KEY:" \
-d "expand[]=customer" | jq '.customer | type'
The output reads "object". Drop the flag and the same command prints "string".
Next steps
- Pagination and list endpoints for walking a collection with expansion in place.
- Retrieve a balance transaction for an expandable
sourcefield. - Create a Payment Intent for the
expand[]body parameter.