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, SHIPMENT_ITEMS, TRACK_AND_TRACES |
| 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 configurations | GET /v2/clustersconfig, GET /v2/clustersconfig/{lookupKey}/{key} | settings |
| Category search | POST /v2/categories/search | sources |
| Inventory | GET /v2/products/{lookupKey}/{key}/inventory, POST /v2/inventory/search | inventoryBalance, which adds the stock records in balance |
| Contacts | GET /v2/contacts/{lookupKey}/{lookupValue} | companies |
Products: expands selects the data
On products, expands selects which data comes back rather than adding to it. Without expands, a product includes its sources, translations and metadata, but not its categories. With expands, only the listed groups come back: ?expands=categories returns the categories without the sources, translations and metadata. A value the endpoint does not know, or a value in upper case, is accepted and leaves out all four groups. The product search works the same way.
The translations are the localized fields other than names, such as descriptions, shortDescriptions and keywords. The metadata are metadataTitles, metadataDescriptions, metadataKeywords and metadataCanonicalUrls. names always come back.
Order search: always list ORDER_ITEMS
Without expands, the order search returns each order with its items. An expands list replaces that default: ?expands=ADDRESSES returns the addresses with an empty items array. Include ORDER_ITEMS whenever you set expands:
POST /v2/orders/search?expands=ORDER_ITEMS,ADDRESSES
Data that is always included
Some endpoints return their related data without expands. The products of a cluster and of a cluster option (GET /v2/clusters/{lookupKey}/{key}/products and GET /v2/clusteroptions/{lookupKey}/{key}/products) always include their sources and translations. A bundle (GET /v2/bundles/{id}) always includes its items and price.
Multiple expansions
Combine multiple expansions in a single request by separating them with commas. This request returns the product with its sources, translations and categories:
GET /v2/products/id/123?expands=sources,translations,categories
See also
- Localized Strings for the multi-language fields in a response
- Pagination for controlling page sizes alongside expansions
- REST API Reference for the expand values per endpoint