---
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](admin/quickstart.md).

## 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: '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 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](../agentic/agent-skills.md) include dedicated SDK and storefront skills (typed clients, Ransack filtering, error handling, custom endpoints), and the [docs MCP server](../agentic/mcp.md) gives your agent the full SDK reference on demand. See [Agentic Development](../agentic/overview.md).