Skip to main content

Products

List Products

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

Filtering Products

Use flat param keys — the SDK wraps them in q[...] automatically:
const products = await client.store.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
  multi_search: 'blue shirt',                              // Full-text search
});

Sorting Products

Pass sort with one of the supported values:
const products = await client.store.products.list({
  sort: 'price asc',    // price asc, price desc, best_selling,
                         // name asc, name desc, available_on desc, available_on asc
});

Get a Product

Fetch a single product by slug or prefix ID:
const product = await client.store.products.get('spree-tote', {
  expand: ['variants', 'images'],
});

Product Filters

Get available filters (price range, availability, options, taxons) and sort options for building filter UIs:
const filters = await client.store.products.filters({
  taxon_id: 'txn_abc123', // Optional: scope filters to a taxon
});

// 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: 'taxons', type: 'taxon', options: [{ id: 'txn_abc', name: 'Shirts', permalink: '...', count: 12 }] },
//   ],
//   sort_options: [{ id: 'manual' }, { id: 'price asc' }, { id: 'best_selling' }, ...],
//   default_sort: 'manual',
//   total_count: 85,
// }

Categories (Taxonomies & Taxons)

List Taxonomies

const taxonomies = await client.store.taxonomies.list({
  expand: ['taxons'],
});

Get a Taxonomy

const categories = await client.store.taxonomies.get('tax_123', {
  expand: ['root', 'taxons'],
});

List Taxons

const taxons = await client.store.taxons.list({
  depth_eq: 1,              // Top-level categories only
  taxonomy_id_eq: '123',    // Filter by taxonomy
});

Get a Taxon

Fetch by ID or permalink:
const taxon = await client.store.taxons.get('categories/clothing', {
  expand: ['ancestors', 'children'], // For breadcrumbs and subcategories
});

List Products in a Category

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

Store

// Get current store information
const store = await client.store.store.get();

Geography

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

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