Expanding resources
Some resources allow you to request additional information as an expanded resource by using the expands request parameter. When an object contains related data, you can expand it inline rather than making separate API calls.
The expands parameter is available on selected retrieve and search endpoints, not on every request. The supported values are specific to each endpoint and the casing differs per resource: order-related endpoints use uppercase values such as ORDER_ITEMS, while catalog endpoints use lowercase values such as translations. Check the endpoint in the REST API Reference for the exact values it accepts.
Supported expand values per resource
| Resource | Endpoints | Expand values |
|---|---|---|
| Orders | GET /v2/orders/id/{id} | ORDER_ITEMS, ADDRESSES, SOURCES, SHIPMENTS |
| Order search | POST /v2/orders/search | ORDER_ITEMS, ADDRESSES, SOURCES, SHIPMENTS, SHIPMENT_ITEMS, TRACK_AND_TRACES |
| Order items | GET /v2/orders/id/{id}/items | SOURCES |
| Shipments | GET /v2/orders/shipments/{id}, POST /v2/orders/shipments/search | SHIPMENT_ITEMS, TRACK_AND_TRACES |
| Products | GET /v2/products/{lookupKey}/{key}, POST /v2/products/search | sources, metadata, translations, categories |
| Clusters | GET /v2/clusters/{lookupKey}/{key}, POST /v2/clusters/search | categories, products |
| Cluster products | GET /v2/clusters/{lookupKey}/{key}/products | sources, translation |
| Cluster option products | GET /v2/clusteroptions/{lookupKey}/{key}/products | sources, translation |
| Cluster configurations | GET /v2/clustersconfig | sources |
| Category search | POST /v2/categories/search | sources |
| Bundles | GET /v2/bundles, GET /v2/bundles/{id} | items, price |
| Order statuses | GET /v2/order-statuses and related endpoints | sets |
| Inventory | GET /v2/products/{lookupKey}/{key}/inventory, POST /v2/inventory/search | expands inventory balance details |
| Companies, contacts and customers | GET /v2/{resource}/{lookupKey}/{lookupValue} | related entities, see the endpoint reference |
Multiple expansions
Combine multiple expansions in a single request by separating them with commas:
GET /v2/products/123?expands=sources,translations
See also
- Localized Strings for retrieving translations with
?expands=translations - Pagination for controlling page sizes alongside expansions
- REST API Reference for the expand values per endpoint