Expanding Resources

Many objects allow you to request additional information as an expanded response by using the expand query parameter. This parameter is available on all API requests, and applies to the response of that request only. You can expand responses in two ways.

In many cases, an object contains the ID of a related object in its response properties. For example, a Checkout Session might have an associated Customer ID. You can expand these objects in line with the expand request parameter, in this specific example expand_customer=true would be the query parameter used. The expandable label in this documentation indicates ID fields that you can expand into objects.

Some available fields aren’t included in the responses by default. You can request these fields as an expanded response by using the expand request parameter.

You can use the expand parameter on any endpoint that returns expandable fields.

You can expand multiple objects at the same time by identifying multiple query params.

Example use case

This can be helpful for scenarios where I’d like to fetch multiple details of objects. For example, if I have a payment intent ID and want to:

Find the checkout session that payment intent corresponds to
Retrieve the customer object that belongs to the checkout session

I can do all of the above by adding the following query params to the list checkout session request

payment_intent=fpi_01HWBS24Z8EFZ7VHJTSEWF2DPQ - Fetch the checkout session that belongs to this payment intent
expand_customer=true - Expand the customer object

curl --request GET \
  --url 'https://api.withflex.com/v1/checkout/sessions?payment_intent=fpi_01HWBS24Z8EFZ7VHJTSEWF2DPQ&expand_customer=true' \
  --header 'authorization: Bearer fsk_test_YzNiYjdhNWItN2FkOS00ZTMyLWE5MmQtZTdhNzMzYzE2NTIy' \
  --header 'content-type: application/json' \
  --header 'user-agent: vscode-restclient'

And we get back the checkout session object with the customer object expanded:

{
  "checkout_sessions": [
    {
      "allow_promotion_codes": false,
      "amount_total": 7000,
      "amount_subtotal": 7000,
      "cancel_url": "https://withflex.com/thank-you?canceled=true",
      "capture_method": "automatic",
      "checkout_session_id": "fcs_01HWBRQCHTEVYWYT31N3QEGS9S",
      "created_at": 1714086982,
      "customer": {
        "customer_id": "fcus_01HWBRQPYZAG0P5S486AMZG18Y",
        "first_name": "Miguel",
        "last_name": "Toledo",
        "email": "miguel@hola.coml",
        "phone": "1234567890",
        "employer": null,
        "shipping": null,
        "created_at": "2024-04-25T23:16:32.866283Z"
      },
      "customer_email": "miguel@hola.coml",
      "defaults": null,
      "expires_at": 1714090582,
      "invoice": null,
      "hsa_fsa_eligible": true,
      "letter_of_medical_necessity_required": true,
      "metadata": null,
      "mode": "subscription",
      "payment_intent": "fpi_01HWBS24Z8EFZ7VHJTSEWF2DPQ",
      "redirect_url": "http://localhost:3000/pay/c/fcs_01HWBRQCHTEVYWYT31N3QEGS9S",
      "setup_intent": null,
      "shipping_options": null,
      "shipping_address_collection": false,
      "shipping_details": null,
      "status": "open",
      "success_url": "https://withflex.com/thank-you?success=true",
      "subscription": "fsub_01HWBRRK1FT4QNG65KTJW8MH34",
      "tax_rate": null,
      "test_mode": false,
      "total_details": {
        "amount_discount": 0,
        "amount_tax": null,
        "amount_shipping": null
      },
      "visit_type": "posture"
    }
  ]
}

I could have also expanded the payment intent, invoice, or subscription, by following the pattern expand_<object_type>=true.

On this page

Expanding resources
Example use case