Documentation Index
Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt
Use this file to discover all available pages before exploring further.
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.
