Saltar al contenido principal

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.

RequestResult
expand[]=customerFull customer object.
expand[]=payment_method.cardFull card object inside the payment method.
expand[]=customer.default_sourceFull source object on the customer.
expand[]=customer.default_source.card.fingerprintRejected: past the depth limit.

Decide when to expand​

Expansion trades request count for response size and latency.

SituationUse expansion
Rendering one payment with its customerYes. One request beats two.
Listing 100 charges for a reportNo. The payload grows past the useful size.
Checking a single related fieldNo. Read the field from the related endpoint.
Verifying a charge in a webhook handlerSometimes. Fetch the related object when the handler needs it.
consejo

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.
aviso

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​