Skip to main content
@spree/sdk is the customer-facing SDK — products, carts, checkout, and account flows against the Store API. For back-office integrations (managing products, orders, customers, stock), use the Admin SDK.

​
Installation

npm install @spree/sdk
# or
yarn add @spree/sdk
# or
pnpm add @spree/sdk

​
Quick Start

import { createClient } from '@spree/sdk';

// Initialize the client
const client = createClient({
  baseUrl: 'https://api.mystore.com',
  publishableKey: 'pk_xxx',   // Store API
});

// Browse products (Store API)
const products = await client.products.list({
  limit: 10,
  expand: ['variants', 'media'],
});

// Get a single product
const product = await client.products.get('spree-tote');

// Authentication
const { token, user } = await client.auth.login({
  email: 'customer@example.com',
  password: 'password123',
});

// Create a cart and add items
const cart = await client.carts.create();
await client.carts.items.create(cart.id, {
  variant_id: 'var_abc123',
  quantity: 2,
}, { spreeToken: cart.token });

// Checkout flow
await client.carts.complete(cart.id, { spreeToken: cart.token });

​
Nested Resources

The SDK uses a resource builder pattern for nested resources:
Parent ResourceNested ResourceAvailable Methods
cartsitemscreate, update, delete
cartspaymentslist, get, create
cartspaymentMethodslist
cartspaymentSessionscreate, get, update, complete
cartsfulfillmentslist, update
cartsdiscountCodesapply, remove
cartsgiftCardsapply, remove
cartsstoreCreditsapply, remove
customeraddresseslist, get, create, update, delete, markAsDefault
customercreditCardslist, get, delete
customergiftCardslist, get
customerorderslist
customerpaymentSetupSessionscreate, get, complete
policies—list, get
wishlistsitemscreate, update, delete
// Nested resources follow the pattern: client.parent.nested.method(parentId, ...)
await client.carts.items.create(cartId, params, options);
await client.carts.payments.list(cartId, options);
await client.carts.fulfillments.update(cartId, fulfillmentId, params, options);
await client.customer.addresses.list({}, options);
await client.wishlists.items.create(wishlistId, params, options);

​
Pair with AI agents

Building your storefront with an AI coding agent? The Spree agent skills include dedicated SDK and storefront skills (typed clients, Ransack filtering, error handling, custom endpoints), and the docs MCP server gives your agent the full SDK reference on demand. See Agentic Development.