List products

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',
  name_cont: 'shirt',
  price_gte: 20,
  price_lte: 100,
  with_option_value_ids: ['optval_abc', 'optval_def'],
  expand: ['variants', 'media'],
})

curl --request GET \
  --url http://{defaultHost}/api/v3/store/products \
  --header 'x-spree-api-key: <api-key>'

{
  "data": [
    {
      "id": "prod_UkLWZg9DAJ",
      "name": "Product 1514432",
      "slug": "product-1514432",
      "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": "A comfortable cotton t-shirt.",
      "description_html": "<p>A <strong>comfortable</strong> cotton t-shirt.</p>",
      "default_variant_id": "variant_gbHJdmfrXB",
      "thumbnail_url": null,
      "tags": [],
      "price": {
        "id": "price_gbHJdmfrXB",
        "amount": "19.99",
        "amount_in_cents": 1999,
        "compare_at_amount": null,
        "compare_at_amount_in_cents": null,
        "currency": "USD",
        "display_amount": "$19.99",
        "display_compare_at_amount": null,
        "price_list_id": null
      },
      "original_price": null
    },
    {
      "id": "prod_gbHJdmfrXB",
      "name": "Product 1526022",
      "slug": "product-1526022",
      "meta_title": null,
      "meta_description": null,
      "meta_keywords": null,
      "variant_count": 0,
      "available_on": null,
      "preorder_ships_at": null,
      "purchasable": true,
      "preorder": false,
      "in_stock": false,
      "backorderable": true,
      "available": true,
      "description": "Pariatur est ratione reprehenderit provident omnis minus. Repellendus a quasi cum mollitia voluptatem. Ut animi aperiam magnam nisi nemo. Pariatur quasi eligendi explicabo molestiae cum ad corporis sunt. Numquam cum nobis adipisci animi. Vitae minima maxime veritatis perspiciatis adipisci dicta soluta. Voluptate repudiandae quia sed qui. Animi dolores commodi architecto sunt eaque. Sint repellendus atque temporibus repudiandae fugiat itaque. Maxime nostrum ducimus ea voluptas atque. Ex quidem omnis cupiditate vel repellendus. Perspiciatis eius rem ad officia. Officia asperiores molestiae quod explicabo quisquam atque. Facilis et aliquam libero magni saepe iure. Doloribus distinctio nemo corrupti voluptate. Provident blanditiis maiores autem accusantium. Ab repellendus ullam repudiandae deserunt fugit eveniet.",
      "description_html": "Pariatur est ratione reprehenderit provident omnis minus. Repellendus a quasi cum mollitia voluptatem. Ut animi aperiam magnam nisi nemo. Pariatur quasi eligendi explicabo molestiae cum ad corporis sunt. Numquam cum nobis adipisci animi.\nVitae minima maxime veritatis perspiciatis adipisci dicta soluta. Voluptate repudiandae quia sed qui. Animi dolores commodi architecto sunt eaque. Sint repellendus atque temporibus repudiandae fugiat itaque.\nMaxime nostrum ducimus ea voluptas atque. Ex quidem omnis cupiditate vel repellendus. Perspiciatis eius rem ad officia. Officia asperiores molestiae quod explicabo quisquam atque. Facilis et aliquam libero magni saepe iure.\nDoloribus distinctio nemo corrupti voluptate. Provident blanditiis maiores autem accusantium. Ab repellendus ullam repudiandae deserunt fugit eveniet.",
      "default_variant_id": "variant_EfhxLZ9ck8",
      "thumbnail_url": null,
      "tags": [],
      "price": {
        "id": "price_EfhxLZ9ck8",
        "amount": "19.99",
        "amount_in_cents": 1999,
        "compare_at_amount": null,
        "compare_at_amount_in_cents": null,
        "currency": "USD",
        "display_amount": "$19.99",
        "display_compare_at_amount": null,
        "price_list_id": null
      },
      "original_price": 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"
  }
}

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

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

q[name_cont]

string

Filter by name containing string

q[in_category]

string

Filter by category prefixed ID (includes descendants)

q[in_categories][]

string

Filter by multiple category prefixed IDs (OR logic, includes descendants)

q[price_gte]

number

Filter by minimum price

q[price_lte]

number

Filter by maximum price

q[with_option_value_ids][]

string

Filter by option value prefix IDs (e.g., optval_abc). Pass multiple values for OR logic.

q[in_stock]

boolean

Filter to only in-stock products

expand

string

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

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

meta

object

required

Show child attributes

Get a category

Get a product

⌘I

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',
  name_cont: 'shirt',
  price_gte: 20,
  price_lte: 100,
  with_option_value_ids: ['optval_abc', 'optval_def'],
  expand: ['variants', 'media'],
})

curl --request GET \
  --url http://{defaultHost}/api/v3/store/products \
  --header 'x-spree-api-key: <api-key>'

{
  "data": [
    {
      "id": "prod_UkLWZg9DAJ",
      "name": "Product 1514432",
      "slug": "product-1514432",
      "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": "A comfortable cotton t-shirt.",
      "description_html": "<p>A <strong>comfortable</strong> cotton t-shirt.</p>",
      "default_variant_id": "variant_gbHJdmfrXB",
      "thumbnail_url": null,
      "tags": [],
      "price": {
        "id": "price_gbHJdmfrXB",
        "amount": "19.99",
        "amount_in_cents": 1999,
        "compare_at_amount": null,
        "compare_at_amount_in_cents": null,
        "currency": "USD",
        "display_amount": "$19.99",
        "display_compare_at_amount": null,
        "price_list_id": null
      },
      "original_price": null
    },
    {
      "id": "prod_gbHJdmfrXB",
      "name": "Product 1526022",
      "slug": "product-1526022",
      "meta_title": null,
      "meta_description": null,
      "meta_keywords": null,
      "variant_count": 0,
      "available_on": null,
      "preorder_ships_at": null,
      "purchasable": true,
      "preorder": false,
      "in_stock": false,
      "backorderable": true,
      "available": true,
      "description": "Pariatur est ratione reprehenderit provident omnis minus. Repellendus a quasi cum mollitia voluptatem. Ut animi aperiam magnam nisi nemo. Pariatur quasi eligendi explicabo molestiae cum ad corporis sunt. Numquam cum nobis adipisci animi. Vitae minima maxime veritatis perspiciatis adipisci dicta soluta. Voluptate repudiandae quia sed qui. Animi dolores commodi architecto sunt eaque. Sint repellendus atque temporibus repudiandae fugiat itaque. Maxime nostrum ducimus ea voluptas atque. Ex quidem omnis cupiditate vel repellendus. Perspiciatis eius rem ad officia. Officia asperiores molestiae quod explicabo quisquam atque. Facilis et aliquam libero magni saepe iure. Doloribus distinctio nemo corrupti voluptate. Provident blanditiis maiores autem accusantium. Ab repellendus ullam repudiandae deserunt fugit eveniet.",
      "description_html": "Pariatur est ratione reprehenderit provident omnis minus. Repellendus a quasi cum mollitia voluptatem. Ut animi aperiam magnam nisi nemo. Pariatur quasi eligendi explicabo molestiae cum ad corporis sunt. Numquam cum nobis adipisci animi.\nVitae minima maxime veritatis perspiciatis adipisci dicta soluta. Voluptate repudiandae quia sed qui. Animi dolores commodi architecto sunt eaque. Sint repellendus atque temporibus repudiandae fugiat itaque.\nMaxime nostrum ducimus ea voluptas atque. Ex quidem omnis cupiditate vel repellendus. Perspiciatis eius rem ad officia. Officia asperiores molestiae quod explicabo quisquam atque. Facilis et aliquam libero magni saepe iure.\nDoloribus distinctio nemo corrupti voluptate. Provident blanditiis maiores autem accusantium. Ab repellendus ullam repudiandae deserunt fugit eveniet.",
      "default_variant_id": "variant_EfhxLZ9ck8",
      "thumbnail_url": null,
      "tags": [],
      "price": {
        "id": "price_EfhxLZ9ck8",
        "amount": "19.99",
        "amount_in_cents": 1999,
        "compare_at_amount": null,
        "compare_at_amount_in_cents": null,
        "currency": "USD",
        "display_amount": "$19.99",
        "display_compare_at_amount": null,
        "price_list_id": null
      },
      "original_price": 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"
  }
}

API basics

Endpoints

Authorizations

Headers

Query Parameters

Response