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
SDK docs fixes: use `media` instead of `images` and `custom_fields` i… (#13906)
Damian Legawiec15cfb3860d0f
diff --git a/docs/api-reference/store-api/authentication.mdx b/docs/api-reference/store-api/authentication.mdxindex b9a27166c3..d6603b7018 100644--- a/docs/api-reference/store-api/authentication.mdx+++ b/docs/api-reference/store-api/authentication.mdx@@ -19,7 +19,7 @@ import { createClient } from '@spree/sdk'const client = createClient({baseUrl: 'http://localhost:3000',- publishableKey: 'spree_pk_xxx',+ publishableKey: 'pk_xxx',})// The SDK automatically sends the publishable key with every request@@ -28,12 +28,12 @@ const products = await client.products.list()```bash cURLcurl -X GET 'http://localhost:3000/api/v3/store/products' \- -H 'X-Spree-Api-Key: spree_pk_xxx'+ -H 'X-Spree-Api-Key: pk_xxx'```</CodeGroup>-Publishable API keys are prefixed with `spree_pk_`. You can create them in the Spree Admin under **Settings > API Keys** or via the Spree CLI:+Publishable API keys are prefixed with `pk_`. You can create them in the Spree Admin under **Settings > API Keys** or via the Spree CLI:```bashspree api-key create # Create a new API key@@ -75,13 +75,13 @@ const orders = await client.customer.orders.list({}, { token })```bash cURL# Logincurl -X POST 'http://localhost:3000/api/v3/store/auth/login' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-H 'Content-Type: application/json' \-d '{"email": "[email protected]", "password": "password123"}'# Use the returned token for authenticated requestscurl -X GET 'http://localhost:3000/api/v3/store/orders' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-H 'Authorization: Bearer <jwt_token>'```@@ -103,7 +103,7 @@ const { token, user } = await client.customers.create({```bash cURLcurl -X POST 'http://localhost:3000/api/v3/store/customers' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-H 'Content-Type: application/json' \-d '{"email": "[email protected]",@@ -128,7 +128,7 @@ const { token } = await client.auth.refresh({ token: currentToken })```bash cURLcurl -X POST 'http://localhost:3000/api/v3/store/auth/refresh' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-H 'Authorization: Bearer <current_jwt_token>'```@@ -159,11 +159,11 @@ await client.carts.items.create(cart.id, {```bash cURL# Create a cartcurl -X POST 'http://localhost:3000/api/v3/store/carts' \- -H 'X-Spree-Api-Key: spree_pk_xxx'+ -H 'X-Spree-Api-Key: pk_xxx'# Use the returned token for cart operationscurl -X POST 'http://localhost:3000/api/v3/store/carts/cart_xxx/items' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-H 'X-Spree-Token: <order_token>' \-H 'Content-Type: application/json' \-d '{"variant_id": "variant_abc123", "quantity": 1}'@@ -186,7 +186,7 @@ await client.carts.associate(cart.id, {```bash cURLcurl -X PATCH 'http://localhost:3000/api/v3/store/carts/cart_xxx/associate' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-H 'Authorization: Bearer <jwt_token>' \-H 'X-Spree-Token: <order_token>'```@@ -197,6 +197,6 @@ curl -X PATCH 'http://localhost:3000/api/v3/store/carts/cart_xxx/associate' \| Method | Header | Use Case ||--------|--------|----------|-| API Key | `X-Spree-Api-Key: spree_pk_xxx` | All requests (required) |+| API Key | `X-Spree-Api-Key: pk_xxx` | All requests (required) || JWT Token | `Authorization: Bearer <token>` | Authenticated customer actions || Order Token | `X-Spree-Token: <token>` | Guest cart and checkout |diff --git a/docs/api-reference/store-api/errors.mdx b/docs/api-reference/store-api/errors.mdxindex 8d9908a426..69897cf0e8 100644--- a/docs/api-reference/store-api/errors.mdx+++ b/docs/api-reference/store-api/errors.mdx@@ -145,7 +145,7 @@ Validation errors include an additional `details` field with per-field error mes```bashcurl https://api.mystore.com/api/v3/store/products/prod_nonexistent \- -H "Authorization: Bearer spree_pk_xxx"+ -H "Authorization: Bearer pk_xxx"``````json 404@@ -185,7 +185,7 @@ curl -X POST https://api.mystore.com/api/v3/store/account/addresses \```bashcurl -X POST https://api.mystore.com/api/v3/store/carts/cart_xxx/items \- -H "Authorization: Bearer spree_pk_xxx" \+ -H "Authorization: Bearer pk_xxx" \-H "X-Spree-Token: abc123" \-H "Content-Type: application/json" \-d '{"variant_id": "var_xxx", "quantity": 999}'@@ -204,7 +204,7 @@ curl -X POST https://api.mystore.com/api/v3/store/carts/cart_xxx/items \```bashcurl -X POST https://api.mystore.com/api/v3/store/carts/cart_xxx/complete \- -H "Authorization: Bearer spree_pk_xxx"+ -H "Authorization: Bearer pk_xxx"``````json 422diff --git a/docs/api-reference/store-api/idempotency.mdx b/docs/api-reference/store-api/idempotency.mdxindex 4bf49bafc7..733e976632 100644--- a/docs/api-reference/store-api/idempotency.mdx+++ b/docs/api-reference/store-api/idempotency.mdx@@ -16,7 +16,7 @@ Include an `Idempotency-Key` header with a unique value (e.g., a UUID) on any su```bashcurl -X POST https://api.mystore.com/api/v3/store/carts/cart_xxx/items \- -H "Authorization: Bearer spree_pk_xxx" \+ -H "Authorization: Bearer pk_xxx" \-H "X-Spree-Token: abc123" \-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \-H "Content-Type: application/json" \@@ -98,7 +98,7 @@ import { createClient } from '@spree/sdk'const client = createClient({baseUrl: 'http://localhost:3000',- publishableKey: 'spree_pk_xxx',+ publishableKey: 'pk_xxx',})// Add item to cart with idempotency keydiff --git a/docs/api-reference/store-api/introduction.mdx b/docs/api-reference/store-api/introduction.mdxindex e4bba80c13..970c568c9a 100644--- a/docs/api-reference/store-api/introduction.mdx+++ b/docs/api-reference/store-api/introduction.mdx@@ -29,6 +29,6 @@ import { createClient } from '@spree/sdk';// Initialize the clientconst client = createClient({baseUrl: 'http://localhost:3000',- publishableKey: 'spree_pk_xxx'+ publishableKey: 'pk_xxx'});```diff --git a/docs/api-reference/store-api/localization.mdx b/docs/api-reference/store-api/localization.mdxindex d025632c88..10c1c278ae 100644--- a/docs/api-reference/store-api/localization.mdx+++ b/docs/api-reference/store-api/localization.mdx@@ -23,7 +23,7 @@ import { createClient } from '@spree/sdk'const client = createClient({baseUrl: 'https://api.mystore.com',- publishableKey: 'spree_pk_xxx',+ publishableKey: 'pk_xxx',locale: 'fr',currency: 'EUR',country: 'FR',@@ -57,7 +57,7 @@ const products = await client.products.list({}, {```bash cURLcurl -G 'http://localhost:3000/api/v3/store/products' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-H 'X-Spree-Locale: fr' \-H 'X-Spree-Currency: EUR'```@@ -79,7 +79,7 @@ const products = await client.products.list({}, {```bash cURLcurl -G 'http://localhost:3000/api/v3/store/products' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-H 'X-Spree-Country: DE'```@@ -107,7 +107,7 @@ client.setCountry('DE')```bash cURL# Resolve market by countrycurl 'http://localhost:3000/api/v3/store/markets/resolve?country=DE' \- -H 'X-Spree-Api-Key: spree_pk_xxx'+ -H 'X-Spree-Api-Key: pk_xxx'```</CodeGroup>@@ -157,12 +157,12 @@ console.log(frProduct.name) // "Sac Spree"```bash cURL# Englishcurl 'http://localhost:3000/api/v3/store/products/spree-tote' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-H 'X-Spree-Locale: en'# Frenchcurl 'http://localhost:3000/api/v3/store/products/spree-tote' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-H 'X-Spree-Locale: fr'```@@ -193,12 +193,12 @@ console.log(eurProduct.price) // { amount: "14.49", currency: "EUR" }```bash cURL# USD pricescurl 'http://localhost:3000/api/v3/store/products/spree-tote' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-H 'X-Spree-Currency: USD'# EUR pricescurl 'http://localhost:3000/api/v3/store/products/spree-tote' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-H 'X-Spree-Currency: EUR'```@@ -226,7 +226,7 @@ const { data: markets } = await client.markets.list()```bash cURLcurl 'http://localhost:3000/api/v3/store/markets' \- -H 'X-Spree-Api-Key: spree_pk_xxx'+ -H 'X-Spree-Api-Key: pk_xxx'```</CodeGroup>@@ -254,15 +254,15 @@ console.log(usa.states) // [{ abbr: "CA", name: "California" }, ...]```bash cURL# All countriescurl 'http://localhost:3000/api/v3/store/countries' \- -H 'X-Spree-Api-Key: spree_pk_xxx'+ -H 'X-Spree-Api-Key: pk_xxx'# Countries in a specific marketcurl 'http://localhost:3000/api/v3/store/markets/mkt_xxx/countries' \- -H 'X-Spree-Api-Key: spree_pk_xxx'+ -H 'X-Spree-Api-Key: pk_xxx'# Get a country with statescurl 'http://localhost:3000/api/v3/store/countries/US?expand=states' \- -H 'X-Spree-Api-Key: spree_pk_xxx'+ -H 'X-Spree-Api-Key: pk_xxx'```</CodeGroup>@@ -278,7 +278,7 @@ const { data: locales } = await client.locales.list()```bash cURLcurl 'http://localhost:3000/api/v3/store/locales' \- -H 'X-Spree-Api-Key: spree_pk_xxx'+ -H 'X-Spree-Api-Key: pk_xxx'```</CodeGroup>@@ -294,7 +294,7 @@ const { data: currencies } = await client.currencies.list()```bash cURLcurl 'http://localhost:3000/api/v3/store/currencies' \- -H 'X-Spree-Api-Key: spree_pk_xxx'+ -H 'X-Spree-Api-Key: pk_xxx'```</CodeGroup>diff --git a/docs/api-reference/store-api/metadata.mdx b/docs/api-reference/store-api/metadata.mdxindex f5e77e5c8e..65b3a9e54c 100644--- a/docs/api-reference/store-api/metadata.mdx+++ b/docs/api-reference/store-api/metadata.mdx@@ -28,7 +28,7 @@ const cart = await client.carts.create({```bash cURLcurl -X POST 'http://localhost:3000/api/v3/store/carts' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-H 'Content-Type: application/json' \-d '{"metadata": {@@ -58,7 +58,7 @@ await client.carts.update(cart.id, {```bash cURLcurl -X PATCH 'http://localhost:3000/api/v3/store/carts/cart_xxx' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-H 'X-Spree-Token: <order_token>' \-H 'Content-Type: application/json' \-d '{@@ -92,7 +92,7 @@ await client.carts.items.create(cart.id, {```bash cURLcurl -X POST 'http://localhost:3000/api/v3/store/carts/cart_xxx/items' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-H 'X-Spree-Token: <order_token>' \-H 'Content-Type: application/json' \-d '{@@ -124,7 +124,7 @@ await client.carts.items.update(cart.id, 'li_xyz789', {```bash cURLcurl -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-Api-Key: pk_xxx' \-H 'X-Spree-Token: <order_token>' \-H 'Content-Type: application/json' \-d '{diff --git a/docs/api-reference/store-api/querying.mdx b/docs/api-reference/store-api/querying.mdxindex 2ab058e0e2..8fc449a837 100644--- a/docs/api-reference/store-api/querying.mdx+++ b/docs/api-reference/store-api/querying.mdx@@ -22,7 +22,7 @@ const products = await client.products.list({```bash cURLcurl -G 'http://localhost:3000/api/v3/store/products' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \--data-urlencode 'q[name_cont]=shirt' \--data-urlencode 'q[price_gte]=20' \--data-urlencode 'q[price_lte]=100'@@ -72,7 +72,7 @@ const products = await client.products.list({```bash cURLcurl -G 'http://localhost:3000/api/v3/store/products' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \--data-urlencode 'q[name_cont]=shirt' \--data-urlencode 'q[price_gteq]=20' \--data-urlencode 'q[price_lteq]=100'@@ -106,12 +106,12 @@ const categories = await client.categories.list({```bash cURL# Products in a specific category (includes descendants)curl -G 'http://localhost:3000/api/v3/store/products' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \--data-urlencode 'q[in_category]=ctg_abc123'# Top-level categories onlycurl -G 'http://localhost:3000/api/v3/store/categories' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \--data-urlencode 'q[depth_eq]=1'```@@ -134,7 +134,7 @@ const products = await client.products.list({```bash cURLcurl -G 'http://localhost:3000/api/v3/store/products' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \--data-urlencode 'q[price_gte]=20' \--data-urlencode 'q[price_lte]=100' \--data-urlencode 'q[with_option_value_ids][]=optval_abc' \@@ -179,12 +179,12 @@ const products = await client.products.list({```bash cURL# Sort by price low to highcurl -G 'http://localhost:3000/api/v3/store/products' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-d 'sort=price'# Sort by price high to lowcurl -G 'http://localhost:3000/api/v3/store/products' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-d 'sort=-price'```@@ -224,12 +224,12 @@ const orders = await client.customer.orders.list({```bash cURL# Categories sorted by namecurl -G 'http://localhost:3000/api/v3/store/categories' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-d 'sort=name'# Customer orders by most recentcurl -G 'http://localhost:3000/api/v3/store/customer/orders' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-H 'Authorization: Bearer <token>' \-d 'sort=-completed_at'```@@ -244,14 +244,14 @@ Use the `expand` parameter to include associated resources in the response. Pass```typescript SDKconst product = await client.products.get('spree-tote', {- expand: ['variants', 'images'],+ expand: ['variants', 'media'],})``````bash cURLcurl -G 'http://localhost:3000/api/v3/store/products/spree-tote' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \- -d 'expand=variants,images'+ -H 'X-Spree-Api-Key: pk_xxx' \+ -d 'expand=variants,media'```</CodeGroup>@@ -263,14 +263,14 @@ Use dot notation to expand nested associations (up to 4 levels deep):<CodeGroup>```typescript SDK-// Expand variants and their images in one request+// Expand variants and their media in one requestconst product = await client.products.get('spree-tote', {- expand: ['variants.images'],+ expand: ['variants.media'],})// Multiple nested expandsconst product = await client.products.get('spree-tote', {- expand: ['variants.images', 'variants.metafields', 'option_types'],+ expand: ['variants.media', 'variants.custom_fields', 'option_types'],})// Category with nested children@@ -280,15 +280,15 @@ const category = await client.categories.get('clothing/shirts', {``````bash cURL-# Expand variants with their images+# Expand variants with their mediacurl -G 'http://localhost:3000/api/v3/store/products/spree-tote' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \- -d 'expand=variants.images'+ -H 'X-Spree-Api-Key: pk_xxx' \+ -d 'expand=variants.media'# Multiple nested expandscurl -G 'http://localhost:3000/api/v3/store/products/spree-tote' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \- -d 'expand=variants.images,variants.metafields,option_types'+ -H 'X-Spree-Api-Key: pk_xxx' \+ -d 'expand=variants.media,variants.custom_fields,option_types'```</CodeGroup>@@ -296,7 +296,7 @@ curl -G 'http://localhost:3000/api/v3/store/products/spree-tote' \### Rules- Maximum depth is **4 levels** (e.g., `a.b.c.d`)-- A nested expand automatically includes its parent — `expand=variants.images` expands both `variants` and their `images`+- A nested expand automatically includes its parent — `expand=variants.media` expands both `variants` and their `media`- Nested expand only applies to conditional associations (those controlled by `expand`)## Field Selection@@ -319,7 +319,7 @@ const product = await client.products.get('spree-tote', {```bash cURLcurl -G 'http://localhost:3000/api/v3/store/products' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-d 'fields=name,slug,price,display_price'```@@ -380,7 +380,7 @@ console.log(meta)```bash cURLcurl -G 'http://localhost:3000/api/v3/store/products' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-d 'page=2' \-d 'limit=10'```diff --git a/docs/api-reference/store-api/rate-limitting.mdx b/docs/api-reference/store-api/rate-limitting.mdxindex 6995ac16b6..1eee10d83b 100644--- a/docs/api-reference/store-api/rate-limitting.mdx+++ b/docs/api-reference/store-api/rate-limitting.mdx@@ -70,7 +70,7 @@ import { createClient } from '@spree/sdk'const client = createClient({baseUrl: 'http://localhost:3000',- publishableKey: 'spree_pk_xxx',+ publishableKey: 'pk_xxx',retry: {maxRetries: 2, // Number of retry attempts (default: 2)baseDelay: 300, // Initial delay in ms (default: 300)diff --git a/docs/api-reference/store-api/relations.mdx b/docs/api-reference/store-api/relations.mdxindex b3d6007c80..72e9def5e5 100644--- a/docs/api-reference/store-api/relations.mdx+++ b/docs/api-reference/store-api/relations.mdx@@ -13,20 +13,20 @@ Pass a comma-separated list of relation names via the `expand` query parameter:<CodeGroup>```typescript SDK-// Product with variants and images+// Product with variants and mediaconst product = await client.products.get('spree-tote', {- expand: ['variants', 'images'],+ expand: ['variants', 'media'],})// Access included relations directlyconsole.log(product.variants) // Array of variant objects-console.log(product.images) // Array of image objects+console.log(product.media) // Array of media objects``````bash cURLcurl -G 'http://localhost:3000/api/v3/store/products/spree-tote' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \- -d 'expand=variants,images'+ -H 'X-Spree-Api-Key: pk_xxx' \+ -d 'expand=variants,media'```</CodeGroup>@@ -45,7 +45,7 @@ Without `expand`, relation fields are omitted from the response:}```-With `?expand=variants,images`, the related resources are embedded:+With `?expand=variants,media`, the related resources are embedded:```json{@@ -63,11 +63,18 @@ With `?expand=variants,images`, the related resources are embedded:"option_values": [{ "name": "Red", "option_type_name": "Color" }]}],- "images": [+ "media": [{- "id": "img_9xPq2wLm",- "url": "https://cdn.example.com/spree-tote.jpg",- "alt": "Spree Tote"+ "id": "asset_9xPq2wLm",+ "position": 1,+ "alt": "Spree Tote",+ "media_type": "image",+ "product_id": "prod_86Rf07xd4z",+ "variant_ids": ["variant_k5nR8xLq"],+ "original_url": "https://cdn.example.com/spree-tote.jpg",+ "small_url": "https://cdn.example.com/spree-tote-small.jpg",+ "medium_url": "https://cdn.example.com/spree-tote-medium.jpg",+ "large_url": "https://cdn.example.com/spree-tote-large.jpg"}]}@@ -81,24 +88,25 @@ With `?expand=variants,images`, the related resources are embedded:|----------|-------------|| `variants` | All purchasable variants || `default_variant` | The default variant |-| `master_variant` | The master variant |-| `images` | All product images (across all variants) |+| `media` | All product media (images and videos across all variants) |+| `primary_media` | The main product image || `option_types` | Option types (e.g., Size, Color) || `categories` | Categories this product belongs to |-| `metafields` | Public metafields (custom structured data) |+| `custom_fields` | Public custom fields (structured metadata) |+| `prior_price` | Previous price history (for showing strikethrough) |<CodeGroup>```typescript SDKconst product = await client.products.get('spree-tote', {- expand: ['variants', 'images', 'option_types', 'metafields'],+ expand: ['variants', 'media', 'option_types', 'custom_fields'],})``````bash cURLcurl -G 'http://localhost:3000/api/v3/store/products/spree-tote' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \- -d 'expand=variants,images,option_types,metafields'+ -H 'X-Spree-Api-Key: pk_xxx' \+ -d 'expand=variants,media,option_types,custom_fields'```</CodeGroup>@@ -107,9 +115,10 @@ curl -G 'http://localhost:3000/api/v3/store/products/spree-tote' \| Relation | Description ||----------|-------------|-| `ancestors` | Parent categories (for breadcrumbs) |+| `parent` | Parent category |+| `ancestors` | All ancestor categories (for breadcrumbs) || `children` | Direct child categories |-| `products` | Products in this category |+| `custom_fields` | Public custom fields (structured metadata) |<CodeGroup>@@ -121,7 +130,7 @@ const category = await client.categories.get('clothing/shirts', {```bash cURLcurl -G 'http://localhost:3000/api/v3/store/categories/clothing/shirts' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-d 'expand=ancestors,children'```@@ -144,7 +153,7 @@ console.log(usa.states) // Array of state objects```bash cURLcurl -G 'http://localhost:3000/api/v3/store/countries/US' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-d 'expand=states'```@@ -157,17 +166,17 @@ The `expand` parameter also works on collection endpoints:<CodeGroup>```typescript SDK-// List products with their images and default variant+// List products with their media and default variantconst { data: products } = await client.products.list({- expand: ['images', 'default_variant'],+ expand: ['media', 'default_variant'],limit: 12,})``````bash cURLcurl -G 'http://localhost:3000/api/v3/store/products' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \- -d 'expand=images,default_variant' \+ -H 'X-Spree-Api-Key: pk_xxx' \+ -d 'expand=media,default_variant' \-d 'limit=12'```@@ -188,7 +197,7 @@ const product = await client.products.get('spree-tote', {```bash cURLcurl -G 'http://localhost:3000/api/v3/store/products/spree-tote' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-d 'expand=variants.option_values'```diff --git a/docs/api-reference/webhooks-events.mdx b/docs/api-reference/webhooks-events.mdxindex ec188d07f8..72b7e3d47d 100644--- a/docs/api-reference/webhooks-events.mdx+++ b/docs/api-reference/webhooks-events.mdx@@ -30,7 +30,7 @@ Event payloads use the same [Store API V3 serializers](/api-reference/introductiFor details on creating webhook endpoints and verifying signatures, see [Webhooks](/developer/core-concepts/webhooks). For the event system internals and subscriber pattern, see [Events](/developer/core-concepts/events).<Info>-Event payloads include the same top-level attributes and unconditional associations as API responses. Conditional associations (like product variants, images, or metafields) are not included in event payloads.+Event payloads include the same top-level attributes and unconditional associations as API responses. Conditional associations (like product variants, media, or custom fields) are not included in event payloads.</Info>---@@ -300,7 +300,7 @@ Shipment payloads include nested `shipping_method`, `stock_location`, and `shippEvents: `product.created`, `product.updated`, `product.deleted`, `product.activate`, `product.archive`, `product.out_of_stock`, `product.back_in_stock`-Product event payloads include pricing, stock status, and availability flags. Conditional associations (variants, images, option types, taxons, metafields) are not included in event payloads.+Product event payloads include pricing, stock status, and availability flags. Conditional associations (variants, media, option types, categories, custom fields) are not included in event payloads.```json{@@ -340,7 +340,7 @@ Product event payloads include pricing, stock status, and availability flags. CoEvents: `variant.created`, `variant.updated`, `variant.deleted`-Variant event payloads include pricing, stock status, and always-included `option_values`. Conditional associations (images, metafields) are not included in event payloads.+Variant event payloads include pricing, stock status, and always-included `option_values`. Conditional associations (media, custom fields) are not included in event payloads.```json{diff --git a/docs/developer/core-concepts/addresses.mdx b/docs/developer/core-concepts/addresses.mdxindex 161ae129f8..fe3228fc19 100644--- a/docs/developer/core-concepts/addresses.mdx+++ b/docs/developer/core-concepts/addresses.mdx@@ -132,14 +132,14 @@ await client.carts.update(cartId, {```bash cURL# Use a saved addresscurl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \- -H 'Authorization: Bearer spree_pk_xxx' \+ -H 'Authorization: Bearer pk_xxx' \-H 'X-Spree-Token: order_token' \-H 'Content-Type: application/json' \-d '{ "shipping_address_id": "addr_xxx", "billing_address_id": "addr_yyy" }'# Or pass a new address inlinecurl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \- -H 'Authorization: Bearer spree_pk_xxx' \+ -H 'Authorization: Bearer pk_xxx' \-H 'X-Spree-Token: order_token' \-H 'Content-Type: application/json' \-d '{@@ -194,15 +194,15 @@ const germany = await client.countries.get('DE', { include: 'market' })```bash cURL# List all countriescurl 'https://api.mystore.com/api/v3/store/countries' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'# Get a country with statescurl 'https://api.mystore.com/api/v3/store/countries/US?include=states' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'# Get a country with its marketcurl 'https://api.mystore.com/api/v3/store/countries/DE?include=market' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -228,7 +228,7 @@ usa.states.forEach(state => {```bash cURLcurl 'https://api.mystore.com/api/v3/store/countries/US?include=states' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>diff --git a/docs/developer/core-concepts/adjustments.mdx b/docs/developer/core-concepts/adjustments.mdxindex bd5f9bb1b1..03e1c5e0df 100644--- a/docs/developer/core-concepts/adjustments.mdx+++ b/docs/developer/core-concepts/adjustments.mdx@@ -95,7 +95,7 @@ order.included_tax_total```bash cURLcurl 'https://api.mystore.com/api/v3/store/orders/or_abc123?expand=items,shipments' \- -H 'Authorization: Bearer spree_pk_xxx' \+ -H 'Authorization: Bearer pk_xxx' \-H 'X-Spree-Token: <token>'```diff --git a/docs/developer/core-concepts/customers.mdx b/docs/developer/core-concepts/customers.mdxindex 1753455080..39f71a3935 100644--- a/docs/developer/core-concepts/customers.mdx+++ b/docs/developer/core-concepts/customers.mdx@@ -58,7 +58,7 @@ const { token, user } = await client.customers.create({```bash cURLcurl -X POST 'https://api.mystore.com/api/v3/store/customers' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-H 'Content-Type: application/json' \-d '{"email": "[email protected]",@@ -85,7 +85,7 @@ const { token, user } = await client.auth.login({```bash cURLcurl -X POST 'https://api.mystore.com/api/v3/store/auth/login' \- -H 'Authorization: Bearer spree_pk_xxx' \+ -H 'Authorization: Bearer pk_xxx' \-H 'Content-Type: application/json' \-d '{"email": "[email protected]",@@ -135,7 +135,7 @@ await client.customer.passwordResets.create({```bash cURLcurl -X POST 'https://api.mystore.com/api/v3/store/customer/password_resets' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-H 'Content-Type: application/json' \-d '{"email": "[email protected]",@@ -166,7 +166,7 @@ const { token, user } = await client.customer.passwordResets.update(```bash cURLcurl -X PATCH 'https://api.mystore.com/api/v3/store/customer/password_resets/RESET_TOKEN' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-H 'Content-Type: application/json' \-d '{"password": "newsecurepassword",diff --git a/docs/developer/core-concepts/events.mdx b/docs/developer/core-concepts/events.mdxindex c20f57bc6e..b23979d77d 100644--- a/docs/developer/core-concepts/events.mdx+++ b/docs/developer/core-concepts/events.mdx@@ -323,7 +323,7 @@ Event serializers receive specific context parameters that control what data is- **`user: nil`** — Events never include user-specific pricing- **`includes: []`** — Conditional associations are not included in event payloads-This means event payloads contain the same top-level attributes and unconditional associations as API responses, but conditional associations (like product variants, images, or metafields) are excluded.+This means event payloads contain the same top-level attributes and unconditional associations as API responses, but conditional associations (like product variants, media, or custom fields) are excluded.### Overriding Event Serializersdiff --git a/docs/developer/core-concepts/markets.mdx b/docs/developer/core-concepts/markets.mdxindex d3d856ccfc..273943012f 100644--- a/docs/developer/core-concepts/markets.mdx+++ b/docs/developer/core-concepts/markets.mdx@@ -94,7 +94,7 @@ const { data: markets } = await client.markets.list()```bash cURLcurl 'https://api.mystore.com/api/v3/store/markets' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -112,7 +112,7 @@ const market = await client.markets.resolve('DE')```bash cURLcurl 'https://api.mystore.com/api/v3/store/markets/resolve?country=DE' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -143,11 +143,11 @@ const usa = await client.markets.countries.get('mkt_k5nR8xLq', 'US', {```bash cURL# List countries in a marketcurl 'https://api.mystore.com/api/v3/store/markets/mkt_k5nR8xLq/countries' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'# Get a country with its statescurl 'https://api.mystore.com/api/v3/store/markets/mkt_k5nR8xLq/countries/US?include=states' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -168,11 +168,11 @@ const germany = await client.countries.get('DE', { include: 'market' })```bash cURL# All countries across all marketscurl 'https://api.mystore.com/api/v3/store/countries' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'# Get a country with its marketcurl 'https://api.mystore.com/api/v3/store/countries/DE?include=market' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -195,10 +195,10 @@ const { data: locales } = await client.locales.list()```bash cURLcurl 'https://api.mystore.com/api/v3/store/currencies' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'curl 'https://api.mystore.com/api/v3/store/locales' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>diff --git a/docs/developer/core-concepts/media.mdx b/docs/developer/core-concepts/media.mdxindex dfffe0807c..42de770680 100644--- a/docs/developer/core-concepts/media.mdx+++ b/docs/developer/core-concepts/media.mdx@@ -58,7 +58,7 @@ products.forEach(product => {```bash cURL# thumbnail_url is always in the response — no ?expand neededcurl 'https://api.mystore.com/api/v3/store/products?limit=12' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -91,7 +91,7 @@ product.variants?.forEach(variant => {```bash cURLcurl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,variants' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>diff --git a/docs/developer/core-concepts/metafields.mdx b/docs/developer/core-concepts/metafields.mdxindex 7aa0d58fd1..55de8aed5f 100644--- a/docs/developer/core-concepts/metafields.mdx+++ b/docs/developer/core-concepts/metafields.mdx@@ -110,26 +110,26 @@ Namespace and key are automatically normalized to snake_case.## Store API-Metafields with `display_on` set to `both` or `front_end` are included in Store API responses when you request the `metafields` expand:+Metafields with `display_on` set to `both` or `front_end` are included in Store API responses when you request the `custom_fields` expand:<CodeGroup>```typescript SDKconst product = await client.products.get('spree-tote', {- expand: ['metafields'],+ expand: ['custom_fields'],})-product.metafields?.forEach(metafield => {- console.log(metafield.key) // "properties.manufacturer"- console.log(metafield.name) // "Manufacturer"- console.log(metafield.value) // "Wilson"- console.log(metafield.type) // "short_text"+product.custom_fields?.forEach(field => {+ console.log(field.key) // "properties.manufacturer"+ console.log(field.label) // "Manufacturer"+ console.log(field.value) // "Wilson"+ console.log(field.type) // "short_text"})``````bash cURL-curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=metafields' \- -H 'Authorization: Bearer spree_pk_xxx'+curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=custom_fields' \+ -H 'X-Spree-Api-Key: pk_xxx'```</CodeGroup>@@ -140,17 +140,17 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=metafields{"id": "prod_86Rf07xd4z","name": "Spree T-Shirt",- "metafields": [+ "custom_fields": [{- "id": "mf_k5nR8xLq",- "name": "Manufacturer",+ "id": "cf_k5nR8xLq",+ "label": "Manufacturer","key": "properties.manufacturer","type": "short_text","value": "Wilson"},{- "id": "mf_m3Rp9wXz",- "name": "Material",+ "id": "cf_m3Rp9wXz",+ "label": "Material","key": "properties.material","type": "short_text","value": "100% Cotton"diff --git a/docs/developer/core-concepts/orders.mdx b/docs/developer/core-concepts/orders.mdxindex f44151793e..0782b75271 100644--- a/docs/developer/core-concepts/orders.mdx+++ b/docs/developer/core-concepts/orders.mdx@@ -110,30 +110,30 @@ await client.carts.items.delete(cart.id, 'li_xxx')```bash cURL# Create a cartcurl -X POST 'https://api.mystore.com/api/v3/store/carts' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'# Get existing cartcurl 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \- -H 'Authorization: Bearer spree_pk_xxx' \+ -H 'Authorization: Bearer pk_xxx' \-H 'X-Spree-Token: abc123'# Add an itemcurl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/items' \- -H 'Authorization: Bearer spree_pk_xxx' \+ -H 'Authorization: Bearer pk_xxx' \-H 'X-Spree-Token: abc123' \-H 'Content-Type: application/json' \-d '{ "variant_id": "var_xxx", "quantity": 2 }'# Update quantitycurl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/items/li_xxx' \- -H 'Authorization: Bearer spree_pk_xxx' \+ -H 'Authorization: Bearer pk_xxx' \-H 'X-Spree-Token: abc123' \-H 'Content-Type: application/json' \-d '{ "quantity": 3 }'# Remove an itemcurl -X DELETE 'https://api.mystore.com/api/v3/store/carts/cart_xxx/items/li_xxx' \- -H 'Authorization: Bearer spree_pk_xxx' \+ -H 'Authorization: Bearer pk_xxx' \-H 'X-Spree-Token: abc123'```@@ -204,7 +204,7 @@ await client.carts.complete(cartId)```bash cURL# Set addressescurl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \- -H 'Authorization: Bearer spree_pk_xxx' \+ -H 'Authorization: Bearer pk_xxx' \-H 'X-Spree-Token: abc123' \-H 'Content-Type: application/json' \-d '{@@ -219,14 +219,14 @@ curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \# Select a shipping ratecurl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/shipments/shp_xxx' \- -H 'Authorization: Bearer spree_pk_xxx' \+ -H 'Authorization: Bearer pk_xxx' \-H 'X-Spree-Token: abc123' \-H 'Content-Type: application/json' \-d '{ "selected_shipping_rate_id": "sr_xxx" }'# Complete the ordercurl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/complete' \- -H 'Authorization: Bearer spree_pk_xxx' \+ -H 'Authorization: Bearer pk_xxx' \-H 'X-Spree-Token: abc123'```@@ -249,14 +249,14 @@ await client.carts.discountCodes.remove(cartId, 'SAVE20')```bash cURL# Apply a discount codecurl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/discount_codes' \- -H 'Authorization: Bearer spree_pk_xxx' \+ -H 'Authorization: Bearer pk_xxx' \-H 'X-Spree-Token: abc123' \-H 'Content-Type: application/json' \-d '{ "code": "SAVE20" }'# Remove a discount codecurl -X DELETE 'https://api.mystore.com/api/v3/store/carts/cart_xxx/discount_codes/SAVE20' \- -H 'Authorization: Bearer spree_pk_xxx' \+ -H 'Authorization: Bearer pk_xxx' \-H 'X-Spree-Token: abc123'```diff --git a/docs/developer/core-concepts/pricing.mdx b/docs/developer/core-concepts/pricing.mdxindex 469990d6c2..489c881eeb 100644--- a/docs/developer/core-concepts/pricing.mdx+++ b/docs/developer/core-concepts/pricing.mdx@@ -46,11 +46,11 @@ detailed.variants?.forEach(variant => {```bash cURL# Product price is always in the responsecurl 'https://api.mystore.com/api/v3/store/products/spree-tote' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'# With variantscurl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=variants' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -192,7 +192,7 @@ if (product.prior_price) {```bash cURLcurl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=prior_price' \- -H 'X-Spree-API-Key: spree_pk_xxx'+ -H 'X-Spree-API-Key: pk_xxx'```</CodeGroup>diff --git a/docs/developer/core-concepts/products.mdx b/docs/developer/core-concepts/products.mdxindex 815b602744..4b4008c744 100644--- a/docs/developer/core-concepts/products.mdx+++ b/docs/developer/core-concepts/products.mdx@@ -108,15 +108,15 @@ const sorted = await client.products.list({```bash cURL# List productscurl 'https://api.mystore.com/api/v3/store/products?limit=12&page=1' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'# Filter by price and stockcurl 'https://api.mystore.com/api/v3/store/products?q[price_gte]=10&q[price_lte]=50&q[in_stock]=true' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'# Searchcurl 'https://api.mystore.com/api/v3/store/products?q[search]=tote+bag' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -142,7 +142,7 @@ const detailed = await client.products.get('spree-tote', {```bash cURLcurl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=variants,media,option_types,categories' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -169,11 +169,11 @@ const categoryFilters = await client.products.filters({```bash cURLcurl 'https://api.mystore.com/api/v3/store/products/filters' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'# Scoped to a categorycurl 'https://api.mystore.com/api/v3/store/products/filters?category_id=ctg_xxx' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -235,7 +235,7 @@ product.option_types?.forEach(optionType => {```bash cURLcurl 'https://api.mystore.com/api/v3/store/products/spree-tee?expand=option_types' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -268,7 +268,7 @@ products.forEach(product => {```bash cURL# thumbnail_url is always in the response — no ?expand neededcurl 'https://api.mystore.com/api/v3/store/products?limit=12' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -301,7 +301,7 @@ product.variants?.forEach(variant => {```bash cURLcurl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,variants' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -355,15 +355,15 @@ const { data: products } = await client.categories.products.list('clothing/shirt```bash cURL# List categoriescurl 'https://api.mystore.com/api/v3/store/categories' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'# Get a category by permalinkcurl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'# List products in a categorycurl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts/products?limit=12' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>diff --git a/docs/developer/core-concepts/promotions.mdx b/docs/developer/core-concepts/promotions.mdxindex 11b03ab2f6..f2606cf285 100644--- a/docs/developer/core-concepts/promotions.mdx+++ b/docs/developer/core-concepts/promotions.mdx@@ -293,7 +293,7 @@ await client.carts.discountCodes.remove('cart_abc123', 'SUMMER20', {```bash cURL# Apply a coupon codecurl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_abc123/coupon_codes' \- -H 'Authorization: Bearer spree_pk_xxx' \+ -H 'Authorization: Bearer pk_xxx' \-H 'X-Spree-Token: <token>' \-H 'Content-Type: application/json' \-d '{ "code": "SUMMER20" }'diff --git a/docs/developer/core-concepts/search-filtering.mdx b/docs/developer/core-concepts/search-filtering.mdxindex 8bd0fa7658..40df647aff 100644--- a/docs/developer/core-concepts/search-filtering.mdx+++ b/docs/developer/core-concepts/search-filtering.mdx@@ -28,7 +28,7 @@ const { data: products } = await client.products.list({```bash cURLcurl 'https://api.mystore.com/api/v3/store/products?q[search]=tote+bag&limit=12' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -48,7 +48,7 @@ const { data: products } = await client.products.list({```bash cURLcurl 'https://api.mystore.com/api/v3/store/products?q[price_gte]=20&q[price_lte]=100' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -65,7 +65,7 @@ const { data: products } = await client.products.list({```bash cURLcurl 'https://api.mystore.com/api/v3/store/products?q[in_stock]=true' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -94,15 +94,15 @@ const { data: products } = await client.products.list({```bash cURL# Products in a categorycurl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts/products?limit=12' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'# Filter by category ID (includes descendants)curl 'https://api.mystore.com/api/v3/store/products?q[in_category]=ctg_xxx' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'# Multiple categories (OR logic)curl 'https://api.mystore.com/api/v3/store/products?q[in_categories][]=ctg_shirts&q[in_categories][]=ctg_pants' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -119,7 +119,7 @@ const { data: products } = await client.products.list({```bash cURLcurl 'https://api.mystore.com/api/v3/store/products?q[tags_cont]=sale' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -140,7 +140,7 @@ const sorted = await client.products.list({```bash cURLcurl 'https://api.mystore.com/api/v3/store/products?sort=price_low_to_high' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -168,11 +168,11 @@ const categoryFilters = await client.products.filters({```bash cURL# All filterscurl 'https://api.mystore.com/api/v3/store/products/filters' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'# Scoped to a categorycurl 'https://api.mystore.com/api/v3/store/products/filters?category_id=ctg_xxx' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -236,7 +236,7 @@ const { data: products, meta } = await client.products.list({```bash cURLcurl 'https://api.mystore.com/api/v3/store/products?page=1&limit=24' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>diff --git a/docs/developer/core-concepts/shipments.mdx b/docs/developer/core-concepts/shipments.mdxindex d2641cae28..4d04cd84a7 100644--- a/docs/developer/core-concepts/shipments.mdx+++ b/docs/developer/core-concepts/shipments.mdx@@ -103,12 +103,12 @@ await client.carts.shipments.update(cartId, shipment.id, {```bash cURL# Get shipmentscurl 'https://api.mystore.com/api/v3/store/carts/cart_xxx?expand=shipments' \- -H 'Authorization: Bearer spree_pk_xxx' \+ -H 'Authorization: Bearer pk_xxx' \-H 'X-Spree-Token: abc123'# Select a shipping ratecurl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/shipments/shp_xxx' \- -H 'Authorization: Bearer spree_pk_xxx' \+ -H 'Authorization: Bearer pk_xxx' \-H 'X-Spree-Token: abc123' \-H 'Content-Type: application/json' \-d '{ "selected_shipping_rate_id": "sr_xxx" }'diff --git a/docs/developer/core-concepts/slugs.mdx b/docs/developer/core-concepts/slugs.mdxindex 5028266ab7..407d928f02 100644--- a/docs/developer/core-concepts/slugs.mdx+++ b/docs/developer/core-concepts/slugs.mdx@@ -23,11 +23,11 @@ const category = await client.categories.get('clothing/shirts')```bash cURL# By slugcurl 'https://api.mystore.com/api/v3/store/products/spree-tote' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'# By IDcurl 'https://api.mystore.com/api/v3/store/products/prod_86Rf07xd4z' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -92,11 +92,11 @@ const product = await client.products.get('chaussures-rouges', {```bash cURL# Englishcurl 'https://api.mystore.com/api/v3/store/products/red-shoes' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'# Frenchcurl 'https://api.mystore.com/api/v3/store/products/chaussures-rouges' \- -H 'Authorization: Bearer spree_pk_xxx' \+ -H 'Authorization: Bearer pk_xxx' \-H 'X-Spree-Locale: fr'```diff --git a/docs/developer/core-concepts/stores.mdx b/docs/developer/core-concepts/stores.mdxindex bbac1430fd..533f195cbd 100644--- a/docs/developer/core-concepts/stores.mdx+++ b/docs/developer/core-concepts/stores.mdx@@ -78,7 +78,7 @@ const store = await client.store.get()```bash cURLcurl 'https://api.mystore.com/api/v3/store/store' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>diff --git a/docs/developer/core-concepts/translations.mdx b/docs/developer/core-concepts/translations.mdxindex b70ef64d34..f6aefb2454 100644--- a/docs/developer/core-concepts/translations.mdx+++ b/docs/developer/core-concepts/translations.mdx@@ -86,7 +86,7 @@ const { data: categories } = await client.categories.list({}, {```bash cURL# Fetch product in Frenchcurl 'https://api.mystore.com/api/v3/store/products/spree-tote' \- -H 'Authorization: Bearer spree_pk_xxx' \+ -H 'Authorization: Bearer pk_xxx' \-H 'X-Spree-Locale: fr'```diff --git a/docs/developer/core-concepts/users.mdx b/docs/developer/core-concepts/users.mdxindex b5b716c1f0..85a49bd009 100644--- a/docs/developer/core-concepts/users.mdx+++ b/docs/developer/core-concepts/users.mdx@@ -74,7 +74,7 @@ const { token, user } = await client.customers.create({```bash cURLcurl -X POST 'https://api.mystore.com/api/v3/store/customers' \- -H 'X-Spree-Api-Key: spree_pk_xxx' \+ -H 'X-Spree-Api-Key: pk_xxx' \-H 'Content-Type: application/json' \-d '{"email": "[email protected]",@@ -101,7 +101,7 @@ const { token, user } = await client.auth.login({```bash cURLcurl -X POST 'https://api.mystore.com/api/v3/store/auth/login' \- -H 'Authorization: Bearer spree_pk_xxx' \+ -H 'Authorization: Bearer pk_xxx' \-H 'Content-Type: application/json' \-d '{"email": "[email protected]",diff --git a/docs/developer/customization/metadata.mdx b/docs/developer/customization/metadata.mdxindex f42ddf3151..ecfa1961be 100644--- a/docs/developer/customization/metadata.mdx+++ b/docs/developer/customization/metadata.mdx@@ -199,7 +199,7 @@ Spree has two permanent, complementary systems for custom data. They are not int| **Validation** | None — accepts any JSON-serializable data | Type-specific (text, number, boolean, rich text, JSON) || **Visibility** | Write-only in Store API, readable in Admin API | Configurable (front-end, back-end, both) || **Admin UI** | JSON preview only | Dedicated management forms |-| **API pattern** | Stripe-style: `metadata: { key: value }` | Expand-based: `?expand=metafields` |+| **API pattern** | Stripe-style: `metadata: { key: value }` | Expand-based: `?expand=custom_fields` || **Queryable** | Via JSONB operators (PostgreSQL) | Via SQL joins, Ransack scopes, search providers |### When to use metadatadiff --git a/docs/developer/sdk/admin/quickstart.mdx b/docs/developer/sdk/admin/quickstart.mdxindex 9dbfc2d4f9..07d9eab696 100644--- a/docs/developer/sdk/admin/quickstart.mdx+++ b/docs/developer/sdk/admin/quickstart.mdx@@ -14,7 +14,7 @@ import { createClient } from '@spree/sdk';const client = createClient({baseUrl: 'https://api.mystore.com',- secretKey: 'spree_sk_xxx', // Admin API requires a secret key+ secretKey: 'sk_xxx', // Admin API requires a secret key});// Admin endpoints will be available under client.admin.*diff --git a/docs/developer/sdk/configuration.mdx b/docs/developer/sdk/configuration.mdxindex dc99632945..d869fe9355 100644--- a/docs/developer/sdk/configuration.mdx+++ b/docs/developer/sdk/configuration.mdx@@ -47,7 +47,7 @@ import { createClient } from '@spree/sdk';const client = createClient({baseUrl: 'https://api.mystore.com',- publishableKey: 'spree_pk_xxx',+ publishableKey: 'pk_xxx',fetch: customFetchImplementation,});```diff --git a/docs/developer/sdk/quickstart.mdx b/docs/developer/sdk/quickstart.mdxindex c387d659fa..3aa368c0c2 100644--- a/docs/developer/sdk/quickstart.mdx+++ b/docs/developer/sdk/quickstart.mdx@@ -21,7 +21,7 @@ import { createClient } from '@spree/sdk';// Initialize the clientconst client = createClient({baseUrl: 'https://api.mystore.com',- publishableKey: 'spree_pk_xxx', // Store API+ publishableKey: 'pk_xxx', // Store API});// Browse products (Store API)diff --git a/docs/developer/sdk/store/markets.mdx b/docs/developer/sdk/store/markets.mdxindex 2ce7c23762..73e24eea89 100644--- a/docs/developer/sdk/store/markets.mdx+++ b/docs/developer/sdk/store/markets.mdx@@ -26,7 +26,7 @@ markets.forEach(market => {```bash cURLcurl 'https://api.mystore.com/api/v3/store/markets' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -79,7 +79,7 @@ market.countries // [{ iso: "DE", ... }, { iso: "FR", ... }]```bash cURLcurl 'https://api.mystore.com/api/v3/store/markets/mkt_gbHJdmfrXB' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -100,7 +100,7 @@ market.currency // "EUR"```bash cURLcurl 'https://api.mystore.com/api/v3/store/markets/resolve?country=DE' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -128,7 +128,7 @@ countries.forEach(country => {```bash cURLcurl 'https://api.mystore.com/api/v3/store/markets/mkt_gbHJdmfrXB/countries' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>@@ -151,7 +151,7 @@ country.states // [{ id: "st_xxx", name: "New York", abbr: "NY" }, ...]```bash cURLcurl 'https://api.mystore.com/api/v3/store/markets/mkt_gbHJdmfrXB/countries/US?expand=states' \- -H 'Authorization: Bearer spree_pk_xxx'+ -H 'Authorization: Bearer pk_xxx'```</CodeGroup>diff --git a/docs/snippets/store-api/sdk-client-setup.mdx b/docs/snippets/store-api/sdk-client-setup.mdxindex 8639f0c1fa..49e7b13b29 100644--- a/docs/snippets/store-api/sdk-client-setup.mdx+++ b/docs/snippets/store-api/sdk-client-setup.mdx@@ -3,6 +3,6 @@ import { createClient } from '@spree/sdk'const client = createClient({baseUrl: 'http://localhost:3000',- publishableKey: 'spree_pk_xxx',+ publishableKey: 'pk_xxx',})```diff --git a/packages/sdk/README.md b/packages/sdk/README.mdindex 58307e9090..51237c837a 100644--- a/packages/sdk/README.md+++ b/packages/sdk/README.md@@ -720,7 +720,7 @@ All types are exported as unprefixed names (e.g., `Product`, `Order`). Legacy `S- `OptionType` - Option type (e.g., Size, Color)- `OptionValue` - Option value (e.g., Small, Red)- `DigitalLink` - Digital download link-- `Metafield` - Custom metafield data+- `CustomField` - Custom field data### Wishlist Types- `Wishlist` - Wishlist