Migrating from Storefront API v2

The Store API is the successor to the legacy Storefront API. It exposes the same surface — products, carts, checkout, customers, wishlists — but with a new transport (flat JSON instead of JSON:API), a new fully-typed TypeScript SDK, and resource-oriented routes that line up with the new Admin API. It's faster, safer and easier to work with.

This guide walks you through the differences and gives you a one-to-one mapping you can grep against during a migration.

TL;DR

Mental model: what changed and why

v2 — JSON:API with action endpoints

Storefront v2 was modelled on JSON:API. Every response had data/attributes/relationships/included, and most non-GET calls invoked a named action on a singleton resource (/cart/add_item, /checkout/next, /checkout/select_shipping_method). The current cart was implicit — the server resolved it from the X-Spree-Order-Token header. Checkout was a five-step state machine; the SPA's job was to drive PATCH /checkout/next until the order reached complete.

This made cart and checkout calls easy to write but hard to reason about. The same payload could land you in different checkout states depending on which step the order happened to be on, and refactoring the front-end meant knowing which actions transitioned which states.

v3 — REST with explicit resources

Store API v3 collapses checkout into the cart. There is no checkout state machine, no /checkout/next, no /checkout/advance. Instead:

• The cart is a real resource with a stable prefixed ID (cart_…). You PATCH /carts/:id to attach an email or addresses, and you POST /carts/:id/items to add line items.
• Delivery rates and payment methods are not separate endpoints — fulfillments are nested under the cart (PATCH /carts/:id/fulfillments/:fid to pick a delivery rate), and payments are nested under the cart (POST /carts/:id/payments for non-session methods, POST /carts/:id/payment_sessions for Stripe/PayPal/Adyen).
• Completing checkout is a single explicit call: POST /carts/:id/complete. It returns the resulting Order.

The cart can be created, edited, abandoned, completed, and associated with a user from a single URL. No step transitions, no implicit current cart. This makes it possible to ship Shopify-style one-page checkout without fighting the API.

Why JSON:API is gone

JSON:API's strengths — sparse fieldsets, relationship graphs, normalized payloads — are real, but most storefront clients flattened the response anyway. The cost was a noisy, hard-to-cache wire format and a two-step deserialization on every call. v3 returns the resource directly with associations inlined when expand is requested:

{
  "data": {
    "id": "96",
    "type": "product",
    "attributes": {
      "name": "Bomber Jacket",
      "slug": "bomber-jacket",
      "available_on": "2021-10-02T11:02:29.288Z",
      "purchasable": true,
      "in_stock": true,
      "currency": "USD",
      "price": "38.99",
      "display_price": "$38.99",
      "compare_at_price": null,
      "display_compare_at_price": null
    },
    "relationships": {
      "variants":  { "data": [{ "id": "212", "type": "variant" }] },
      "default_variant": { "data": { "id": "212", "type": "variant" } }
    }
  },
  "included": [
    {
      "id": "212",
      "type": "variant",
      "attributes": { "sku": "JacketsandCoats_bomberjacket_38.99", "price": "38.99" }
    }
  ]
}

{
  "id": "prod_UkLWZg9DAJ",
  "name": "Bomber Jacket",
  "slug": "bomber-jacket",
  "available_on": "2025-05-13T22:27:22.136Z",
  "purchasable": true,
  "in_stock": true,
  "description": "Dolorem nulla odit nostrum placeat...",
  "description_html": "<p>Dolorem nulla odit nostrum placeat...</p>",
  "default_variant_id": "variant_gbHJdmfrXB",
  "thumbnail_url": null,
  "tags": [],
  "price": {
    "id": "price_gbHJdmfrXB",
    "amount": "38.99",
    "amount_in_cents": 3899,
    "currency": "USD",
    "display_amount": "$38.99",
    "compare_at_amount": null,
    "compare_at_amount_in_cents": null,
    "display_compare_at_amount": null
  },
  "original_price": null,
  "variants": [
    {
      "id": "variant_gbHJdmfrXB",
      "product_id": "prod_UkLWZg9DAJ",
      "sku": "JacketsandCoats_bomberjacket_38.99",
      "options_text": "Size: M",
      "purchasable": true,
      "in_stock": true,
      "price": {
        "amount": "38.99",
        "amount_in_cents": 3899,
        "currency": "USD",
        "display_amount": "$38.99"
      }
    }
  ]
}

You can still ask for sparse fields (?fields=name,price), and you still control association depth (?expand=variants.media), but you no longer have to walk included to assemble the response. See Querying and Relations.

Prefixed IDs everywhere

Every v3 resource has a Stripe-style prefixed ID — prod_…, variant_…, cart_…, ord_…, addr_…. The prefix is part of the public surface: pass it back exactly as received, never strip the prefix or cast it to an integer. (Internally, IDs are still numeric, but the API only ever exposes the prefixed form.) See the Introduction.

SDK: @spree/storefront-api-v2-sdk → @spree/sdk

The two SDKs cover the same ground but differ in shape. The legacy @spree/storefront-api-v2-sdk uses a makeClient factory, exposes resource namespaces (account, cart, checkout, products, taxons, wishlists), wraps every response in a Result<Error, Response> envelope, and passes tokens via an IToken ({ orderToken, bearerToken }) argument on every method.

@spree/sdk uses a createClient factory, lines its resource namespaces up with the REST tree (products, categories, carts, carts.items, customer.orders, …), returns the resource directly (no Result wrapper), and threads auth through a per-call RequestOptions ({ token, spreeToken }) — the publishable key is set once at client construction.

Installing

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

npm install @spree/storefront-api-v2-sdk

Creating a client

import { createClient } from '@spree/sdk'

const client = createClient({
  baseUrl: 'https://your-store.com',
  publishableKey: 'pk_xxx',
})

import { makeClient } from '@spree/storefront-api-v2-sdk'

const client = makeClient({
  host: 'https://your-store.com',
})
// No API key — the Storefront API v2 was fully public.

The Storefront API v2 had no API key concept — anyone with the host could call it. Store API v3 introduces a publishable key (pk_xxx) that's required on every request and identifies which store the call targets. The key is safe to expose in client-side code; it's how v3 supports multi-store on a single domain and gives you per-key rate limits, scopes, and audit trails.

Calling an endpoint

// Returns the Product directly — throws on failure
const product = await client.products.get('spree-tote', {
  expand: ['variants', 'media'],
})

console.log(product.name, product.price)

// Returns a Result wrapper
const response = await client.products.show({
  id: 'spree-tote',
  include: 'variants,images',
})

if (response.isSuccess()) {
  const { data, included } = response.success()
  console.log(data.attributes.name, data.attributes.price)
  // Walk `included` to resolve relationships…
} else {
  console.error(response.fail())
}

Auth tokens

// Guest cart (uses cart's order token as `spreeToken`)
const cart = await client.carts.create()
await client.carts.items.create(
  cart.id,
  { variant_id: 'variant_abc', quantity: 1 },
  { spreeToken: cart.token },
)

// Authenticated customer (JWT)
const { token } = await client.auth.login({
  email: '[email protected]',
  password: 'spree123',
})
const orders = await client.customer.orders.list({}, { token })

// Guest cart (orderToken)
const cartResponse = await client.cart.create()
const orderToken = cartResponse.success().data.attributes.token

await client.cart.addItem({
  order_token: orderToken,
}, { variant_id: 10, quantity: 1 })

// Authenticated customer (OAuth via /spree_oauth/token)
const tokenResponse = await client.authentication.getToken({
  username: '[email protected]',
  password: 'spree123',
})
const bearer = tokenResponse.success().access_token

const ordersResponse = await client.account.ordersList({
  bearer_token: bearer,
})

In v3, token and spreeToken are passed via the RequestOptions object on each call — no more per-method bearer_token / order_token arguments mixed into the body. JWT refresh uses client.auth.refresh({ refresh_token }); the old OAuth refresh_token grant against /spree_oauth/token is gone.

Error handling

In v3 the SDK throws a SpreeError instance with code, status, and details properties. Wrap calls in try/catch or let them bubble. The Result<Error, Response> wrapper from v2 is gone — code that branched on response.isSuccess() becomes a single happy path plus a catch.

TypeScript types

v3 ships generated TypeScript types and runtime Zod schemas that stay in lockstep with the API — every response field is typed, and you can validate payloads at runtime where you need belt-and-braces safety (form submissions, untrusted webhooks). v2's types were hand-maintained interfaces inside the SDK, which drifted from the actual responses over time.

Endpoint mapping

The tables below cover every public path in /api/v2/storefront/* and where to find its v3 equivalent. Anything not listed is unchanged in scope but follows the new conventions (flat JSON, prefixed IDs, Ransack filters).

Catalog: products, taxons, categories

This is an area where API v3 has the biggest performance advantage over v2. GET /products by default will expose default_variant_id, thumbnail_url and price which are essential for building product lists. You don't need to expand variants or media (images) like with API v2.

Cart and checkout

This is the biggest conceptual change. The v2 cart was a singleton accessed via the order token header; v3 carts have prefixed IDs and live alongside line items, payments, fulfillments, and discount codes as nested resources. There is no checkout state machine in v3. Backend will handle that automatically, without any developer action needed. This aligns with Spree 6 upcoming changes.

By default all Cart endpoints will return all associations auto-expanded.

The new RESTful design allows you to implement different usage scenarios like multiple saved carts per customer or organization (company).

Session-based payments (Stripe, Adyen, PayPal)

API v2 had per-gateway endpoints (/stripe/payment_intents, /adyen/payment_sessions). API v3 unifies these behind a generic Payment Sessions API — the gateway-specific payload moves into the request body, and Spree dispatches to the right provider based on the payment_method_id. This shortens the integration time and allows teams to deliver payment integrations faster. Also your frontend code doesn't need to change per gateway.

Customer account

API v2 exposed a singleton /account endpoint with OAuth tokens minted at /spree_oauth/token. API v3 splits the surface into a public registration endpoint (POST /customers) and a /customers/me namespace for the authenticated customer. Auth moves from OAuth to JWT (POST /auth/login).

Geography and store metadata

Wishlists

Digital downloads

Removed without a v3 equivalent

A handful of v2 surfaces don't exist in v3:

• Posts / Menus / CMS Pages — the blog/CMS surface is not part of v3 or Spree Core anymore. Recommended: use a dedicated CMS like Payload or Strapi

Migration checklist

The mechanical bits, in order:

1. Install @spree/sdk alongside @spree/storefront-api-v2-sdk. They have different package names, so both can coexist while you cut over endpoints incrementally.
2. Create a publishable API key in Spree Admin → Settings → API Keys (or via spree api-key create). v3 requires it on every request — v2 had no API key concept at all.
3. Replace makeClient({ host }) with createClient({ baseUrl, publishableKey }) in one entry point at a time. Keep the v2 client wired up for not-yet-migrated calls.
4. Switch from Result<…> to direct returns + try/catch. Any code that did if (response.isSuccess()) { response.success() } becomes a single statement, with errors thrown as SpreeError.
5. Update token handling. Replace { bearer_token, order_token } per-method arguments with the { token, spreeToken } second-argument RequestOptions. JWT tokens come from client.auth.login / client.customers.create; cart tokens come from cart.token on the cart resource.
6. Convert filters from filter[...] to q[...]. Most filters have a direct Ransack equivalent (see the Querying reference). For products specifically, taxon_ids → in_categories, name → name_cont or search, price range → price_gte / price_lte.
7. Rewrite cart/checkout calls as resource operations. This is the deepest change. The cleanest path is to delete your checkout step controller wholesale and rebuild it as a single page that PATCHes the cart and POSTs to nested resources, then calls complete at the end.
8. Stop walking included. Replace JSON:API normalization helpers with direct attribute access. Use expand to pull in associations, and accept that they arrive inlined.
9. Replace numeric IDs and slugs with prefixed IDs. Update any code that parsed integers out of IDs, stored IDs as numbers in state, or constructed admin links from raw IDs.
10. Switch the OAuth token endpoints for JWT. The /spree_oauth/token endpoints are no longer the customer auth surface; use /api/v3/store/auth/login / /auth/refresh / /auth/logout. Refresh tokens are rotated on each refresh call, and logout revokes the token server-side.

For the conceptual changes — flat JSON, RESTful checkout, Markets — give yourself a sprint of breathing room rather than treating the migration as a string-replace. The win on the other side is a smaller, more obvious client surface and a Store API that lines up with the Admin API for full-stack work.

See also

• Store API — Introduction
• Authentication
• Querying (Ransack, sorting, pagination, expand, fields)
• Relations — expand rules and nested associations
• Localization — Markets, currencies, locales
• Errors