List products

Spree SDK

import { createClient } from '@spree/sdk'

const client = createClient({
  baseUrl: 'https://your-store.com',
  publishableKey: '<api-key>',
})

const products = await client.products.list({
  page: 1,
  limit: 25,
  sort: 'price',
  search: 'shirt',
  price_gte: '20',
  price_lte: '100',
  with_option_value_ids: ['optval_abc', 'optval_def'],
  expand: ['variants', 'media'],
})

{
  "data": [
    {
      "id": "prod_UkLWZg9DAJ",
      "name": "Product 3959085",
      "slug": "product-3959085",
      "meta_title": null,
      "meta_description": null,
      "meta_keywords": null,
      "variant_count": 2,
      "available_on": null,
      "preorder_ships_at": null,
      "purchasable": true,
      "preorder": false,
      "in_stock": false,
      "backorderable": true,
      "available": true,
      "description": "A comfortable cotton t-shirt.",
      "description_html": "<p>A <strong>comfortable</strong> cotton t-shirt.</p>",
      "default_variant_id": "variant_UkLWZg9DAJ",
      "buy_box_variant_id": "variant_UkLWZg9DAJ",
      "thumbnail_url": null,
      "tags": [],
      "price": {
        "id": "price_UkLWZg9DAJ",
        "currency": "USD",
        "amount": "19.99",
        "compare_at_amount": null,
        "amount_in_cents": 1999,
        "compare_at_amount_in_cents": null,
        "display_amount": "$19.99",
        "display_compare_at_amount": null,
        "price_list_id": null
      },
      "original_price": null,
      "seller_id": null
    },
    {
      "id": "prod_gbHJdmfrXB",
      "name": "Product 3968209",
      "slug": "product-3968209",
      "meta_title": null,
      "meta_description": null,
      "meta_keywords": null,
      "variant_count": 1,
      "available_on": null,
      "preorder_ships_at": null,
      "purchasable": true,
      "preorder": false,
      "in_stock": false,
      "backorderable": true,
      "available": true,
      "description": "Quasi nostrum error iste autem recusandae consequuntur consectetur. Dolorem ea officia rerum a. Asperiores et occaecati laudantium deserunt modi reiciendis rem. Iste soluta tempora odit voluptate cupiditate. Architecto nostrum aliquid est odit minima repudiandae. Doloribus quos est in illum. Occaecati vero soluta asperiores aliquam odio accusamus incidunt. Officia magnam fugiat sint optio ipsa. Deserunt reiciendis aliquid architecto occaecati rem maxime vero doloremque. Recusandae ipsum natus eius assumenda.",
      "description_html": "Quasi nostrum error iste autem recusandae consequuntur consectetur. Dolorem ea officia rerum a. Asperiores et occaecati laudantium deserunt modi reiciendis rem. Iste soluta tempora odit voluptate cupiditate. Architecto nostrum aliquid est odit minima repudiandae.\nDoloribus quos est in illum. Occaecati vero soluta asperiores aliquam odio accusamus incidunt. Officia magnam fugiat sint optio ipsa. Deserunt reiciendis aliquid architecto occaecati rem maxime vero doloremque. Recusandae ipsum natus eius assumenda.",
      "default_variant_id": "variant_EfhxLZ9ck8",
      "buy_box_variant_id": "variant_EfhxLZ9ck8",
      "thumbnail_url": null,
      "tags": [],
      "price": {
        "id": "price_EfhxLZ9ck8",
        "currency": "USD",
        "amount": "19.99",
        "compare_at_amount": null,
        "amount_in_cents": 1999,
        "compare_at_amount_in_cents": null,
        "display_amount": "$19.99",
        "display_compare_at_amount": null,
        "price_list_id": null
      },
      "original_price": null,
      "seller_id": null
    }
  ],
  "meta": {
    "page": 1,
    "limit": 25,
    "count": 2,
    "pages": 1,
    "from": 1,
    "to": 2,
    "in": 2,
    "previous": null,
    "next": null
  }
}

{
  "error": {
    "code": "invalid_token",
    "message": "Valid API key required"
  }
}

GET

api

store

products

Spree SDK

import { createClient } from '@spree/sdk'

const client = createClient({
  baseUrl: 'https://your-store.com',
  publishableKey: '<api-key>',
})

const products = await client.products.list({
  page: 1,
  limit: 25,
  sort: 'price',
  search: 'shirt',
  price_gte: '20',
  price_lte: '100',
  with_option_value_ids: ['optval_abc', 'optval_def'],
  expand: ['variants', 'media'],
})

{
  "data": [
    {
      "id": "prod_UkLWZg9DAJ",
      "name": "Product 3959085",
      "slug": "product-3959085",
      "meta_title": null,
      "meta_description": null,
      "meta_keywords": null,
      "variant_count": 2,
      "available_on": null,
      "preorder_ships_at": null,
      "purchasable": true,
      "preorder": false,
      "in_stock": false,
      "backorderable": true,
      "available": true,
      "description": "A comfortable cotton t-shirt.",
      "description_html": "<p>A <strong>comfortable</strong> cotton t-shirt.</p>",
      "default_variant_id": "variant_UkLWZg9DAJ",
      "buy_box_variant_id": "variant_UkLWZg9DAJ",
      "thumbnail_url": null,
      "tags": [],
      "price": {
        "id": "price_UkLWZg9DAJ",
        "currency": "USD",
        "amount": "19.99",
        "compare_at_amount": null,
        "amount_in_cents": 1999,
        "compare_at_amount_in_cents": null,
        "display_amount": "$19.99",
        "display_compare_at_amount": null,
        "price_list_id": null
      },
      "original_price": null,
      "seller_id": null
    },
    {
      "id": "prod_gbHJdmfrXB",
      "name": "Product 3968209",
      "slug": "product-3968209",
      "meta_title": null,
      "meta_description": null,
      "meta_keywords": null,
      "variant_count": 1,
      "available_on": null,
      "preorder_ships_at": null,
      "purchasable": true,
      "preorder": false,
      "in_stock": false,
      "backorderable": true,
      "available": true,
      "description": "Quasi nostrum error iste autem recusandae consequuntur consectetur. Dolorem ea officia rerum a. Asperiores et occaecati laudantium deserunt modi reiciendis rem. Iste soluta tempora odit voluptate cupiditate. Architecto nostrum aliquid est odit minima repudiandae. Doloribus quos est in illum. Occaecati vero soluta asperiores aliquam odio accusamus incidunt. Officia magnam fugiat sint optio ipsa. Deserunt reiciendis aliquid architecto occaecati rem maxime vero doloremque. Recusandae ipsum natus eius assumenda.",
      "description_html": "Quasi nostrum error iste autem recusandae consequuntur consectetur. Dolorem ea officia rerum a. Asperiores et occaecati laudantium deserunt modi reiciendis rem. Iste soluta tempora odit voluptate cupiditate. Architecto nostrum aliquid est odit minima repudiandae.\nDoloribus quos est in illum. Occaecati vero soluta asperiores aliquam odio accusamus incidunt. Officia magnam fugiat sint optio ipsa. Deserunt reiciendis aliquid architecto occaecati rem maxime vero doloremque. Recusandae ipsum natus eius assumenda.",
      "default_variant_id": "variant_EfhxLZ9ck8",
      "buy_box_variant_id": "variant_EfhxLZ9ck8",
      "thumbnail_url": null,
      "tags": [],
      "price": {
        "id": "price_EfhxLZ9ck8",
        "currency": "USD",
        "amount": "19.99",
        "compare_at_amount": null,
        "amount_in_cents": 1999,
        "compare_at_amount_in_cents": null,
        "display_amount": "$19.99",
        "display_compare_at_amount": null,
        "price_list_id": null
      },
      "original_price": null,
      "seller_id": null
    }
  ],
  "meta": {
    "page": 1,
    "limit": 25,
    "count": 2,
    "pages": 1,
    "from": 1,
    "to": 2,
    "in": 2,
    "previous": null,
    "next": null
  }
}

{
  "error": {
    "code": "invalid_token",
    "message": "Valid API key required"
  }
}

Filters

Filter with q[<attribute>_<predicate>]=value, for example q[name_cont]=…. Send a list as q[<attribute>_in][]=a&q[<attribute>_in][]=b. How filters work.

Attribute	Kind	Predicates
`available_on`	Date and time	`eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null`
`created_at`	Date and time	`eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null`
`description`	Text	`eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank`
`discontinue_on`	Date and time	`eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null`
`id`	Prefixed ID	`eq` `not_eq` `in` `not_in` `null` `not_null`
`name`	Text	`eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank`
`price`	Amount	`eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null`
`seller_id`	Prefixed ID	`eq` `not_eq` `in` `not_in` `null` `not_null`
`slug`	Text	`eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank`
`status`	One of `draft`, `active`, `archived`, `proposed`, `rejected`	`eq` `not_eq` `in` `not_in` `null` `not_null`
`updated_at`	Date and time	`eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null`

Filters through associations

Prefix an associated record’s attribute with the association, as in q[categories_id_eq]. The same predicates apply.

Prefix	Attributes
`categories_`	`automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at`
`collections_`	`automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at`
`tags_`	`created_at`, `id`, `name`, `updated_at`

Also filters and sorts on the store’s searchable custom fields, as q[cf_<namespace>_<key>_<predicate>] and sort=cf_<namespace>_<key>. Sort by: available_on, best_selling, created_at, description, discontinue_on, id, manual, name, price, seller_id, slug, status, updated_at. Prefix a field with - to sort descending.

Authorizations

x-spree-api-key

string

header

required

Publishable API key for store access

Headers

x-spree-api-key

string

required

Publishable API key

Query Parameters

q[search]

string

Matches product name or variant SKU (partial, case-insensitive), and the store's searchable custom fields.

q[ascend_by_price]

boolean

Set to true to apply ascend_by_price.

q[descend_by_price]

boolean

Set to true to apply descend_by_price.

q[in_categories][]

string[]

Category prefixed IDs; matches products in any of them, including descendants.

q[in_category]

string

A category's prefixed ID; includes products in its descendants.

q[in_collection]

string

A collection's prefixed ID.

q[in_stock]

boolean

Set to true for products available to buy.

q[in_taxon]

string

Applies in_taxon to the given value.

q[not_discontinued]

boolean

Set to true to apply not_discontinued.

q[out_of_stock]

boolean

Set to true for products that are sold out.

q[price_between][]

number[]

Lowest and highest price, in the current currency.

Required array length: 2 elements

q[price_gte]

number

Lowest price, in the current currency.

q[price_lte]

number

Highest price, in the current currency.

q[search_by_name]

string

Applies search_by_name to the given value.

q[with_option_value_ids][]

string[]

Option value IDs (optval_…); matches products with any of them.

page

integer

Page number (default: 1)

limit

integer

Number of items per page (default: 25, max: 100)

sort

string

Sort order. Prefix with - for descending. Values: price, -price, best_selling, name, -name, -available_on, available_on

object

Attribute filters, as q[<attribute>_<predicate>]=value. See Filters above for the list.

expand

string

Comma-separated associations to expand (variants, media, categories, option_types, seller, seller.policies)

fields

string

Comma-separated list of fields to include (e.g., name,slug,price). id is always included.

Response

products found

data

object[]

required

Show child attributes

API basics

Endpoints

Filters

Authorizations

Headers

Query Parameters

Response

​Filters

Authorizations

Headers

Query Parameters

Response

Filters