@spree/docs 0.1.0

package/dist/api-reference/store-api/introduction.md

@@ -0,0 +1,34 @@
+---
+title: "Store API"
+sidebarTitle: "Introduction"
+---
+
+This API reference includes Spree Store APIs, which are REST APIs exposed by the Spree application. They are used to create a storefront for your commerce store, such as a website, point of sale or a commerce mobile app.
+
+All API Routes are prefixed with `/api/v3/store`. So, during development, the API Routes will be available under the path `http://localhost:3000/api/v3/store`. For production, replace `http://localhost:3000` with your Spree application URL.
+
+## Using SDK
+
+We recommend using the Spree SDK to interact with the Store API. The SDK provides a convenient way to make API requests and handle responses.
+
+### 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: 'http://localhost:3000',
+  publishableKey: 'spree_pk_xxx'
+});
+```

package/dist/api-reference/store-api/localization.md

@@ -0,0 +1,279 @@
+---
+title: "Localization"
+sidebarTitle: "Localization"
+description: "How to set locale, currency, and country for API requests"
+---
+
+The Store API supports multi-language, multi-currency, and market-aware responses. Use request headers to control the locale, currency, and country for each request.
+
+## Headers
+
+| Header | Example | Description |
+|--------|---------|-------------|
+| `X-Spree-Locale` | `fr` | Language for translated content (product names, descriptions, etc.) |
+| `X-Spree-Currency` | `EUR` | Currency for prices and totals |
+| `X-Spree-Country` | `FR` | Country ISO code for market resolution |
+
+## Client-Level Defaults
+
+Set locale, currency, and country once at initialization — all subsequent requests use these defaults:
+
+```typescript SDK
+import { createClient } from '@spree/sdk'
+
+const client = createClient({
+  baseUrl: 'https://api.mystore.com',
+  publishableKey: 'spree_pk_xxx',
+  locale: 'fr',
+  currency: 'EUR',
+  country: 'FR',
+})
+
+// All requests use fr/EUR/FR automatically
+const products = await client.products.list()
+```
+
+Update defaults at any time:
+
+```typescript
+client.setLocale('de')
+client.setCurrency('EUR')
+client.setCountry('DE')
+```
+
+## Per-Request Overrides
+
+Override client defaults for individual requests:
+
+
+```typescript SDK
+const products = await client.products.list({}, {
+  locale: 'fr',
+  currency: 'EUR',
+  country: 'FR',
+})
+```
+
+```bash cURL
+curl -G 'http://localhost:3000/api/v3/store/products' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -H 'X-Spree-Locale: fr' \
+  -H 'X-Spree-Currency: EUR'
+```
+
+
+## Country and Markets
+
+The `X-Spree-Country` header resolves the customer's [market](/developer/core-concepts/markets), which influences default locale and currency. Markets allow you to configure different pricing, languages, and product availability per region.
+
+
+```typescript SDK
+// Setting country automatically resolves the market
+const products = await client.products.list({}, {
+  country: 'DE', // Resolves German market → EUR, de locale
+})
+```
+
+```bash cURL
+curl -G 'http://localhost:3000/api/v3/store/products' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -H 'X-Spree-Country: DE'
+```
+
+
+When a market is resolved from the country:
+1. The market's default locale is used (unless overridden by `X-Spree-Locale`)
+2. The market's default currency is used (unless overridden by `X-Spree-Currency`)
+
+You can also resolve the market explicitly using the [Markets API](/developer/sdk/store/markets):
+
+
+```typescript SDK
+// Resolve which market applies for a country
+const market = await client.markets.resolve('DE')
+// => { id: "mkt_xxx", name: "Europe", currency: "EUR", default_locale: "de", ... }
+
+// Then set the client defaults
+client.setLocale(market.default_locale)
+client.setCurrency(market.currency)
+client.setCountry('DE')
+```
+
+```bash cURL
+# Resolve market by country
+curl 'http://localhost:3000/api/v3/store/markets/resolve?country=DE' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx'
+```
+
+
+## Resolution Priority
+
+Each value is resolved in the following order:
+
+### Locale
+1. `X-Spree-Locale` header
+2. `locale` query parameter
+3. Market default locale (if country is set)
+4. Store default locale
+
+### Currency
+1. `X-Spree-Currency` header
+2. `currency` query parameter
+3. Market default currency (if country is set)
+4. Store default currency
+
+### Market
+1. `X-Spree-Country` header
+2. `country` query parameter
+
+> **NOTE:** The locale and currency must be supported by the current store. If an unsupported value is provided, the API falls back to the store's default.
+
+## Translated Content
+
+When a locale is set, all translatable fields are returned in the requested language. This includes product names, descriptions, category names, and other content managed through [translations](/developer/core-concepts/translations).
+
+
+```typescript SDK
+// English (default)
+const enProduct = await client.products.get('spree-tote')
+console.log(enProduct.name) // "Spree Tote"
+
+// French
+const frProduct = await client.products.get('spree-tote', {}, {
+  locale: 'fr',
+})
+console.log(frProduct.name) // "Sac Spree"
+```
+
+```bash cURL
+# English
+curl 'http://localhost:3000/api/v3/store/products/spree-tote' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -H 'X-Spree-Locale: en'
+
+# French
+curl 'http://localhost:3000/api/v3/store/products/spree-tote' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -H 'X-Spree-Locale: fr'
+```
+
+
+If a translation doesn't exist for the requested locale, the API falls back to the store's default locale automatically.
+
+## Currency-Aware Prices
+
+All price fields in the response reflect the requested currency:
+
+
+```typescript SDK
+// USD prices
+const usdProduct = await client.products.get('spree-tote', {}, {
+  currency: 'USD',
+})
+console.log(usdProduct.price) // { amount: "15.99", currency: "USD" }
+
+// EUR prices
+const eurProduct = await client.products.get('spree-tote', {}, {
+  currency: 'EUR',
+})
+console.log(eurProduct.price) // { amount: "14.49", currency: "EUR" }
+```
+
+```bash cURL
+# USD prices
+curl 'http://localhost:3000/api/v3/store/products/spree-tote' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -H 'X-Spree-Currency: USD'
+
+# EUR prices
+curl 'http://localhost:3000/api/v3/store/products/spree-tote' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -H 'X-Spree-Currency: EUR'
+```
+
+
+## Discovering Available Options
+
+Use the dedicated endpoints to discover which markets, countries, locales, and currencies are available. These are derived from your store's [markets](/developer/core-concepts/markets) configuration.
+
+### Markets
+
+List all markets to get the full picture of regions, currencies, and supported locales:
+
+
+```typescript SDK
+const { data: markets } = await client.markets.list()
+// [
+//   { id: "mkt_xxx", name: "North America", currency: "USD", default_locale: "en",
+//     supported_locales: ["en", "es"], countries: [{ iso: "US", ... }, { iso: "CA", ... }] },
+//   { id: "mkt_yyy", name: "Europe", currency: "EUR", default_locale: "de",
+//     supported_locales: ["de", "en", "fr"], countries: [{ iso: "DE", ... }, { iso: "FR", ... }] },
+// ]
+```
+
+```bash cURL
+curl 'http://localhost:3000/api/v3/store/markets' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx'
+```
+
+
+### Countries
+
+List all countries or countries within a specific market. Each country includes its market's currency and supported locales:
+
+
+```typescript SDK
+// All countries across all markets
+const { data: countries } = await client.countries.list()
+
+// Countries in a specific market (useful for checkout address forms)
+const { data: marketCountries } = await client.markets.countries.list('mkt_xxx')
+
+// Get a single country with states
+const usa = await client.countries.get('US', {
+  expand: ['states'],
+})
+console.log(usa.states) // [{ abbr: "CA", name: "California" }, ...]
+```
+
+```bash cURL
+# All countries
+curl 'http://localhost:3000/api/v3/store/countries' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx'
+
+# Countries in a specific market
+curl 'http://localhost:3000/api/v3/store/markets/mkt_xxx/countries' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx'
+
+# Get a country with states
+curl 'http://localhost:3000/api/v3/store/countries/US?expand=states' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx'
+```
+
+
+### Locales
+
+
+```typescript SDK
+const { data: locales } = await client.locales.list()
+// [{ code: "en", name: "English" }, { code: "fr", name: "French" }, ...]
+```
+
+```bash cURL
+curl 'http://localhost:3000/api/v3/store/locales' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx'
+```
+
+
+### Currencies
+
+
+```typescript SDK
+const { data: currencies } = await client.currencies.list()
+// [{ iso_code: "USD", name: "US Dollar", symbol: "$" }, { iso_code: "EUR", name: "Euro", symbol: "€" }, ...]
+```
+
+```bash cURL
+curl 'http://localhost:3000/api/v3/store/currencies' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx'
+```

package/dist/api-reference/store-api/metadata.md

@@ -0,0 +1,160 @@
+---
+title: "Metadata"
+sidebarTitle: "Metadata"
+description: "How to store and retrieve custom metadata on carts, orders, and line items"
+---
+
+The Store API supports storing arbitrary key-value **metadata** on carts (orders) and line items. Metadata is useful for tracking custom information like gift messages, attribution data, or integration-specific fields.
+
+> **NOTE:** Metadata is different from [metafields](/developer/core-concepts/metafields). Metadata is simple JSON storage (untyped, no schema), while metafields are structured, typed, and schema-defined. Use metadata for integration data and internal tracking. Use metafields for customer-facing custom attributes.
+
+## Cart Metadata
+
+You can attach metadata when creating a cart:
+
+
+```typescript SDK
+const cart = await client.carts.create({
+  metadata: {
+    utm_source: 'google',
+    utm_campaign: 'summer_sale',
+    referral_code: 'FRIEND20',
+  },
+})
+```
+
+```bash cURL
+curl -X POST 'http://localhost:3000/api/v3/store/carts' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "metadata": {
+      "utm_source": "google",
+      "utm_campaign": "summer_sale",
+      "referral_code": "FRIEND20"
+    }
+  }'
+```
+
+
+## Cart Metadata (Update)
+
+Update metadata on an existing cart:
+
+
+```typescript SDK
+await client.carts.update(cart.id, {
+  metadata: {
+    gift_message: 'Happy Birthday!',
+    preferred_delivery: 'morning',
+  },
+}, { spreeToken: cart.token })
+```
+
+```bash cURL
+curl -X PATCH 'http://localhost:3000/api/v3/store/carts/cart_xxx' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -H 'X-Spree-Token: <order_token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "metadata": {
+      "gift_message": "Happy Birthday!",
+      "preferred_delivery": "morning"
+    }
+  }'
+```
+
+
+## Item Metadata
+
+Attach metadata to individual items when adding or updating them:
+
+### When Adding an Item
+
+
+```typescript SDK
+await client.carts.items.create(cart.id, {
+  variant_id: 'variant_abc123',
+  quantity: 1,
+  metadata: {
+    personalization: 'John',
+    gift_wrap: true,
+  },
+}, { spreeToken: cart.token })
+```
+
+```bash cURL
+curl -X POST 'http://localhost:3000/api/v3/store/carts/cart_xxx/items' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -H 'X-Spree-Token: <order_token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "variant_id": "variant_abc123",
+    "quantity": 1,
+    "metadata": {
+      "personalization": "John",
+      "gift_wrap": true
+    }
+  }'
+```
+
+
+### When Updating an Item
+
+Updating metadata **merges** with existing values rather than replacing them:
+
+
+```typescript SDK
+await client.carts.items.update(cart.id, 'li_xyz789', {
+  metadata: {
+    personalization: 'Jane', // Updates existing key
+    engraving: 'With Love',  // Adds new key
+  },
+}, { spreeToken: cart.token })
+```
+
+```bash cURL
+curl -X PATCH 'http://localhost:3000/api/v3/store/carts/cart_xxx/items/li_xyz789' \
+  -H 'X-Spree-Api-Key: spree_pk_xxx' \
+  -H 'X-Spree-Token: <order_token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "metadata": {
+      "personalization": "Jane",
+      "engraving": "With Love"
+    }
+  }'
+```
+
+
+> **INFO:** Metadata values can be any JSON-serializable type: strings, numbers, booleans, arrays, or nested objects.
+
+## Metadata Structure
+
+Metadata is stored as a flat JSON object. You can use any keys and values:
+
+```json
+{
+  "metadata": {
+    "string_value": "hello",
+    "number_value": 42,
+    "boolean_value": true,
+    "nested_object": {
+      "key": "value"
+    }
+  }
+}
+```
+
+## Metadata vs Metafields
+
+| | Metadata | Metafields |
+|-|----------|------------|
+| **Structure** | Untyped JSON | Schema-defined, strongly typed |
+| **Validation** | None | Type-specific validation |
+| **Visibility** | Write-only in Store API | Configurable (public/private) |
+| **Admin UI** | JSON preview | Dedicated form fields |
+| **Best for** | Integration data, tracking, attribution | Product specs, custom fields, customer-facing data |
+| **API access** | Write via Store API, read via Admin API | Read/write via both APIs |
+
+For more details on metafields, see the [Metafields guide](/developer/core-concepts/metafields).

package/dist/api-reference/store-api/monetary-amounts.md

@@ -0,0 +1,65 @@
+---
+title: "Monetary Amounts"
+sidebarTitle: "Monetary Amounts"
+description: "How monetary values are represented in API responses"
+---
+
+All monetary values in the Store API are returned as **strings** (e.g., `"29.99"`, `"0.0"`), not numbers. This preserves decimal precision and avoids floating-point rounding issues common with JSON numbers.
+
+## Response Format
+
+Every monetary field has a corresponding `display_` field that includes currency formatting:
+
+```json
+{
+  "total": "129.99",
+  "display_total": "$129.99",
+  "item_total": "99.99",
+  "display_item_total": "$99.99",
+  "ship_total": "10.00",
+  "display_ship_total": "$10.00",
+  "tax_total": "20.00",
+  "display_tax_total": "$20.00"
+}
+```
+
+## Affected Types
+
+This convention applies to all monetary fields across all resources:
+
+| Resource | Monetary Fields |
+|----------|----------------|
+| **Order** | `total`, `item_total`, `ship_total`, `tax_total`, `adjustment_total`, `promo_total`, `included_tax_total`, `additional_tax_total` |
+| **Line Item** | `price`, `total`, `adjustment_total`, `promo_total`, `pre_tax_amount`, `discounted_amount`, `compare_at_amount` |
+| **Shipment** | `cost` |
+| **Payment** | `amount` |
+| **Gift Card** | `amount`, `amount_used`, `amount_authorized`, `amount_remaining` |
+| **Store Credit** | `amount`, `amount_used`, `amount_remaining` |
+| **Price** | `amount`, `compare_at_amount` |
+
+## Working with Amounts
+
+
+```typescript SDK
+const order = await client.orders.get('or_abc123', {}, { token });
+
+// Raw string values
+order.total;         // "129.99"
+order.display_total; // "$129.99"
+
+// Convert to number for calculations
+const total = parseFloat(order.total);
+```
+
+```javascript JavaScript
+const data = await response.json();
+
+// Use display fields for rendering
+element.textContent = data.display_total; // "$129.99"
+
+// Use raw fields for calculations
+const total = parseFloat(data.total);
+```
+
+
+> **TIP:** Use `display_*` fields for rendering prices in the UI — they are pre-formatted with the correct currency symbol and decimal places based on the order's currency. Use the raw string fields when you need to perform calculations.