Configuration

// Set locale and currency per request
const products = await client.products.list({}, {
  locale: 'fr',
  currency: 'EUR',
  country: 'FR',
})

// Works with all endpoints
const category = await client.categories.get('clothing/shirts', {
  expand: ['ancestors'],
}, {
  locale: 'de',
  currency: 'EUR',
})

// Client-level default — every request runs against the POS channel
const client = createClient({
  baseUrl: 'https://api.mystore.com',
  publishableKey: 'pk_xxx',
  channel: 'pos',
})

// Sticky setter — switch channels mid-session (e.g. after the user
// changes storefront context)
client.setChannel('wholesale')

// Per-request override — one request only
const products = await client.products.list({}, { channel: 'pos' })

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

try {
  await client.products.get('non-existent');
} catch (error) {
  if (error instanceof SpreeError) {
    console.log(error.code);    // 'record_not_found'
    console.log(error.message); // 'Product not found'
    console.log(error.status);  // 404
    console.log(error.details); // Validation errors (if any)
  }
}

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

const client = createClient({
  baseUrl: 'https://api.mystore.com',
  publishableKey: 'pk_xxx',
  fetch: customFetchImplementation,
});

const order = await client.orders.get('or_abc123', {}, { token });

// Monetary fields are strings
order.total;         // "129.99"
order.item_total;    // "99.99"
order.delivery_total;    // "10.00"
order.tax_total;     // "20.00"

// Display fields include currency formatting
order.display_total; // "$129.99"

// Convert to number when needed for calculations
const total = parseFloat(order.total);

import { CountryCode, CurrencyCode, LocaleCode } from '@spree/sdk';

client.setCurrency(CurrencyCode.EUR);
client.setLocale(LocaleCode.pt_BR); // 'pt-BR'

// Plain strings work too, and a code Spree does not know is a type error
const country: CountryCode = 'DE';

// Every currency, for a picker
const currencies = Object.values(CurrencyCode);

import type {
  Product,
  Order,
  Cart,
  Variant,
  Category,
  LineItem,
  Address,
  Customer,
  PaginatedResponse,
} from '@spree/sdk';

// All responses are fully typed
const products: PaginatedResponse<Product> = await client.products.list();
const category: Category = await client.categories.get('clothing');

# app/serializers/my_store/product_serializer.rb
module MyStore
  class ProductSerializer < Spree::Api::V3::ProductSerializer
    typelize brand_id: :string

    attribute :brand_id do |product|
      product.brand&.prefixed_id
    end
  end
end

# config/initializers/spree.rb
Spree.api.product_serializer = MyStore::ProductSerializer

// types/spree.d.ts
declare module '@spree/sdk' {
  interface Product {
    brand_id: string;
  }
}

const products = await client.products.list();
products.data.forEach((product) => {
  console.log(product.brand_id); // fully typed
});

import { z } from 'zod';
import { ProductSchema } from '@spree/sdk/zod';

const MyProductSchema = ProductSchema.extend({
  brand_id: z.string(),
});

// Use for runtime validation
const product = MyProductSchema.parse(apiResponse);