Skip to content

armgit / spree

Public Imported from GitHub
0

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.

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.mdx
index 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 cURL
curl -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:
```bash
spree api-key create # Create a new API key
@@ -75,13 +75,13 @@ const orders = await client.customer.orders.list({}, { token })
```bash cURL
# Login
curl -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 requests
curl -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 cURL
curl -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 cURL
curl -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 cart
curl -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 operations
curl -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 cURL
curl -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.mdx
index 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
```bash
curl 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 \
```bash
curl -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 \
```bash
curl -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 422
diff --git a/docs/api-reference/store-api/idempotency.mdx b/docs/api-reference/store-api/idempotency.mdx
index 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
```bash
curl -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 key
diff --git a/docs/api-reference/store-api/introduction.mdx b/docs/api-reference/store-api/introduction.mdx
index 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 client
const 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.mdx
index 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 cURL
curl -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 cURL
curl -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 country
curl '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
# English
curl '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'
# French
curl '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 prices
curl '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 prices
curl '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 cURL
curl '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 countries
curl '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 market
curl '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 states
curl '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 cURL
curl '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 cURL
curl '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.mdx
index 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 cURL
curl -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 cURL
curl -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 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-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 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-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.mdx
index 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 cURL
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[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 cURL
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[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 only
curl -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 cURL
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[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 high
curl -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 low
curl -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 name
curl -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 recent
curl -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 SDK
const product = await client.products.get('spree-tote', {
- expand: ['variants', 'images'],
+ expand: ['variants', 'media'],
})
```
```bash cURL
curl -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 request
const product = await client.products.get('spree-tote', {
- expand: ['variants.images'],
+ expand: ['variants.media'],
})
// Multiple nested expands
const 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 media
curl -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 expands
curl -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 cURL
curl -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 cURL
curl -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.mdx
index 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.mdx
index 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 media
const product = await client.products.get('spree-tote', {
- expand: ['variants', 'images'],
+ expand: ['variants', 'media'],
})
// Access included relations directly
console.log(product.variants) // Array of variant objects
-console.log(product.images) // Array of image objects
+console.log(product.media) // Array of media objects
```
```bash cURL
curl -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 SDK
const product = await client.products.get('spree-tote', {
- expand: ['variants', 'images', 'option_types', 'metafields'],
+ expand: ['variants', 'media', 'option_types', 'custom_fields'],
})
```
```bash cURL
curl -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 cURL
curl -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 cURL
curl -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 variant
const { data: products } = await client.products.list({
- expand: ['images', 'default_variant'],
+ expand: ['media', 'default_variant'],
limit: 12,
})
```
```bash cURL
curl -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 cURL
curl -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.mdx
index 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/introducti
For 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 `shipp
Events: `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. Co
Events: `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.mdx
index 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 address
curl -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 inline
curl -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 countries
curl 'https://api.mystore.com/api/v3/store/countries' \
- -H 'Authorization: Bearer spree_pk_xxx'
+ -H 'Authorization: Bearer pk_xxx'
# Get a country with states
curl '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 market
curl '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 cURL
curl '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.mdx
index 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 cURL
curl '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.mdx
index 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 cURL
curl -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 cURL
curl -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 cURL
curl -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 cURL
curl -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.mdx
index 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 Serializers
diff --git a/docs/developer/core-concepts/markets.mdx b/docs/developer/core-concepts/markets.mdx
index 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 cURL
curl '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 cURL
curl '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 market
curl '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 states
curl '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 markets
curl 'https://api.mystore.com/api/v3/store/countries' \
- -H 'Authorization: Bearer spree_pk_xxx'
+ -H 'Authorization: Bearer pk_xxx'
# Get a country with its market
curl '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 cURL
curl '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.mdx
index 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 needed
curl '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 cURL
curl '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.mdx
index 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 SDK
const 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.mdx
index 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 cart
curl -X POST 'https://api.mystore.com/api/v3/store/carts' \
- -H 'Authorization: Bearer spree_pk_xxx'
+ -H 'Authorization: Bearer pk_xxx'
# Get existing cart
curl '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 item
curl -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 quantity
curl -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 item
curl -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 addresses
curl -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 rate
curl -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 order
curl -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 code
curl -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 code
curl -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.mdx
index 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 response
curl 'https://api.mystore.com/api/v3/store/products/spree-tote' \
- -H 'Authorization: Bearer spree_pk_xxx'
+ -H 'Authorization: Bearer pk_xxx'
# With variants
curl '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 cURL
curl '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.mdx
index 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 products
curl '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 stock
curl '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'
# Search
curl '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 cURL
curl '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 cURL
curl 'https://api.mystore.com/api/v3/store/products/filters' \
- -H 'Authorization: Bearer spree_pk_xxx'
+ -H 'Authorization: Bearer pk_xxx'
# Scoped to a category
curl '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 cURL
curl '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 needed
curl '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 cURL
curl '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 categories
curl 'https://api.mystore.com/api/v3/store/categories' \
- -H 'Authorization: Bearer spree_pk_xxx'
+ -H 'Authorization: Bearer pk_xxx'
# Get a category by permalink
curl '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 category
curl '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.mdx
index 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 code
curl -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.mdx
index 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 cURL
curl '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 cURL
curl '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 cURL
curl '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 category
curl '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 cURL
curl '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 cURL
curl '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 filters
curl 'https://api.mystore.com/api/v3/store/products/filters' \
- -H 'Authorization: Bearer spree_pk_xxx'
+ -H 'Authorization: Bearer pk_xxx'
# Scoped to a category
curl '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 cURL
curl '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.mdx
index 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 shipments
curl '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 rate
curl -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.mdx
index 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 slug
curl 'https://api.mystore.com/api/v3/store/products/spree-tote' \
- -H 'Authorization: Bearer spree_pk_xxx'
+ -H 'Authorization: Bearer pk_xxx'
# By ID
curl '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
# English
curl 'https://api.mystore.com/api/v3/store/products/red-shoes' \
- -H 'Authorization: Bearer spree_pk_xxx'
+ -H 'Authorization: Bearer pk_xxx'
# French
curl '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.mdx
index 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 cURL
curl '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.mdx
index 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 French
curl '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.mdx
index 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 cURL
curl -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 cURL
curl -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.mdx
index 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 metadata
diff --git a/docs/developer/sdk/admin/quickstart.mdx b/docs/developer/sdk/admin/quickstart.mdx
index 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.mdx
index 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.mdx
index 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 client
const 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.mdx
index 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 cURL
curl '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 cURL
curl '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 cURL
curl '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 cURL
curl '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 cURL
curl '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.mdx
index 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.md
index 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