Products & Categories

const products = await client.products.list({
  page: 1,
  limit: 25,
  expand: ['variants', 'media', 'categories'],
});

const products = await client.products.list({
  name_cont: 'shirt',                                     // Name contains
  price_gte: 20,                                           // Min price
  price_lte: 100,                                          // Max price
  with_option_value_ids: ['optval_abc', 'optval_def'], // By option values
  in_stock: true,                                          // In stock only
  search: 'blue shirt',                                     // Full-text search
});

const products = await client.products.list({
  sort: 'price',        // price, -price, best_selling,
                         // name, -name, -available_on, available_on
});

const products = await client.products.list({
  fields: ['name', 'slug', 'price', 'display_price'],
});

const product = await client.products.get('spree-tote', {
  fields: ['name', 'slug', 'price'],
  expand: ['media'],  // expanded associations are always included
});

// Expand variants with their images in one request
const product = await client.products.get('spree-tote', {
  expand: ['variants.media', 'option_types'],
});

// Access nested data
product.variants.forEach(variant => {
  console.log(variant.media); // Media are included
});

const product = await client.products.get('spree-tote', {
  expand: ['variants', 'media'],
});

const product = await client.products.get('spree-tote', {
  expand: ['prior_price'],
});

if (product.prior_price) {
  console.log(product.prior_price.amount);         // "9.99"
  console.log(product.prior_price.display_amount);  // "$9.99"
  console.log(product.prior_price.currency);        // "USD"
  console.log(product.prior_price.recorded_at);     // "2026-03-10T..."
}

const filters = await client.products.filters({
  category_id: 'ctg_abc123', // Optional: scope filters to a category
});

// Response:
// {
//   filters: [
//     { id: 'price', type: 'price_range', min: 9.99, max: 199.99, currency: 'USD' },
//     { id: 'availability', type: 'availability', options: [{ id: 'in_stock', count: 42 }, ...] },
//     { id: 'opttype_abc', type: 'option', name: 'color', presentation: 'Color', options: [...] },
//     { id: 'categories', type: 'category', options: [{ id: 'ctg_abc', name: 'Shirts', permalink: '...', count: 12 }] },
//   ],
//   sort_options: [{ id: 'manual' }, { id: 'price' }, { id: 'best_selling' }, ...],
//   default_sort: 'manual',
//   total_count: 85,
// }

const categories = await client.categories.list({
  depth_eq: 1,              // Top-level categories only
});

const category = await client.categories.get('clothing/shirts', {
  expand: ['ancestors', 'children'], // For breadcrumbs and subcategories
});

const categoryProducts = await client.categories.products.list('clothing/shirts', {
  page: 1,
  limit: 12,
  expand: ['media', 'default_variant'],
});

// List countries available for checkout
const { data: countries } = await client.countries.list();

// Get country by ISO code (includes states)
const usa = await client.countries.get('US');
console.log(usa.states); // Array of states