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.

Fixed docs around API headers and events with prefix IDs

Damian Legawiecfbba813178f2
diff --git a/docs/api-reference/store-api/errors.mdx b/docs/api-reference/store-api/errors.mdx
index 69897cf0e8..ba70921240 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 pk_xxx"
+ -H "X-Spree-API-Key: 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 pk_xxx" \
+ -H "X-Spree-API-Key: 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 pk_xxx"
+ -H "X-Spree-API-Key: pk_xxx"
```
```json 422
diff --git a/docs/api-reference/store-api/idempotency.mdx b/docs/api-reference/store-api/idempotency.mdx
index 733e976632..86dff449f0 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 pk_xxx" \
+ -H "X-Spree-API-Key: pk_xxx" \
-H "X-Spree-Token: abc123" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
diff --git a/docs/developer/contributing/creating-an-extension.mdx b/docs/developer/contributing/creating-an-extension.mdx
index 5d2ff63275..38a4b61ed1 100644
--- a/docs/developer/contributing/creating-an-extension.mdx
+++ b/docs/developer/contributing/creating-an-extension.mdx
@@ -250,7 +250,7 @@ module MyExtension
subscribes_to 'product.updated'
def handle(event)
- product = Spree::Product.find_by(id: event.payload['id'])
+ product = Spree::Product.find_by_prefix_id(event.payload['id'])
return unless product
ExternalService.sync(product)
diff --git a/docs/developer/core-concepts/addresses.mdx b/docs/developer/core-concepts/addresses.mdx
index fe3228fc19..d0e070867d 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 pk_xxx' \
+ -H 'X-Spree-API-Key: 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 pk_xxx' \
+ -H 'X-Spree-API-Key: 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 pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
# Get a country with states
-curl 'https://api.mystore.com/api/v3/store/countries/US?include=states' \
- -H 'Authorization: Bearer pk_xxx'
+curl 'https://api.mystore.com/api/v3/store/countries/US?expand=states' \
+ -H 'X-Spree-API-Key: pk_xxx'
# Get a country with its market
-curl 'https://api.mystore.com/api/v3/store/countries/DE?include=market' \
- -H 'Authorization: Bearer pk_xxx'
+curl 'https://api.mystore.com/api/v3/store/countries/DE?expand=market' \
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
@@ -213,7 +213,7 @@ Use the `states_required` and `zipcode_required` fields to build adaptive addres
States (provinces, regions) belong to a country and are used for address validation and zone matching. Countries like the US, Canada, Australia, and India have predefined states — for these countries, customers must select a state from the list rather than typing a name.
-States are fetched via the country endpoint using `?include=states`:
+States are fetched via the country endpoint using `?expand=states`:
<CodeGroup>
@@ -227,8 +227,8 @@ usa.states.forEach(state => {
```
```bash cURL
-curl 'https://api.mystore.com/api/v3/store/countries/US?include=states' \
- -H 'Authorization: Bearer pk_xxx'
+curl 'https://api.mystore.com/api/v3/store/countries/US?expand=states' \
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
diff --git a/docs/developer/core-concepts/adjustments.mdx b/docs/developer/core-concepts/adjustments.mdx
index c8a0161eb4..36341a8980 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,fulfillments' \
- -H 'Authorization: Bearer pk_xxx' \
+ -H 'X-Spree-API-Key: pk_xxx' \
-H 'X-Spree-Token: <token>'
```
diff --git a/docs/developer/core-concepts/customers.mdx b/docs/developer/core-concepts/customers.mdx
index ede29cb9bc..4736275d0c 100644
--- a/docs/developer/core-concepts/customers.mdx
+++ b/docs/developer/core-concepts/customers.mdx
@@ -87,7 +87,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 pk_xxx' \
+ -H 'X-Spree-API-Key: pk_xxx' \
-H 'Content-Type: application/json' \
-d '{
"email": "[email protected]",
diff --git a/docs/developer/core-concepts/events.mdx b/docs/developer/core-concepts/events.mdx
index cd4a7b7c9c..fdc98f1b57 100644
--- a/docs/developer/core-concepts/events.mdx
+++ b/docs/developer/core-concepts/events.mdx
@@ -66,7 +66,7 @@ module MyApp
def handle(event)
order_id = event.payload['id']
- order = Spree::Order.find_by(id: order_id)
+ order = Spree::Order.find_by_prefix_id(order_id)
return unless order
# Your custom logic here
@@ -76,6 +76,14 @@ module MyApp
end
```
+Then register it in an initializer — subscribers are not auto-discovered (see [Registering Subscribers](#registering-subscribers)):
+
+```ruby config/initializers/event_subscribers.rb
+Rails.application.config.after_initialize do
+ Spree.subscribers << MyApp::OrderCompletedSubscriber
+end
+```
+
### Subscriber DSL
The `Spree::Subscriber` class provides a clean DSL for declaring subscriptions:
@@ -165,7 +173,7 @@ The payload contains serialized attributes, not the actual record. To get the re
```ruby
def handle(event)
record_id = event.payload['id']
- record = Spree::Order.find_by(id: record_id)
+ record = Spree::Order.find_by_prefix_id(record_id)
return unless record
# Work with the record
@@ -400,9 +408,7 @@ Models without a matching serializer will use a minimal fallback payload contain
## Registering Subscribers
-Subscribers in `app/subscribers/` are automatically registered during application initialization.
-
-For subscribers in other locations, add them to the `Spree.subscribers` array in an initializer:
+Subscribers are not auto-discovered — every subscriber must be registered explicitly, regardless of where the class lives. Add it to the `Spree.subscribers` array in an initializer:
```ruby config/initializers/event_subscribers.rb
Rails.application.config.after_initialize do
@@ -536,7 +542,7 @@ module MyApp
private
def find_stock_item(event)
- Spree::StockItem.find_by(id: event.payload['id'])
+ Spree::StockItem.find_by_prefix_id(event.payload['id'])
end
def stock_dropped_below_threshold?(event, stock_item)
diff --git a/docs/developer/core-concepts/markets.mdx b/docs/developer/core-concepts/markets.mdx
index fc16a39200..dc4f29342d 100644
--- a/docs/developer/core-concepts/markets.mdx
+++ b/docs/developer/core-concepts/markets.mdx
@@ -98,7 +98,7 @@ const { data: markets } = await client.markets.list()
```bash cURL
curl 'https://api.mystore.com/api/v3/store/markets' \
- -H 'Authorization: Bearer pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
@@ -116,7 +116,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 pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
@@ -147,11 +147,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 pk_xxx'
+ -H 'X-Spree-API-Key: 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 pk_xxx'
+curl 'https://api.mystore.com/api/v3/store/markets/mkt_k5nR8xLq/countries/US?expand=states' \
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
@@ -172,11 +172,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 pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
# Get a country with its market
-curl 'https://api.mystore.com/api/v3/store/countries/DE?include=market' \
- -H 'Authorization: Bearer pk_xxx'
+curl 'https://api.mystore.com/api/v3/store/countries/DE?expand=market' \
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
@@ -199,10 +199,10 @@ const { data: locales } = await client.locales.list()
```bash cURL
curl 'https://api.mystore.com/api/v3/store/currencies' \
- -H 'Authorization: Bearer pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
curl 'https://api.mystore.com/api/v3/store/locales' \
- -H 'Authorization: Bearer pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
diff --git a/docs/developer/core-concepts/media.mdx b/docs/developer/core-concepts/media.mdx
index 8d0854bd39..65899cf113 100644
--- a/docs/developer/core-concepts/media.mdx
+++ b/docs/developer/core-concepts/media.mdx
@@ -119,7 +119,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 pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
@@ -152,7 +152,7 @@ product.variants?.forEach(variant => {
```bash cURL
curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,variants' \
- -H 'Authorization: Bearer pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
diff --git a/docs/developer/core-concepts/orders.mdx b/docs/developer/core-concepts/orders.mdx
index ea87a5b1e8..a973716f0b 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 pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
# Get existing cart
curl 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
- -H 'Authorization: Bearer pk_xxx' \
+ -H 'X-Spree-API-Key: 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 pk_xxx' \
+ -H 'X-Spree-API-Key: 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 pk_xxx' \
+ -H 'X-Spree-API-Key: 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 pk_xxx' \
+ -H 'X-Spree-API-Key: pk_xxx' \
-H 'X-Spree-Token: abc123'
```
@@ -205,7 +205,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 pk_xxx' \
+ -H 'X-Spree-API-Key: pk_xxx' \
-H 'X-Spree-Token: abc123' \
-H 'Content-Type: application/json' \
-d '{
@@ -220,14 +220,14 @@ curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
# Select a delivery rate
curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/fulfillments/ful_xxx' \
- -H 'Authorization: Bearer pk_xxx' \
+ -H 'X-Spree-API-Key: pk_xxx' \
-H 'X-Spree-Token: abc123' \
-H 'Content-Type: application/json' \
-d '{ "selected_delivery_rate_id": "rate_xxx" }'
# Complete the order
curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/complete' \
- -H 'Authorization: Bearer pk_xxx' \
+ -H 'X-Spree-API-Key: pk_xxx' \
-H 'X-Spree-Token: abc123'
```
@@ -250,14 +250,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 pk_xxx' \
+ -H 'X-Spree-API-Key: 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 pk_xxx' \
+ -H 'X-Spree-API-Key: pk_xxx' \
-H 'X-Spree-Token: abc123'
```
diff --git a/docs/developer/core-concepts/pricing.mdx b/docs/developer/core-concepts/pricing.mdx
index b7c1680ab9..979d67656a 100644
--- a/docs/developer/core-concepts/pricing.mdx
+++ b/docs/developer/core-concepts/pricing.mdx
@@ -48,11 +48,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 pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
# With variants
curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=variants' \
- -H 'Authorization: Bearer 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 2e594c266d..21f464a8bc 100644
--- a/docs/developer/core-concepts/products.mdx
+++ b/docs/developer/core-concepts/products.mdx
@@ -110,15 +110,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 pk_xxx'
+ -H 'X-Spree-API-Key: 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 pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
# Search
curl 'https://api.mystore.com/api/v3/store/products?q[search]=tote+bag' \
- -H 'Authorization: Bearer pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
@@ -144,7 +144,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 pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
@@ -171,11 +171,11 @@ const categoryFilters = await client.products.filters({
```bash cURL
curl 'https://api.mystore.com/api/v3/store/products/filters' \
- -H 'Authorization: Bearer pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
# Scoped to a category
curl 'https://api.mystore.com/api/v3/store/products/filters?category_id=ctg_xxx' \
- -H 'Authorization: Bearer pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
@@ -237,7 +237,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 pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
@@ -270,7 +270,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 pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
@@ -303,7 +303,7 @@ product.variants?.forEach(variant => {
```bash cURL
curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,variants' \
- -H 'Authorization: Bearer pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
@@ -357,15 +357,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 pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
# Get a category by permalink
curl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts' \
- -H 'Authorization: Bearer pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
# List products in a category
curl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts/products?limit=12' \
- -H 'Authorization: Bearer pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
diff --git a/docs/developer/core-concepts/promotions.mdx b/docs/developer/core-concepts/promotions.mdx
index f2606cf285..3e42c2cc30 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 pk_xxx' \
+ -H 'X-Spree-API-Key: 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 38e19950d7..f044ba5eed 100644
--- a/docs/developer/core-concepts/search-filtering.mdx
+++ b/docs/developer/core-concepts/search-filtering.mdx
@@ -30,7 +30,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 pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
@@ -50,7 +50,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 pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
@@ -67,7 +67,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 pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
@@ -96,15 +96,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 pk_xxx'
+ -H 'X-Spree-API-Key: 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 pk_xxx'
+ -H 'X-Spree-API-Key: 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 pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
@@ -121,7 +121,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 pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
@@ -142,7 +142,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 pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
@@ -170,11 +170,11 @@ const categoryFilters = await client.products.filters({
```bash cURL
# All filters
curl 'https://api.mystore.com/api/v3/store/products/filters' \
- -H 'Authorization: Bearer pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
# Scoped to a category
curl 'https://api.mystore.com/api/v3/store/products/filters?category_id=ctg_xxx' \
- -H 'Authorization: Bearer pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
@@ -238,7 +238,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 pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
diff --git a/docs/developer/core-concepts/shipments.mdx b/docs/developer/core-concepts/shipments.mdx
index 55222115dc..cae546a421 100644
--- a/docs/developer/core-concepts/shipments.mdx
+++ b/docs/developer/core-concepts/shipments.mdx
@@ -110,12 +110,12 @@ await client.carts.fulfillments.update(cartId, fulfillment.id, {
```bash cURL
# Get fulfillments
curl 'https://api.mystore.com/api/v3/store/carts/cart_xxx?expand=fulfillments' \
- -H 'Authorization: Bearer pk_xxx' \
+ -H 'X-Spree-API-Key: pk_xxx' \
-H 'X-Spree-Token: abc123'
# Select a delivery rate
curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/fulfillments/ful_xxx' \
- -H 'Authorization: Bearer pk_xxx' \
+ -H 'X-Spree-API-Key: pk_xxx' \
-H 'X-Spree-Token: abc123' \
-H 'Content-Type: application/json' \
-d '{ "selected_delivery_rate_id": "rate_xxx" }'
diff --git a/docs/developer/core-concepts/slugs.mdx b/docs/developer/core-concepts/slugs.mdx
index f1e112ea82..6ea8e03e38 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 pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
# By ID
curl 'https://api.mystore.com/api/v3/store/products/prod_86Rf07xd4z' \
- -H 'Authorization: Bearer pk_xxx'
+ -H 'X-Spree-API-Key: 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 pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
# French
curl 'https://api.mystore.com/api/v3/store/products/chaussures-rouges' \
- -H 'Authorization: Bearer pk_xxx' \
+ -H 'X-Spree-API-Key: pk_xxx' \
-H 'X-Spree-Locale: fr'
```
diff --git a/docs/developer/core-concepts/stores.mdx b/docs/developer/core-concepts/stores.mdx
index 289e6e7544..8889cdcfd6 100644
--- a/docs/developer/core-concepts/stores.mdx
+++ b/docs/developer/core-concepts/stores.mdx
@@ -43,7 +43,7 @@ const store = await client.store.get()
```bash cURL
curl 'https://api.mystore.com/api/v3/store/store' \
- -H 'Authorization: Bearer pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
diff --git a/docs/developer/core-concepts/translations.mdx b/docs/developer/core-concepts/translations.mdx
index f6aefb2454..92ea620691 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 pk_xxx' \
+ -H 'X-Spree-API-Key: pk_xxx' \
-H 'X-Spree-Locale: fr'
```
diff --git a/docs/developer/core-concepts/users.mdx b/docs/developer/core-concepts/users.mdx
index 85a49bd009..eb72b94e98 100644
--- a/docs/developer/core-concepts/users.mdx
+++ b/docs/developer/core-concepts/users.mdx
@@ -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 pk_xxx' \
+ -H 'X-Spree-API-Key: pk_xxx' \
-H 'Content-Type: application/json' \
-d '{
"email": "[email protected]",
diff --git a/docs/developer/customization/checkout.mdx b/docs/developer/customization/checkout.mdx
index 89d5dc664e..2e38a2fd88 100644
--- a/docs/developer/customization/checkout.mdx
+++ b/docs/developer/customization/checkout.mdx
@@ -108,7 +108,7 @@ module MyApp
subscribes_to 'order.completed'
def handle(event)
- order = Spree::Order.find_by(id: event.payload['id'])
+ order = Spree::Order.find_by_prefix_id(event.payload['id'])
return unless order
# Sync to fulfillment system, notify warehouse, etc.
diff --git a/docs/developer/customization/decorators.mdx b/docs/developer/customization/decorators.mdx
index e33104278a..7215e8b24e 100644
--- a/docs/developer/customization/decorators.mdx
+++ b/docs/developer/customization/decorators.mdx
@@ -509,7 +509,7 @@ module MyApp
subscribes_to 'product.updated'
def handle(event)
- product = Spree::Product.find_by(id: event.payload['id'])
+ product = Spree::Product.find_by_prefix_id(event.payload['id'])
return unless product
# The payload includes changes, check if name changed
diff --git a/docs/developer/customization/quickstart.mdx b/docs/developer/customization/quickstart.mdx
index 16f9e0e613..ae55242dde 100644
--- a/docs/developer/customization/quickstart.mdx
+++ b/docs/developer/customization/quickstart.mdx
@@ -61,7 +61,7 @@ Spree is a flexible platform allowing you to customize every part of it to suit
subscribes_to 'order.completed'
def handle(event)
- order = Spree::Order.find_by(id: event.payload['id'])
+ order = Spree::Order.find_by_prefix_id(event.payload['id'])
return unless order
# Sync to external service, send notification, etc.
diff --git a/docs/developer/deployment/environment_variables.mdx b/docs/developer/deployment/environment_variables.mdx
index 9ca5e3cef4..9083e37195 100644
--- a/docs/developer/deployment/environment_variables.mdx
+++ b/docs/developer/deployment/environment_variables.mdx
@@ -21,7 +21,7 @@ These variables are required to run Spree in production.
This configuration is used for system emails (e.g. staff invitations, report ready, export complete). Customer facing emails are handled by the [storefront via webhooks](/developer/storefront/nextjs/customization#transactional-emails).
</Tip>
-Spree works with any SMTP provider (Resend, Postmark, Mailgun, SendGrid, Amazon SES, etc.). Set `SMTP_HOST` to enable email delivery — when not set, emails are logged to stdout.
+Spree works with any SMTP provider (Resend, Postmark, Mailgun, SendGrid, Amazon SES, etc.). Set `SMTP_HOST` to enable email delivery — when not set, no delivery method is configured and production email delivery fails (development opens emails in the browser via `letter_opener`).
| Variable | Default | Description |
| --- | --- | --- |
diff --git a/docs/developer/sdk/store/markets.mdx b/docs/developer/sdk/store/markets.mdx
index 73e24eea89..da13544f87 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 pk_xxx'
+ -H 'X-Spree-API-Key: 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 pk_xxx'
+ -H 'X-Spree-API-Key: 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 pk_xxx'
+ -H 'X-Spree-API-Key: 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 pk_xxx'
+ -H 'X-Spree-API-Key: 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 pk_xxx'
+ -H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
diff --git a/docs/developer/tutorial/extending-models.mdx b/docs/developer/tutorial/extending-models.mdx
index f5485b232c..a659caa302 100644
--- a/docs/developer/tutorial/extending-models.mdx
+++ b/docs/developer/tutorial/extending-models.mdx
@@ -307,7 +307,7 @@ module MyApp
subscribes_to 'product.updated'
def handle(event)
- product = Spree::Product.find_by(id: event.payload['id'])
+ product = Spree::Product.find_by_prefix_id(event.payload['id'])
return unless product
ExternalSyncService.sync(product)