Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: Spree TypeScript SDK quickstart for the Store API
sidebarTitle: Quickstart
description: Install @spree/sdk, configure the Store API client, and make your first calls to products, carts, checkout, and customer account endpoints from TypeScript.
---
`@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](/developer/sdk/admin/quickstart).
## Installation
```bash
npm install @spree/sdk
# or
yarn add @spree/sdk
# or
pnpm add @spree/sdk
```
## Quick Start
```typescript
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 });
```
## Nested Resources
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` |
```typescript
// 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](/developer/agentic/agent-skills) include dedicated SDK and storefront skills (typed clients, Ransack filtering, error handling, custom endpoints), and the [docs MCP server](/developer/agentic/docs-mcp) gives your agent the full SDK reference on demand. See [Agentic Development](/developer/agentic/overview).