> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bitgpt.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Expanding Objects

> Learn how to request additional nested data in a single API call using the `expand` parameter.

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

<Card title="Get Invoice Endpoint" icon="file-invoice" href="/developer-resources/reference/payments/get-invoice-details" arrow="true">
  Check the get invoice details endpoint and try out the request yourself
</Card>

`POST` `/invoices/:id`

```json theme={"system"}
{
  "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 [support@bitgpt.xyz](mailto:support@bitgpt.xyz).