Many objects allow you to request additional information as an expanded response by using the expand[]
request parameter. This parameter is available for all GET requests.
In some cases, there is related information not included in responses by default, for example, the Invoice data associated with an Account object. You can request these fields as an expanded response by using the expand[]
query parameter.
You can also expand recursively by specifying nested fields after a dot (.
). For example, requesting billing_documents.payment_method
on an account will expand the billing documents attribute into a list of full Billing Document objects, and will then expand the payment_method
attribute on those billing documents into a full Payment Method object.
Moreover, you have the flexibility to expand multiple objects at once by identifying multiple items in the expand[]
array.
Expansions have a maximum depth of three levels. Therefore, when listing accounts, a value like accounts.subscriptions.subscription_plans.subscription_items
is the deepest allowed for the expand[]
field.
Related Guide: See the Expand responses section in the Quickstart API Tutorials.