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 media
const product = await client.products.get('spree-tote', {
expand: ['variants', 'media'],
})
// Access included relations directly
console.log(product.variants) // Array of variant objects
console.log(product.media) // Array of media 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,media, 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" }]
}
],
"media": [
{
"id": "asset_9xPq2wLm",
"position": 1,
"alt": "Spree Tote",
"media_type": "image",
"product_id": "prod_86Rf07xd4z",
"variant_ids": ["variant_k5nR8xLq"],
"original_url": "https://cdn.example.com/spree-tote.jpg",
"small_url": "https://cdn.example.com/spree-tote-small.jpg",
"medium_url": "https://cdn.example.com/spree-tote-medium.jpg",
"large_url": "https://cdn.example.com/spree-tote-large.jpg"
}
]
}
Available Relations by Resource
Products
| Relation | Description |
|---|
variants | All purchasable variants |
default_variant | The default variant |
media | All product media (images and videos across all variants) |
primary_media | The main product image |
option_types | Option types (e.g., Size, Color) |
categories | Categories this product belongs to |
custom_fields | Public custom fields (structured metadata) |
prior_price | Previous price history (for showing strikethrough) |
const product = await client.products.get('spree-tote', {
expand: ['variants', 'media', 'option_types', 'custom_fields'],
})
Categories
| Relation | Description |
|---|
parent | Parent category |
ancestors | All ancestor categories (for breadcrumbs) |
children | Direct child categories |
custom_fields | Public custom fields (structured metadata) |
const category = await client.categories.get('clothing/shirts', {
expand: ['ancestors', 'children'],
})
Countries
| Relation | Description |
|---|
states | States/provinces within the country |
const usa = await client.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 media and default variant
const { data: products } = await client.products.list({
expand: ['media', 'default_variant'],
limit: 12,
})
Nested Includes
Use dot notation to include nested relations:
// Include variants and their nested option values
const product = await client.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.
