Expanding responses

Many response fields hold the id of a related object — a PaymentIntent’s latest_charge is a ch_... string, a Charge’s customer is a cus_... string. Pass the expand[] parameter to have the API return the full related object inline instead of the id, saving you a second request.

expand[] is accepted as a query parameter on retrieve and list endpoints (Charges, Customers, Events, Payment Intents, Payment Methods, Refunds, Webhook Endpoints) and as a body parameter on write calls that return the object you are mutating (creating, updating, confirming, capturing, or canceling a PaymentIntent; creating or updating a Customer or Refund).

Expanding on a retrieve

$
curl -G https://api.fluveo.dev/v1/payment_intents/pi_3Nk8AzB2xQRH9Jf \
>
  -u sk_test_123: \
>
  -d "expand[]=latest_charge"

The response’s latest_charge is now the full Charge object rather than a ch_... id:

1
{
2
  "id": "pi_3Nk8AzB2xQRH9Jf",
3
  "object": "payment_intent",
4
  "latest_charge": {
5
    "id": "ch_3Nk8AzB2xQRH9Jf",
6
    "object": "charge",
7
    "status": "succeeded"
8
  }
9
}

Expanding on a write

Write endpoints accept expand in the form body, so the object you get back is already expanded:

$
curl https://api.fluveo.dev/v1/payment_intents \
>
  -u sk_test_123: \
>
  -d amount=4242 \
>
  -d currency=usd \
>
  -d "expand[]=latest_charge"

Expanding inside a list

On list endpoints the items live under data, so prefix the path with data. — the standard Stripe-shape convention:

$
curl -G https://api.fluveo.dev/v1/payment_intents \
>
  -u sk_test_123: \
>
  -d limit=10 \
>
  -d "expand[]=data.latest_charge"

What can be expanded

Expandable fields are the id-reference fields on each object — the API Reference is the source of truth for which fields each endpoint supports. Pass multiple expand[] entries to expand several fields in one request, and use dot notation to reach nested references. Requesting an expansion an endpoint does not support returns an invalid_request_error naming the offending param.

Expansion is a convenience for reads you would otherwise do anyway — expanding many fields across large list pages makes responses heavier and slower, so expand only what you consume.