docs/developer/sdk/quickstart.mdx
@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.
npm install @spree/sdk
# or
yarn add @spree/sdk
# or
pnpm add @spree/sdk
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: '[email protected]',
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 });
The SDK uses a resource builder pattern for nested resources:
| Parent Resource | Nested Resource | Available Methods |
|---|---|---|
carts | items | create, update, delete |
carts | payments | list, get, create |
carts | paymentMethods | list |
carts | paymentSessions | create, get, update, complete |
carts | fulfillments | list, update |
carts | discountCodes | apply, remove |
carts | giftCards | apply, remove |
carts | storeCredits | apply, remove |
customer | addresses | list, get, create, update, delete, markAsDefault |
customer | creditCards | list, get, delete |
customer | giftCards | list, get |
customer | orders | list |
customer | paymentSetupSessions | create, get, complete |
policies | — | list, get |
wishlists | items | create, 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);
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.