Skip to main content
Our API supports object expansion to help reduce the number of API calls your application needs to make. This allows you to fetch related objects inline as part of the main resource response.

​
What Is Object Expansion?

Some objects returned by the API contain references to other objects (e.g., an invoice references an organization, items, or payments). By default, these fields may appear only as IDs. Using the expand parameter, you can request that specific fields be fully populated with their related object data in a single API call.

​
Current Support

At the moment, object expansion is supported only for invoice retrieval, and is done via a POST request:

​
Example endpoint and payload

Get Invoice Endpoint

Check the get invoice details endpoint and try out the request yourself
 POST /invoices/:id 
{
  "expand": [
    "organization",
    "items",
    "calculations",
    "items.product",
    "items.billing_schema",
    "items.payment_intent"
  ]
}
Each path in the expand array tells the API to resolve and include that nested object in the response instead of just returning its ID. Expandable Fields (for Invoices) You can currently expand the following fields on invoice objects:
  • organization – Full details of the organization that owns the invoice
  • items – List of items associated with the invoice
  • calculations – Details about taxes, discounts, and fees
  • items.product – Full product details for each line item
  • items.billing_schema – Billing rules associated with each item
  • items.payment_intent – Payment intent (if one was created for the invoice)
More expandable fields and support for other endpoints will be added over time.

​
Best Practices

  • Only expand what you need — requesting too many nested objects can increase response size and latency.
  • Use dot notation (items.product) to expand nested fields on lists or sub-objects.
  • If no expand parameter is passed, related objects will default to their reference form (e.g., just an ID).
Need support or have suggestions for more expandable fields? Reach out at [email protected].