By default, the Store API returns only the primary resource attributes to keep responses fast and lightweight. Use the expand parameter to expand related resources inline.
Including Relations
Pass a comma-separated list of relation names via the expand query parameter:
// Product with variants and images
const product = await client.store.products.get('spree-tote', {
expand: ['variants', 'images'],
})
// Access included relations directly
console.log(product.variants) // Array of variant objects
console.log(product.images) // Array of image objects
expand, relation fields are omitted from the response:
{
"id": "prod_86Rf07xd4z",
"name": "Spree Tote",
"slug": "spree-tote",
"price": { "amount": "15.99", "currency": "USD" },
"created_at": "2025-01-15T10:30:00Z"
}
?expand=variants,images, the related resources are embedded:
{
"id": "prod_86Rf07xd4z",
"name": "Spree Tote",
"slug": "spree-tote",
"price": { "amount": "15.99", "currency": "USD" },
"created_at": "2025-01-15T10:30:00Z",
"variants": [
{
"id": "variant_k5nR8xLq",
"sku": "SPR-TOTE-RED",
"price": { "amount": "15.99", "currency": "USD" },
"in_stock": true,
"option_values": [{ "name": "Red", "option_type_name": "Color" }]
}
],
"images": [
{
"id": "img_9xPq2wLm",
"url": "https://cdn.example.com/spree-tote.jpg",
"alt": "Spree Tote"
}
]
}
Available Relations by Resource
Products
| Relation | Description |
|---|
variants | All purchasable variants |
default_variant | The default variant |
master_variant | The master variant |
images | All product images (across all variants) |
option_types | Option types (e.g., Size, Color) |
taxons | Categories this product belongs to |
metafields | Public metafields (custom structured data) |
const product = await client.store.products.get('spree-tote', {
expand: ['variants', 'images', 'option_types', 'metafields'],
})
Taxons (Categories)
| Relation | Description |
|---|
ancestors | Parent taxons (for breadcrumbs) |
children | Direct child taxons |
products | Products in this taxon |
const taxon = await client.store.taxons.get('categories/clothing', {
expand: ['ancestors', 'children'],
})
Taxonomies
| Relation | Description |
|---|
root | Root taxon |
taxons | All taxons in this taxonomy |
Countries
| Relation | Description |
|---|
states | States/provinces within the country |
const usa = await client.store.countries.get('US', {
expand: ['states'],
})
console.log(usa.states) // Array of state objects
Collections with Includes
The expand parameter also works on collection endpoints:
// List products with their images and default variant
const { data: products } = await client.store.products.list({
expand: ['images', 'default_variant'],
limit: 12,
})
Nested Includes
Use dot notation to include nested relations:
// Include variants and their nested option values
const product = await client.store.products.get('spree-tote', {
expand: ['variants.option_values'],
})
Only include relations you actually need. Each included relation requires additional database queries, so requesting unnecessary relations will slow down the response.
