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.

Setup docs for API v3 and SDK (#13650)

Damian Legawiec14facc7b98d6
diff --git a/docs/api-reference/platform/addresses/create-an-address.mdx b/docs/api-reference/platform/addresses/create-an-address.mdx
deleted file mode 100644
index 6e49b9edca..0000000000
--- a/docs/api-reference/platform/addresses/create-an-address.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/addresses
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/addresses/delete-an-address.mdx b/docs/api-reference/platform/addresses/delete-an-address.mdx
deleted file mode 100644
index 3eac60561f..0000000000
--- a/docs/api-reference/platform/addresses/delete-an-address.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/addresses/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/addresses/return-a-list-of-addresses.mdx b/docs/api-reference/platform/addresses/return-a-list-of-addresses.mdx
deleted file mode 100644
index 2ea89ce0ee..0000000000
--- a/docs/api-reference/platform/addresses/return-a-list-of-addresses.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/addresses
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/addresses/return-an-address.mdx b/docs/api-reference/platform/addresses/return-an-address.mdx
deleted file mode 100644
index 12da3c1a86..0000000000
--- a/docs/api-reference/platform/addresses/return-an-address.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/addresses/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/addresses/update-an-address.mdx b/docs/api-reference/platform/addresses/update-an-address.mdx
deleted file mode 100644
index d50a884ae3..0000000000
--- a/docs/api-reference/platform/addresses/update-an-address.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/addresses/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/adjustments/create-an-adjustment.mdx b/docs/api-reference/platform/adjustments/create-an-adjustment.mdx
deleted file mode 100644
index a90603302c..0000000000
--- a/docs/api-reference/platform/adjustments/create-an-adjustment.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/adjustments
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/adjustments/delete-an-adjustment.mdx b/docs/api-reference/platform/adjustments/delete-an-adjustment.mdx
deleted file mode 100644
index 757163fc20..0000000000
--- a/docs/api-reference/platform/adjustments/delete-an-adjustment.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/adjustments/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/adjustments/return-a-list-of-adjustments.mdx b/docs/api-reference/platform/adjustments/return-a-list-of-adjustments.mdx
deleted file mode 100644
index 6fbf7864a2..0000000000
--- a/docs/api-reference/platform/adjustments/return-a-list-of-adjustments.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/adjustments
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/adjustments/return-an-adjustment.mdx b/docs/api-reference/platform/adjustments/return-an-adjustment.mdx
deleted file mode 100644
index 11eb49be4d..0000000000
--- a/docs/api-reference/platform/adjustments/return-an-adjustment.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/adjustments/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/adjustments/update-an-adjustment.mdx b/docs/api-reference/platform/adjustments/update-an-adjustment.mdx
deleted file mode 100644
index 0f1a2eca73..0000000000
--- a/docs/api-reference/platform/adjustments/update-an-adjustment.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/adjustments/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/classifications/create-a-classification.mdx b/docs/api-reference/platform/classifications/create-a-classification.mdx
deleted file mode 100644
index b0601ea708..0000000000
--- a/docs/api-reference/platform/classifications/create-a-classification.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/classifications
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/classifications/delete-a-classification.mdx b/docs/api-reference/platform/classifications/delete-a-classification.mdx
deleted file mode 100644
index d4c980fddb..0000000000
--- a/docs/api-reference/platform/classifications/delete-a-classification.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/classifications/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/classifications/return-a-classification.mdx b/docs/api-reference/platform/classifications/return-a-classification.mdx
deleted file mode 100644
index 53fe8cf15d..0000000000
--- a/docs/api-reference/platform/classifications/return-a-classification.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/classifications/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/classifications/return-a-list-of-classifications.mdx b/docs/api-reference/platform/classifications/return-a-list-of-classifications.mdx
deleted file mode 100644
index 927e3bb0ce..0000000000
--- a/docs/api-reference/platform/classifications/return-a-list-of-classifications.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/classifications
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/classifications/update-a-classification.mdx b/docs/api-reference/platform/classifications/update-a-classification.mdx
deleted file mode 100644
index 19864a46fa..0000000000
--- a/docs/api-reference/platform/classifications/update-a-classification.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/classifications/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/countries/returns-a-country.mdx b/docs/api-reference/platform/countries/returns-a-country.mdx
deleted file mode 100644
index bc9774df1b..0000000000
--- a/docs/api-reference/platform/countries/returns-a-country.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/countries/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/countries/returns-a-list-of-countries.mdx b/docs/api-reference/platform/countries/returns-a-list-of-countries.mdx
deleted file mode 100644
index d1a4843c68..0000000000
--- a/docs/api-reference/platform/countries/returns-a-list-of-countries.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/countries
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/data-feeds/create-a-data-feed.mdx b/docs/api-reference/platform/data-feeds/create-a-data-feed.mdx
deleted file mode 100644
index d881d1f0a0..0000000000
--- a/docs/api-reference/platform/data-feeds/create-a-data-feed.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/data_feeds
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/data-feeds/delete-a-data-feed.mdx b/docs/api-reference/platform/data-feeds/delete-a-data-feed.mdx
deleted file mode 100644
index ef911c13a4..0000000000
--- a/docs/api-reference/platform/data-feeds/delete-a-data-feed.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/data_feeds/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/data-feeds/return-a-data-feed.mdx b/docs/api-reference/platform/data-feeds/return-a-data-feed.mdx
deleted file mode 100644
index fa033eaba0..0000000000
--- a/docs/api-reference/platform/data-feeds/return-a-data-feed.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/data_feeds/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/data-feeds/return-a-list-of-data-feeds.mdx b/docs/api-reference/platform/data-feeds/return-a-list-of-data-feeds.mdx
deleted file mode 100644
index 5baab2c69f..0000000000
--- a/docs/api-reference/platform/data-feeds/return-a-list-of-data-feeds.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/data_feeds
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/data-feeds/update-a-data-feed.mdx b/docs/api-reference/platform/data-feeds/update-a-data-feed.mdx
deleted file mode 100644
index eef9d1c38d..0000000000
--- a/docs/api-reference/platform/data-feeds/update-a-data-feed.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/data_feeds/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/digital-assets/create-a-digital-asset.mdx b/docs/api-reference/platform/digital-assets/create-a-digital-asset.mdx
deleted file mode 100644
index 260127ea3e..0000000000
--- a/docs/api-reference/platform/digital-assets/create-a-digital-asset.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/digitals
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/digital-assets/delete-a-digital-asset.mdx b/docs/api-reference/platform/digital-assets/delete-a-digital-asset.mdx
deleted file mode 100644
index 731ae32fba..0000000000
--- a/docs/api-reference/platform/digital-assets/delete-a-digital-asset.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/digitals/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/digital-assets/return-a-digital-asset.mdx b/docs/api-reference/platform/digital-assets/return-a-digital-asset.mdx
deleted file mode 100644
index 85c703a321..0000000000
--- a/docs/api-reference/platform/digital-assets/return-a-digital-asset.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/digitals/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/digital-assets/return-a-list-of-digital-assets.mdx b/docs/api-reference/platform/digital-assets/return-a-list-of-digital-assets.mdx
deleted file mode 100644
index dc1053a3c6..0000000000
--- a/docs/api-reference/platform/digital-assets/return-a-list-of-digital-assets.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/digitals
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/digital-assets/update-a-digital-asset.mdx b/docs/api-reference/platform/digital-assets/update-a-digital-asset.mdx
deleted file mode 100644
index 262ccd30f9..0000000000
--- a/docs/api-reference/platform/digital-assets/update-a-digital-asset.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/digitals/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/digital-links/create-a-digital-link.mdx b/docs/api-reference/platform/digital-links/create-a-digital-link.mdx
deleted file mode 100644
index 863b8dff16..0000000000
--- a/docs/api-reference/platform/digital-links/create-a-digital-link.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/digital_links
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/digital-links/delete-a-digital-link.mdx b/docs/api-reference/platform/digital-links/delete-a-digital-link.mdx
deleted file mode 100644
index 643956f5d2..0000000000
--- a/docs/api-reference/platform/digital-links/delete-a-digital-link.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/digital_links/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/digital-links/reset-a-digital-link.mdx b/docs/api-reference/platform/digital-links/reset-a-digital-link.mdx
deleted file mode 100644
index 1a466494f7..0000000000
--- a/docs/api-reference/platform/digital-links/reset-a-digital-link.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/digital_links/{id}/reset
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/digital-links/return-a-digital-link.mdx b/docs/api-reference/platform/digital-links/return-a-digital-link.mdx
deleted file mode 100644
index 055d5312fa..0000000000
--- a/docs/api-reference/platform/digital-links/return-a-digital-link.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/digital_links/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/digital-links/return-a-list-of-digital-links.mdx b/docs/api-reference/platform/digital-links/return-a-list-of-digital-links.mdx
deleted file mode 100644
index 35bc821f45..0000000000
--- a/docs/api-reference/platform/digital-links/return-a-list-of-digital-links.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/digital_links
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/digital-links/update-a-digital-link.mdx b/docs/api-reference/platform/digital-links/update-a-digital-link.mdx
deleted file mode 100644
index 864186a2bf..0000000000
--- a/docs/api-reference/platform/digital-links/update-a-digital-link.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/digital_links/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/line-items/create-a-line-item.mdx b/docs/api-reference/platform/line-items/create-a-line-item.mdx
deleted file mode 100644
index 633a967296..0000000000
--- a/docs/api-reference/platform/line-items/create-a-line-item.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/line_items
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/line-items/delete-a-line-item.mdx b/docs/api-reference/platform/line-items/delete-a-line-item.mdx
deleted file mode 100644
index 69a28f0603..0000000000
--- a/docs/api-reference/platform/line-items/delete-a-line-item.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/line_items/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/line-items/return-a-line-item.mdx b/docs/api-reference/platform/line-items/return-a-line-item.mdx
deleted file mode 100644
index 84006937bd..0000000000
--- a/docs/api-reference/platform/line-items/return-a-line-item.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/line_items/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/line-items/return-a-list-of-line-items.mdx b/docs/api-reference/platform/line-items/return-a-list-of-line-items.mdx
deleted file mode 100644
index 32018b2af9..0000000000
--- a/docs/api-reference/platform/line-items/return-a-list-of-line-items.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/line_items
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/line-items/update-a-line-item.mdx b/docs/api-reference/platform/line-items/update-a-line-item.mdx
deleted file mode 100644
index da8694c53b..0000000000
--- a/docs/api-reference/platform/line-items/update-a-line-item.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/line_items/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/option-types/create-an-option-type.mdx b/docs/api-reference/platform/option-types/create-an-option-type.mdx
deleted file mode 100644
index 39f8db934c..0000000000
--- a/docs/api-reference/platform/option-types/create-an-option-type.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/option_types
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/option-types/delete-an-option-type.mdx b/docs/api-reference/platform/option-types/delete-an-option-type.mdx
deleted file mode 100644
index 4045b7f87d..0000000000
--- a/docs/api-reference/platform/option-types/delete-an-option-type.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/option_types/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/option-types/return-a-list-of-option-types.mdx b/docs/api-reference/platform/option-types/return-a-list-of-option-types.mdx
deleted file mode 100644
index 85982e1afb..0000000000
--- a/docs/api-reference/platform/option-types/return-a-list-of-option-types.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/option_types
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/option-types/return-an-option-type.mdx b/docs/api-reference/platform/option-types/return-an-option-type.mdx
deleted file mode 100644
index 00b7cbdd9a..0000000000
--- a/docs/api-reference/platform/option-types/return-an-option-type.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/option_types/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/option-types/update-an-option-type.mdx b/docs/api-reference/platform/option-types/update-an-option-type.mdx
deleted file mode 100644
index f5a9ed48d0..0000000000
--- a/docs/api-reference/platform/option-types/update-an-option-type.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/option_types/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/option-values/create-an-option-value.mdx b/docs/api-reference/platform/option-values/create-an-option-value.mdx
deleted file mode 100644
index a2e7fdf01c..0000000000
--- a/docs/api-reference/platform/option-values/create-an-option-value.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/option_values
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/option-values/delete-an-option-value.mdx b/docs/api-reference/platform/option-values/delete-an-option-value.mdx
deleted file mode 100644
index bbd818f473..0000000000
--- a/docs/api-reference/platform/option-values/delete-an-option-value.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/option_values/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/option-values/return-a-list-of-option-values.mdx b/docs/api-reference/platform/option-values/return-a-list-of-option-values.mdx
deleted file mode 100644
index 808282333d..0000000000
--- a/docs/api-reference/platform/option-values/return-a-list-of-option-values.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/option_values
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/option-values/return-an-option-value.mdx b/docs/api-reference/platform/option-values/return-an-option-value.mdx
deleted file mode 100644
index 76c4161b2a..0000000000
--- a/docs/api-reference/platform/option-values/return-an-option-value.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/option_values/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/option-values/update-an-option-value.mdx b/docs/api-reference/platform/option-values/update-an-option-value.mdx
deleted file mode 100644
index e811e6a258..0000000000
--- a/docs/api-reference/platform/option-values/update-an-option-value.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/option_values/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/orders/advances-an-order.mdx b/docs/api-reference/platform/orders/advances-an-order.mdx
deleted file mode 100644
index fff5b54933..0000000000
--- a/docs/api-reference/platform/orders/advances-an-order.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/orders/{id}/advance
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/orders/apply-coupon-code-for-an-order.mdx b/docs/api-reference/platform/orders/apply-coupon-code-for-an-order.mdx
deleted file mode 100644
index 617f56c9a3..0000000000
--- a/docs/api-reference/platform/orders/apply-coupon-code-for-an-order.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/orders/{id}/apply_coupon_code
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/orders/approves-an-order.mdx b/docs/api-reference/platform/orders/approves-an-order.mdx
deleted file mode 100644
index da455275e9..0000000000
--- a/docs/api-reference/platform/orders/approves-an-order.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/orders/{id}/approve
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/orders/cancels-an-order.mdx b/docs/api-reference/platform/orders/cancels-an-order.mdx
deleted file mode 100644
index 5f9af4f976..0000000000
--- a/docs/api-reference/platform/orders/cancels-an-order.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/orders/{id}/cancel
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/orders/completes-an-order.mdx b/docs/api-reference/platform/orders/completes-an-order.mdx
deleted file mode 100644
index ed92231caf..0000000000
--- a/docs/api-reference/platform/orders/completes-an-order.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/orders/{id}/complete
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/orders/creates-an-order.mdx b/docs/api-reference/platform/orders/creates-an-order.mdx
deleted file mode 100644
index 326c9f9bd2..0000000000
--- a/docs/api-reference/platform/orders/creates-an-order.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/orders
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/orders/delete-an-order.mdx b/docs/api-reference/platform/orders/delete-an-order.mdx
deleted file mode 100644
index f1fbc3083b..0000000000
--- a/docs/api-reference/platform/orders/delete-an-order.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/orders/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/orders/empties-an-order.mdx b/docs/api-reference/platform/orders/empties-an-order.mdx
deleted file mode 100644
index 8728b9a20e..0000000000
--- a/docs/api-reference/platform/orders/empties-an-order.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/orders/{id}/empty
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/orders/next-an-order.mdx b/docs/api-reference/platform/orders/next-an-order.mdx
deleted file mode 100644
index f59b186984..0000000000
--- a/docs/api-reference/platform/orders/next-an-order.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/orders/{id}/next
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/orders/return-a-list-of-orders.mdx b/docs/api-reference/platform/orders/return-a-list-of-orders.mdx
deleted file mode 100644
index 28b6f042e8..0000000000
--- a/docs/api-reference/platform/orders/return-a-list-of-orders.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/orders
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/orders/return-an-order.mdx b/docs/api-reference/platform/orders/return-an-order.mdx
deleted file mode 100644
index 3a6acfd852..0000000000
--- a/docs/api-reference/platform/orders/return-an-order.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/orders/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/orders/update-an-order.mdx b/docs/api-reference/platform/orders/update-an-order.mdx
deleted file mode 100644
index 352506b304..0000000000
--- a/docs/api-reference/platform/orders/update-an-order.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/orders/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/orders/use-store-credit-for-an-order.mdx b/docs/api-reference/platform/orders/use-store-credit-for-an-order.mdx
deleted file mode 100644
index 4929cfec69..0000000000
--- a/docs/api-reference/platform/orders/use-store-credit-for-an-order.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/orders/{id}/use_store_credit
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/payment-methods/create-a-payment-method.mdx b/docs/api-reference/platform/payment-methods/create-a-payment-method.mdx
deleted file mode 100644
index a3556d7c4c..0000000000
--- a/docs/api-reference/platform/payment-methods/create-a-payment-method.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/payment_methods
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/payment-methods/delete-a-payment-method.mdx b/docs/api-reference/platform/payment-methods/delete-a-payment-method.mdx
deleted file mode 100644
index d8c6959087..0000000000
--- a/docs/api-reference/platform/payment-methods/delete-a-payment-method.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/payment_methods/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/payment-methods/return-a-list-of-payment-methods.mdx b/docs/api-reference/platform/payment-methods/return-a-list-of-payment-methods.mdx
deleted file mode 100644
index 9fc7b5cec3..0000000000
--- a/docs/api-reference/platform/payment-methods/return-a-list-of-payment-methods.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/payment_methods
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/payment-methods/return-a-payment-method.mdx b/docs/api-reference/platform/payment-methods/return-a-payment-method.mdx
deleted file mode 100644
index 27198044c5..0000000000
--- a/docs/api-reference/platform/payment-methods/return-a-payment-method.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/payment_methods/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/payment-methods/update-a-payment-method.mdx b/docs/api-reference/platform/payment-methods/update-a-payment-method.mdx
deleted file mode 100644
index 5e818cf100..0000000000
--- a/docs/api-reference/platform/payment-methods/update-a-payment-method.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/payment_methods/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/payments/delete-a-payment.mdx b/docs/api-reference/platform/payments/delete-a-payment.mdx
deleted file mode 100644
index 0864b894ed..0000000000
--- a/docs/api-reference/platform/payments/delete-a-payment.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/payments/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/payments/return-a-list-of-payments.mdx b/docs/api-reference/platform/payments/return-a-list-of-payments.mdx
deleted file mode 100644
index 2b65508132..0000000000
--- a/docs/api-reference/platform/payments/return-a-list-of-payments.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/payments
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/payments/return-a-payment.mdx b/docs/api-reference/platform/payments/return-a-payment.mdx
deleted file mode 100644
index ce69fd133b..0000000000
--- a/docs/api-reference/platform/payments/return-a-payment.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/payments/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/products/create-a-product.mdx b/docs/api-reference/platform/products/create-a-product.mdx
deleted file mode 100644
index c84361a53e..0000000000
--- a/docs/api-reference/platform/products/create-a-product.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/products
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/products/delete-a-product.mdx b/docs/api-reference/platform/products/delete-a-product.mdx
deleted file mode 100644
index 36fa9eb6f7..0000000000
--- a/docs/api-reference/platform/products/delete-a-product.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/products/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/products/return-a-list-of-products.mdx b/docs/api-reference/platform/products/return-a-list-of-products.mdx
deleted file mode 100644
index 69bd7ac2da..0000000000
--- a/docs/api-reference/platform/products/return-a-list-of-products.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/products
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/products/return-a-product.mdx b/docs/api-reference/platform/products/return-a-product.mdx
deleted file mode 100644
index b7a6205235..0000000000
--- a/docs/api-reference/platform/products/return-a-product.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/products/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/products/update-a-product.mdx b/docs/api-reference/platform/products/update-a-product.mdx
deleted file mode 100644
index bdefe94284..0000000000
--- a/docs/api-reference/platform/products/update-a-product.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/products/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/promotion-actions/create-a-promotion-action.mdx b/docs/api-reference/platform/promotion-actions/create-a-promotion-action.mdx
deleted file mode 100644
index 21abca25d1..0000000000
--- a/docs/api-reference/platform/promotion-actions/create-a-promotion-action.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/promotion_actions
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/promotion-actions/delete-a-promotion-action.mdx b/docs/api-reference/platform/promotion-actions/delete-a-promotion-action.mdx
deleted file mode 100644
index ca7b20a7e2..0000000000
--- a/docs/api-reference/platform/promotion-actions/delete-a-promotion-action.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/promotion_actions/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/promotion-actions/return-a-list-of-promotion-actions.mdx b/docs/api-reference/platform/promotion-actions/return-a-list-of-promotion-actions.mdx
deleted file mode 100644
index 4f3ad26386..0000000000
--- a/docs/api-reference/platform/promotion-actions/return-a-list-of-promotion-actions.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/promotion_actions
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/promotion-actions/return-a-promotion-action.mdx b/docs/api-reference/platform/promotion-actions/return-a-promotion-action.mdx
deleted file mode 100644
index 103b809aed..0000000000
--- a/docs/api-reference/platform/promotion-actions/return-a-promotion-action.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/promotion_actions/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/promotion-actions/update-a-promotion-action.mdx b/docs/api-reference/platform/promotion-actions/update-a-promotion-action.mdx
deleted file mode 100644
index db14ddb7fd..0000000000
--- a/docs/api-reference/platform/promotion-actions/update-a-promotion-action.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/promotion_actions/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/promotion-categories/create-a-promotion-category.mdx b/docs/api-reference/platform/promotion-categories/create-a-promotion-category.mdx
deleted file mode 100644
index 97ba502402..0000000000
--- a/docs/api-reference/platform/promotion-categories/create-a-promotion-category.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/promotion_categories
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/promotion-categories/delete-a-promotion-category.mdx b/docs/api-reference/platform/promotion-categories/delete-a-promotion-category.mdx
deleted file mode 100644
index 9afaf85def..0000000000
--- a/docs/api-reference/platform/promotion-categories/delete-a-promotion-category.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/promotion_categories/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/promotion-categories/return-a-list-of-promotion-categories.mdx b/docs/api-reference/platform/promotion-categories/return-a-list-of-promotion-categories.mdx
deleted file mode 100644
index a3361549dd..0000000000
--- a/docs/api-reference/platform/promotion-categories/return-a-list-of-promotion-categories.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/promotion_categories
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/promotion-categories/return-a-promotion-category.mdx b/docs/api-reference/platform/promotion-categories/return-a-promotion-category.mdx
deleted file mode 100644
index 539ec2b230..0000000000
--- a/docs/api-reference/platform/promotion-categories/return-a-promotion-category.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/promotion_categories/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/promotion-categories/update-a-promotion-category.mdx b/docs/api-reference/platform/promotion-categories/update-a-promotion-category.mdx
deleted file mode 100644
index ee2c3e4d69..0000000000
--- a/docs/api-reference/platform/promotion-categories/update-a-promotion-category.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/promotion_categories/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/promotion-rules/create-a-promotion-rule.mdx b/docs/api-reference/platform/promotion-rules/create-a-promotion-rule.mdx
deleted file mode 100644
index 58b900f405..0000000000
--- a/docs/api-reference/platform/promotion-rules/create-a-promotion-rule.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/promotion_rules
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/promotion-rules/delete-a-promotion-rule.mdx b/docs/api-reference/platform/promotion-rules/delete-a-promotion-rule.mdx
deleted file mode 100644
index 06a3bdb3a5..0000000000
--- a/docs/api-reference/platform/promotion-rules/delete-a-promotion-rule.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/promotion_rules/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/promotion-rules/return-a-list-of-promotion-rules.mdx b/docs/api-reference/platform/promotion-rules/return-a-list-of-promotion-rules.mdx
deleted file mode 100644
index f510809307..0000000000
--- a/docs/api-reference/platform/promotion-rules/return-a-list-of-promotion-rules.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/promotion_rules
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/promotion-rules/return-a-promotion-rule.mdx b/docs/api-reference/platform/promotion-rules/return-a-promotion-rule.mdx
deleted file mode 100644
index 464523a363..0000000000
--- a/docs/api-reference/platform/promotion-rules/return-a-promotion-rule.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/promotion_rules/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/promotion-rules/update-a-promotion-rule.mdx b/docs/api-reference/platform/promotion-rules/update-a-promotion-rule.mdx
deleted file mode 100644
index 1e4554f9a3..0000000000
--- a/docs/api-reference/platform/promotion-rules/update-a-promotion-rule.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/promotion_rules/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/promotions/create-a-promotion.mdx b/docs/api-reference/platform/promotions/create-a-promotion.mdx
deleted file mode 100644
index 7846ce5b90..0000000000
--- a/docs/api-reference/platform/promotions/create-a-promotion.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/promotions
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/promotions/delete-a-promotion.mdx b/docs/api-reference/platform/promotions/delete-a-promotion.mdx
deleted file mode 100644
index 980281529e..0000000000
--- a/docs/api-reference/platform/promotions/delete-a-promotion.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/promotions/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/promotions/return-a-list-of-promotions.mdx b/docs/api-reference/platform/promotions/return-a-list-of-promotions.mdx
deleted file mode 100644
index 6a86d3e577..0000000000
--- a/docs/api-reference/platform/promotions/return-a-list-of-promotions.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/promotions
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/promotions/return-a-promotion.mdx b/docs/api-reference/platform/promotions/return-a-promotion.mdx
deleted file mode 100644
index 23ea5404cb..0000000000
--- a/docs/api-reference/platform/promotions/return-a-promotion.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/promotions/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/promotions/update-a-promotion.mdx b/docs/api-reference/platform/promotions/update-a-promotion.mdx
deleted file mode 100644
index e016f2e620..0000000000
--- a/docs/api-reference/platform/promotions/update-a-promotion.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/promotions/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/roles/create-a-role.mdx b/docs/api-reference/platform/roles/create-a-role.mdx
deleted file mode 100644
index 76214a762d..0000000000
--- a/docs/api-reference/platform/roles/create-a-role.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/roles
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/roles/delete-a-role.mdx b/docs/api-reference/platform/roles/delete-a-role.mdx
deleted file mode 100644
index 7d3f20fd41..0000000000
--- a/docs/api-reference/platform/roles/delete-a-role.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/roles/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/roles/return-a-list-of-roles.mdx b/docs/api-reference/platform/roles/return-a-list-of-roles.mdx
deleted file mode 100644
index 780278d5be..0000000000
--- a/docs/api-reference/platform/roles/return-a-list-of-roles.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/roles
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/roles/return-a-role.mdx b/docs/api-reference/platform/roles/return-a-role.mdx
deleted file mode 100644
index 529011ae57..0000000000
--- a/docs/api-reference/platform/roles/return-a-role.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/roles/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/roles/update-a-role.mdx b/docs/api-reference/platform/roles/update-a-role.mdx
deleted file mode 100644
index 6714cdcda2..0000000000
--- a/docs/api-reference/platform/roles/update-a-role.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/roles/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/shipments/adds-item-variant-to-an-existing-shipment.mdx b/docs/api-reference/platform/shipments/adds-item-variant-to-an-existing-shipment.mdx
deleted file mode 100644
index ea1a112b1f..0000000000
--- a/docs/api-reference/platform/shipments/adds-item-variant-to-an-existing-shipment.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/shipments/{id}/add_item
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/shipments/cancels-the-shipment.mdx b/docs/api-reference/platform/shipments/cancels-the-shipment.mdx
deleted file mode 100644
index 12cf6ce766..0000000000
--- a/docs/api-reference/platform/shipments/cancels-the-shipment.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/shipments/{id}/cancel
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/shipments/create-a-shipment.mdx b/docs/api-reference/platform/shipments/create-a-shipment.mdx
deleted file mode 100644
index 83f6cb1299..0000000000
--- a/docs/api-reference/platform/shipments/create-a-shipment.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/shipments
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/shipments/delete-a-shipment.mdx b/docs/api-reference/platform/shipments/delete-a-shipment.mdx
deleted file mode 100644
index cfd4c1e2b2..0000000000
--- a/docs/api-reference/platform/shipments/delete-a-shipment.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/shipments/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/shipments/mark-shipment-as-ready-to-be-shipped.mdx b/docs/api-reference/platform/shipments/mark-shipment-as-ready-to-be-shipped.mdx
deleted file mode 100644
index 04c4bd05b1..0000000000
--- a/docs/api-reference/platform/shipments/mark-shipment-as-ready-to-be-shipped.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/shipments/{id}/ready
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/shipments/mark-shipment-as-shipped.mdx b/docs/api-reference/platform/shipments/mark-shipment-as-shipped.mdx
deleted file mode 100644
index eab0b3e05a..0000000000
--- a/docs/api-reference/platform/shipments/mark-shipment-as-shipped.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/shipments/{id}/ship
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/shipments/moves-shipment-back-to-pending-state.mdx b/docs/api-reference/platform/shipments/moves-shipment-back-to-pending-state.mdx
deleted file mode 100644
index 37075b98aa..0000000000
--- a/docs/api-reference/platform/shipments/moves-shipment-back-to-pending-state.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/shipments/{id}/pend
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/shipments/removes-item-variant-from-shipment.mdx b/docs/api-reference/platform/shipments/removes-item-variant-from-shipment.mdx
deleted file mode 100644
index fa72033207..0000000000
--- a/docs/api-reference/platform/shipments/removes-item-variant-from-shipment.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/shipments/{id}/remove_item
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/shipments/resumes-the-shipment.mdx b/docs/api-reference/platform/shipments/resumes-the-shipment.mdx
deleted file mode 100644
index 7bb75420de..0000000000
--- a/docs/api-reference/platform/shipments/resumes-the-shipment.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/shipments/{id}/resume
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/shipments/return-a-list-of-shipments.mdx b/docs/api-reference/platform/shipments/return-a-list-of-shipments.mdx
deleted file mode 100644
index 332b9d2abf..0000000000
--- a/docs/api-reference/platform/shipments/return-a-list-of-shipments.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/shipments
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/shipments/return-a-shipment.mdx b/docs/api-reference/platform/shipments/return-a-shipment.mdx
deleted file mode 100644
index 30928294f9..0000000000
--- a/docs/api-reference/platform/shipments/return-a-shipment.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/shipments/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/shipments/update-a-shipment.mdx b/docs/api-reference/platform/shipments/update-a-shipment.mdx
deleted file mode 100644
index 82fad4cf68..0000000000
--- a/docs/api-reference/platform/shipments/update-a-shipment.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/shipments/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/shipping-categories/create-a-shipping-category.mdx b/docs/api-reference/platform/shipping-categories/create-a-shipping-category.mdx
deleted file mode 100644
index 0c598f0086..0000000000
--- a/docs/api-reference/platform/shipping-categories/create-a-shipping-category.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/shipping_categories
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/shipping-categories/delete-a-shipping-category.mdx b/docs/api-reference/platform/shipping-categories/delete-a-shipping-category.mdx
deleted file mode 100644
index c76792d844..0000000000
--- a/docs/api-reference/platform/shipping-categories/delete-a-shipping-category.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/shipping_categories/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/shipping-categories/return-a-list-of-shipping-categories.mdx b/docs/api-reference/platform/shipping-categories/return-a-list-of-shipping-categories.mdx
deleted file mode 100644
index baeef1db20..0000000000
--- a/docs/api-reference/platform/shipping-categories/return-a-list-of-shipping-categories.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/shipping_categories
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/shipping-categories/return-a-shipping-category.mdx b/docs/api-reference/platform/shipping-categories/return-a-shipping-category.mdx
deleted file mode 100644
index a6ccbe23a1..0000000000
--- a/docs/api-reference/platform/shipping-categories/return-a-shipping-category.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/shipping_categories/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/shipping-categories/update-a-shipping-category.mdx b/docs/api-reference/platform/shipping-categories/update-a-shipping-category.mdx
deleted file mode 100644
index 4e17126143..0000000000
--- a/docs/api-reference/platform/shipping-categories/update-a-shipping-category.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/shipping_categories/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/shipping-methods/create-a-shipping-method.mdx b/docs/api-reference/platform/shipping-methods/create-a-shipping-method.mdx
deleted file mode 100644
index 1c10585de0..0000000000
--- a/docs/api-reference/platform/shipping-methods/create-a-shipping-method.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/shipping_methods
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/shipping-methods/delete-a-shipping-method.mdx b/docs/api-reference/platform/shipping-methods/delete-a-shipping-method.mdx
deleted file mode 100644
index e84d93f58c..0000000000
--- a/docs/api-reference/platform/shipping-methods/delete-a-shipping-method.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/shipping_methods/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/shipping-methods/return-a-list-of-shipping-methods.mdx b/docs/api-reference/platform/shipping-methods/return-a-list-of-shipping-methods.mdx
deleted file mode 100644
index 1049066612..0000000000
--- a/docs/api-reference/platform/shipping-methods/return-a-list-of-shipping-methods.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/shipping_methods
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/shipping-methods/return-a-shipping-method.mdx b/docs/api-reference/platform/shipping-methods/return-a-shipping-method.mdx
deleted file mode 100644
index f1bc0d1e90..0000000000
--- a/docs/api-reference/platform/shipping-methods/return-a-shipping-method.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/shipping_methods/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/shipping-methods/update-a-shipping-method.mdx b/docs/api-reference/platform/shipping-methods/update-a-shipping-method.mdx
deleted file mode 100644
index da7ce1c982..0000000000
--- a/docs/api-reference/platform/shipping-methods/update-a-shipping-method.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/shipping_methods/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/states/returns-a-list-of-states.mdx b/docs/api-reference/platform/states/returns-a-list-of-states.mdx
deleted file mode 100644
index e2e029b363..0000000000
--- a/docs/api-reference/platform/states/returns-a-list-of-states.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/states
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/states/returns-a-state.mdx b/docs/api-reference/platform/states/returns-a-state.mdx
deleted file mode 100644
index ea88d288fb..0000000000
--- a/docs/api-reference/platform/states/returns-a-state.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/states/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/stock-items/create-a-stock-item.mdx b/docs/api-reference/platform/stock-items/create-a-stock-item.mdx
deleted file mode 100644
index 265065b0ee..0000000000
--- a/docs/api-reference/platform/stock-items/create-a-stock-item.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/stock_items
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/stock-items/delete-a-stock-item.mdx b/docs/api-reference/platform/stock-items/delete-a-stock-item.mdx
deleted file mode 100644
index 91bad5442f..0000000000
--- a/docs/api-reference/platform/stock-items/delete-a-stock-item.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/stock_items/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/stock-items/return-a-list-of-stock-items.mdx b/docs/api-reference/platform/stock-items/return-a-list-of-stock-items.mdx
deleted file mode 100644
index edce90da4b..0000000000
--- a/docs/api-reference/platform/stock-items/return-a-list-of-stock-items.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/stock_items
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/stock-items/return-a-stock-item.mdx b/docs/api-reference/platform/stock-items/return-a-stock-item.mdx
deleted file mode 100644
index 88771e9306..0000000000
--- a/docs/api-reference/platform/stock-items/return-a-stock-item.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/stock_items/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/stock-items/update-a-stock-item.mdx b/docs/api-reference/platform/stock-items/update-a-stock-item.mdx
deleted file mode 100644
index ef665ea3d9..0000000000
--- a/docs/api-reference/platform/stock-items/update-a-stock-item.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/stock_items/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/stock-locations/create-a-stock-location.mdx b/docs/api-reference/platform/stock-locations/create-a-stock-location.mdx
deleted file mode 100644
index c515a38484..0000000000
--- a/docs/api-reference/platform/stock-locations/create-a-stock-location.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/stock_locations
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/stock-locations/delete-a-stock-location.mdx b/docs/api-reference/platform/stock-locations/delete-a-stock-location.mdx
deleted file mode 100644
index 29762b4c4f..0000000000
--- a/docs/api-reference/platform/stock-locations/delete-a-stock-location.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/stock_locations/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/stock-locations/return-a-list-of-stock-locations.mdx b/docs/api-reference/platform/stock-locations/return-a-list-of-stock-locations.mdx
deleted file mode 100644
index 7df8e6c28a..0000000000
--- a/docs/api-reference/platform/stock-locations/return-a-list-of-stock-locations.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/stock_locations
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/stock-locations/return-a-stock-location.mdx b/docs/api-reference/platform/stock-locations/return-a-stock-location.mdx
deleted file mode 100644
index 7938b58d6c..0000000000
--- a/docs/api-reference/platform/stock-locations/return-a-stock-location.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/stock_locations/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/stock-locations/update-a-stock-location.mdx b/docs/api-reference/platform/stock-locations/update-a-stock-location.mdx
deleted file mode 100644
index d419270546..0000000000
--- a/docs/api-reference/platform/stock-locations/update-a-stock-location.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/stock_locations/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/store-credit-categories/create-a-store-credit-category.mdx b/docs/api-reference/platform/store-credit-categories/create-a-store-credit-category.mdx
deleted file mode 100644
index 9cddfdebbe..0000000000
--- a/docs/api-reference/platform/store-credit-categories/create-a-store-credit-category.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/store_credit_categories
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/store-credit-categories/delete-a-store-credit-category.mdx b/docs/api-reference/platform/store-credit-categories/delete-a-store-credit-category.mdx
deleted file mode 100644
index f2a9924121..0000000000
--- a/docs/api-reference/platform/store-credit-categories/delete-a-store-credit-category.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/store_credit_categories/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/store-credit-categories/return-a-list-of-store-credit-categories.mdx b/docs/api-reference/platform/store-credit-categories/return-a-list-of-store-credit-categories.mdx
deleted file mode 100644
index 896f951e07..0000000000
--- a/docs/api-reference/platform/store-credit-categories/return-a-list-of-store-credit-categories.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/store_credit_categories
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/store-credit-categories/return-a-store-credit-category.mdx b/docs/api-reference/platform/store-credit-categories/return-a-store-credit-category.mdx
deleted file mode 100644
index 0588ef1b5b..0000000000
--- a/docs/api-reference/platform/store-credit-categories/return-a-store-credit-category.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/store_credit_categories/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/store-credit-categories/update-a-store-credit-category.mdx b/docs/api-reference/platform/store-credit-categories/update-a-store-credit-category.mdx
deleted file mode 100644
index b82ccfce24..0000000000
--- a/docs/api-reference/platform/store-credit-categories/update-a-store-credit-category.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/store_credit_categories/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/store-credit-types/create-a-store-credit-type.mdx b/docs/api-reference/platform/store-credit-types/create-a-store-credit-type.mdx
deleted file mode 100644
index 93c3fc6b7d..0000000000
--- a/docs/api-reference/platform/store-credit-types/create-a-store-credit-type.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/store_credit_types
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/store-credit-types/delete-a-store-credit-type.mdx b/docs/api-reference/platform/store-credit-types/delete-a-store-credit-type.mdx
deleted file mode 100644
index a37dd1f065..0000000000
--- a/docs/api-reference/platform/store-credit-types/delete-a-store-credit-type.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/store_credit_types/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/store-credit-types/return-a-list-of-store-credit-types.mdx b/docs/api-reference/platform/store-credit-types/return-a-list-of-store-credit-types.mdx
deleted file mode 100644
index 1b554bcdc4..0000000000
--- a/docs/api-reference/platform/store-credit-types/return-a-list-of-store-credit-types.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/store_credit_types
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/store-credit-types/return-a-store-credit-type.mdx b/docs/api-reference/platform/store-credit-types/return-a-store-credit-type.mdx
deleted file mode 100644
index b474055211..0000000000
--- a/docs/api-reference/platform/store-credit-types/return-a-store-credit-type.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/store_credit_types/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/store-credit-types/update-a-store-credit-type.mdx b/docs/api-reference/platform/store-credit-types/update-a-store-credit-type.mdx
deleted file mode 100644
index 5e9b406986..0000000000
--- a/docs/api-reference/platform/store-credit-types/update-a-store-credit-type.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/store_credit_types/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/store-credits/create-a-store-credit.mdx b/docs/api-reference/platform/store-credits/create-a-store-credit.mdx
deleted file mode 100644
index 62a74da372..0000000000
--- a/docs/api-reference/platform/store-credits/create-a-store-credit.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/store_credits
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/store-credits/delete-a-store-credit.mdx b/docs/api-reference/platform/store-credits/delete-a-store-credit.mdx
deleted file mode 100644
index 6c1e493e90..0000000000
--- a/docs/api-reference/platform/store-credits/delete-a-store-credit.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/store_credits/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/store-credits/return-a-list-of-store-credits.mdx b/docs/api-reference/platform/store-credits/return-a-list-of-store-credits.mdx
deleted file mode 100644
index f2b17acdc4..0000000000
--- a/docs/api-reference/platform/store-credits/return-a-list-of-store-credits.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/store_credits
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/store-credits/return-a-store-credit.mdx b/docs/api-reference/platform/store-credits/return-a-store-credit.mdx
deleted file mode 100644
index d086b532c3..0000000000
--- a/docs/api-reference/platform/store-credits/return-a-store-credit.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/store_credits/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/store-credits/update-a-store-credit.mdx b/docs/api-reference/platform/store-credits/update-a-store-credit.mdx
deleted file mode 100644
index fff92e4b52..0000000000
--- a/docs/api-reference/platform/store-credits/update-a-store-credit.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/store_credits/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/tax-categories/create-a-tax-category.mdx b/docs/api-reference/platform/tax-categories/create-a-tax-category.mdx
deleted file mode 100644
index f249313e01..0000000000
--- a/docs/api-reference/platform/tax-categories/create-a-tax-category.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/tax_categories
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/tax-categories/delete-a-tax-category.mdx b/docs/api-reference/platform/tax-categories/delete-a-tax-category.mdx
deleted file mode 100644
index 9722cb3b14..0000000000
--- a/docs/api-reference/platform/tax-categories/delete-a-tax-category.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/tax_categories/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/tax-categories/return-a-list-of-tax-categories.mdx b/docs/api-reference/platform/tax-categories/return-a-list-of-tax-categories.mdx
deleted file mode 100644
index 429ab6e93e..0000000000
--- a/docs/api-reference/platform/tax-categories/return-a-list-of-tax-categories.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/tax_categories
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/tax-categories/return-a-tax-category.mdx b/docs/api-reference/platform/tax-categories/return-a-tax-category.mdx
deleted file mode 100644
index a2cac66898..0000000000
--- a/docs/api-reference/platform/tax-categories/return-a-tax-category.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/tax_categories/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/tax-categories/update-a-tax-category.mdx b/docs/api-reference/platform/tax-categories/update-a-tax-category.mdx
deleted file mode 100644
index edcc60ff2a..0000000000
--- a/docs/api-reference/platform/tax-categories/update-a-tax-category.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/tax_categories/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/tax-rates/create-a-tax-rate.mdx b/docs/api-reference/platform/tax-rates/create-a-tax-rate.mdx
deleted file mode 100644
index 0fa41418c9..0000000000
--- a/docs/api-reference/platform/tax-rates/create-a-tax-rate.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/tax_rates
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/tax-rates/delete-a-tax-rate.mdx b/docs/api-reference/platform/tax-rates/delete-a-tax-rate.mdx
deleted file mode 100644
index faba1ecf18..0000000000
--- a/docs/api-reference/platform/tax-rates/delete-a-tax-rate.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/tax_rates/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/tax-rates/return-a-list-of-tax-rates.mdx b/docs/api-reference/platform/tax-rates/return-a-list-of-tax-rates.mdx
deleted file mode 100644
index 95e66c3bc8..0000000000
--- a/docs/api-reference/platform/tax-rates/return-a-list-of-tax-rates.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/tax_rates
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/tax-rates/return-a-tax-rate.mdx b/docs/api-reference/platform/tax-rates/return-a-tax-rate.mdx
deleted file mode 100644
index 35ccd68b67..0000000000
--- a/docs/api-reference/platform/tax-rates/return-a-tax-rate.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/tax_rates/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/tax-rates/update-a-tax-rate.mdx b/docs/api-reference/platform/tax-rates/update-a-tax-rate.mdx
deleted file mode 100644
index d3d8906abd..0000000000
--- a/docs/api-reference/platform/tax-rates/update-a-tax-rate.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/tax_rates/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/taxonomies/create-a-taxonomy.mdx b/docs/api-reference/platform/taxonomies/create-a-taxonomy.mdx
deleted file mode 100644
index 4407591fe7..0000000000
--- a/docs/api-reference/platform/taxonomies/create-a-taxonomy.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/taxonomies
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/taxonomies/delete-a-taxonomy.mdx b/docs/api-reference/platform/taxonomies/delete-a-taxonomy.mdx
deleted file mode 100644
index 22a43f02b1..0000000000
--- a/docs/api-reference/platform/taxonomies/delete-a-taxonomy.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/taxonomies/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/taxonomies/return-a-list-of-taxonomies.mdx b/docs/api-reference/platform/taxonomies/return-a-list-of-taxonomies.mdx
deleted file mode 100644
index 80ec0e7f94..0000000000
--- a/docs/api-reference/platform/taxonomies/return-a-list-of-taxonomies.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/taxonomies
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/taxonomies/return-a-taxonomy.mdx b/docs/api-reference/platform/taxonomies/return-a-taxonomy.mdx
deleted file mode 100644
index 53d02f163f..0000000000
--- a/docs/api-reference/platform/taxonomies/return-a-taxonomy.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/taxonomies/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/taxonomies/update-a-taxonomy.mdx b/docs/api-reference/platform/taxonomies/update-a-taxonomy.mdx
deleted file mode 100644
index 3fe654e1f8..0000000000
--- a/docs/api-reference/platform/taxonomies/update-a-taxonomy.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/taxonomies/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/taxons/create-a-taxon.mdx b/docs/api-reference/platform/taxons/create-a-taxon.mdx
deleted file mode 100644
index bb0384e752..0000000000
--- a/docs/api-reference/platform/taxons/create-a-taxon.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/taxons
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/taxons/delete-a-taxon.mdx b/docs/api-reference/platform/taxons/delete-a-taxon.mdx
deleted file mode 100644
index cfa589b0de..0000000000
--- a/docs/api-reference/platform/taxons/delete-a-taxon.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/taxons/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/taxons/reposition-a-taxon.mdx b/docs/api-reference/platform/taxons/reposition-a-taxon.mdx
deleted file mode 100644
index 60cfd02fc4..0000000000
--- a/docs/api-reference/platform/taxons/reposition-a-taxon.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/taxons/{id}/reposition
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/taxons/return-a-list-of-taxons.mdx b/docs/api-reference/platform/taxons/return-a-list-of-taxons.mdx
deleted file mode 100644
index 7999e61355..0000000000
--- a/docs/api-reference/platform/taxons/return-a-list-of-taxons.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/taxons
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/taxons/return-a-taxon.mdx b/docs/api-reference/platform/taxons/return-a-taxon.mdx
deleted file mode 100644
index 2fa2ea2836..0000000000
--- a/docs/api-reference/platform/taxons/return-a-taxon.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/taxons/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/taxons/update-a-taxon.mdx b/docs/api-reference/platform/taxons/update-a-taxon.mdx
deleted file mode 100644
index ee6b79123f..0000000000
--- a/docs/api-reference/platform/taxons/update-a-taxon.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/taxons/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/users/create-a-user.mdx b/docs/api-reference/platform/users/create-a-user.mdx
deleted file mode 100644
index f9cf189a8d..0000000000
--- a/docs/api-reference/platform/users/create-a-user.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/users
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/users/delete-a-user.mdx b/docs/api-reference/platform/users/delete-a-user.mdx
deleted file mode 100644
index 03f85ef2a9..0000000000
--- a/docs/api-reference/platform/users/delete-a-user.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/users/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/users/return-a-list-of-users.mdx b/docs/api-reference/platform/users/return-a-list-of-users.mdx
deleted file mode 100644
index 1571f5aeac..0000000000
--- a/docs/api-reference/platform/users/return-a-list-of-users.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/users
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/users/return-a-user.mdx b/docs/api-reference/platform/users/return-a-user.mdx
deleted file mode 100644
index 93e3716c9e..0000000000
--- a/docs/api-reference/platform/users/return-a-user.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/users/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/users/update-a-user.mdx b/docs/api-reference/platform/users/update-a-user.mdx
deleted file mode 100644
index 9b640e3e75..0000000000
--- a/docs/api-reference/platform/users/update-a-user.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/users/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/variants/delete-a-variant.mdx b/docs/api-reference/platform/variants/delete-a-variant.mdx
deleted file mode 100644
index 68908d721d..0000000000
--- a/docs/api-reference/platform/variants/delete-a-variant.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/variants/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/variants/return-a-list-of-variants.mdx b/docs/api-reference/platform/variants/return-a-list-of-variants.mdx
deleted file mode 100644
index 08c5bb1a6c..0000000000
--- a/docs/api-reference/platform/variants/return-a-list-of-variants.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/variants
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/variants/return-a-variant.mdx b/docs/api-reference/platform/variants/return-a-variant.mdx
deleted file mode 100644
index 748edf5670..0000000000
--- a/docs/api-reference/platform/variants/return-a-variant.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/variants/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/vendors/approves-vendor.mdx b/docs/api-reference/platform/vendors/approves-vendor.mdx
deleted file mode 100644
index 85da1fa704..0000000000
--- a/docs/api-reference/platform/vendors/approves-vendor.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-openapi: patch /api/v2/platform/vendors/{id}/approve
-version: v5
----
diff --git a/docs/api-reference/platform/vendors/completes-onboarding-process.mdx b/docs/api-reference/platform/vendors/completes-onboarding-process.mdx
deleted file mode 100644
index 41d3a8b91d..0000000000
--- a/docs/api-reference/platform/vendors/completes-onboarding-process.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-openapi: patch /api/v2/platform/vendors/{id}/complete_onboarding
-version: v5
----
diff --git a/docs/api-reference/platform/vendors/create-a-vendor.mdx b/docs/api-reference/platform/vendors/create-a-vendor.mdx
deleted file mode 100644
index 01a7491611..0000000000
--- a/docs/api-reference/platform/vendors/create-a-vendor.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-openapi: post /api/v2/platform/vendors
-version: v5
----
diff --git a/docs/api-reference/platform/vendors/delete-a-vendor.mdx b/docs/api-reference/platform/vendors/delete-a-vendor.mdx
deleted file mode 100644
index 1a0a4e013f..0000000000
--- a/docs/api-reference/platform/vendors/delete-a-vendor.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-openapi: delete /api/v2/platform/vendors/{id}
-version: v5
----
diff --git a/docs/api-reference/platform/vendors/invites-vendor-to-the-platform.mdx b/docs/api-reference/platform/vendors/invites-vendor-to-the-platform.mdx
deleted file mode 100644
index e55b4c6beb..0000000000
--- a/docs/api-reference/platform/vendors/invites-vendor-to-the-platform.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-openapi: patch /api/v2/platform/vendors/{id}/invite
-version: v5
----
diff --git a/docs/api-reference/platform/vendors/rejects-vendor.mdx b/docs/api-reference/platform/vendors/rejects-vendor.mdx
deleted file mode 100644
index b872153f9b..0000000000
--- a/docs/api-reference/platform/vendors/rejects-vendor.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-openapi: patch /api/v2/platform/vendors/{id}/reject
-version: v5
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/vendors/return-a-list-of-vendors.mdx b/docs/api-reference/platform/vendors/return-a-list-of-vendors.mdx
deleted file mode 100644
index 3cb9d666c7..0000000000
--- a/docs/api-reference/platform/vendors/return-a-list-of-vendors.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-openapi: get /api/v2/platform/vendors
-version: v5
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/vendors/return-a-vendor.mdx b/docs/api-reference/platform/vendors/return-a-vendor.mdx
deleted file mode 100644
index aa1095d2f0..0000000000
--- a/docs/api-reference/platform/vendors/return-a-vendor.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-openapi: get /api/v2/platform/vendors/{id}
-version: v5
----
diff --git a/docs/api-reference/platform/vendors/start-onboarding-process.mdx b/docs/api-reference/platform/vendors/start-onboarding-process.mdx
deleted file mode 100644
index 580b988196..0000000000
--- a/docs/api-reference/platform/vendors/start-onboarding-process.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-openapi: patch /api/v2/platform/vendors/{id}/start_onboarding
-version: v5
----
diff --git a/docs/api-reference/platform/vendors/suspends-vendor.mdx b/docs/api-reference/platform/vendors/suspends-vendor.mdx
deleted file mode 100644
index 62579f755f..0000000000
--- a/docs/api-reference/platform/vendors/suspends-vendor.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-openapi: patch /api/v2/platform/vendors/{id}/suspend
-version: v5
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/vendors/update-a-vendor.mdx b/docs/api-reference/platform/vendors/update-a-vendor.mdx
deleted file mode 100644
index dbba636f8f..0000000000
--- a/docs/api-reference/platform/vendors/update-a-vendor.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-openapi: patch /api/v2/platform/vendors/{id}
-version: v5
----
diff --git a/docs/api-reference/platform/webhook-events/return-a-list-of-webhook-events.mdx b/docs/api-reference/platform/webhook-events/return-a-list-of-webhook-events.mdx
deleted file mode 100644
index 380ebe9b89..0000000000
--- a/docs/api-reference/platform/webhook-events/return-a-list-of-webhook-events.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/webhooks/events
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/webhook-subscribers/create-a-webhook-subscriber.mdx b/docs/api-reference/platform/webhook-subscribers/create-a-webhook-subscriber.mdx
deleted file mode 100644
index 7567d2156a..0000000000
--- a/docs/api-reference/platform/webhook-subscribers/create-a-webhook-subscriber.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/webhooks/subscribers
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/webhook-subscribers/delete-a-webhook-subscriber.mdx b/docs/api-reference/platform/webhook-subscribers/delete-a-webhook-subscriber.mdx
deleted file mode 100644
index ccda9996e9..0000000000
--- a/docs/api-reference/platform/webhook-subscribers/delete-a-webhook-subscriber.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/webhooks/subscribers/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/webhook-subscribers/return-a-list-of-webhook-subscribers.mdx b/docs/api-reference/platform/webhook-subscribers/return-a-list-of-webhook-subscribers.mdx
deleted file mode 100644
index fa43e9b1b9..0000000000
--- a/docs/api-reference/platform/webhook-subscribers/return-a-list-of-webhook-subscribers.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/webhooks/subscribers
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/webhook-subscribers/return-a-webhook-subscriber.mdx b/docs/api-reference/platform/webhook-subscribers/return-a-webhook-subscriber.mdx
deleted file mode 100644
index c47a87bbbe..0000000000
--- a/docs/api-reference/platform/webhook-subscribers/return-a-webhook-subscriber.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/webhooks/subscribers/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/webhook-subscribers/update-a-webhook-subscriber.mdx b/docs/api-reference/platform/webhook-subscribers/update-a-webhook-subscriber.mdx
deleted file mode 100644
index d58ba2cb34..0000000000
--- a/docs/api-reference/platform/webhook-subscribers/update-a-webhook-subscriber.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/webhooks/subscribers/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/wished-items/create-a-wished-item.mdx b/docs/api-reference/platform/wished-items/create-a-wished-item.mdx
deleted file mode 100644
index 7b8da7b42c..0000000000
--- a/docs/api-reference/platform/wished-items/create-a-wished-item.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/wished_items
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/wished-items/delete-a-wished-item.mdx b/docs/api-reference/platform/wished-items/delete-a-wished-item.mdx
deleted file mode 100644
index aa0f97f71e..0000000000
--- a/docs/api-reference/platform/wished-items/delete-a-wished-item.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/wished_items/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/wished-items/return-a-list-of-wished-items.mdx b/docs/api-reference/platform/wished-items/return-a-list-of-wished-items.mdx
deleted file mode 100644
index f02fb57f07..0000000000
--- a/docs/api-reference/platform/wished-items/return-a-list-of-wished-items.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/wished_items
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/wished-items/return-a-wished-item.mdx b/docs/api-reference/platform/wished-items/return-a-wished-item.mdx
deleted file mode 100644
index 2490dce19f..0000000000
--- a/docs/api-reference/platform/wished-items/return-a-wished-item.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/wished_items/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/wished-items/update-a-wished-item.mdx b/docs/api-reference/platform/wished-items/update-a-wished-item.mdx
deleted file mode 100644
index 174d6001bb..0000000000
--- a/docs/api-reference/platform/wished-items/update-a-wished-item.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/wished_items/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/wishlists/create-a-wishlist.mdx b/docs/api-reference/platform/wishlists/create-a-wishlist.mdx
deleted file mode 100644
index 3b1ec82d5d..0000000000
--- a/docs/api-reference/platform/wishlists/create-a-wishlist.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/wishlists
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/wishlists/delete-a-wishlist.mdx b/docs/api-reference/platform/wishlists/delete-a-wishlist.mdx
deleted file mode 100644
index a7d3df960a..0000000000
--- a/docs/api-reference/platform/wishlists/delete-a-wishlist.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/wishlists/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/wishlists/return-a-list-of-wishlists.mdx b/docs/api-reference/platform/wishlists/return-a-list-of-wishlists.mdx
deleted file mode 100644
index a907367629..0000000000
--- a/docs/api-reference/platform/wishlists/return-a-list-of-wishlists.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/wishlists
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/wishlists/return-a-wishlist.mdx b/docs/api-reference/platform/wishlists/return-a-wishlist.mdx
deleted file mode 100644
index 6a98cfca81..0000000000
--- a/docs/api-reference/platform/wishlists/return-a-wishlist.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/wishlists/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/wishlists/update-a-wishlist.mdx b/docs/api-reference/platform/wishlists/update-a-wishlist.mdx
deleted file mode 100644
index a68292aa65..0000000000
--- a/docs/api-reference/platform/wishlists/update-a-wishlist.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/wishlists/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/zones/create-a-zone.mdx b/docs/api-reference/platform/zones/create-a-zone.mdx
deleted file mode 100644
index 1391b1be61..0000000000
--- a/docs/api-reference/platform/zones/create-a-zone.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/platform/zones
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/zones/delete-a-zone.mdx b/docs/api-reference/platform/zones/delete-a-zone.mdx
deleted file mode 100644
index c493e1a2bb..0000000000
--- a/docs/api-reference/platform/zones/delete-a-zone.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/platform/zones/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/zones/return-a-list-of-zones.mdx b/docs/api-reference/platform/zones/return-a-list-of-zones.mdx
deleted file mode 100644
index 987932f643..0000000000
--- a/docs/api-reference/platform/zones/return-a-list-of-zones.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/zones
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/zones/return-a-zone.mdx b/docs/api-reference/platform/zones/return-a-zone.mdx
deleted file mode 100644
index 3a20d9645c..0000000000
--- a/docs/api-reference/platform/zones/return-a-zone.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/platform/zones/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/platform/zones/update-a-zone.mdx b/docs/api-reference/platform/zones/update-a-zone.mdx
deleted file mode 100644
index f371f98195..0000000000
--- a/docs/api-reference/platform/zones/update-a-zone.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/platform/zones/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/store-api/authentication.mdx b/docs/api-reference/store-api/authentication.mdx
new file mode 100644
index 0000000000..7553a9f721
--- /dev/null
+++ b/docs/api-reference/store-api/authentication.mdx
@@ -0,0 +1,202 @@
+---
+title: "Authentication"
+sidebarTitle: "Authentication"
+description: "How to authenticate requests to the Store API"
+---
+
+The Store API uses three authentication mechanisms depending on the use case: **API keys** for all requests, **JWT tokens** for authenticated customers, and **order tokens** for guest checkout.
+
+## API Key (Required)
+
+Every request to the Store API requires a **publishable API key**. This key identifies your storefront and is safe to use in client-side code.
+
+Pass the key via the `X-Spree-Api-Key` header:
+
+<CodeGroup>
+
+```typescript SDK
+import { createSpreeClient } from '@spree/sdk'
+
+const client = createSpreeClient({
+ baseUrl: 'http://localhost:3000',
+ publishableKey: 'spree_pk_xxx',
+})
+
+// The SDK automatically sends the publishable key with every request
+const products = await client.store.products.list()
+```
+
+```bash cURL
+curl -X GET 'http://localhost:3000/api/v3/store/products' \
+ -H 'X-Spree-Api-Key: spree_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:
+
+```bash
+spree api-key create # Create a new API key
+spree api-key list # List existing API keys
+```
+
+<Warning>
+If you omit the API key, the API returns a `401 Unauthorized` error:
+
+```json
+{
+ "error": {
+ "code": "invalid_token",
+ "message": "Valid API key required"
+ }
+}
+```
+</Warning>
+
+## JWT Token (Authenticated Customer)
+
+For actions that require a logged-in customer (viewing orders, managing addresses, saved payment methods), use a **JWT bearer token** in addition to the API key.
+
+### Login
+
+<CodeGroup>
+
+```typescript SDK
+// Login to get a JWT token
+const { token, user } = await client.store.auth.login({
+ email: '[email protected]',
+ password: 'password123',
+})
+
+// Use the token for authenticated requests
+const orders = await client.store.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 '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 'Authorization: Bearer <jwt_token>'
+```
+
+</CodeGroup>
+
+### Register
+
+<CodeGroup>
+
+```typescript SDK
+const { token, user } = await client.store.auth.register({
+ email: '[email protected]',
+ password: 'password123',
+ password_confirmation: 'password123',
+ first_name: 'John',
+ last_name: 'Doe',
+})
+```
+
+```bash cURL
+curl -X POST 'http://localhost:3000/api/v3/store/auth/register' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "email": "[email protected]",
+ "password": "password123",
+ "password_confirmation": "password123",
+ "first_name": "John",
+ "last_name": "Doe"
+ }'
+```
+
+</CodeGroup>
+
+### Token Refresh
+
+JWT tokens expire after 1 hour by default. Use the refresh endpoint to get a new token:
+
+<CodeGroup>
+
+```typescript SDK
+const { token } = await client.store.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 'Authorization: Bearer <current_jwt_token>'
+```
+
+</CodeGroup>
+
+## Order Token (Guest Checkout)
+
+For guest checkout flows, use the **order token** returned when creating a cart. This allows unauthenticated users to manage their cart and complete checkout.
+
+Pass the token via the `X-Spree-Order-Token` header or `order_token` query parameter:
+
+<CodeGroup>
+
+```typescript SDK
+// Create a cart (guest)
+const cart = await client.store.cart.create()
+
+// Use orderToken for all cart operations
+const options = { orderToken: cart.token }
+
+// Add items
+await client.store.orders.lineItems.create(cart.id, {
+ variant_id: 'variant_abc123',
+ quantity: 1,
+}, options)
+```
+
+```bash cURL
+# Create a cart
+curl -X POST 'http://localhost:3000/api/v3/store/cart' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx'
+
+# Use the returned token for cart operations
+curl -X POST 'http://localhost:3000/api/v3/store/orders/or_xxx/line_items' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx' \
+ -H 'X-Spree-Order-Token: <order_token>' \
+ -H 'Content-Type: application/json' \
+ -d '{"variant_id": "variant_abc123", "quantity": 1}'
+```
+
+</CodeGroup>
+
+### Associating a Guest Cart
+
+After a guest user logs in, you can associate their guest cart with their account:
+
+<CodeGroup>
+
+```typescript SDK
+await client.store.cart.associate({
+ token: jwtToken,
+ orderToken: cart.token,
+})
+```
+
+```bash cURL
+curl -X PATCH 'http://localhost:3000/api/v3/store/cart/associate' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx' \
+ -H 'Authorization: Bearer <jwt_token>' \
+ -H 'X-Spree-Order-Token: <order_token>'
+```
+
+</CodeGroup>
+
+## Authentication Summary
+
+| Method | Header | Use Case |
+|--------|--------|----------|
+| API Key | `X-Spree-Api-Key: spree_pk_xxx` | All requests (required) |
+| JWT Token | `Authorization: Bearer <token>` | Authenticated customer actions |
+| Order Token | `X-Spree-Order-Token: <token>` | Guest cart and checkout |
diff --git a/docs/api-reference/store-api/errors.mdx b/docs/api-reference/store-api/errors.mdx
new file mode 100644
index 0000000000..876a4ac9d9
--- /dev/null
+++ b/docs/api-reference/store-api/errors.mdx
@@ -0,0 +1,267 @@
+---
+title: Errors
+description: Error response format, error codes, and handling strategies
+---
+
+The Store API uses a consistent, Stripe-style error format across all endpoints. Every error response includes a machine-readable `code` and a human-readable `message`.
+
+## Error Response Format
+
+All errors return a JSON object with a single `error` key:
+
+```json
+{
+ "error": {
+ "code": "record_not_found",
+ "message": "Product not found"
+ }
+}
+```
+
+Validation errors include an additional `details` field with per-field error messages:
+
+```json
+{
+ "error": {
+ "code": "validation_error",
+ "message": "Name can't be blank and Email is invalid",
+ "details": {
+ "name": ["can't be blank"],
+ "email": ["is invalid"]
+ }
+ }
+}
+```
+
+### Schema
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `error.code` | `string` | Machine-readable error code (see table below) |
+| `error.message` | `string` | Human-readable description of the error |
+| `error.details` | `object` | Field-specific validation errors. Each key is a field name, each value is an array of error strings. Only present for validation errors. |
+
+## HTTP Status Codes
+
+| Status | Meaning | When |
+|--------|---------|------|
+| `400` | Bad Request | Missing required parameters, malformed JSON, invalid arguments |
+| `401` | Unauthorized | Missing or invalid API key, expired JWT token |
+| `403` | Forbidden | Authenticated but not authorized for this resource |
+| `404` | Not Found | Resource doesn't exist or isn't accessible |
+| `422` | Unprocessable Content | Validation failed, invalid state transition, payment error |
+| `429` | Too Many Requests | Rate limit exceeded (see [Rate Limiting](/api-reference/store-api/rate-limitting)) |
+
+## Error Codes
+
+### Authentication & Authorization
+
+| Code | Status | Description |
+|------|--------|-------------|
+| `authentication_required` | 401 | Request requires a valid JWT token |
+| `authentication_failed` | 401 | Email or password is incorrect |
+| `invalid_token` | 401 | API key or JWT token is invalid or expired |
+| `invalid_provider` | 400 | OAuth provider not recognized |
+| `access_denied` | 403 | User doesn't have permission for this action |
+
+### Resource Errors
+
+| Code | Status | Description |
+|------|--------|-------------|
+| `record_not_found` | 404 | Resource doesn't exist or isn't accessible in the current store |
+| `resource_invalid` | 422 | Resource couldn't be saved |
+
+### Validation Errors
+
+| Code | Status | Description |
+|------|--------|-------------|
+| `validation_error` | 422 | Model validation failed. Check `details` for field-specific messages. |
+| `parameter_missing` | 400 | A required parameter is missing |
+| `parameter_invalid` | 400 | A parameter has an invalid value |
+
+### Order Errors
+
+| Code | Status | Description |
+|------|--------|-------------|
+| `order_not_found` | 404 | Order doesn't exist or doesn't belong to the current user/guest |
+| `order_already_completed` | 422 | Cannot modify an order that has already been completed |
+| `order_cannot_transition` | 422 | Order can't move to the requested state (e.g., advancing without an address) |
+| `order_empty` | 422 | Order has no line items |
+| `order_invalid_state` | 422 | Order is in an invalid state for this operation |
+
+### Line Item & Stock Errors
+
+| Code | Status | Description |
+|------|--------|-------------|
+| `line_item_not_found` | 404 | Line item doesn't exist in this order |
+| `variant_not_found` | 404 | Variant doesn't exist or isn't available |
+| `insufficient_stock` | 422 | Not enough stock to fulfill the requested quantity |
+| `invalid_quantity` | 422 | Quantity must be a positive integer |
+
+### Payment Errors
+
+| Code | Status | Description |
+|------|--------|-------------|
+| `payment_failed` | 422 | Payment was declined or couldn't be processed |
+| `payment_processing_error` | 422 | Error communicating with the payment gateway |
+| `gateway_error` | 422 | Payment gateway returned an error |
+
+### Digital Download Errors
+
+| Code | Status | Description |
+|------|--------|-------------|
+| `attachment_missing` | 403 | File attachment not found for this digital product |
+| `download_unauthorized` | 403 | User is not authorized to download this file |
+| `digital_link_expired` | 403 | Download link has expired |
+| `download_limit_exceeded` | 403 | Maximum number of downloads reached |
+
+### Other Errors
+
+| Code | Status | Description |
+|------|--------|-------------|
+| `rate_limit_exceeded` | 429 | Too many requests. Retry after the `Retry-After` header value. |
+| `request_too_large` | 413 | Request body exceeds the size limit |
+| `processing_error` | 422 | Generic server-side processing error |
+| `invalid_request` | 400 | Request is malformed (e.g., invalid JSON body) |
+
+## Examples
+
+### Not Found
+
+```bash
+curl https://api.mystore.com/api/v3/store/products/prod_nonexistent \
+ -H "Authorization: Bearer spree_pk_xxx"
+```
+
+```json 404
+{
+ "error": {
+ "code": "record_not_found",
+ "message": "Product not found"
+ }
+}
+```
+
+### Validation Error
+
+```bash
+curl -X POST https://api.mystore.com/api/v3/store/account/addresses \
+ -H "Authorization: Bearer <jwt_token>" \
+ -H "Content-Type: application/json" \
+ -d '{}'
+```
+
+```json 422
+{
+ "error": {
+ "code": "validation_error",
+ "message": "First name can't be blank, Address can't be blank, City can't be blank, and Country can't be blank",
+ "details": {
+ "firstname": ["can't be blank"],
+ "address1": ["can't be blank"],
+ "city": ["can't be blank"],
+ "country": ["can't be blank"]
+ }
+ }
+}
+```
+
+### Insufficient Stock
+
+```bash
+curl -X POST https://api.mystore.com/api/v3/store/cart/line_items \
+ -H "Authorization: Bearer spree_pk_xxx" \
+ -H "X-Spree-Order-Token: abc123" \
+ -H "Content-Type: application/json" \
+ -d '{"variant_id": "var_xxx", "quantity": 999}'
+```
+
+```json 422
+{
+ "error": {
+ "code": "insufficient_stock",
+ "message": "Quantity selected exceeds available stock"
+ }
+}
+```
+
+### Invalid State Transition
+
+```bash
+curl -X PATCH https://api.mystore.com/api/v3/store/orders/or_xxx/advance \
+ -H "Authorization: Bearer spree_pk_xxx" \
+ -H "X-Spree-Order-Token: abc123"
+```
+
+```json 422
+{
+ "error": {
+ "code": "order_cannot_transition",
+ "message": "Cannot transition state via :next from :cart"
+ }
+}
+```
+
+## Handling Errors in the SDK
+
+The `@spree/sdk` package throws a `SpreeError` for all non-2xx responses:
+
+```typescript
+import { SpreeError } from '@spree/sdk';
+
+try {
+ const product = await client.store.products.get('nonexistent');
+} catch (error) {
+ if (error instanceof SpreeError) {
+ console.log(error.code); // 'record_not_found'
+ console.log(error.message); // 'Product not found'
+ console.log(error.status); // 404
+ console.log(error.details); // undefined (or field errors for validation)
+ }
+}
+```
+
+### Common Patterns
+
+Handle specific error codes:
+
+```typescript
+try {
+ await client.store.orders.lineItems.create(orderId, {
+ variant_id: variantId,
+ quantity: 1,
+ });
+} catch (error) {
+ if (error instanceof SpreeError) {
+ switch (error.code) {
+ case 'insufficient_stock':
+ showNotification('This item is out of stock');
+ break;
+ case 'variant_not_found':
+ showNotification('This product is no longer available');
+ break;
+ case 'order_already_completed':
+ // Cart was already checked out — create a new one
+ await createNewCart();
+ break;
+ default:
+ showNotification(error.message);
+ }
+ }
+}
+```
+
+Display validation errors per field:
+
+```typescript
+try {
+ await client.store.customer.addresses.create(addressData);
+} catch (error) {
+ if (error instanceof SpreeError && error.details) {
+ // error.details = { city: ["can't be blank"], zipcode: ["is invalid"] }
+ for (const [field, messages] of Object.entries(error.details)) {
+ setFieldError(field, messages.join(', '));
+ }
+ }
+}
+```
diff --git a/docs/api-reference/store-api/introduction.mdx b/docs/api-reference/store-api/introduction.mdx
new file mode 100644
index 0000000000..c76765a7a5
--- /dev/null
+++ b/docs/api-reference/store-api/introduction.mdx
@@ -0,0 +1,34 @@
+---
+title: "Store API"
+sidebarTitle: "Introduction"
+---
+
+This API reference includes Spree Store APIs, which are REST APIs exposed by the Spree application. They are used to create a storefront for your commerce store, such as a website, point of sale or a commerce mobile app.
+
+All API Routes are prefixed with `/api/v3/store`. So, during development, the API Routes will be available under the path `http://localhost:3000/api/v3/store`. For production, replace `http://localhost:3000` with your Spree application URL.
+
+## Using SDK
+
+We recommend using the Spree SDK to interact with the Store API. The SDK provides a convenient way to make API requests and handle responses.
+
+### Installation
+
+```bash
+npm install @spree/sdk
+# or
+yarn add @spree/sdk
+# or
+pnpm add @spree/sdk
+```
+
+### Quick Start
+
+```typescript
+import { createSpreeClient } from '@spree/sdk';
+
+// Initialize the client
+const client = createSpreeClient({
+ baseUrl: 'http://localhost:3000',
+ publishableKey: 'spree_pk_xxx'
+});
+```
diff --git a/docs/api-reference/store-api/localization.mdx b/docs/api-reference/store-api/localization.mdx
new file mode 100644
index 0000000000..ee1e104cc2
--- /dev/null
+++ b/docs/api-reference/store-api/localization.mdx
@@ -0,0 +1,300 @@
+---
+title: "Localization"
+sidebarTitle: "Localization"
+description: "How to set locale, currency, and country for API requests"
+---
+
+The Store API supports multi-language, multi-currency, and market-aware responses. Use request headers to control the locale, currency, and country for each request.
+
+## Headers
+
+| Header | Example | Description |
+|--------|---------|-------------|
+| `X-Spree-Locale` | `fr` | Language for translated content (product names, descriptions, etc.) |
+| `X-Spree-Currency` | `EUR` | Currency for prices and totals |
+| `X-Spree-Country` | `FR` | Country ISO code for market resolution |
+
+## Client-Level Defaults
+
+Set locale, currency, and country once at initialization — all subsequent requests use these defaults:
+
+```typescript SDK
+import { createSpreeClient } from '@spree/sdk'
+
+const client = createSpreeClient({
+ baseUrl: 'https://api.mystore.com',
+ publishableKey: 'spree_pk_xxx',
+ locale: 'fr',
+ currency: 'EUR',
+ country: 'FR',
+})
+
+// All requests use fr/EUR/FR automatically
+const products = await client.store.products.list()
+```
+
+Update defaults at any time:
+
+```typescript
+client.setLocale('de')
+client.setCurrency('EUR')
+client.setCountry('DE')
+```
+
+## Per-Request Overrides
+
+Override client defaults for individual requests:
+
+<CodeGroup>
+
+```typescript SDK
+const products = await client.store.products.list({}, {
+ locale: 'fr',
+ currency: 'EUR',
+ country: 'FR',
+})
+```
+
+```bash cURL
+curl -G 'http://localhost:3000/api/v3/store/products' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx' \
+ -H 'X-Spree-Locale: fr' \
+ -H 'X-Spree-Currency: EUR'
+```
+
+</CodeGroup>
+
+## Country and Markets
+
+The `X-Spree-Country` header resolves the customer's [market](/developer/core-concepts/markets), which influences default locale and currency. Markets allow you to configure different pricing, languages, and product availability per region.
+
+<CodeGroup>
+
+```typescript SDK
+// Setting country automatically resolves the market
+const products = await client.store.products.list({}, {
+ country: 'DE', // Resolves German market → EUR, de locale
+})
+```
+
+```bash cURL
+curl -G 'http://localhost:3000/api/v3/store/products' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx' \
+ -H 'X-Spree-Country: DE'
+```
+
+</CodeGroup>
+
+When a market is resolved from the country:
+1. The market's default locale is used (unless overridden by `X-Spree-Locale`)
+2. The market's default currency is used (unless overridden by `X-Spree-Currency`)
+
+You can also resolve the market explicitly using the [Markets API](/developer/sdk/store/markets):
+
+<CodeGroup>
+
+```typescript SDK
+// Resolve which market applies for a country
+const market = await client.store.markets.resolve('DE')
+// => { id: "mkt_xxx", name: "Europe", currency: "EUR", default_locale: "de", ... }
+
+// Then set the client defaults
+client.setLocale(market.default_locale)
+client.setCurrency(market.currency)
+client.setCountry('DE')
+```
+
+```bash cURL
+# Resolve market by country
+curl 'http://localhost:3000/api/v3/store/markets/resolve?country=DE' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx'
+```
+
+</CodeGroup>
+
+## Resolution Priority
+
+Each value is resolved in the following order:
+
+### Locale
+1. `X-Spree-Locale` header
+2. `locale` query parameter
+3. Market default locale (if country is set)
+4. Store default locale
+
+### Currency
+1. `X-Spree-Currency` header
+2. `currency` query parameter
+3. Market default currency (if country is set)
+4. Store default currency
+
+### Market
+1. `X-Spree-Country` header
+2. `country` query parameter
+
+<Note>
+The locale and currency must be supported by the current store. If an unsupported value is provided, the API falls back to the store's default.
+</Note>
+
+## Translated Content
+
+When a locale is set, all translatable fields are returned in the requested language. This includes product names, descriptions, taxon names, and other content managed through [translations](/developer/core-concepts/translations).
+
+<CodeGroup>
+
+```typescript SDK
+// English (default)
+const enProduct = await client.store.products.get('spree-tote')
+console.log(enProduct.name) // "Spree Tote"
+
+// French
+const frProduct = await client.store.products.get('spree-tote', {}, {
+ locale: 'fr',
+})
+console.log(frProduct.name) // "Sac Spree"
+```
+
+```bash cURL
+# English
+curl 'http://localhost:3000/api/v3/store/products/spree-tote' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx' \
+ -H 'X-Spree-Locale: en'
+
+# French
+curl 'http://localhost:3000/api/v3/store/products/spree-tote' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx' \
+ -H 'X-Spree-Locale: fr'
+```
+
+</CodeGroup>
+
+If a translation doesn't exist for the requested locale, the API falls back to the store's default locale automatically.
+
+## Currency-Aware Prices
+
+All price fields in the response reflect the requested currency:
+
+<CodeGroup>
+
+```typescript SDK
+// USD prices
+const usdProduct = await client.store.products.get('spree-tote', {}, {
+ currency: 'USD',
+})
+console.log(usdProduct.price) // { amount: "15.99", currency: "USD" }
+
+// EUR prices
+const eurProduct = await client.store.products.get('spree-tote', {}, {
+ currency: 'EUR',
+})
+console.log(eurProduct.price) // { amount: "14.49", currency: "EUR" }
+```
+
+```bash cURL
+# USD prices
+curl 'http://localhost:3000/api/v3/store/products/spree-tote' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx' \
+ -H 'X-Spree-Currency: USD'
+
+# EUR prices
+curl 'http://localhost:3000/api/v3/store/products/spree-tote' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx' \
+ -H 'X-Spree-Currency: EUR'
+```
+
+</CodeGroup>
+
+## Discovering Available Options
+
+Use the dedicated endpoints to discover which markets, countries, locales, and currencies are available. These are derived from your store's [markets](/developer/core-concepts/markets) configuration.
+
+### Markets
+
+List all markets to get the full picture of regions, currencies, and supported locales:
+
+<CodeGroup>
+
+```typescript SDK
+const { data: markets } = await client.store.markets.list()
+// [
+// { id: "mkt_xxx", name: "North America", currency: "USD", default_locale: "en",
+// supported_locales: ["en", "es"], countries: [{ iso: "US", ... }, { iso: "CA", ... }] },
+// { id: "mkt_yyy", name: "Europe", currency: "EUR", default_locale: "de",
+// supported_locales: ["de", "en", "fr"], countries: [{ iso: "DE", ... }, { iso: "FR", ... }] },
+// ]
+```
+
+```bash cURL
+curl 'http://localhost:3000/api/v3/store/markets' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx'
+```
+
+</CodeGroup>
+
+### Countries
+
+List all countries or countries within a specific market. Each country includes its market's currency and supported locales:
+
+<CodeGroup>
+
+```typescript SDK
+// All countries across all markets
+const { data: countries } = await client.store.countries.list()
+
+// Countries in a specific market (useful for checkout address forms)
+const { data: marketCountries } = await client.store.markets.countries.list('mkt_xxx')
+
+// Get a single country with states
+const usa = await client.store.countries.get('US', {
+ expand: ['states'],
+})
+console.log(usa.states) // [{ abbr: "CA", name: "California" }, ...]
+```
+
+```bash cURL
+# All countries
+curl 'http://localhost:3000/api/v3/store/countries' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx'
+
+# Countries in a specific market
+curl 'http://localhost:3000/api/v3/store/markets/mkt_xxx/countries' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx'
+
+# Get a country with states
+curl 'http://localhost:3000/api/v3/store/countries/US?expand=states' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx'
+```
+
+</CodeGroup>
+
+### Locales
+
+<CodeGroup>
+
+```typescript SDK
+const { data: locales } = await client.store.locales.list()
+// [{ code: "en", name: "English" }, { code: "fr", name: "French" }, ...]
+```
+
+```bash cURL
+curl 'http://localhost:3000/api/v3/store/locales' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx'
+```
+
+</CodeGroup>
+
+### Currencies
+
+<CodeGroup>
+
+```typescript SDK
+const { data: currencies } = await client.store.currencies.list()
+// [{ iso_code: "USD", name: "US Dollar", symbol: "$" }, { iso_code: "EUR", name: "Euro", symbol: "€" }, ...]
+```
+
+```bash cURL
+curl 'http://localhost:3000/api/v3/store/currencies' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx'
+```
+
+</CodeGroup>
diff --git a/docs/api-reference/store-api/metadata.mdx b/docs/api-reference/store-api/metadata.mdx
new file mode 100644
index 0000000000..4595218ec7
--- /dev/null
+++ b/docs/api-reference/store-api/metadata.mdx
@@ -0,0 +1,172 @@
+---
+title: "Metadata"
+sidebarTitle: "Metadata"
+description: "How to store and retrieve custom metadata on carts, orders, and line items"
+---
+
+The Store API supports storing arbitrary key-value **metadata** on carts (orders) and line items. Metadata is useful for tracking custom information like gift messages, attribution data, or integration-specific fields.
+
+<Note>
+Metadata is different from [metafields](/developer/core-concepts/metafields). Metadata is simple JSON storage (untyped, no schema), while metafields are structured, typed, and schema-defined. Use metadata for integration data and internal tracking. Use metafields for customer-facing custom attributes.
+</Note>
+
+## Cart Metadata
+
+You can attach metadata when creating a cart:
+
+<CodeGroup>
+
+```typescript SDK
+const cart = await client.store.cart.create({
+ metadata: {
+ utm_source: 'google',
+ utm_campaign: 'summer_sale',
+ referral_code: 'FRIEND20',
+ },
+})
+```
+
+```bash cURL
+curl -X POST 'http://localhost:3000/api/v3/store/cart' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "metadata": {
+ "utm_source": "google",
+ "utm_campaign": "summer_sale",
+ "referral_code": "FRIEND20"
+ }
+ }'
+```
+
+</CodeGroup>
+
+## Order Metadata
+
+Update metadata on an existing order:
+
+<CodeGroup>
+
+```typescript SDK
+await client.store.orders.update(cart.id, {
+ metadata: {
+ gift_message: 'Happy Birthday!',
+ preferred_delivery: 'morning',
+ },
+}, { orderToken: cart.token })
+```
+
+```bash cURL
+curl -X PATCH 'http://localhost:3000/api/v3/store/orders/or_xxx' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx' \
+ -H 'X-Spree-Order-Token: <order_token>' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "metadata": {
+ "gift_message": "Happy Birthday!",
+ "preferred_delivery": "morning"
+ }
+ }'
+```
+
+</CodeGroup>
+
+## Line Item Metadata
+
+Attach metadata to individual line items when adding or updating them:
+
+### When Adding an Item
+
+<CodeGroup>
+
+```typescript SDK
+await client.store.orders.lineItems.create(cart.id, {
+ variant_id: 'variant_abc123',
+ quantity: 1,
+ metadata: {
+ personalization: 'John',
+ gift_wrap: true,
+ },
+}, { orderToken: cart.token })
+```
+
+```bash cURL
+curl -X POST 'http://localhost:3000/api/v3/store/orders/or_xxx/line_items' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx' \
+ -H 'X-Spree-Order-Token: <order_token>' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "variant_id": "variant_abc123",
+ "quantity": 1,
+ "metadata": {
+ "personalization": "John",
+ "gift_wrap": true
+ }
+ }'
+```
+
+</CodeGroup>
+
+### When Updating an Item
+
+Updating metadata **merges** with existing values rather than replacing them:
+
+<CodeGroup>
+
+```typescript SDK
+await client.store.orders.lineItems.update(cart.id, 'li_xyz789', {
+ metadata: {
+ personalization: 'Jane', // Updates existing key
+ engraving: 'With Love', // Adds new key
+ },
+}, { orderToken: cart.token })
+```
+
+```bash cURL
+curl -X PATCH 'http://localhost:3000/api/v3/store/orders/or_xxx/line_items/li_xyz789' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx' \
+ -H 'X-Spree-Order-Token: <order_token>' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "metadata": {
+ "personalization": "Jane",
+ "engraving": "With Love"
+ }
+ }'
+```
+
+</CodeGroup>
+
+<Info>
+Metadata values can be any JSON-serializable type: strings, numbers, booleans, arrays, or nested objects.
+</Info>
+
+## Metadata Structure
+
+Metadata is stored as a flat JSON object. You can use any keys and values:
+
+```json
+{
+ "metadata": {
+ "string_value": "hello",
+ "number_value": 42,
+ "boolean_value": true,
+ "nested_object": {
+ "key": "value"
+ }
+ }
+}
+```
+
+## Metadata vs Metafields
+
+| | Metadata | Metafields |
+|-|----------|------------|
+| **Structure** | Untyped JSON | Schema-defined, strongly typed |
+| **Validation** | None | Type-specific validation |
+| **Visibility** | Write-only in Store API | Configurable (public/private) |
+| **Admin UI** | JSON preview | Dedicated form fields |
+| **Best for** | Integration data, tracking, attribution | Product specs, custom fields, customer-facing data |
+| **API access** | Write via Store API, read via Admin API | Read/write via both APIs |
+
+For more details on metafields, see the [Metafields guide](/developer/core-concepts/metafields).
diff --git a/docs/api-reference/store-api/querying.mdx b/docs/api-reference/store-api/querying.mdx
new file mode 100644
index 0000000000..57e9635760
--- /dev/null
+++ b/docs/api-reference/store-api/querying.mdx
@@ -0,0 +1,293 @@
+---
+title: "Querying"
+sidebarTitle: "Querying"
+description: "How to filter, sort, and paginate Store API results using Ransack"
+---
+
+The Store API uses [Ransack](https://activerecord-hackery.github.io/ransack/) for filtering and sorting collection endpoints. All query parameters are passed via the `q` parameter.
+
+## Filtering
+
+Pass filter conditions using the `q` parameter with Ransack predicates:
+
+<CodeGroup>
+
+```typescript SDK
+const products = await client.store.products.list({
+ name_cont: 'shirt',
+ price_gte: 20,
+ price_lte: 100,
+})
+```
+
+```bash cURL
+curl -G 'http://localhost:3000/api/v3/store/products' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx' \
+ --data-urlencode 'q[name_cont]=shirt' \
+ --data-urlencode 'q[price_gte]=20' \
+ --data-urlencode 'q[price_lte]=100'
+```
+
+</CodeGroup>
+
+### Common Predicates
+
+| Predicate | Description | SDK | cURL |
+|-----------|-------------|-----|------|
+| `eq` | Equals | `status_eq: 'active'` | `q[status_eq]=active` |
+| `not_eq` | Not equals | `status_not_eq: 'draft'` | `q[status_not_eq]=draft` |
+| `cont` | Contains (case-insensitive) | `name_cont: 'shirt'` | `q[name_cont]=shirt` |
+| `start` | Starts with | `name_start: 'Spree'` | `q[name_start]=Spree` |
+| `end` | Ends with | `slug_end: 'tote'` | `q[slug_end]=tote` |
+| `lt` | Less than | `price_lt: 50` | `q[price_lt]=50` |
+| `lteq` | Less than or equal | `price_lteq: 50` | `q[price_lteq]=50` |
+| `gt` | Greater than | `price_gt: 10` | `q[price_gt]=10` |
+| `gteq` | Greater than or equal | `price_gteq: 10` | `q[price_gteq]=10` |
+| `in` | In a list | `status_in: ['active', 'draft']` | `q[status_in][]=active&q[status_in][]=draft` |
+| `null` | Is null | `deleted_at_null: true` | `q[deleted_at_null]=true` |
+| `not_null` | Is not null | `completed_at_not_null: true` | `q[completed_at_not_null]=true` |
+| `present` | Is present (not empty) | `description_present: true` | `q[description_present]=true` |
+| `blank` | Is blank (null or empty) | `description_blank: true` | `q[description_blank]=true` |
+| `true` | Is true (boolean) | `purchasable_true: 1` | `q[purchasable_true]=1` |
+| `false` | Is false (boolean) | `purchasable_false: 1` | `q[purchasable_false]=1` |
+
+<Note>
+The SDK automatically wraps filter keys in `q[...]` and appends `[]` for array values — just pass flat params.
+</Note>
+
+### Combining Filters
+
+Multiple filters are combined with AND logic:
+
+<CodeGroup>
+
+```typescript SDK
+// Products that contain "shirt" AND cost between $20-$100
+const products = await client.store.products.list({
+ name_cont: 'shirt',
+ price_gteq: 20,
+ price_lteq: 100,
+})
+```
+
+```bash cURL
+curl -G 'http://localhost:3000/api/v3/store/products' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx' \
+ --data-urlencode 'q[name_cont]=shirt' \
+ --data-urlencode 'q[price_gteq]=20' \
+ --data-urlencode 'q[price_lteq]=100'
+```
+
+</CodeGroup>
+
+### Filtering by Association
+
+You can filter by associated model attributes using underscore notation:
+
+<CodeGroup>
+
+```typescript SDK
+// Products in a specific taxon (category)
+const products = await client.store.products.list({
+ taxons_id_eq: 'txn_abc123',
+})
+
+// Taxons at a specific depth
+const taxons = await client.store.taxons.list({
+ depth_eq: 1,
+})
+```
+
+```bash cURL
+# Products in a specific taxon
+curl -G 'http://localhost:3000/api/v3/store/products' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx' \
+ --data-urlencode 'q[taxons_id_eq]=txn_abc123'
+
+# Top-level taxons only
+curl -G 'http://localhost:3000/api/v3/store/taxons' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx' \
+ --data-urlencode 'q[depth_eq]=1'
+```
+
+</CodeGroup>
+
+## Product Scopes
+
+Products support additional filter scopes beyond standard Ransack predicates:
+
+<CodeGroup>
+
+```typescript SDK
+const products = await client.store.products.list({
+ price_gte: 20, // Minimum price
+ price_lte: 100, // Maximum price
+ with_option_value_ids: ['optval_abc', 'optval_def'], // Filter by option values
+ in_stock: true, // Only in-stock products
+})
+```
+
+```bash cURL
+curl -G 'http://localhost:3000/api/v3/store/products' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx' \
+ --data-urlencode 'q[price_gte]=20' \
+ --data-urlencode 'q[price_lte]=100' \
+ --data-urlencode 'q[with_option_value_ids][]=optval_abc' \
+ --data-urlencode 'q[with_option_value_ids][]=optval_def' \
+ --data-urlencode 'q[in_stock]=true'
+```
+
+</CodeGroup>
+
+| Scope | Description | SDK | cURL |
+|-------|-------------|-----|------|
+| `price_gte` | Minimum price | `price_gte: 20` | `q[price_gte]=20` |
+| `price_lte` | Maximum price | `price_lte: 100` | `q[price_lte]=100` |
+| `with_option_value_ids` | Filter by option value IDs | `with_option_value_ids: ['optval_abc']` | `q[with_option_value_ids][]=optval_abc` |
+| `in_stock` | Only in-stock products | `in_stock: true` | `q[in_stock]=true` |
+| `out_of_stock` | Only out-of-stock products | `out_of_stock: true` | `q[out_of_stock]=true` |
+| `multi_search` | Full-text search | `multi_search: 'shirt'` | `q[multi_search]=shirt` |
+
+## Sorting
+
+Use the `sort` parameter to sort product results. The backend handles routing to the appropriate sort mechanism:
+
+<CodeGroup>
+
+```typescript SDK
+// Sort by price
+const products = await client.store.products.list({
+ sort: 'price asc',
+})
+
+// Sort by best selling
+const products = await client.store.products.list({
+ sort: 'best_selling',
+})
+
+// Sort by name
+const products = await client.store.products.list({
+ sort: 'name asc',
+})
+```
+
+```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' \
+ -d 'sort=price+asc'
+
+# Sort by best selling
+curl -G 'http://localhost:3000/api/v3/store/products' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx' \
+ -d 'sort=best_selling'
+```
+
+</CodeGroup>
+
+### Product Sort Options
+
+| Value | Description |
+|-------|-------------|
+| `manual` | Manual sort order (default, uses taxon position) |
+| `best_selling` | Best selling products first |
+| `price asc` | Price low to high |
+| `price desc` | Price high to low |
+| `name asc` | Name A-Z |
+| `name desc` | Name Z-A |
+| `available_on desc` | Newest first |
+| `available_on asc` | Oldest first |
+
+For other resources, use `q[s]` with standard Ransack column sorts:
+
+<CodeGroup>
+
+```typescript SDK
+const taxons = await client.store.taxons.list({
+ sort: 'name asc',
+})
+```
+
+```bash cURL
+curl -G 'http://localhost:3000/api/v3/store/taxons' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx' \
+ --data-urlencode 'q[s]=name asc'
+```
+
+</CodeGroup>
+
+## Pagination
+
+All collection endpoints return paginated results. Control pagination with `page` and `limit` parameters:
+
+<CodeGroup>
+
+```typescript SDK
+const { data: products, meta } = await client.store.products.list({
+ page: 2,
+ limit: 10,
+})
+
+// meta contains pagination info
+console.log(meta)
+// {
+// page: 2,
+// limit: 10,
+// count: 85,
+// pages: 9,
+// from: 11,
+// to: 20,
+// in: 10,
+// previous: 1,
+// next: 3
+// }
+```
+
+```bash cURL
+curl -G 'http://localhost:3000/api/v3/store/products' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx' \
+ -d 'page=2' \
+ -d 'limit=10'
+```
+
+</CodeGroup>
+
+### Pagination Parameters
+
+| Parameter | Default | Max | Description |
+|-----------|---------|-----|-------------|
+| `page` | `1` | - | Page number |
+| `limit` | `25` | `100` | Number of records per page |
+
+### Pagination Metadata
+
+Collection responses include a `meta` object with pagination info:
+
+```json
+{
+ "data": [...],
+ "meta": {
+ "page": 1,
+ "limit": 25,
+ "count": 85,
+ "pages": 4,
+ "from": 1,
+ "to": 25,
+ "in": 25,
+ "previous": null,
+ "next": 2
+ }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `page` | Current page number |
+| `limit` | Records per page |
+| `count` | Total number of records |
+| `pages` | Total number of pages |
+| `from` | Starting record number on this page |
+| `to` | Ending record number on this page |
+| `in` | Number of records returned on this page |
+| `previous` | Previous page number (null if first page) |
+| `next` | Next page number (null if last page) |
diff --git a/docs/api-reference/store-api/rate-limitting.mdx b/docs/api-reference/store-api/rate-limitting.mdx
new file mode 100644
index 0000000000..f7ecdb97bc
--- /dev/null
+++ b/docs/api-reference/store-api/rate-limitting.mdx
@@ -0,0 +1,82 @@
+---
+title: "Rate Limiting"
+sidebarTitle: "Rate Limiting"
+description: "Rate limits and throttling for the Store API"
+---
+
+The Store API enforces rate limits to protect against abuse and ensure fair usage. Rate limits are applied per API key or per IP address depending on the endpoint.
+
+## Default Limits
+
+| Endpoint | Limit | Scope | Window |
+|----------|-------|-------|--------|
+| All endpoints | 300 requests | Per API key | 1 minute |
+| `POST /auth/login` | 5 requests | Per IP | 1 minute |
+| `POST /auth/register` | 3 requests | Per IP | 1 minute |
+| `POST /auth/refresh` | 10 requests | Per IP | 1 minute |
+| `POST /auth/oauth/callback` | 5 requests | Per IP | 1 minute |
+
+The global rate limit is tracked by your publishable API key (`X-Spree-Api-Key`). If the key is not provided, the limit falls back to the client's IP address.
+
+Authentication endpoints have stricter per-IP limits to prevent brute-force attacks.
+
+## Rate Limit Response
+
+When you exceed the rate limit, the API returns a `429 Too Many Requests` response:
+
+```json
+{
+ "error": {
+ "code": "rate_limit_exceeded",
+ "message": "Too many requests. Please retry later."
+ }
+}
+```
+
+The response includes a `Retry-After` header indicating how many seconds to wait before retrying:
+
+```
+HTTP/1.1 429 Too Many Requests
+Content-Type: application/json
+Retry-After: 60
+```
+
+## SDK Retry Handling
+
+The Spree SDK automatically handles rate-limited responses with built-in retry logic and exponential backoff:
+
+```typescript
+import { createSpreeClient } from '@spree/sdk'
+
+const client = createSpreeClient({
+ baseUrl: 'http://localhost:3000',
+ publishableKey: 'spree_pk_xxx',
+ retry: {
+ maxRetries: 2, // Number of retry attempts (default: 2)
+ baseDelay: 300, // Initial delay in ms (default: 300)
+ maxDelay: 10000, // Maximum delay in ms (default: 10000)
+ },
+})
+```
+
+The SDK respects the `Retry-After` header and only retries on `429` status codes for non-GET requests. For GET/HEAD requests, it also retries on `500`, `502`, `503`, and `504` errors.
+
+## Configuring Rate Limits
+
+If you're self-hosting Spree, you can adjust rate limits in your initializer:
+
+```ruby
+# config/initializers/spree.rb
+Spree::Api::Config[:rate_limit_per_key] = 300 # Global limit per API key
+Spree::Api::Config[:rate_limit_login] = 5 # Login attempts per IP
+Spree::Api::Config[:rate_limit_register] = 3 # Registration attempts per IP
+Spree::Api::Config[:rate_limit_refresh] = 10 # Token refresh per IP
+Spree::Api::Config[:rate_limit_oauth] = 5 # OAuth callbacks per IP
+```
+
+Rate limiting uses `Rails.cache` as the backing store. For production environments with multiple application servers, ensure you're using a shared cache store like Redis:
+
+```ruby
+# config/environments/production.rb
+config.cache_store = :redis_cache_store, { url: ENV['REDIS_URL'] }
+```
diff --git a/docs/api-reference/store-api/relations.mdx b/docs/api-reference/store-api/relations.mdx
new file mode 100644
index 0000000000..e776e2a636
--- /dev/null
+++ b/docs/api-reference/store-api/relations.mdx
@@ -0,0 +1,206 @@
+---
+title: "Relations"
+sidebarTitle: "Relations"
+description: "How to include related resources in API responses"
+---
+
+By default, the Store API returns only the primary resource attributes to keep responses fast and lightweight. Use the `expand` parameter to expand related resources inline.
+
+## Including Relations
+
+Pass a comma-separated list of relation names via the `expand` query parameter:
+
+<CodeGroup>
+
+```typescript SDK
+// Product with variants and images
+const product = await client.store.products.get('spree-tote', {
+ expand: ['variants', 'images'],
+})
+
+// Access included relations directly
+console.log(product.variants) // Array of variant objects
+console.log(product.images) // Array of image 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'
+```
+
+</CodeGroup>
+
+## Response Format
+
+Without `expand`, relation fields are omitted from the response:
+
+```json
+{
+ "id": "prod_86Rf07xd4z",
+ "name": "Spree Tote",
+ "slug": "spree-tote",
+ "price": { "amount": "15.99", "currency": "USD" },
+ "created_at": "2025-01-15T10:30:00Z"
+}
+```
+
+With `?expand=variants,images`, the related resources are embedded:
+
+```json
+{
+ "id": "prod_86Rf07xd4z",
+ "name": "Spree Tote",
+ "slug": "spree-tote",
+ "price": { "amount": "15.99", "currency": "USD" },
+ "created_at": "2025-01-15T10:30:00Z",
+ "variants": [
+ {
+ "id": "variant_k5nR8xLq",
+ "sku": "SPR-TOTE-RED",
+ "price": { "amount": "15.99", "currency": "USD" },
+ "in_stock": true,
+ "option_values": [{ "name": "Red", "option_type_name": "Color" }]
+ }
+ ],
+ "images": [
+ {
+ "id": "img_9xPq2wLm",
+ "url": "https://cdn.example.com/spree-tote.jpg",
+ "alt": "Spree Tote"
+ }
+ ]
+}
+```
+
+## Available Relations by Resource
+
+### Products
+
+| Relation | Description |
+|----------|-------------|
+| `variants` | All purchasable variants |
+| `default_variant` | The default variant |
+| `master_variant` | The master variant |
+| `images` | All product images (across all variants) |
+| `option_types` | Option types (e.g., Size, Color) |
+| `taxons` | Categories this product belongs to |
+| `metafields` | Public metafields (custom structured data) |
+
+<CodeGroup>
+
+```typescript SDK
+const product = await client.store.products.get('spree-tote', {
+ expand: ['variants', 'images', 'option_types', 'metafields'],
+})
+```
+
+```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'
+```
+
+</CodeGroup>
+
+### Taxons (Categories)
+
+| Relation | Description |
+|----------|-------------|
+| `ancestors` | Parent taxons (for breadcrumbs) |
+| `children` | Direct child taxons |
+| `products` | Products in this taxon |
+
+<CodeGroup>
+
+```typescript SDK
+const taxon = await client.store.taxons.get('categories/clothing', {
+ expand: ['ancestors', 'children'],
+})
+```
+
+```bash cURL
+curl -G 'http://localhost:3000/api/v3/store/taxons/categories/clothing' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx' \
+ -d 'expand=ancestors,children'
+```
+
+</CodeGroup>
+
+### Taxonomies
+
+| Relation | Description |
+|----------|-------------|
+| `root` | Root taxon |
+| `taxons` | All taxons in this taxonomy |
+
+### Countries
+
+| Relation | Description |
+|----------|-------------|
+| `states` | States/provinces within the country |
+
+<CodeGroup>
+
+```typescript SDK
+const usa = await client.store.countries.get('US', {
+ expand: ['states'],
+})
+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' \
+ -d 'expand=states'
+```
+
+</CodeGroup>
+
+## Collections with Includes
+
+The `expand` parameter also works on collection endpoints:
+
+<CodeGroup>
+
+```typescript SDK
+// List products with their images and default variant
+const { data: products } = await client.store.products.list({
+ expand: ['images', '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' \
+ -d 'limit=12'
+```
+
+</CodeGroup>
+
+## Nested Includes
+
+Use dot notation to include nested relations:
+
+<CodeGroup>
+
+```typescript SDK
+// Include variants and their nested option values
+const product = await client.store.products.get('spree-tote', {
+ expand: ['variants.option_values'],
+})
+```
+
+```bash cURL
+curl -G 'http://localhost:3000/api/v3/store/products/spree-tote' \
+ -H 'X-Spree-Api-Key: spree_pk_xxx' \
+ -d 'expand=variants.option_values'
+```
+
+</CodeGroup>
+
+<Note>
+Only include relations you actually need. Each included relation requires additional database queries, so requesting unnecessary relations will slow down the response.
+</Note>
diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yaml
index ef301d37b6..94fb6fbded 100644
--- a/docs/api-reference/store.yaml
+++ b/docs/api-reference/store.yaml
@@ -79,7 +79,7 @@ paths:
required: false
schema:
type: integer
- - name: per_page
+ - name: limit
in: query
required: false
schema:
@@ -647,14 +647,14 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImY4ZTYzODZhLTVmNDQtNGE5Ny05NTE0LWY0YWY1M2JiMDhhMSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzcyNTUyMTc5fQ.a_ZmK6jt5FG-j322Yp8eYXvCsnT4zt6X8ldAqBsg0OI
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjBhNWQ2NzA4LTJjYTEtNDU3Yy1hYmJiLTI1YzEwYTYyYjZmNyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzcyNjQzOTQ5fQ.12mHdQdXE8xePvpizjJewo80HUBKVBLSYW3CoallQuY
user:
id: cus_UkLWZg9DAJ
- first_name: Glynis
- last_name: Mertz
- created_at: '2026-03-03T14:36:19.567Z'
- updated_at: '2026-03-03T14:36:19.567Z'
+ first_name: Jetta
+ last_name: Parker
+ created_at: '2026-03-04T16:05:49.531Z'
+ updated_at: '2026-03-04T16:05:49.531Z'
addresses: []
default_billing_address:
default_shipping_address:
@@ -727,14 +727,14 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImM5ZGQxZTYxLTdmMGYtNDVjMy1iYTVjLWU2NzgyMjVlNWI4NSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzcyNTUyMTgxfQ.TElCXlhcJPmmACUe24d1eOll2RR8hlhiZDSDo5MJ17s
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImFiNWYxOTYyLTgzNjktNDUyOS1hNjM5LTEwMjQ1OGMxNGYyYiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzcyNjQzOTUwfQ.kwBAKkFi6VkYFa1NOo81zKKg1gdTBk7L0OqipFhh2d4
user:
id: cus_UkLWZg9DAJ
first_name: John
last_name: Doe
- created_at: '2026-03-03T14:36:21.239Z'
- updated_at: '2026-03-03T14:36:21.239Z'
+ created_at: '2026-03-04T16:05:50.950Z'
+ updated_at: '2026-03-04T16:05:50.950Z'
addresses: []
default_billing_address:
default_shipping_address:
@@ -820,14 +820,14 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImVhNjAyODc2LTljYmUtNDVjZi1hZWJmLTAwYjU3MDdkNGFlOSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzcyNTUyMTgxfQ.UIvyFyy5V_7xNW0ijHoUQtpCi39SH-n12YcBlCyztDs
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjhiY2NjYWYxLTU5YzEtNGNjZC05N2E3LWU5ODliNzUwNmMyZSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzcyNjQzOTUxfQ.wMHxEAVnGRJzGeDM0RtlLz7SezkmcHekvAs1J00pIRw
user:
id: cus_UkLWZg9DAJ
- first_name: Vinnie
- last_name: Gutkowski
- created_at: '2026-03-03T14:36:21.924Z'
- updated_at: '2026-03-03T14:36:21.924Z'
+ first_name: Santina
+ last_name: O'Connell
+ created_at: '2026-03-04T16:05:51.515Z'
+ updated_at: '2026-03-04T16:05:51.515Z'
addresses: []
default_billing_address:
default_shipping_address:
@@ -884,9 +884,9 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R388833213
+ number: R537185861
state: cart
- token: Ut5XjgEW3W4UF6V4qtmmAg1772548582712
+ token: haMda0BfgDa7SXWeDETgrA1772640352152
email:
special_instructions:
currency: USD
@@ -912,8 +912,8 @@ paths:
total: '0.0'
display_total: "$0.00"
completed_at:
- created_at: '2026-03-03T14:36:22.714Z'
- updated_at: '2026-03-03T14:36:22.714Z'
+ created_at: '2026-03-04T16:05:52.154Z'
+ updated_at: '2026-03-04T16:05:52.154Z'
order_promotions: []
line_items: []
shipments: []
@@ -998,10 +998,10 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R756913174
+ number: R165404082
state: cart
- token: LEHQu2xd7Yb7WAX5o1MaBNJ4YLSc2cN38GZ
+ token: JQZnWGn9SRkinUtsD1N4pzjo9o8Z5juBEe2
special_instructions:
currency: USD
locale: en
@@ -1026,16 +1026,16 @@ paths:
total: '110.0'
display_total: "$110.00"
completed_at:
- created_at: '2026-03-03T14:36:24.037Z'
- updated_at: '2026-03-03T14:36:24.142Z'
+ created_at: '2026-03-04T16:05:53.193Z'
+ updated_at: '2026-03-04T16:05:53.270Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 27732
- slug: product-27732
+ name: Product 26048
+ slug: product-26048
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1054,23 +1054,23 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-03T14:36:24.105Z'
- updated_at: '2026-03-03T14:36:24.105Z'
+ created_at: '2026-03-04T16:05:53.240Z'
+ updated_at: '2026-03-04T16:05:53.240Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_UkLWZg9DAJ
- number: H16003361634
+ number: H79589869682
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-03T14:36:24.114Z'
- updated_at: '2026-03-03T14:36:24.140Z'
+ created_at: '2026-03-04T16:05:53.248Z'
+ updated_at: '2026-03-04T16:05:53.267Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
@@ -1078,7 +1078,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_41
- name: Clifford Homenick
+ name: Susannah Kshlerin
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -1202,10 +1202,10 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R417114298
+ number: R326810844
state: cart
- token: G5XsUhL9iEwZgYVHHtmCuv4cPtWzZQmARHq
+ token: eShAvrVAXcy5yQY7fjaejUknUNqvNDkBQWy
special_instructions:
currency: USD
locale: en
@@ -1230,16 +1230,16 @@ paths:
total: '110.0'
display_total: "$110.00"
completed_at:
- created_at: '2026-03-03T14:36:24.206Z'
- updated_at: '2026-03-03T14:36:24.266Z'
+ created_at: '2026-03-04T16:05:53.386Z'
+ updated_at: '2026-03-04T16:05:53.454Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 39759
- slug: product-39759
+ name: Product 32098
+ slug: product-32098
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1258,23 +1258,23 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-03T14:36:24.240Z'
- updated_at: '2026-03-03T14:36:24.240Z'
+ created_at: '2026-03-04T16:05:53.425Z'
+ updated_at: '2026-03-04T16:05:53.425Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_UkLWZg9DAJ
- number: H92357513743
+ number: H85534823095
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-03T14:36:24.248Z'
- updated_at: '2026-03-03T14:36:24.263Z'
+ created_at: '2026-03-04T16:05:53.433Z'
+ updated_at: '2026-03-04T16:05:53.451Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
@@ -1282,7 +1282,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_45
- name: Ila Fritsch
+ name: Yuki Walker
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -1365,7 +1365,7 @@ paths:
- Internationalization
security:
- api_key: []
- description: Returns countries available in the store. Use ?include=market to
+ description: Returns countries available in the store. Use ?expand=market to
include market details (currency, locale, tax_inclusive).
x-codeSamples:
- lang: javascript
@@ -1428,8 +1428,8 @@ paths:
- Internationalization
security:
- api_key: []
- description: Returns a single country by ISO code. Supports ?include=states
- for address forms and ?include=market for market details.
+ description: Returns a single country by ISO code. Supports ?expand=states for
+ address forms and ?expand=market for market details.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -1550,10 +1550,10 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R812063541
+ number: R872970211
state: cart
- token: 3gr9TyRkm9MfS58wDQmM8pcmvCbq6SJhz23
+ token: 7Jsku92AUZam9fGjYdYr9GH3Xh84V6ZuGfk
special_instructions:
currency: USD
locale: en
@@ -1578,16 +1578,16 @@ paths:
total: '110.0'
display_total: "$110.00"
completed_at:
- created_at: '2026-03-03T14:36:28.572Z'
- updated_at: '2026-03-03T14:36:28.695Z'
+ created_at: '2026-03-04T16:05:57.723Z'
+ updated_at: '2026-03-04T16:05:57.886Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 86465
- slug: product-86465
+ name: Product 81455
+ slug: product-81455
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1606,23 +1606,23 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-03T14:36:28.612Z'
- updated_at: '2026-03-03T14:36:28.612Z'
+ created_at: '2026-03-04T16:05:57.772Z'
+ updated_at: '2026-03-04T16:05:57.772Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_UkLWZg9DAJ
- number: H32364746957
+ number: H71363339490
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-03T14:36:28.620Z'
- updated_at: '2026-03-03T14:36:28.637Z'
+ created_at: '2026-03-04T16:05:57.779Z'
+ updated_at: '2026-03-04T16:05:57.794Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
@@ -1630,7 +1630,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_65
- name: Hong Klein
+ name: Martha Schowalter
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -1652,12 +1652,12 @@ paths:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
state: checkout
- response_code: 1-SC-20260303143628685903
- number: PPNI3TAB
+ response_code: 1-SC-20260304160557873706
+ number: PTK3N0RM
amount: '50.0'
display_amount: "$50.00"
- created_at: '2026-03-03T14:36:28.689Z'
- updated_at: '2026-03-03T14:36:28.689Z'
+ created_at: '2026-03-04T16:05:57.879Z'
+ updated_at: '2026-03-04T16:05:57.879Z'
source_type: store_credit
source_id: credit_UkLWZg9DAJ
source:
@@ -1809,10 +1809,10 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R633362137
+ number: R180943434
state: cart
- token: RM5F8WM2cT6Jhs4u7UTgdaVSpD5U8VU6NQw
+ token: 6s3yQjG9ef2Q7Zk8whPFCaVFSRYm1YkNvNz
special_instructions:
currency: USD
locale: en
@@ -1837,16 +1837,16 @@ paths:
total: '110.0'
display_total: "$110.00"
completed_at:
- created_at: '2026-03-03T14:36:30.517Z'
- updated_at: '2026-03-03T14:36:30.647Z'
+ created_at: '2026-03-04T16:05:59.715Z'
+ updated_at: '2026-03-04T16:05:59.853Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 119571
- slug: product-119571
+ name: Product 118921
+ slug: product-118921
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1865,23 +1865,23 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-03T14:36:30.549Z'
- updated_at: '2026-03-03T14:36:30.641Z'
+ created_at: '2026-03-04T16:05:59.760Z'
+ updated_at: '2026-03-04T16:05:59.848Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_UkLWZg9DAJ
- number: H30697862313
+ number: H00165700846
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-03T14:36:30.554Z'
- updated_at: '2026-03-03T14:36:30.569Z'
+ created_at: '2026-03-04T16:05:59.767Z'
+ updated_at: '2026-03-04T16:05:59.785Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
@@ -1889,7 +1889,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_77
- name: Gus Schultz
+ name: Klara Goldner
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -1994,7 +1994,7 @@ paths:
required: false
schema:
type: integer
- - name: per_page
+ - name: limit
in: query
required: false
schema:
@@ -2239,7 +2239,7 @@ paths:
const orders = await client.store.customer.orders.list({
page: 1,
- per_page: 25,
+ limit: 25,
}, {
bearerToken: '<token>',
})
@@ -2259,7 +2259,7 @@ paths:
required: false
schema:
type: integer
- - name: per_page
+ - name: limit
in: query
required: false
schema:
@@ -2284,10 +2284,10 @@ paths:
example:
data:
- id: or_UkLWZg9DAJ
- number: R615968848
+ number: R768402886
state: cart
- token: Ljp44Aws6xyPd14bUtYHFVapV6rKyERGxcG
+ token: pXv2yid4pmiqFhnRjSY4dGJpyb9cdTjzm4z
special_instructions:
currency: USD
locale: en
@@ -2312,16 +2312,16 @@ paths:
total: '110.0'
display_total: "$110.00"
completed_at:
- created_at: '2026-03-03T14:36:35.419Z'
- updated_at: '2026-03-03T14:36:35.482Z'
+ created_at: '2026-03-04T16:06:04.911Z'
+ updated_at: '2026-03-04T16:06:04.985Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 139330
- slug: product-139330
+ name: Product 13627
+ slug: product-13627
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -2340,23 +2340,23 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-03T14:36:35.456Z'
- updated_at: '2026-03-03T14:36:35.456Z'
+ created_at: '2026-03-04T16:06:04.947Z'
+ updated_at: '2026-03-04T16:06:04.947Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_UkLWZg9DAJ
- number: H23975587975
+ number: H96823411548
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-03T14:36:35.463Z'
- updated_at: '2026-03-03T14:36:35.479Z'
+ created_at: '2026-03-04T16:06:04.953Z'
+ updated_at: '2026-03-04T16:06:04.982Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
@@ -2364,7 +2364,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_100
- name: Quyen Kirlin
+ name: Zona Willms
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -2489,11 +2489,11 @@ paths:
application/json:
example:
id: cus_UkLWZg9DAJ
- first_name: Deidra
- last_name: Emmerich
- created_at: '2026-03-03T14:36:36.403Z'
- updated_at: '2026-03-03T14:36:36.677Z'
+ first_name: Britta
+ last_name: Lakin
+ created_at: '2026-03-04T16:06:06.600Z'
+ updated_at: '2026-03-04T16:06:06.877Z'
addresses:
- id: addr_gbHJdmfrXB
firstname: John
@@ -2616,11 +2616,11 @@ paths:
application/json:
example:
id: cus_UkLWZg9DAJ
first_name: Updated
last_name: Name
- created_at: '2026-03-03T14:36:36.973Z'
- updated_at: '2026-03-03T14:36:37.258Z'
+ created_at: '2026-03-04T16:06:07.178Z'
+ updated_at: '2026-03-04T16:06:07.468Z'
addresses:
- id: addr_gbHJdmfrXB
firstname: John
@@ -2820,7 +2820,7 @@ paths:
required: false
schema:
type: integer
- - name: per_page
+ - name: limit
in: query
required: false
schema:
@@ -2833,7 +2833,7 @@ paths:
example:
data:
- id: gc_UkLWZg9DAJ
- code: C54F714F654EC511
+ code: F64199AD3D97830A
state: active
currency: USD
amount: 10.0
@@ -2847,8 +2847,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-03-03T14:36:40.475Z'
- updated_at: '2026-03-03T14:36:40.475Z'
+ created_at: '2026-03-04T16:06:10.592Z'
+ updated_at: '2026-03-04T16:06:10.592Z'
meta:
page: 1
limit: 25
@@ -2924,7 +2924,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: 56B5EC95494A442C
+ code: 2393ACE132103C6B
state: active
currency: USD
amount: 10.0
@@ -2938,8 +2938,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-03-03T14:36:41.618Z'
- updated_at: '2026-03-03T14:36:41.618Z'
+ created_at: '2026-03-04T16:06:11.691Z'
+ updated_at: '2026-03-04T16:06:11.691Z'
schema:
"$ref": "#/components/schemas/StoreGiftCard"
'404':
@@ -3010,10 +3010,10 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R469844415
+ number: R236214024
state: cart
- token: 6vp6Kx594qeM1mRkQWQU49Y28yUKEgKr7eJ
+ token: dVLmiSbkNXDQ7CbK7fiNAUXUZXYY1axpmSd
special_instructions:
currency: USD
locale: en
@@ -3038,16 +3038,16 @@ paths:
total: '29.99'
display_total: "$29.99"
completed_at:
- created_at: '2026-03-03T14:36:43.634Z'
- updated_at: '2026-03-03T14:36:43.908Z'
+ created_at: '2026-03-04T16:06:13.432Z'
+ updated_at: '2026-03-04T16:06:13.519Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 231068
- slug: product-231068
+ name: Product 234204
+ slug: product-234204
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3066,8 +3066,8 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-03T14:36:43.703Z'
- updated_at: '2026-03-03T14:36:43.703Z'
+ created_at: '2026-03-04T16:06:13.458Z'
+ updated_at: '2026-03-04T16:06:13.458Z'
compare_at_amount:
thumbnail_url:
option_values: []
@@ -3076,8 +3076,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 1
currency: USD
- name: Product 242577
- slug: product-242577
+ name: Product 246835
+ slug: product-246835
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -3096,8 +3096,8 @@ paths:
discounted_amount: '19.99'
display_discounted_amount: "$19.99"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-03T14:36:43.807Z'
- updated_at: '2026-03-03T14:36:43.807Z'
+ created_at: '2026-03-04T16:06:13.496Z'
+ updated_at: '2026-03-04T16:06:13.496Z'
compare_at_amount:
thumbnail_url:
option_values: []
@@ -3217,10 +3217,10 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R066084861
+ number: R591932780
state: cart
- token: MuJAUaYSBFBrJw4AsJrec5H8wCMzg1n7kJf
+ token: cgNGkxDW1eKu9BCLu6ZXCiVwup3EYcRvb7A
special_instructions:
currency: USD
locale: en
@@ -3245,16 +3245,16 @@ paths:
total: '0.0'
display_total: "$0.00"
completed_at:
- created_at: '2026-03-03T14:36:46.347Z'
- updated_at: '2026-03-03T14:36:46.381Z'
+ created_at: '2026-03-04T16:06:15.902Z'
+ updated_at: '2026-03-04T16:06:15.953Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 288811
- slug: product-288811
+ name: Product 28811
+ slug: product-28811
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3273,8 +3273,8 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-03T14:36:46.381Z'
- updated_at: '2026-03-03T14:36:46.400Z'
+ created_at: '2026-03-04T16:06:15.952Z'
+ updated_at: '2026-03-04T16:06:15.989Z'
compare_at_amount:
thumbnail_url:
option_values: []
@@ -3373,10 +3373,10 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R819351012
+ number: R963371608
state: cart
- token: b5oa7rbcx8bEakg1LUwVWnVNhFyM7mniTdS
+ token: r9j9D6tSYoK7ZZrWKBKaXiZXrwynehZ8Kzu
special_instructions:
currency: USD
locale: en
@@ -3401,8 +3401,8 @@ paths:
total: '0.0'
display_total: "$0.00"
completed_at:
- created_at: '2026-03-03T14:36:47.005Z'
- updated_at: '2026-03-03T14:36:47.063Z'
+ created_at: '2026-03-04T16:06:16.552Z'
+ updated_at: '2026-03-04T16:06:16.643Z'
order_promotions: []
line_items: []
shipments: []
@@ -3791,7 +3791,7 @@ paths:
security:
- api_key: []
description: Returns a single country by ISO code within a market. Supports
- ?include=states for address forms.
+ ?expand=states for address forms.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -3866,7 +3866,7 @@ paths:
})
const order = await client.store.orders.get('or_abc123', {
- includes: 'line_items,shipments',
+ expand: 'line_items,shipments',
}, {
bearerToken: '<token>',
})
@@ -3893,10 +3893,10 @@ paths:
description: Order token for guest access
schema:
type: string
- - name: includes
+ - name: expand
in: query
required: false
- description: Include associations (line_items, shipments, payments)
+ description: Expand associations (line_items, shipments, payments)
schema:
type: string
responses:
@@ -3906,9 +3906,9 @@ paths:
application/json:
example:
id: or_gbHJdmfrXB
- number: R164163296
+ number: R675029144
state: cart
- token: YyTe1ueyRd4Frh8Jc4cd1bBcRZGMrqdKP3G
+ token: sZpAzNLV4AfoukPA1oNZicJiGdfksoVSVX3
email:
special_instructions:
currency: USD
@@ -3934,16 +3934,16 @@ paths:
total: '110.0'
display_total: "$110.00"
completed_at:
- created_at: '2026-03-03T14:36:49.496Z'
- updated_at: '2026-03-03T14:36:49.546Z'
+ created_at: '2026-03-04T16:06:18.972Z'
+ updated_at: '2026-03-04T16:06:19.035Z'
order_promotions: []
line_items:
- id: li_gbHJdmfrXB
variant_id: variant_gbHJdmfrXB
quantity: 1
currency: USD
- name: Product 334792
- slug: product-334792
+ name: Product 339056
+ slug: product-339056
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3962,23 +3962,23 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-03T14:36:49.528Z'
- updated_at: '2026-03-03T14:36:49.528Z'
+ created_at: '2026-03-04T16:06:19.002Z'
+ updated_at: '2026-03-04T16:06:19.002Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_gbHJdmfrXB
- number: H99507458771
+ number: H23180965194
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-03T14:36:49.535Z'
- updated_at: '2026-03-03T14:36:49.544Z'
+ created_at: '2026-03-04T16:06:19.017Z'
+ updated_at: '2026-03-04T16:06:19.032Z'
shipping_method:
id: shpm_gbHJdmfrXB
name: UPS Ground
@@ -3986,7 +3986,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_159
- name: Noel Botsford
+ name: Hilario Walter
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -4114,10 +4114,10 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R933097036
+ number: R281749931
state: cart
- token: 64aT8KqKH88BiDg6TkzKKKynDZQhib2Qxjd
+ token: 64hDRyHxmaojaiz2VuzoMdbm1w59JDMXLhb
special_instructions:
currency: USD
locale: en
@@ -4142,16 +4142,16 @@ paths:
total: '110.0'
display_total: "$110.00"
completed_at:
- created_at: '2026-03-03T14:36:52.283Z'
- updated_at: '2026-03-03T14:36:52.357Z'
+ created_at: '2026-03-04T16:06:21.877Z'
+ updated_at: '2026-03-04T16:06:21.954Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 379604
- slug: product-379604
+ name: Product 374001
+ slug: product-374001
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4170,23 +4170,23 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-03T14:36:52.317Z'
- updated_at: '2026-03-03T14:36:52.317Z'
+ created_at: '2026-03-04T16:06:21.908Z'
+ updated_at: '2026-03-04T16:06:21.908Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_UkLWZg9DAJ
- number: H26887045117
+ number: H40586075137
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-03T14:36:52.323Z'
- updated_at: '2026-03-03T14:36:52.338Z'
+ created_at: '2026-03-04T16:06:21.914Z'
+ updated_at: '2026-03-04T16:06:21.929Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
@@ -4194,7 +4194,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_178
- name: Genia Nicolas
+ name: Hellen Romaguera
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -4398,10 +4398,10 @@ paths:
application/json:
example:
id: or_gbHJdmfrXB
- number: R646770035
+ number: R543208889
state: address
- token: 5MBMCcV5XYHif9ajxtZaXyBNboHgCbsUib4
+ token: XE5g44nDo5bFe2QkaXQeBWtGur8C7sgkPmL
special_instructions:
currency: USD
locale: en
@@ -4426,16 +4426,16 @@ paths:
total: '110.0'
display_total: "$110.00"
completed_at:
- created_at: '2026-03-03T14:36:53.786Z'
- updated_at: '2026-03-03T14:36:53.855Z'
+ created_at: '2026-03-04T16:06:23.363Z'
+ updated_at: '2026-03-04T16:06:23.476Z'
order_promotions: []
line_items:
- id: li_gbHJdmfrXB
variant_id: variant_gbHJdmfrXB
quantity: 1
currency: USD
- name: Product 416930
- slug: product-416930
+ name: Product 413573
+ slug: product-413573
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4454,23 +4454,23 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-03T14:36:53.818Z'
- updated_at: '2026-03-03T14:36:53.818Z'
+ created_at: '2026-03-04T16:06:23.415Z'
+ updated_at: '2026-03-04T16:06:23.415Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_gbHJdmfrXB
- number: H12255208923
+ number: H41354476269
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-03T14:36:53.826Z'
- updated_at: '2026-03-03T14:36:53.836Z'
+ created_at: '2026-03-04T16:06:23.427Z'
+ updated_at: '2026-03-04T16:06:23.443Z'
shipping_method:
id: shpm_gbHJdmfrXB
name: UPS Ground
@@ -4478,7 +4478,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_188
- name: Josefa Altenwerth
+ name: Fernande Zboncak
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -4596,10 +4596,10 @@ paths:
application/json:
example:
id: or_gbHJdmfrXB
- number: R501083114
+ number: R803000634
state: payment
- token: K5ZQoEsDiH1xPxkbTqknTDsJuy8kFW62n79
+ token: HmNxrximDn5YNDS9Ddh6zdJKUfN9VCBqGGc
special_instructions:
currency: USD
locale: en
@@ -4624,16 +4624,16 @@ paths:
total: '29.99'
display_total: "$29.99"
completed_at:
- created_at: '2026-03-03T14:36:55.111Z'
- updated_at: '2026-03-03T14:36:55.276Z'
+ created_at: '2026-03-04T16:06:24.750Z'
+ updated_at: '2026-03-04T16:06:24.929Z'
order_promotions: []
line_items:
- id: li_gbHJdmfrXB
variant_id: variant_gbHJdmfrXB
quantity: 1
currency: USD
- name: Product 441474
- slug: product-441474
+ name: Product 447878
+ slug: product-447878
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -4652,23 +4652,23 @@ paths:
discounted_amount: '19.99'
display_discounted_amount: "$19.99"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-03T14:36:55.140Z'
- updated_at: '2026-03-03T14:36:55.211Z'
+ created_at: '2026-03-04T16:06:24.776Z'
+ updated_at: '2026-03-04T16:06:24.846Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_EfhxLZ9ck8
- number: H46859328738
+ number: H00828533318
state: pending
tracking:
tracking_url:
cost: '10.0'
display_cost: "$10.00"
shipped_at:
- created_at: '2026-03-03T14:36:55.234Z'
- updated_at: '2026-03-03T14:36:55.248Z'
+ created_at: '2026-03-04T16:06:24.879Z'
+ updated_at: '2026-03-04T16:06:24.899Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
@@ -4676,7 +4676,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_198
- name: Ruben Heller
+ name: Dani Mosciski
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -4793,10 +4793,10 @@ paths:
application/json:
example:
id: or_gbHJdmfrXB
- number: R966169097
+ number: R016735353
state: complete
- token: AH3gCKZb1hUfG7PzdupzRu3vZRgSZHNt726
+ token: UMttPPpGmi9UXVgeveX6WL2PgXW7QYpK4Rc
special_instructions:
currency: USD
locale: en
@@ -4820,17 +4820,17 @@ paths:
display_additional_tax_total: "$0.00"
total: '29.99'
display_total: "$29.99"
- completed_at: '2026-03-03T14:36:56.086Z'
- created_at: '2026-03-03T14:36:55.900Z'
- updated_at: '2026-03-03T14:36:56.086Z'
+ completed_at: '2026-03-04T16:06:25.849Z'
+ created_at: '2026-03-04T16:06:25.584Z'
+ updated_at: '2026-03-04T16:06:25.849Z'
order_promotions: []
line_items:
- id: li_gbHJdmfrXB
variant_id: variant_gbHJdmfrXB
quantity: 1
currency: USD
- name: Product 461631
- slug: product-461631
+ name: Product 468734
+ slug: product-468734
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -4849,23 +4849,23 @@ paths:
discounted_amount: '19.99'
display_discounted_amount: "$19.99"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-03T14:36:55.927Z'
- updated_at: '2026-03-03T14:36:55.979Z'
+ created_at: '2026-03-04T16:06:25.628Z'
+ updated_at: '2026-03-04T16:06:25.708Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_EfhxLZ9ck8
- number: H98553619556
+ number: H00074416971
state: pending
tracking:
tracking_url:
cost: '10.0'
display_cost: "$10.00"
shipped_at:
- created_at: '2026-03-03T14:36:55.995Z'
- updated_at: '2026-03-03T14:36:56.077Z'
+ created_at: '2026-03-04T16:06:25.728Z'
+ updated_at: '2026-03-04T16:06:25.839Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
@@ -4873,7 +4873,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_204
- name: Elroy Hahn
+ name: Zenaida Marquardt
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -4906,11 +4906,11 @@ paths:
payment_method_id: pm_UkLWZg9DAJ
state: checkout
response_code: '12345'
- number: PCGVL7QE
+ number: PR8IC4H0
amount: '29.99'
display_amount: "$29.99"
- created_at: '2026-03-03T14:36:56.051Z'
- updated_at: '2026-03-03T14:36:56.051Z'
+ created_at: '2026-03-04T16:06:25.810Z'
+ updated_at: '2026-03-04T16:06:25.810Z'
source_type: credit_card
source_id: card_UkLWZg9DAJ
source:
@@ -5136,13 +5136,13 @@ paths:
id: ps_gbHJdmfrXB
status: pending
currency: USD
- external_id: bogus_f7bcbdfbf6d05267ca34c41b
+ external_id: bogus_0313fa605fe6659f4fb7100e
external_data:
- client_secret: bogus_secret_1a22ed5651b2fa0f
+ client_secret: bogus_secret_fcd390c64b32debe
customer_external_id:
expires_at:
- created_at: '2026-03-03T14:36:58.568Z'
- updated_at: '2026-03-03T14:36:58.568Z'
+ created_at: '2026-03-04T16:06:28.416Z'
+ updated_at: '2026-03-04T16:06:28.416Z'
amount: '110.0'
payment_method_id: pm_UkLWZg9DAJ
order_id: or_UkLWZg9DAJ
@@ -5247,13 +5247,13 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_7f8a012ea8c8ed3c164a8a5f
+ external_id: bogus_9b4729ae9b94ad71756b5abd
external_data:
client_secret: secret_123
customer_external_id:
expires_at:
- created_at: '2026-03-03T14:36:59.864Z'
- updated_at: '2026-03-03T14:36:59.864Z'
+ created_at: '2026-03-04T16:06:29.687Z'
+ updated_at: '2026-03-04T16:06:29.687Z'
amount: '110.0'
payment_method_id: pm_UkLWZg9DAJ
order_id: or_UkLWZg9DAJ
@@ -5310,13 +5310,13 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_553ea2882ac2fe7f2944046e
+ external_id: bogus_5755a3569c891bc7a824fa91
external_data:
client_secret: secret_123
customer_external_id:
expires_at:
- created_at: '2026-03-03T14:37:01.126Z'
- updated_at: '2026-03-03T14:37:01.141Z'
+ created_at: '2026-03-04T16:06:31.103Z'
+ updated_at: '2026-03-04T16:06:31.119Z'
amount: '50.0'
payment_method_id: pm_UkLWZg9DAJ
order_id: or_UkLWZg9DAJ
@@ -5407,13 +5407,13 @@ paths:
id: ps_UkLWZg9DAJ
status: completed
currency: USD
- external_id: bogus_abf9e5071172f4d00972d817
+ external_id: bogus_fb50876d2a636ae2f27665d8
external_data:
client_secret: secret_123
customer_external_id:
expires_at:
- created_at: '2026-03-03T14:37:01.749Z'
- updated_at: '2026-03-03T14:37:01.762Z'
+ created_at: '2026-03-04T16:06:31.783Z'
+ updated_at: '2026-03-04T16:06:31.796Z'
amount: '110.0'
payment_method_id: pm_UkLWZg9DAJ
order_id: or_UkLWZg9DAJ
@@ -5493,11 +5493,11 @@ paths:
example:
id: pss_gbHJdmfrXB
status: pending
- external_id: bogus_seti_451f28fde80b33e0f58d6814
- external_client_secret: bogus_seti_secret_c0ce547d31c07256
+ external_id: bogus_seti_10930820bcce9bcd95334cce
+ external_client_secret: bogus_seti_secret_b28ec543d83ce6c2
external_data: {}
- created_at: '2026-03-03T14:37:02.943Z'
- updated_at: '2026-03-03T14:37:02.943Z'
+ created_at: '2026-03-04T16:06:33.021Z'
+ updated_at: '2026-03-04T16:06:33.021Z'
payment_method_id: pm_UkLWZg9DAJ
payment_source_id:
payment_source_type:
@@ -5594,12 +5594,12 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: pending
- external_id: seti_test_1259abec239154721b3940fe
- external_client_secret: seti_secret_38b5d8c198c8128a7a756ab6
+ external_id: seti_test_1ae842feabdce64ba3a67783
+ external_client_secret: seti_secret_aea0a64b2251d5ccd564686c
external_data:
client_secret: secret_123
- created_at: '2026-03-03T14:37:04.589Z'
- updated_at: '2026-03-03T14:37:04.589Z'
+ created_at: '2026-03-04T16:06:34.851Z'
+ updated_at: '2026-03-04T16:06:34.851Z'
payment_method_id: pm_UkLWZg9DAJ
payment_source_id:
payment_source_type:
@@ -5672,12 +5672,12 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: completed
- external_id: seti_test_27bab4b8df8e72a86da0aa50
- external_client_secret: seti_secret_83563a432ee3924b8e52882f
+ external_id: seti_test_3dc952bb9f474c1bfe6e9669
+ external_client_secret: seti_secret_fb574aaf0a37cf0464034886
external_data:
client_secret: secret_123
- created_at: '2026-03-03T14:37:05.700Z'
- updated_at: '2026-03-03T14:37:05.714Z'
+ created_at: '2026-03-04T16:06:36.023Z'
+ updated_at: '2026-03-04T16:06:36.057Z'
payment_method_id: pm_UkLWZg9DAJ
payment_source_id: card_UkLWZg9DAJ
payment_source_type: Spree::CreditCard
@@ -5760,11 +5760,11 @@ paths:
payment_method_id: pm_UkLWZg9DAJ
state: checkout
response_code: '12345'
- number: PZICLFEG
+ number: PU73KHUY
amount: '110.0'
display_amount: "$110.00"
- created_at: '2026-03-03T14:37:06.892Z'
- updated_at: '2026-03-03T14:37:06.892Z'
+ created_at: '2026-03-04T16:06:37.321Z'
+ updated_at: '2026-03-04T16:06:37.321Z'
source_type: credit_card
source_id: card_UkLWZg9DAJ
source:
@@ -5858,11 +5858,11 @@ paths:
payment_method_id: pm_UkLWZg9DAJ
state: checkout
response_code: '12345'
- number: P7D4WAWM
+ number: PQAVAP10
amount: '110.0'
display_amount: "$110.00"
- created_at: '2026-03-03T14:37:08.154Z'
- updated_at: '2026-03-03T14:37:08.154Z'
+ created_at: '2026-03-04T16:06:38.639Z'
+ updated_at: '2026-03-04T16:06:38.639Z'
source_type: credit_card
source_id: card_UkLWZg9DAJ
source:
@@ -5913,13 +5913,13 @@ paths:
const products = await client.store.products.list({
page: 1,
- per_page: 25,
+ limit: 25,
sort: 'price asc',
name_cont: 'shirt',
price_gte: 20,
price_lte: 100,
with_option_value_ids: ['optval_abc', 'optval_def'],
- includes: ['variants', 'images'],
+ expand: ['variants', 'images'],
})
parameters:
- name: x-spree-api-key
@@ -5934,7 +5934,7 @@ paths:
description: 'Page number (default: 1)'
schema:
type: integer
- - name: per_page
+ - name: limit
in: query
required: false
description: 'Number of items per page (default: 25, max: 100)'
@@ -5984,10 +5984,10 @@ paths:
description: Filter to only in-stock products
schema:
type: boolean
- - name: includes
+ - name: expand
in: query
required: false
- description: Comma-separated associations to include (variants, images, taxons,
+ description: Comma-separated associations to expand (variants, images, taxons,
option_types)
schema:
type: string
@@ -5999,18 +5999,16 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 639396
- description: Aliquid libero quo eveniet illo. Cum ab tempore aperiam
- aspernatur soluta esse nostrum. Omnis animi ex dignissimos odio
- quo reiciendis totam. Accusamus quasi officiis esse ipsam sit
- delectus distinctio.
- slug: product-639396
+ name: Product 631333
+ description: Sed vero dignissimos minus ipsa. Nobis voluptate laborum
+ vero quia non. Vero aperiam odio pariatur delectus reiciendis.
+ slug: product-631333
meta_description:
meta_keywords:
variant_count: 1
- available_on: '2025-03-03T14:37:08.829Z'
- created_at: '2026-03-03T14:37:08.848Z'
- updated_at: '2026-03-03T14:37:08.893Z'
+ available_on: '2025-03-04T16:06:39.379Z'
+ created_at: '2026-03-04T16:06:39.398Z'
+ updated_at: '2026-03-04T16:06:39.448Z'
purchasable: true
in_stock: false
backorderable: true
@@ -6030,18 +6028,17 @@ paths:
price_list_id:
original_price:
- id: prod_gbHJdmfrXB
- name: Product 649006
+ name: Product 647402
description: |-
- Cumque aliquam optio voluptatibus similique expedita fugiat. Laboriosam nihil fugit iusto dolores. Aperiam eos harum porro perspiciatis commodi tempore. Excepturi repellat porro distinctio dignissimos reprehenderit. Nostrum facere nemo quo praesentium at aperiam autem possimus.
- Repudiandae consequatur nulla veniam quo possimus nam esse. Quidem facere rerum quod laudantium ipsa qui quaerat soluta. Sapiente veritatis culpa sint deserunt molestiae minus.
- Vitae nostrum asperiores assumenda pariatur eius beatae facilis sit. Eveniet similique beatae minima illum distinctio. Sint aspernatur quasi quaerat magni pariatur fugit optio ratione. Illum facilis voluptatum esse cumque repellat reprehenderit ab aliquid. Non at blanditiis iusto modi.
- slug: product-649006
+ Repudiandae accusantium nobis alias sit officia neque. A iure culpa dignissimos expedita maxime nam corrupti aspernatur. Tempora quo est soluta amet alias quasi ratione pariatur. Explicabo aut velit quo itaque magnam modi exercitationem. Dolorem neque facere vero fugit repellat.
+ Accusantium enim veritatis vel fugit repudiandae veniam sequi. Eligendi magnam neque vitae doloremque corrupti. Molestiae beatae corrupti quis ipsam.
+ slug: product-647402
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-03-03T14:37:08.899Z'
- created_at: '2026-03-03T14:37:08.910Z'
- updated_at: '2026-03-03T14:37:08.923Z'
+ available_on: '2025-03-04T16:06:39.454Z'
+ created_at: '2026-03-04T16:06:39.464Z'
+ updated_at: '2026-03-04T16:06:39.477Z'
purchasable: true
in_stock: false
backorderable: true
@@ -6112,7 +6109,7 @@ paths:
})
const product = await client.store.products.get('spree-tote', {
- includes: ['variants', 'images'],
+ expand: ['variants', 'images'],
})
parameters:
- name: x-spree-api-key
@@ -6127,10 +6124,10 @@ paths:
description: Product slug (e.g., spree-tote) or prefix ID (e.g., product_abc123)
schema:
type: string
- - name: includes
+ - name: expand
in: query
required: false
- description: Comma-separated associations to include
+ description: Comma-separated associations to expand
schema:
type: string
responses:
@@ -6140,17 +6137,17 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 755722
- description: Commodi assumenda dolores saepe animi beatae impedit
- ea quod. Consectetur expedita repellat rem officiis. Iusto corporis
- delectus quo dolorum mollitia porro.
- slug: product-755722
+ name: Product 755700
+ description: Odio consectetur quo maxime perferendis soluta. Sit ex
+ dolores nostrum perspiciatis quisquam dolore dolorum. Rerum distinctio
+ veniam maiores blanditiis porro voluptates inventore.
+ slug: product-755700
meta_description:
meta_keywords:
variant_count: 1
- available_on: '2025-03-03T14:37:09.795Z'
- created_at: '2026-03-03T14:37:09.810Z'
- updated_at: '2026-03-03T14:37:09.851Z'
+ available_on: '2025-03-04T16:06:40.415Z'
+ created_at: '2026-03-04T16:06:40.435Z'
+ updated_at: '2026-03-04T16:06:40.483Z'
purchasable: true
in_stock: false
backorderable: true
@@ -6367,15 +6364,15 @@ paths:
example:
data:
- id: ship_UkLWZg9DAJ
- number: H51580232101
+ number: H68559881109
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-03T14:37:12.300Z'
- updated_at: '2026-03-03T14:37:12.315Z'
+ created_at: '2026-03-04T16:06:43.172Z'
+ updated_at: '2026-03-04T16:06:43.188Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
@@ -6383,7 +6380,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_290
- name: Lidia Stehr
+ name: Zada Hammes
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -6467,10 +6464,10 @@ paths:
description: Order token for guest access
schema:
type: string
- - name: includes
+ - name: expand
in: query
required: false
- description: Include shipping_rates
+ description: Expand shipping_rates
schema:
type: string
responses:
@@ -6480,15 +6477,15 @@ paths:
application/json:
example:
id: ship_UkLWZg9DAJ
- number: H28785597517
+ number: H48157892507
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-03T14:37:13.555Z'
- updated_at: '2026-03-03T14:37:13.577Z'
+ created_at: '2026-03-04T16:06:44.438Z'
+ updated_at: '2026-03-04T16:06:44.456Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
@@ -6496,7 +6493,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_298
- name: June Kilback
+ name: Leeanne O'Hara
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -6585,10 +6582,10 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R313947968
+ number: R478020368
state: delivery
- token: mb7qBP9Hdwt5xyesbymYspjoj9knrd3tiFJ
+ token: mzkALXVF5mEQ6PuNLNS1UnMN6F6ncFh4cMb
special_instructions:
currency: USD
locale: en
@@ -6613,16 +6610,16 @@ paths:
total: '110.0'
display_total: "$110.00"
completed_at:
- created_at: '2026-03-03T14:37:14.792Z'
- updated_at: '2026-03-03T14:37:14.894Z'
+ created_at: '2026-03-04T16:06:45.679Z'
+ updated_at: '2026-03-04T16:06:45.756Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 107458
- slug: product-107458
+ name: Product 1079998
+ slug: product-1079998
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -6641,23 +6638,23 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-03T14:37:14.828Z'
- updated_at: '2026-03-03T14:37:14.828Z'
+ created_at: '2026-03-04T16:06:45.714Z'
+ updated_at: '2026-03-04T16:06:45.714Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_UkLWZg9DAJ
- number: H06023482160
+ number: H05992913620
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-03T14:37:14.834Z'
- updated_at: '2026-03-03T14:37:14.893Z'
+ created_at: '2026-03-04T16:06:45.719Z'
+ updated_at: '2026-03-04T16:06:45.755Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
@@ -6665,7 +6662,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_306
- name: Shana Nienow
+ name: Diedra Pacocha
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -6794,10 +6791,10 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R652057980
+ number: R596378261
state: cart
- token: B5WvvHUBubCjv173HxVWKWGLDbsCHgsX6Se
+ token: wiD2RBhoBgsQJZdoSR2qwo8ZzSYAskshGQX
special_instructions:
currency: USD
locale: en
@@ -6822,16 +6819,16 @@ paths:
total: '110.0'
display_total: "$110.00"
completed_at:
- created_at: '2026-03-03T14:37:16.126Z'
- updated_at: '2026-03-03T14:37:16.209Z'
+ created_at: '2026-03-04T16:06:47.025Z'
+ updated_at: '2026-03-04T16:06:47.088Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1095167
- slug: product-1095167
+ name: Product 1092396
+ slug: product-1092396
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -6850,23 +6847,23 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-03T14:37:16.181Z'
- updated_at: '2026-03-03T14:37:16.181Z'
+ created_at: '2026-03-04T16:06:47.064Z'
+ updated_at: '2026-03-04T16:06:47.064Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_UkLWZg9DAJ
- number: H63878554400
+ number: H65443447345
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-03T14:37:16.188Z'
- updated_at: '2026-03-03T14:37:16.206Z'
+ created_at: '2026-03-04T16:06:47.070Z'
+ updated_at: '2026-03-04T16:06:47.085Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
@@ -6874,7 +6871,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_314
- name: Dorian Hamill
+ name: Lisha Lebsack
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -6896,12 +6893,12 @@ paths:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
state: checkout
- response_code: 1-SC-20260303143716525721
- number: PV1C3VZZ
+ response_code: 1-SC-20260304160647410770
+ number: P0U66OPH
amount: '10.0'
display_amount: "$10.00"
- created_at: '2026-03-03T14:37:16.530Z'
- updated_at: '2026-03-03T14:37:16.530Z'
+ created_at: '2026-03-04T16:06:47.414Z'
+ updated_at: '2026-03-04T16:06:47.414Z'
source_type: store_credit
source_id: credit_UkLWZg9DAJ
source:
@@ -7031,10 +7028,10 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R939878041
+ number: R408021519
state: cart
- token: xdRs9KuA4RSbPbejsCJ8GLzM626BVM5RzZZ
+ token: TxGqrzcd6FMgoJznLVA5JZydXAepGV2SsvK
special_instructions:
currency: USD
locale: en
@@ -7059,16 +7056,16 @@ paths:
total: '110.0'
display_total: "$110.00"
completed_at:
- created_at: '2026-03-03T14:37:17.733Z'
- updated_at: '2026-03-03T14:37:17.779Z'
+ created_at: '2026-03-04T16:06:48.641Z'
+ updated_at: '2026-03-04T16:06:48.697Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1119946
- slug: product-1119946
+ name: Product 1116951
+ slug: product-1116951
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -7087,23 +7084,23 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-03T14:37:17.760Z'
- updated_at: '2026-03-03T14:37:17.760Z'
+ created_at: '2026-03-04T16:06:48.676Z'
+ updated_at: '2026-03-04T16:06:48.676Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_UkLWZg9DAJ
- number: H79108104976
+ number: H12520242433
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-03T14:37:17.765Z'
- updated_at: '2026-03-03T14:37:17.777Z'
+ created_at: '2026-03-04T16:06:48.681Z'
+ updated_at: '2026-03-04T16:06:48.694Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
@@ -7111,7 +7108,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_322
- name: Gearldine Prohaska
+ name: Svetlana Lindgren
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -7210,8 +7207,8 @@ paths:
twitter: spreecommerce
instagram: spreecommerce
customer_support_email: [email protected]
- created_at: '2026-03-03T14:36:12.047Z'
- updated_at: '2026-03-03T14:36:12.145Z'
+ created_at: '2026-03-04T16:05:42.263Z'
+ updated_at: '2026-03-04T16:05:42.363Z'
favicon_image_url:
logo_image_url:
social_image_url:
@@ -7250,7 +7247,7 @@ paths:
const taxonomies = await client.store.taxonomies.list({
page: 1,
- per_page: 25,
+ limit: 25,
})
parameters:
- name: x-spree-api-key
@@ -7263,15 +7260,15 @@ paths:
required: false
schema:
type: integer
- - name: per_page
+ - name: limit
in: query
required: false
schema:
type: integer
- - name: includes
+ - name: expand
in: query
required: false
- description: Include root taxon
+ description: Expand root taxon
schema:
type: string
responses:
@@ -7284,32 +7281,32 @@ paths:
- id: txnmy_UkLWZg9DAJ
name: Categories
position: 1
- created_at: '2026-03-03T14:36:12.056Z'
- updated_at: '2026-03-03T14:36:12.076Z'
+ created_at: '2026-03-04T16:05:42.274Z'
+ updated_at: '2026-03-04T16:05:42.294Z'
root_id: txn_UkLWZg9DAJ
- id: txnmy_gbHJdmfrXB
name: Brands
position: 2
- created_at: '2026-03-03T14:36:12.077Z'
- updated_at: '2026-03-03T14:36:12.087Z'
+ created_at: '2026-03-04T16:05:42.295Z'
+ updated_at: '2026-03-04T16:05:42.304Z'
root_id: txn_gbHJdmfrXB
- id: txnmy_EfhxLZ9ck8
name: Collections
position: 3
- created_at: '2026-03-03T14:36:12.088Z'
- updated_at: '2026-03-03T14:36:12.148Z'
+ created_at: '2026-03-04T16:05:42.305Z'
+ updated_at: '2026-03-04T16:05:42.365Z'
root_id: txn_EfhxLZ9ck8
- id: txnmy_VqXmZF31wY
name: taxonomy_11
position: 4
- created_at: '2026-03-03T14:37:17.868Z'
- updated_at: '2026-03-03T14:37:17.876Z'
+ created_at: '2026-03-04T16:06:48.786Z'
+ updated_at: '2026-03-04T16:06:48.797Z'
root_id: txn_OIJLhNcSbf
- id: txnmy_uw2YK1rnl0
name: taxonomy_12
position: 5
- created_at: '2026-03-03T14:37:17.877Z'
- updated_at: '2026-03-03T14:37:17.884Z'
+ created_at: '2026-03-04T16:06:48.798Z'
+ updated_at: '2026-03-04T16:06:48.807Z'
root_id: txn_AXs1igzRC6
meta:
page: 1
@@ -7360,7 +7357,7 @@ paths:
})
const taxonomy = await client.store.taxonomies.get('taxonomy_abc123', {
- includes: 'taxons',
+ expand: 'taxons',
})
parameters:
- name: x-spree-api-key
@@ -7374,10 +7371,10 @@ paths:
description: Taxonomy ID (prefixed)
schema:
type: string
- - name: includes
+ - name: expand
in: query
required: false
- description: Include taxons
+ description: Expand taxons
schema:
type: string
responses:
@@ -7389,8 +7386,8 @@ paths:
id: txnmy_VqXmZF31wY
name: taxonomy_17
position: 4
- created_at: '2026-03-03T14:37:18.117Z'
- updated_at: '2026-03-03T14:37:18.127Z'
+ created_at: '2026-03-04T16:06:49.077Z'
+ updated_at: '2026-03-04T16:06:49.087Z'
root_id: txn_OIJLhNcSbf
schema:
"$ref": "#/components/schemas/StoreTaxonomy"
@@ -7426,7 +7423,7 @@ paths:
const taxons = await client.store.taxons.list({
page: 1,
- per_page: 25,
+ limit: 25,
})
parameters:
- name: x-spree-api-key
@@ -7439,7 +7436,7 @@ paths:
required: false
schema:
type: integer
- - name: per_page
+ - name: limit
in: query
required: false
schema:
@@ -7466,8 +7463,8 @@ paths:
meta_description:
meta_keywords:
children_count: 0
- created_at: '2026-03-03T14:36:12.067Z'
- updated_at: '2026-03-03T14:36:12.075Z'
+ created_at: '2026-03-04T16:05:42.284Z'
+ updated_at: '2026-03-04T16:05:42.292Z'
parent_id:
taxonomy_id: txnmy_UkLWZg9DAJ
description: ''
@@ -7486,8 +7483,8 @@ paths:
meta_description:
meta_keywords:
children_count: 0
- created_at: '2026-03-03T14:36:12.081Z'
- updated_at: '2026-03-03T14:36:12.086Z'
+ created_at: '2026-03-04T16:05:42.298Z'
+ updated_at: '2026-03-04T16:05:42.303Z'
parent_id:
taxonomy_id: txnmy_gbHJdmfrXB
description: ''
@@ -7506,8 +7503,8 @@ paths:
meta_description:
meta_keywords:
children_count: 2
- created_at: '2026-03-03T14:36:12.091Z'
- updated_at: '2026-03-03T14:36:12.148Z'
+ created_at: '2026-03-04T16:05:42.308Z'
+ updated_at: '2026-03-04T16:05:42.365Z'
parent_id:
taxonomy_id: txnmy_EfhxLZ9ck8
description: ''
@@ -7526,8 +7523,8 @@ paths:
meta_description:
meta_keywords:
children_count: 0
- created_at: '2026-03-03T14:36:12.103Z'
- updated_at: '2026-03-03T14:36:12.105Z'
+ created_at: '2026-03-04T16:05:42.321Z'
+ updated_at: '2026-03-04T16:05:42.323Z'
parent_id: txn_EfhxLZ9ck8
taxonomy_id: txnmy_EfhxLZ9ck8
description: ''
@@ -7546,8 +7543,8 @@ paths:
meta_description:
meta_keywords:
children_count: 0
- created_at: '2026-03-03T14:36:12.116Z'
- updated_at: '2026-03-03T14:36:12.117Z'
+ created_at: '2026-03-04T16:05:42.333Z'
+ updated_at: '2026-03-04T16:05:42.335Z'
parent_id: txn_EfhxLZ9ck8
taxonomy_id: txnmy_EfhxLZ9ck8
description: ''
@@ -7566,8 +7563,8 @@ paths:
meta_description:
meta_keywords:
children_count: 1
- created_at: '2026-03-03T14:37:18.524Z'
- updated_at: '2026-03-03T14:37:18.580Z'
+ created_at: '2026-03-04T16:06:49.543Z'
+ updated_at: '2026-03-04T16:06:49.587Z'
parent_id:
taxonomy_id: txnmy_VqXmZF31wY
description: ''
@@ -7586,8 +7583,8 @@ paths:
meta_description:
meta_keywords:
children_count: 1
- created_at: '2026-03-03T14:37:18.533Z'
- updated_at: '2026-03-03T14:37:18.580Z'
+ created_at: '2026-03-04T16:06:49.551Z'
+ updated_at: '2026-03-04T16:06:49.587Z'
parent_id: txn_OIJLhNcSbf
taxonomy_id: txnmy_VqXmZF31wY
description: ''
@@ -7606,8 +7603,8 @@ paths:
meta_description:
meta_keywords:
children_count: 0
- created_at: '2026-03-03T14:37:18.543Z'
- updated_at: '2026-03-03T14:37:18.550Z'
+ created_at: '2026-03-04T16:06:49.559Z'
+ updated_at: '2026-03-04T16:06:49.565Z'
parent_id: txn_AXs1igzRC6
taxonomy_id: txnmy_VqXmZF31wY
description: ''
@@ -7666,7 +7663,7 @@ paths:
})
const taxon = await client.store.taxons.get('categories/clothing/shirts', {
- includes: 'children,products',
+ expand: 'children,products',
})
parameters:
- name: x-spree-api-key
@@ -7681,10 +7678,10 @@ paths:
ID (e.g., taxon_abc123)
schema:
type: string
- - name: includes
+ - name: expand
in: query
required: false
- description: Include associations (children, products, parent)
+ description: Expand associations (children, products, parent)
schema:
type: string
responses:
@@ -7702,8 +7699,8 @@ paths:
meta_description:
meta_keywords:
children_count: 1
- created_at: '2026-03-03T14:37:19.303Z'
- updated_at: '2026-03-03T14:37:19.343Z'
+ created_at: '2026-03-04T16:06:50.234Z'
+ updated_at: '2026-03-04T16:06:50.306Z'
parent_id: txn_OIJLhNcSbf
taxonomy_id: txnmy_VqXmZF31wY
description: ''
@@ -7757,7 +7754,7 @@ paths:
const products = await client.store.taxons.products.list('categories/clothing', {
page: 1,
- per_page: 25,
+ limit: 25,
sort: 'price asc',
with_option_value_ids: ['optval_abc'],
})
@@ -7779,7 +7776,7 @@ paths:
description: 'Page number (default: 1)'
schema:
type: integer
- - name: per_page
+ - name: limit
in: query
required: false
description: 'Number of items per page (default: 25, max: 100)'
@@ -7824,19 +7821,19 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 1191051
+ name: Product 119267
description: |-
- Odio voluptates omnis aliquam recusandae. Eius magni vitae aspernatur quam itaque aliquam. Vitae ut expedita vel magnam. Ducimus architecto voluptatem nihil explicabo. Omnis laborum suscipit numquam velit vero.
- Eaque fugit debitis facilis repellendus eos. Deserunt porro laborum hic saepe numquam ab. Officiis eos repudiandae dolore numquam dolores. Nisi pariatur ipsam adipisci unde. Quis nulla molestiae est voluptate totam officia nobis iure.
- Modi neque occaecati accusantium a soluta facere in. Aut beatae deserunt tenetur dolor. Dolorum aliquid tenetur minima praesentium libero eligendi unde. Perferendis velit facilis voluptate totam cum. Ad assumenda recusandae tempore eligendi aut corporis quos.
- A quisquam sit quo minus quibusdam. Unde temporibus similique fugiat praesentium. Earum in voluptatibus eum tempora mollitia sapiente.
- slug: product-1191051
+ Et perspiciatis magnam doloremque rerum beatae placeat. Sapiente alias recusandae similique laudantium explicabo. Cumque iure harum unde a consectetur atque impedit. Repudiandae facere ea architecto perferendis similique nam.
+ Illo nam pariatur rem magni nostrum dolorem. Ad neque optio quod eos hic incidunt. Sit dolor sed laboriosam odio inventore illo optio ipsa. Nihil quibusdam officia dicta tempora hic aspernatur reiciendis.
+ Facere repudiandae nostrum nesciunt ad. Sunt temporibus labore facere quia ab ad hic optio. Fuga voluptates recusandae doloribus dignissimos. Numquam sequi aperiam non animi quaerat cum. Nam saepe mollitia blanditiis deleniti.
+ Assumenda soluta dolore voluptatum tenetur. Recusandae cupiditate dignissimos optio error. Necessitatibus molestias maiores neque dolores doloremque eaque unde fugit.
+ slug: product-119267
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-03-03T14:37:20.099Z'
- created_at: '2026-03-03T14:37:20.119Z'
- updated_at: '2026-03-03T14:37:20.132Z'
+ available_on: '2025-03-04T16:06:51.160Z'
+ created_at: '2026-03-04T16:06:51.177Z'
+ updated_at: '2026-03-04T16:06:51.195Z'
purchasable: true
in_stock: false
backorderable: true
@@ -7933,7 +7930,7 @@ paths:
required: false
schema:
type: integer
- - name: per_page
+ - name: limit
in: query
required: false
schema:
@@ -7947,9 +7944,9 @@ paths:
data:
- id: wl_UkLWZg9DAJ
name: My Wishlist
- token: TfRJrMjL6UeQcEMR3c8kRnF1
- created_at: '2026-03-03T14:37:21.211Z'
- updated_at: '2026-03-03T14:37:21.211Z'
+ token: fSB8UBBUsifLQeeuKZNu3hRv
+ created_at: '2026-03-04T16:06:52.563Z'
+ updated_at: '2026-03-04T16:06:52.563Z'
is_default: false
is_private: true
meta:
@@ -8025,9 +8022,9 @@ paths:
example:
id: wl_gbHJdmfrXB
name: Birthday Ideas
- token: 1g193KAXPVqWhcnMkUz4aHMZ
- created_at: '2026-03-03T14:37:22.438Z'
- updated_at: '2026-03-03T14:37:22.438Z'
+ token: xMetULp51ccxziLwrcH69BPz
+ created_at: '2026-03-04T16:06:53.781Z'
+ updated_at: '2026-03-04T16:06:53.781Z'
is_default: false
is_private: true
schema:
@@ -8082,7 +8079,7 @@ paths:
})
const wishlist = await client.store.wishlists.get('wl_abc123', {
- includes: 'wished_items',
+ expand: 'wished_items',
}, {
bearerToken: '<token>',
})
@@ -8102,10 +8099,10 @@ paths:
required: true
schema:
type: string
- - name: includes
+ - name: expand
in: query
required: false
- description: Include wished_items
+ description: Expand wished_items
schema:
type: string
responses:
@@ -8116,9 +8113,9 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: My Wishlist
- token: VRLRAR5fumcVgGSG58hrfzWg
- created_at: '2026-03-03T14:37:23.588Z'
- updated_at: '2026-03-03T14:37:23.588Z'
+ token: 4cXrsogbdXfXaxJxU1HnnmWh
+ created_at: '2026-03-04T16:06:54.889Z'
+ updated_at: '2026-03-04T16:06:54.889Z'
is_default: false
is_private: true
schema:
@@ -8180,9 +8177,9 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: Updated Name
- token: SkL6MBvWVoDLCzsVDqKyfuU1
- created_at: '2026-03-03T14:37:24.819Z'
- updated_at: '2026-03-03T14:37:24.873Z'
+ token: TwEoczgtRRjNA6Gmqa6QKRsT
+ created_at: '2026-03-04T16:06:56.062Z'
+ updated_at: '2026-03-04T16:06:56.102Z'
is_default: false
is_private: true
schema:
@@ -8294,8 +8291,8 @@ paths:
variant_id: variant_gbHJdmfrXB
wishlist_id: wl_UkLWZg9DAJ
quantity: 1
- created_at: '2026-03-03T14:37:26.098Z'
- updated_at: '2026-03-03T14:37:26.098Z'
+ created_at: '2026-03-04T16:06:57.305Z'
+ updated_at: '2026-03-04T16:06:57.305Z'
variant:
id: variant_gbHJdmfrXB
product_id: prod_gbHJdmfrXB
@@ -8304,8 +8301,8 @@ paths:
options_text: ''
track_inventory: true
image_count: 0
- created_at: '2026-03-03T14:37:26.068Z'
- updated_at: '2026-03-03T14:37:26.081Z'
+ created_at: '2026-03-04T16:06:57.278Z'
+ updated_at: '2026-03-04T16:06:57.289Z'
thumbnail:
purchasable: true
in_stock: false
diff --git a/docs/api-reference/storefront/account-address/create-an-address.mdx b/docs/api-reference/storefront/account-address/create-an-address.mdx
deleted file mode 100644
index 45078b90ee..0000000000
--- a/docs/api-reference/storefront/account-address/create-an-address.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/storefront/account/addresses
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/account-address/list-all-addresses.mdx b/docs/api-reference/storefront/account-address/list-all-addresses.mdx
deleted file mode 100644
index 9e07fd3448..0000000000
--- a/docs/api-reference/storefront/account-address/list-all-addresses.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/account/addresses
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/account-address/remove-an-address.mdx b/docs/api-reference/storefront/account-address/remove-an-address.mdx
deleted file mode 100644
index 2f8e54f184..0000000000
--- a/docs/api-reference/storefront/account-address/remove-an-address.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/storefront/account/addresses/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/account-address/update-an-address.mdx b/docs/api-reference/storefront/account-address/update-an-address.mdx
deleted file mode 100644
index 2fa44de96e..0000000000
--- a/docs/api-reference/storefront/account-address/update-an-address.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/storefront/account/addresses/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/account-credit-cards/list-all-credit-cards.mdx b/docs/api-reference/storefront/account-credit-cards/list-all-credit-cards.mdx
deleted file mode 100644
index cc7ce5b39f..0000000000
--- a/docs/api-reference/storefront/account-credit-cards/list-all-credit-cards.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/account/credit_cards
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/account-credit-cards/remove-a-credit-card.mdx b/docs/api-reference/storefront/account-credit-cards/remove-a-credit-card.mdx
deleted file mode 100644
index 63e55d196f..0000000000
--- a/docs/api-reference/storefront/account-credit-cards/remove-a-credit-card.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/storefront/account/credit_cards/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/account-credit-cards/retrieve-the-default-credit-card.mdx b/docs/api-reference/storefront/account-credit-cards/retrieve-the-default-credit-card.mdx
deleted file mode 100644
index bda6dde380..0000000000
--- a/docs/api-reference/storefront/account-credit-cards/retrieve-the-default-credit-card.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/account/credit_cards/default
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/account-orders/list-all-orders.mdx b/docs/api-reference/storefront/account-orders/list-all-orders.mdx
deleted file mode 100644
index eaca22061a..0000000000
--- a/docs/api-reference/storefront/account-orders/list-all-orders.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/account/orders
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/account-orders/retrieve-an-order.mdx b/docs/api-reference/storefront/account-orders/retrieve-an-order.mdx
deleted file mode 100644
index 5a88b815d3..0000000000
--- a/docs/api-reference/storefront/account-orders/retrieve-an-order.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/account/orders/{order_number}
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/account/create-an-account.mdx b/docs/api-reference/storefront/account/create-an-account.mdx
deleted file mode 100644
index 352ce21ea4..0000000000
--- a/docs/api-reference/storefront/account/create-an-account.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/storefront/account
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/account/retrieve-an-account.mdx b/docs/api-reference/storefront/account/retrieve-an-account.mdx
deleted file mode 100644
index 580bd2f845..0000000000
--- a/docs/api-reference/storefront/account/retrieve-an-account.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/account
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/account/update-an-account.mdx b/docs/api-reference/storefront/account/update-an-account.mdx
deleted file mode 100644
index c19ab29477..0000000000
--- a/docs/api-reference/storefront/account/update-an-account.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/storefront/account
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/adyen/complete-an-adyen-payment-session.mdx b/docs/api-reference/storefront/adyen/complete-an-adyen-payment-session.mdx
deleted file mode 100644
index 12b57b9cc1..0000000000
--- a/docs/api-reference/storefront/adyen/complete-an-adyen-payment-session.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/storefront/adyen/payment_sessions/{id}/complete
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/adyen/create-an-adyen-payment-session.mdx b/docs/api-reference/storefront/adyen/create-an-adyen-payment-session.mdx
deleted file mode 100644
index 03641a7589..0000000000
--- a/docs/api-reference/storefront/adyen/create-an-adyen-payment-session.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/storefront/adyen/payment_sessions
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/adyen/get-adyen-payment-session.mdx b/docs/api-reference/storefront/adyen/get-adyen-payment-session.mdx
deleted file mode 100644
index ee9038411b..0000000000
--- a/docs/api-reference/storefront/adyen/get-adyen-payment-session.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/adyen/payment_sessions/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/cart-coupons/apply-a-coupon-code.mdx b/docs/api-reference/storefront/cart-coupons/apply-a-coupon-code.mdx
deleted file mode 100644
index 574aaf0c79..0000000000
--- a/docs/api-reference/storefront/cart-coupons/apply-a-coupon-code.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/storefront/cart/apply_coupon_code
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/cart-coupons/remove-a-coupon.mdx b/docs/api-reference/storefront/cart-coupons/remove-a-coupon.mdx
deleted file mode 100644
index d32bc37a85..0000000000
--- a/docs/api-reference/storefront/cart-coupons/remove-a-coupon.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/storefront/cart/remove_coupon_code/{coupon_code}
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/cart-coupons/remove-all-coupons.mdx b/docs/api-reference/storefront/cart-coupons/remove-all-coupons.mdx
deleted file mode 100644
index e7a6ff187b..0000000000
--- a/docs/api-reference/storefront/cart-coupons/remove-all-coupons.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/storefront/cart/remove_coupon_code
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/cart-line-items/add-an-item-to-cart.mdx b/docs/api-reference/storefront/cart-line-items/add-an-item-to-cart.mdx
deleted file mode 100644
index 4a035fe3ce..0000000000
--- a/docs/api-reference/storefront/cart-line-items/add-an-item-to-cart.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/storefront/cart/add_item
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/cart-line-items/remove-a-line-item.mdx b/docs/api-reference/storefront/cart-line-items/remove-a-line-item.mdx
deleted file mode 100644
index 5753fa78f6..0000000000
--- a/docs/api-reference/storefront/cart-line-items/remove-a-line-item.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/storefront/cart/remove_line_item/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/cart-line-items/set-line-item-quantity.mdx b/docs/api-reference/storefront/cart-line-items/set-line-item-quantity.mdx
deleted file mode 100644
index 719c0a357b..0000000000
--- a/docs/api-reference/storefront/cart-line-items/set-line-item-quantity.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/storefront/cart/set_quantity
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/cart-other/associate-a-cart-with-a-user.mdx b/docs/api-reference/storefront/cart-other/associate-a-cart-with-a-user.mdx
deleted file mode 100644
index 902a6476a3..0000000000
--- a/docs/api-reference/storefront/cart-other/associate-a-cart-with-a-user.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/storefront/cart/associate
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/cart-other/change-cart-currency.mdx b/docs/api-reference/storefront/cart-other/change-cart-currency.mdx
deleted file mode 100644
index f25fb99233..0000000000
--- a/docs/api-reference/storefront/cart-other/change-cart-currency.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/storefront/cart/change_currency
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/cart-other/empty-the-cart.mdx b/docs/api-reference/storefront/cart-other/empty-the-cart.mdx
deleted file mode 100644
index 1db8e1f61c..0000000000
--- a/docs/api-reference/storefront/cart-other/empty-the-cart.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/storefront/cart/empty
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/cart-other/list-estimated-shipping-rates.mdx b/docs/api-reference/storefront/cart-other/list-estimated-shipping-rates.mdx
deleted file mode 100644
index ce2efacf11..0000000000
--- a/docs/api-reference/storefront/cart-other/list-estimated-shipping-rates.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/cart/estimate_shipping_rates
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/cart/create-a-cart.mdx b/docs/api-reference/storefront/cart/create-a-cart.mdx
deleted file mode 100644
index 587aa91b16..0000000000
--- a/docs/api-reference/storefront/cart/create-a-cart.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/storefront/cart
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/cart/delete-a-cart.mdx b/docs/api-reference/storefront/cart/delete-a-cart.mdx
deleted file mode 100644
index d69c9bb461..0000000000
--- a/docs/api-reference/storefront/cart/delete-a-cart.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/storefront/cart
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/cart/retrieve-a-cart.mdx b/docs/api-reference/storefront/cart/retrieve-a-cart.mdx
deleted file mode 100644
index 6186c0e4c2..0000000000
--- a/docs/api-reference/storefront/cart/retrieve-a-cart.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/cart
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/checkout-payments/create-new-payment.mdx b/docs/api-reference/storefront/checkout-payments/create-new-payment.mdx
deleted file mode 100644
index e83b0aca50..0000000000
--- a/docs/api-reference/storefront/checkout-payments/create-new-payment.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/storefront/checkout/create_payment
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/checkout-payments/list-payment-methods.mdx b/docs/api-reference/storefront/checkout-payments/list-payment-methods.mdx
deleted file mode 100644
index dd1307e274..0000000000
--- a/docs/api-reference/storefront/checkout-payments/list-payment-methods.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/checkout/payment_methods
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/checkout-shipments/list-shipping-rates.mdx b/docs/api-reference/storefront/checkout-shipments/list-shipping-rates.mdx
deleted file mode 100644
index cba7da0699..0000000000
--- a/docs/api-reference/storefront/checkout-shipments/list-shipping-rates.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/checkout/shipping_rates
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/checkout-shipments/selects-shipping-method-for-shipments.mdx b/docs/api-reference/storefront/checkout-shipments/selects-shipping-method-for-shipments.mdx
deleted file mode 100644
index 8a5075364a..0000000000
--- a/docs/api-reference/storefront/checkout-shipments/selects-shipping-method-for-shipments.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/storefront/checkout/select_shipping_method
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/checkout-state/advance-checkout.mdx b/docs/api-reference/storefront/checkout-state/advance-checkout.mdx
deleted file mode 100644
index de31273607..0000000000
--- a/docs/api-reference/storefront/checkout-state/advance-checkout.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/storefront/checkout/advance
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/checkout-state/complete-checkout.mdx b/docs/api-reference/storefront/checkout-state/complete-checkout.mdx
deleted file mode 100644
index 6b84313d81..0000000000
--- a/docs/api-reference/storefront/checkout-state/complete-checkout.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/storefront/checkout/complete
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/checkout-state/next-checkout-step.mdx b/docs/api-reference/storefront/checkout-state/next-checkout-step.mdx
deleted file mode 100644
index 870d1ef4f1..0000000000
--- a/docs/api-reference/storefront/checkout-state/next-checkout-step.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/storefront/checkout/next
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/checkout-store-credit/add-store-credit.mdx b/docs/api-reference/storefront/checkout-store-credit/add-store-credit.mdx
deleted file mode 100644
index 230c12083b..0000000000
--- a/docs/api-reference/storefront/checkout-store-credit/add-store-credit.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/storefront/checkout/add_store_credit
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/checkout-store-credit/remove-store-credit.mdx b/docs/api-reference/storefront/checkout-store-credit/remove-store-credit.mdx
deleted file mode 100644
index 132ef5dc9c..0000000000
--- a/docs/api-reference/storefront/checkout-store-credit/remove-store-credit.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/storefront/checkout/remove_store_credit
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/checkout/update-checkout.mdx b/docs/api-reference/storefront/checkout/update-checkout.mdx
deleted file mode 100644
index 17a035b91f..0000000000
--- a/docs/api-reference/storefront/checkout/update-checkout.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/storefront/checkout
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/checkout/validate-order-payment.mdx b/docs/api-reference/storefront/checkout/validate-order-payment.mdx
deleted file mode 100644
index be3b9d2e1e..0000000000
--- a/docs/api-reference/storefront/checkout/validate-order-payment.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-openapi: post /api/v2/storefront/checkout/validate_order_for_payment
-version: v5
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/countries/get-default-country.mdx b/docs/api-reference/storefront/countries/get-default-country.mdx
deleted file mode 100644
index eca1642f1c..0000000000
--- a/docs/api-reference/storefront/countries/get-default-country.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/countries/default
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/countries/list-all-countries.mdx b/docs/api-reference/storefront/countries/list-all-countries.mdx
deleted file mode 100644
index ea4891b922..0000000000
--- a/docs/api-reference/storefront/countries/list-all-countries.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/countries
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/countries/retrieve-a-country.mdx b/docs/api-reference/storefront/countries/retrieve-a-country.mdx
deleted file mode 100644
index 51ab308f06..0000000000
--- a/docs/api-reference/storefront/countries/retrieve-a-country.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/countries/{iso}
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/digital-downloads/download-a-digital-asset.mdx b/docs/api-reference/storefront/digital-downloads/download-a-digital-asset.mdx
deleted file mode 100644
index 848aad6ba8..0000000000
--- a/docs/api-reference/storefront/digital-downloads/download-a-digital-asset.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/digitals/{token}
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/order-status/retrieve-an-order-status.mdx b/docs/api-reference/storefront/order-status/retrieve-an-order-status.mdx
deleted file mode 100644
index a1a960e778..0000000000
--- a/docs/api-reference/storefront/order-status/retrieve-an-order-status.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/order_status/{order_number}
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/policies/list-all-store-policies.mdx b/docs/api-reference/storefront/policies/list-all-store-policies.mdx
deleted file mode 100644
index 0a78340d32..0000000000
--- a/docs/api-reference/storefront/policies/list-all-store-policies.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/policies
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/policies/retrieve-a-policy.mdx b/docs/api-reference/storefront/policies/retrieve-a-policy.mdx
deleted file mode 100644
index 7c135a2356..0000000000
--- a/docs/api-reference/storefront/policies/retrieve-a-policy.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/policies/{policy_slug}
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/post-categories/list-all-post-categories.mdx b/docs/api-reference/storefront/post-categories/list-all-post-categories.mdx
deleted file mode 100644
index 5e96da5abf..0000000000
--- a/docs/api-reference/storefront/post-categories/list-all-post-categories.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/post_categories
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/post-categories/retrieve-a-post-category.mdx b/docs/api-reference/storefront/post-categories/retrieve-a-post-category.mdx
deleted file mode 100644
index 55e61725b0..0000000000
--- a/docs/api-reference/storefront/post-categories/retrieve-a-post-category.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/post_categories/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/posts/list-all-posts.mdx b/docs/api-reference/storefront/posts/list-all-posts.mdx
deleted file mode 100644
index 9aa0baf065..0000000000
--- a/docs/api-reference/storefront/posts/list-all-posts.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/posts
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/posts/retrieve-a-post.mdx b/docs/api-reference/storefront/posts/retrieve-a-post.mdx
deleted file mode 100644
index 9f22c05924..0000000000
--- a/docs/api-reference/storefront/posts/retrieve-a-post.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/posts/{id}
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/products/list-all-products.mdx b/docs/api-reference/storefront/products/list-all-products.mdx
deleted file mode 100644
index 83872d25c0..0000000000
--- a/docs/api-reference/storefront/products/list-all-products.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/products
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/products/retrieve-a-product.mdx b/docs/api-reference/storefront/products/retrieve-a-product.mdx
deleted file mode 100644
index 47a27e5cd3..0000000000
--- a/docs/api-reference/storefront/products/retrieve-a-product.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/products/{product_slug}
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/stores/return-the-current-store.mdx b/docs/api-reference/storefront/stores/return-the-current-store.mdx
deleted file mode 100644
index 2b87aa830e..0000000000
--- a/docs/api-reference/storefront/stores/return-the-current-store.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/store
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/stripe/create-a-stripe-payment-intent.mdx b/docs/api-reference/storefront/stripe/create-a-stripe-payment-intent.mdx
deleted file mode 100644
index 4a3ff3ed27..0000000000
--- a/docs/api-reference/storefront/stripe/create-a-stripe-payment-intent.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-openapi: post /api/v2/storefront/stripe/payment_intents
-version: v5
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/stripe/create-a-stripe-setup-intent.mdx b/docs/api-reference/storefront/stripe/create-a-stripe-setup-intent.mdx
deleted file mode 100644
index 8abafa9eb8..0000000000
--- a/docs/api-reference/storefront/stripe/create-a-stripe-setup-intent.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-openapi: post /api/v2/storefront/stripe/setup_intents
-version: v5
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/stripe/mark-the-payment-intent-as-confirmed-and-move-the-order-to-the-complete-state.mdx b/docs/api-reference/storefront/stripe/mark-the-payment-intent-as-confirmed-and-move-the-order-to-the-complete-state.mdx
deleted file mode 100644
index 96ef278cae..0000000000
--- a/docs/api-reference/storefront/stripe/mark-the-payment-intent-as-confirmed-and-move-the-order-to-the-complete-state.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-openapi: patch /api/v2/storefront/stripe/payment_intents/{id}/confirm
-version: v5
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/stripe/return-a-stripe-payment-intent.mdx b/docs/api-reference/storefront/stripe/return-a-stripe-payment-intent.mdx
deleted file mode 100644
index 48b058b38e..0000000000
--- a/docs/api-reference/storefront/stripe/return-a-stripe-payment-intent.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-openapi: get /api/v2/storefront/stripe/payment_intents/{id}
-version: v5
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/stripe/updates-stripe-payment-intent.mdx b/docs/api-reference/storefront/stripe/updates-stripe-payment-intent.mdx
deleted file mode 100644
index 964ad50753..0000000000
--- a/docs/api-reference/storefront/stripe/updates-stripe-payment-intent.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-openapi: patch /api/v2/storefront/stripe/payment_intents/{id}
-version: v5
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/taxons/list-all-taxons.mdx b/docs/api-reference/storefront/taxons/list-all-taxons.mdx
deleted file mode 100644
index e78c11a7b2..0000000000
--- a/docs/api-reference/storefront/taxons/list-all-taxons.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-openapi: get /api/v2/storefront/taxons
-version: v5
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/taxons/retrieve-a-taxon.mdx b/docs/api-reference/storefront/taxons/retrieve-a-taxon.mdx
deleted file mode 100644
index 2fa186a8d2..0000000000
--- a/docs/api-reference/storefront/taxons/retrieve-a-taxon.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/taxons/{taxon_permalink}
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/variants/list-all-product-variants.mdx b/docs/api-reference/storefront/variants/list-all-product-variants.mdx
deleted file mode 100644
index 360566dec1..0000000000
--- a/docs/api-reference/storefront/variants/list-all-product-variants.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/products/{product_slug}/variants
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/vendors/list-all-vendors.mdx b/docs/api-reference/storefront/vendors/list-all-vendors.mdx
deleted file mode 100644
index 9b7b0c694c..0000000000
--- a/docs/api-reference/storefront/vendors/list-all-vendors.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/vendors
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/vendors/retrieve-a-vendor.mdx b/docs/api-reference/storefront/vendors/retrieve-a-vendor.mdx
deleted file mode 100644
index fccf7d8962..0000000000
--- a/docs/api-reference/storefront/vendors/retrieve-a-vendor.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-openapi: get /api/v2/storefront/vendors/{vendor_slug}
-version: v5
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/wishlists-wished-items/add-item-to-wishlist.mdx b/docs/api-reference/storefront/wishlists-wished-items/add-item-to-wishlist.mdx
deleted file mode 100644
index 4437ff9e86..0000000000
--- a/docs/api-reference/storefront/wishlists-wished-items/add-item-to-wishlist.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/storefront/wishlists/{token}/add_item
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/wishlists-wished-items/add-items-to-wishlist.mdx b/docs/api-reference/storefront/wishlists-wished-items/add-items-to-wishlist.mdx
deleted file mode 100644
index 87c1d0f2b2..0000000000
--- a/docs/api-reference/storefront/wishlists-wished-items/add-items-to-wishlist.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-openapi: post /api/v2/storefront/wishlists/{token}/add_items
-version: v5
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/wishlists-wished-items/delete-item-from-wishlist.mdx b/docs/api-reference/storefront/wishlists-wished-items/delete-item-from-wishlist.mdx
deleted file mode 100644
index 6185b41dca..0000000000
--- a/docs/api-reference/storefront/wishlists-wished-items/delete-item-from-wishlist.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/storefront/wishlists/{token}/remove_item/{item_id}
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/wishlists-wished-items/delete-items-from-wishlist.mdx b/docs/api-reference/storefront/wishlists-wished-items/delete-items-from-wishlist.mdx
deleted file mode 100644
index afb16b8726..0000000000
--- a/docs/api-reference/storefront/wishlists-wished-items/delete-items-from-wishlist.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-openapi: delete /api/v2/storefront/wishlists/{token}/remove_items
-version: v5
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/wishlists-wished-items/set-wished-item-quantity.mdx b/docs/api-reference/storefront/wishlists-wished-items/set-wished-item-quantity.mdx
deleted file mode 100644
index 98f5c15cdb..0000000000
--- a/docs/api-reference/storefront/wishlists-wished-items/set-wished-item-quantity.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/storefront/wishlists/{token}/set_item_quantity/{item_id}
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/wishlists/create-a-wishlist.mdx b/docs/api-reference/storefront/wishlists/create-a-wishlist.mdx
deleted file mode 100644
index 813298c0f0..0000000000
--- a/docs/api-reference/storefront/wishlists/create-a-wishlist.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: post /api/v2/storefront/wishlists
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/wishlists/delete-a-wishlist.mdx b/docs/api-reference/storefront/wishlists/delete-a-wishlist.mdx
deleted file mode 100644
index 65a2fafaea..0000000000
--- a/docs/api-reference/storefront/wishlists/delete-a-wishlist.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: delete /api/v2/storefront/wishlists/{token}
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/wishlists/list-all-wishlists.mdx b/docs/api-reference/storefront/wishlists/list-all-wishlists.mdx
deleted file mode 100644
index 9d9856391e..0000000000
--- a/docs/api-reference/storefront/wishlists/list-all-wishlists.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/wishlists
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/wishlists/retrieve-a-wishlist.mdx b/docs/api-reference/storefront/wishlists/retrieve-a-wishlist.mdx
deleted file mode 100644
index 53cf2c0d47..0000000000
--- a/docs/api-reference/storefront/wishlists/retrieve-a-wishlist.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/wishlists/{token}
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/wishlists/retrieve-the-default-wishlist.mdx b/docs/api-reference/storefront/wishlists/retrieve-the-default-wishlist.mdx
deleted file mode 100644
index 0d57b55bfc..0000000000
--- a/docs/api-reference/storefront/wishlists/retrieve-the-default-wishlist.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: get /api/v2/storefront/wishlists/default
----
\ No newline at end of file
diff --git a/docs/api-reference/storefront/wishlists/update-a-wishlist.mdx b/docs/api-reference/storefront/wishlists/update-a-wishlist.mdx
deleted file mode 100644
index 6a6e3bd814..0000000000
--- a/docs/api-reference/storefront/wishlists/update-a-wishlist.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-openapi: patch /api/v2/storefront/wishlists/{token}
----
\ No newline at end of file
diff --git a/docs/api-reference/fetching-multiple-resources.mdx b/docs/api-reference/v2/fetching-multiple-resources.mdx
similarity index 100%
rename from docs/api-reference/fetching-multiple-resources.mdx
rename to docs/api-reference/v2/fetching-multiple-resources.mdx
diff --git a/docs/api-reference/filtering-and-sorting.mdx b/docs/api-reference/v2/filtering-and-sorting.mdx
similarity index 100%
rename from docs/api-reference/filtering-and-sorting.mdx
rename to docs/api-reference/v2/filtering-and-sorting.mdx
diff --git a/docs/api-reference/introduction.mdx b/docs/api-reference/v2/introduction.mdx
similarity index 100%
rename from docs/api-reference/introduction.mdx
rename to docs/api-reference/v2/introduction.mdx
diff --git a/docs/api-reference/pagination.mdx b/docs/api-reference/v2/pagination.mdx
similarity index 100%
rename from docs/api-reference/pagination.mdx
rename to docs/api-reference/v2/pagination.mdx
diff --git a/docs/api-reference/webhooks-events.mdx b/docs/api-reference/webhooks-events.mdx
new file mode 100644
index 0000000000..39019804d6
--- /dev/null
+++ b/docs/api-reference/webhooks-events.mdx
@@ -0,0 +1,887 @@
+---
+title: Webhook Events & Payloads
+description: Complete reference of all webhook event types and their payload schemas
+---
+
+Every webhook delivery sends a JSON envelope with the event metadata and a `data` object containing the serialized resource:
+
+```json
+{
+ "id": "550e8400-e29b-41d4-a716-446655440000",
+ "name": "order.completed",
+ "created_at": "2025-01-15T10:30:00Z",
+ "data": { ... },
+ "metadata": {
+ "spree_version": "5.4.0"
+ }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique UUID for this event |
+| `name` | string | Event name (e.g., `order.completed`) |
+| `created_at` | string | ISO 8601 timestamp |
+| `data` | object | Serialized resource (see payloads below) |
+| `metadata` | object | Additional context including Spree version |
+
+Event payloads use the same [Store API V3 serializers](/api-reference/introduction) as the REST API. All `id` fields use [prefixed IDs](/api-reference/introduction) (e.g., `or_m3Rp9wXz`, `prod_86Rf07xd4z`). All monetary values are strings. All timestamps are ISO 8601.
+
+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.
+</Info>
+
+---
+
+## Order Events
+
+Events: `order.created`, `order.updated`, `order.completed`, `order.canceled`, `order.resumed`, `order.paid`, `order.shipped`
+
+Order payloads include nested `line_items`, `shipments`, `payments`, `bill_address`, `ship_address`, `payment_methods`, and `order_promotions`.
+
+```json
+{
+ "id": "or_m3Rp9wXz",
+ "number": "R123456789",
+ "state": "complete",
+ "token": "abc123def456",
+ "email": "[email protected]",
+ "special_instructions": null,
+ "currency": "USD",
+ "item_count": 3,
+ "shipment_state": "shipped",
+ "payment_state": "paid",
+ "item_total": "89.99",
+ "display_item_total": "$89.99",
+ "ship_total": "10.00",
+ "display_ship_total": "$10.00",
+ "adjustment_total": "0.00",
+ "display_adjustment_total": "$0.00",
+ "promo_total": "0.00",
+ "display_promo_total": "$0.00",
+ "tax_total": "0.00",
+ "display_tax_total": "$0.00",
+ "included_tax_total": "0.00",
+ "display_included_tax_total": "$0.00",
+ "additional_tax_total": "0.00",
+ "display_additional_tax_total": "$0.00",
+ "total": "99.99",
+ "display_total": "$99.99",
+ "completed_at": "2025-01-15T10:30:00Z",
+ "created_at": "2025-01-15T10:00:00Z",
+ "updated_at": "2025-01-15T10:30:00Z",
+ "order_promotions": [],
+ "line_items": [
+ {
+ "id": "li_7xRt4wPq",
+ "variant_id": "var_k5nR8xLq",
+ "quantity": 2,
+ "currency": "USD",
+ "name": "Spree Tote Bag",
+ "slug": "spree-tote-bag",
+ "options_text": "Size: M, Color: Black",
+ "price": "29.99",
+ "display_price": "$29.99",
+ "total": "59.98",
+ "display_total": "$59.98",
+ "thumbnail_url": "https://cdn.example.com/images/tote-bag.jpg",
+ "option_values": [],
+ "digital_links": [],
+ "..."
+ }
+ ],
+ "shipments": [
+ {
+ "id": "shp_9xPq4wMn",
+ "number": "H123456789",
+ "state": "shipped",
+ "tracking": "1Z999AA10123456784",
+ "tracking_url": "https://tools.usps.com/go/TrackConfirmAction?tLabels=1Z999AA10123456784",
+ "cost": "10.00",
+ "display_cost": "$10.00",
+ "shipped_at": "2025-01-16T14:00:00Z",
+ "shipping_method": { "id": "sm_2wMn7xRt", "..." },
+ "stock_location": { "id": "sl_2wMn7xRt", "..." },
+ "shipping_rates": [],
+ "..."
+ }
+ ],
+ "payments": [
+ {
+ "id": "pay_3wXz7mRp",
+ "state": "completed",
+ "number": "P123456",
+ "amount": "99.99",
+ "display_amount": "$99.99",
+ "response_code": "ch_abc123",
+ "payment_method_id": "pm_4xLq8nRt",
+ "source_type": "credit_card",
+ "source_id": "cc_5wPq9mXz",
+ "source": { "..." },
+ "payment_method": { "id": "pm_4xLq8nRt", "..." },
+ "..."
+ }
+ ],
+ "bill_address": {
+ "id": "addr_1xPq2wMn",
+ "..."
+ },
+ "ship_address": {
+ "id": "addr_2wMn3xPq",
+ "..."
+ },
+ "payment_methods": [
+ { "id": "pm_4xLq8nRt", "..." }
+ ]
+}
+```
+
+## Line Item Events
+
+Events: `line_item.created`, `line_item.updated`, `line_item.deleted`
+
+Line item payloads include nested `option_values` and `digital_links`.
+
+```json
+{
+ "id": "li_7xRt4wPq",
+ "variant_id": "var_k5nR8xLq",
+ "quantity": 2,
+ "currency": "USD",
+ "name": "Spree Tote Bag",
+ "slug": "spree-tote-bag",
+ "options_text": "Size: M, Color: Black",
+ "price": "29.99",
+ "display_price": "$29.99",
+ "total": "59.98",
+ "display_total": "$59.98",
+ "adjustment_total": "0.00",
+ "display_adjustment_total": "$0.00",
+ "additional_tax_total": "2.40",
+ "display_additional_tax_total": "$2.40",
+ "included_tax_total": "0.00",
+ "display_included_tax_total": "$0.00",
+ "promo_total": "-5.00",
+ "display_promo_total": "-$5.00",
+ "pre_tax_amount": "54.98",
+ "display_pre_tax_amount": "$54.98",
+ "discounted_amount": "54.98",
+ "display_discounted_amount": "$54.98",
+ "compare_at_amount": null,
+ "display_compare_at_amount": null,
+ "thumbnail_url": "https://cdn.example.com/images/tote-bag.jpg",
+ "created_at": "2025-01-15T10:00:00Z",
+ "updated_at": "2025-01-15T10:00:00Z",
+ "option_values": [
+ { "id": "ov_2wMn9xPq", "name": "M", "presentation": "Medium" }
+ ],
+ "digital_links": []
+}
+```
+
+## Payment Events
+
+Events: `payment.created`, `payment.updated`, `payment.paid`
+
+Payment payloads include a nested `payment_method` and polymorphic `source` (credit card, store credit, or payment source).
+
+```json
+{
+ "id": "pay_3wXz7mRp",
+ "state": "completed",
+ "number": "P123456",
+ "amount": "99.99",
+ "display_amount": "$99.99",
+ "response_code": "ch_abc123",
+ "payment_method_id": "pm_4xLq8nRt",
+ "source_type": "credit_card",
+ "source_id": "cc_5wPq9mXz",
+ "source": {
+ "id": "cc_5wPq9mXz",
+ "..."
+ },
+ "payment_method": {
+ "id": "pm_4xLq8nRt",
+ "..."
+ },
+ "created_at": "2025-01-15T10:25:00Z",
+ "updated_at": "2025-01-15T10:25:00Z"
+}
+```
+
+The `source_type` field is normalized to one of: `"credit_card"`, `"store_credit"`, `"payment_source"`, or `null`.
+
+## Payment Session Events
+
+Events: `payment_session.created`, `payment_session.updated`, `payment_session.deleted`
+
+Payment session payloads include a nested `payment_method` and optionally a nested `payment`.
+
+```json
+{
+ "id": "ps_6nRt2xLq",
+ "status": "pending",
+ "amount": "99.99",
+ "currency": "USD",
+ "external_id": "pi_3abc123",
+ "external_data": {},
+ "customer_external_id": null,
+ "order_id": "or_m3Rp9wXz",
+ "payment_method_id": "pm_4xLq8nRt",
+ "payment_method": {
+ "id": "pm_4xLq8nRt",
+ "..."
+ },
+ "expires_at": "2025-01-15T11:00:00Z",
+ "created_at": "2025-01-15T10:25:00Z",
+ "updated_at": "2025-01-15T10:25:00Z"
+}
+```
+
+## Payment Setup Session Events
+
+Events: `payment_setup_session.created`, `payment_setup_session.updated`, `payment_setup_session.deleted`
+
+Payment setup session payloads include a nested `payment_method`.
+
+```json
+{
+ "id": "pss_8mXz3wPq",
+ "status": "pending",
+ "external_id": "seti_abc123",
+ "external_client_secret": "seti_abc123_secret_xyz",
+ "external_data": {},
+ "payment_method_id": "pm_4xLq8nRt",
+ "payment_source_id": "cc_5wPq9mXz",
+ "payment_source_type": "Spree::CreditCard",
+ "customer_id": "usr_k5nR8xLq",
+ "payment_method": {
+ "id": "pm_4xLq8nRt",
+ "..."
+ },
+ "created_at": "2025-01-15T10:25:00Z",
+ "updated_at": "2025-01-15T10:25:00Z"
+}
+```
+
+## Shipment Events
+
+Events: `shipment.created`, `shipment.updated`, `shipment.shipped`, `shipment.canceled`, `shipment.resumed`
+
+Shipment payloads include nested `shipping_method`, `stock_location`, and `shipping_rates`.
+
+```json
+{
+ "id": "shp_9xPq4wMn",
+ "number": "H123456789",
+ "state": "shipped",
+ "tracking": "1Z999AA10123456784",
+ "tracking_url": "https://tools.usps.com/go/TrackConfirmAction?tLabels=1Z999AA10123456784",
+ "cost": "10.00",
+ "display_cost": "$10.00",
+ "shipped_at": "2025-01-16T14:00:00Z",
+ "created_at": "2025-01-15T10:30:00Z",
+ "updated_at": "2025-01-16T14:00:00Z",
+ "shipping_method": {
+ "id": "sm_2wMn7xRt",
+ "..."
+ },
+ "stock_location": {
+ "id": "sl_2wMn7xRt",
+ "..."
+ },
+ "shipping_rates": []
+}
+```
+
+## Product Events
+
+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.
+
+```json
+{
+ "id": "prod_86Rf07xd4z",
+ "name": "Spree Tote Bag",
+ "slug": "spree-tote-bag",
+ "description": "A beautiful tote bag",
+ "meta_description": null,
+ "meta_keywords": null,
+ "variant_count": 3,
+ "default_variant_id": "var_k5nR8xLq",
+ "thumbnail_url": "https://cdn.example.com/images/tote-bag.jpg",
+ "purchasable": true,
+ "in_stock": true,
+ "backorderable": false,
+ "available": true,
+ "tags": ["summer", "accessories"],
+ "price": {
+ "id": "pri_4wPq9mXz",
+ "amount": "29.99",
+ "amount_in_cents": 2999,
+ "display_amount": "$29.99",
+ "compare_at_amount": null,
+ "compare_at_amount_in_cents": null,
+ "display_compare_at_amount": null,
+ "currency": "USD",
+ "price_list_id": null
+ },
+ "original_price": null,
+ "available_on": "2025-01-01T00:00:00Z",
+ "created_at": "2025-01-01T00:00:00Z",
+ "updated_at": "2025-01-15T10:00:00Z"
+}
+```
+
+## Variant Events
+
+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.
+
+```json
+{
+ "id": "var_k5nR8xLq",
+ "product_id": "prod_86Rf07xd4z",
+ "sku": "SPR-TOTE-BLK",
+ "is_master": false,
+ "options_text": "Size: M, Color: Black",
+ "track_inventory": true,
+ "image_count": 2,
+ "thumbnail": "https://cdn.example.com/images/tote-bag-black.jpg",
+ "purchasable": true,
+ "in_stock": true,
+ "backorderable": false,
+ "weight": 0.5,
+ "height": 40.0,
+ "width": 35.0,
+ "depth": 10.0,
+ "price": {
+ "id": "pri_4wPq9mXz",
+ "amount": "29.99",
+ "amount_in_cents": 2999,
+ "display_amount": "$29.99",
+ "compare_at_amount": null,
+ "compare_at_amount_in_cents": null,
+ "display_compare_at_amount": null,
+ "currency": "USD",
+ "price_list_id": null
+ },
+ "original_price": null,
+ "created_at": "2025-01-01T00:00:00Z",
+ "updated_at": "2025-01-15T10:00:00Z",
+ "option_values": [
+ { "id": "ov_2wMn9xPq", "name": "M", "presentation": "Medium" },
+ { "id": "ov_3xLq8nRt", "name": "Black", "presentation": "Black" }
+ ]
+}
+```
+
+## Price Events
+
+Events: `price.created`, `price.updated`, `price.deleted`
+
+```json
+{
+ "id": "pri_4wPq9mXz",
+ "amount": "29.99",
+ "amount_in_cents": 2999,
+ "display_amount": "$29.99",
+ "compare_at_amount": "39.99",
+ "compare_at_amount_in_cents": 3999,
+ "display_compare_at_amount": "$39.99",
+ "currency": "USD",
+ "price_list_id": null
+}
+```
+
+## Image Events
+
+Events: `image.created`, `image.updated`, `image.deleted`
+
+Image payloads include URLs for all configured image variants (mini, small, medium, large, xlarge).
+
+```json
+{
+ "id": "img_5mXz3wPq",
+ "type": "Spree::Image",
+ "viewable_type": "Spree::Variant",
+ "viewable_id": "var_k5nR8xLq",
+ "position": 1,
+ "alt": "Black tote bag front view",
+ "original_url": "https://cdn.example.com/images/original.jpg",
+ "mini_url": "https://cdn.example.com/images/mini.jpg",
+ "small_url": "https://cdn.example.com/images/small.jpg",
+ "medium_url": "https://cdn.example.com/images/medium.jpg",
+ "large_url": "https://cdn.example.com/images/large.jpg",
+ "xlarge_url": "https://cdn.example.com/images/xlarge.jpg",
+ "og_image_url": "https://cdn.example.com/images/og.jpg",
+ "created_at": "2025-01-01T00:00:00Z",
+ "updated_at": "2025-01-01T00:00:00Z"
+}
+```
+
+## Stock Item Events
+
+Events: `stock_item.created`, `stock_item.updated`, `stock_item.deleted`
+
+```json
+{
+ "id": "si_6nRt2xLq",
+ "count_on_hand": 25,
+ "backorderable": false,
+ "stock_location_id": "sl_2wMn7xRt",
+ "variant_id": "var_k5nR8xLq",
+ "created_at": "2025-01-01T00:00:00Z",
+ "updated_at": "2025-01-15T10:00:00Z"
+}
+```
+
+## Stock Movement Events
+
+Events: `stock_movement.created`, `stock_movement.updated`, `stock_movement.deleted`
+
+```json
+{
+ "id": "sm_7xRt4wPq",
+ "quantity": -1,
+ "action": "sold",
+ "originator_type": "Spree::Shipment",
+ "originator_id": "shp_9xPq4wMn",
+ "stock_item_id": "si_6nRt2xLq",
+ "created_at": "2025-01-15T10:30:00Z",
+ "updated_at": "2025-01-15T10:30:00Z"
+}
+```
+
+## Stock Transfer Events
+
+Events: `stock_transfer.created`, `stock_transfer.updated`, `stock_transfer.deleted`
+
+```json
+{
+ "id": "st_8mXz3wPq",
+ "number": "T123456789",
+ "type": "Spree::StockTransfer",
+ "reference": "Warehouse rebalance",
+ "source_location_id": "sl_2wMn7xRt",
+ "destination_location_id": "sl_9xPq4wMn",
+ "created_at": "2025-01-15T10:00:00Z",
+ "updated_at": "2025-01-15T10:00:00Z"
+}
+```
+
+## Customer Events
+
+Events: `customer.created`, `customer.updated`, `customer.deleted`
+
+Customer payloads include nested `addresses`, `default_billing_address`, and `default_shipping_address`.
+
+```json
+{
+ "id": "usr_k5nR8xLq",
+ "email": "[email protected]",
+ "first_name": "John",
+ "last_name": "Doe",
+ "created_at": "2025-01-01T00:00:00Z",
+ "updated_at": "2025-01-15T10:00:00Z",
+ "addresses": [],
+ "default_billing_address": null,
+ "default_shipping_address": null
+}
+```
+
+## Promotion Events
+
+Events: `promotion.created`, `promotion.updated`, `promotion.deleted`
+
+```json
+{
+ "id": "promo_2wMn9xPq",
+ "name": "Summer Sale 20% Off",
+ "description": "20% off all summer items",
+ "code": "SUMMER20",
+ "type": "Spree::Promotion",
+ "kind": "coupon",
+ "path": null,
+ "match_policy": "all",
+ "usage_limit": 1000,
+ "advertise": true,
+ "multi_codes": false,
+ "code_prefix": null,
+ "number_of_codes": null,
+ "starts_at": "2025-06-01T00:00:00Z",
+ "expires_at": "2025-08-31T23:59:59Z",
+ "promotion_category_id": "pcat_3xLq8nRt",
+ "created_at": "2025-05-15T10:00:00Z",
+ "updated_at": "2025-05-15T10:00:00Z"
+}
+```
+
+## Gift Card Events
+
+Events: `gift_card.created`, `gift_card.updated`, `gift_card.deleted`
+
+```json
+{
+ "id": "gc_4xLq8nRt",
+ "code": "****-1234",
+ "state": "active",
+ "amount": 50.0,
+ "amount_used": 15.0,
+ "amount_authorized": 0.0,
+ "amount_remaining": 35.0,
+ "display_amount": "$50.00",
+ "display_amount_used": "$15.00",
+ "display_amount_remaining": "$35.00",
+ "currency": "USD",
+ "expired": false,
+ "active": true,
+ "expires_at": "2026-01-01T00:00:00Z",
+ "redeemed_at": "2025-02-01T10:00:00Z",
+ "created_at": "2025-01-01T00:00:00Z",
+ "updated_at": "2025-02-01T10:00:00Z"
+}
+```
+
+<Info>
+The gift card `code` is displayed as a masked value (e.g., `****-1234`) for security.
+</Info>
+
+## Gift Card Batch Events
+
+Events: `gift_card_batch.created`, `gift_card_batch.updated`, `gift_card_batch.deleted`
+
+```json
+{
+ "id": "gcb_5wPq9mXz",
+ "codes_count": 100,
+ "amount": "25.00",
+ "currency": "USD",
+ "prefix": "HOLIDAY",
+ "expires_at": "2026-12-31T00:00:00Z",
+ "created_by_id": "adm_8mXz3wPq",
+ "created_at": "2025-01-01T00:00:00Z",
+ "updated_at": "2025-01-01T00:00:00Z"
+}
+```
+
+## Store Credit Events
+
+Events: `store_credit.created`, `store_credit.updated`, `store_credit.deleted`
+
+```json
+{
+ "id": "sc_6nRt2xLq",
+ "amount": "100.00",
+ "amount_used": "25.00",
+ "amount_remaining": "75.00",
+ "display_amount": "$100.00",
+ "display_amount_used": "$25.00",
+ "display_amount_remaining": "$75.00",
+ "currency": "USD"
+}
+```
+
+## Refund Events
+
+Events: `refund.created`, `refund.updated`, `refund.deleted`
+
+```json
+{
+ "id": "ref_7xRt4wPq",
+ "amount": "29.99",
+ "transaction_id": "txn_abc123",
+ "payment_id": "pay_3wXz7mRp",
+ "refund_reason_id": "rr_2wMn9xPq",
+ "reimbursement_id": "rei_3xLq8nRt",
+ "created_at": "2025-01-20T10:00:00Z",
+ "updated_at": "2025-01-20T10:00:00Z"
+}
+```
+
+## Reimbursement Events
+
+Events: `reimbursement.created`, `reimbursement.updated`, `reimbursement.deleted`
+
+```json
+{
+ "id": "rei_3xLq8nRt",
+ "number": "RI123456789",
+ "reimbursement_status": "reimbursed",
+ "total": "29.99",
+ "order_id": "or_m3Rp9wXz",
+ "customer_return_id": "cr_4xLq8nRt",
+ "created_at": "2025-01-20T10:00:00Z",
+ "updated_at": "2025-01-20T10:00:00Z"
+}
+```
+
+## Return Authorization Events
+
+Events: `return_authorization.created`, `return_authorization.updated`, `return_authorization.deleted`
+
+```json
+{
+ "id": "ra_8mXz3wPq",
+ "number": "RA123456789",
+ "state": "authorized",
+ "order_id": "or_m3Rp9wXz",
+ "stock_location_id": "sl_2wMn7xRt",
+ "return_authorization_reason_id": "rar_9xPq4wMn",
+ "created_at": "2025-01-18T10:00:00Z",
+ "updated_at": "2025-01-18T10:00:00Z"
+}
+```
+
+## Return Item Events
+
+Events: `return_item.created`, `return_item.updated`, `return_item.deleted`
+
+```json
+{
+ "id": "ri_9xPq4wMn",
+ "reception_status": "received",
+ "acceptance_status": "accepted",
+ "pre_tax_amount": "29.99",
+ "included_tax_total": "0.00",
+ "additional_tax_total": "2.40",
+ "inventory_unit_id": "iu_2wMn7xRt",
+ "return_authorization_id": "ra_8mXz3wPq",
+ "customer_return_id": "cr_4xLq8nRt",
+ "reimbursement_id": "rei_3xLq8nRt",
+ "exchange_variant_id": null,
+ "created_at": "2025-01-19T10:00:00Z",
+ "updated_at": "2025-01-19T10:00:00Z"
+}
+```
+
+## Customer Return Events
+
+Events: `customer_return.created`, `customer_return.updated`, `customer_return.deleted`
+
+```json
+{
+ "id": "cr_4xLq8nRt",
+ "number": "CR123456789",
+ "stock_location_id": "sl_2wMn7xRt",
+ "created_at": "2025-01-19T10:00:00Z",
+ "updated_at": "2025-01-19T10:00:00Z"
+}
+```
+
+## Wishlist Events
+
+Events: `wishlist.created`, `wishlist.updated`, `wishlist.deleted`
+
+Wishlist items are a conditional association and are not included in event payloads.
+
+```json
+{
+ "id": "wl_5wPq9mXz",
+ "name": "My Wishlist",
+ "token": "abc123def456",
+ "is_default": true,
+ "is_private": true,
+ "created_at": "2025-01-01T00:00:00Z",
+ "updated_at": "2025-01-15T10:00:00Z"
+}
+```
+
+## Wished Item Events
+
+Events: `wished_item.created`, `wished_item.updated`, `wished_item.deleted`
+
+Wished item payloads include a nested `variant`.
+
+```json
+{
+ "id": "wi_6nRt2xLq",
+ "variant_id": "var_k5nR8xLq",
+ "wishlist_id": "wl_5wPq9mXz",
+ "quantity": 1,
+ "created_at": "2025-01-15T10:00:00Z",
+ "updated_at": "2025-01-15T10:00:00Z",
+ "variant": {
+ "id": "var_k5nR8xLq",
+ "..."
+ }
+}
+```
+
+## Post Events
+
+Events: `post.created`, `post.updated`, `post.deleted`
+
+```json
+{
+ "id": "post_7xRt4wPq",
+ "title": "Summer Collection 2025",
+ "slug": "summer-collection-2025",
+ "meta_title": "Summer Collection | My Store",
+ "meta_description": "Discover our new summer collection",
+ "published_at": "2025-06-01T00:00:00Z",
+ "author_id": "adm_8mXz3wPq",
+ "post_category_id": "pcat_9xPq4wMn",
+ "created_at": "2025-05-15T10:00:00Z",
+ "updated_at": "2025-05-15T10:00:00Z"
+}
+```
+
+## Post Category Events
+
+Events: `post_category.created`, `post_category.updated`, `post_category.deleted`
+
+```json
+{
+ "id": "pcat_9xPq4wMn",
+ "title": "News",
+ "slug": "news",
+ "created_at": "2025-01-01T00:00:00Z",
+ "updated_at": "2025-01-01T00:00:00Z"
+}
+```
+
+## Newsletter Subscriber Events
+
+Events: `newsletter_subscriber.created`, `newsletter_subscriber.updated`, `newsletter_subscriber.deleted`
+
+```json
+{
+ "id": "ns_2wMn9xPq",
+ "email": "[email protected]",
+ "verified": true,
+ "verified_at": "2025-01-02T10:00:00Z",
+ "user_id": "usr_k5nR8xLq",
+ "created_at": "2025-01-01T00:00:00Z",
+ "updated_at": "2025-01-02T10:00:00Z"
+}
+```
+
+## Digital Product Events
+
+Events: `digital.created`, `digital.updated`, `digital.deleted`
+
+```json
+{
+ "id": "dig_3xLq8nRt",
+ "variant_id": "var_k5nR8xLq",
+ "created_at": "2025-01-01T00:00:00Z",
+ "updated_at": "2025-01-01T00:00:00Z"
+}
+```
+
+## Digital Link Events
+
+Events: `digital_link.created`, `digital_link.updated`, `digital_link.deleted`
+
+```json
+{
+ "id": "dl_4xLq8nRt",
+ "access_counter": 3,
+ "filename": "ebook.pdf",
+ "content_type": "application/pdf",
+ "download_url": "/api/v3/store/digital_downloads/abc123",
+ "authorizable": true,
+ "expired": false,
+ "access_limit_exceeded": false,
+ "created_at": "2025-01-15T10:30:00Z",
+ "updated_at": "2025-01-15T12:00:00Z"
+}
+```
+
+## Import Events
+
+Events: `import.created`, `import.updated`, `import.deleted`
+
+```json
+{
+ "id": "imp_5wPq9mXz",
+ "number": "I123456789",
+ "type": "Spree::Imports::Products",
+ "status": "completed",
+ "owner_type": "Spree::Store",
+ "owner_id": "str_9xPq2wMn",
+ "user_id": "adm_8mXz3wPq",
+ "rows_count": 150,
+ "created_at": "2025-01-15T10:00:00Z",
+ "updated_at": "2025-01-15T10:05:00Z"
+}
+```
+
+## Import Row Events
+
+Events: `import_row.created`, `import_row.updated`, `import_row.deleted`
+
+```json
+{
+ "id": "ir_6nRt2xLq",
+ "import_id": "imp_5wPq9mXz",
+ "row_number": 42,
+ "status": "success",
+ "validation_errors": [],
+ "item_type": "Spree::Product",
+ "item_id": "prod_86Rf07xd4z",
+ "created_at": "2025-01-15T10:01:00Z",
+ "updated_at": "2025-01-15T10:01:00Z"
+}
+```
+
+## Export Events
+
+Events: `export.created`, `export.updated`, `export.deleted`
+
+```json
+{
+ "id": "exp_7xRt4wPq",
+ "number": "E123456789",
+ "type": "Spree::Exports::Products",
+ "format": "csv",
+ "user_id": "adm_8mXz3wPq",
+ "created_at": "2025-01-15T10:00:00Z",
+ "updated_at": "2025-01-15T10:02:00Z"
+}
+```
+
+## Report Events
+
+Events: `report.created`, `report.updated`, `report.deleted`
+
+```json
+{
+ "id": "rep_8mXz3wPq",
+ "type": "Spree::Reports::SalesByProduct",
+ "user_id": "adm_8mXz3wPq",
+ "currency": "USD",
+ "date_from": "2025-01-01T00:00:00Z",
+ "date_to": "2025-01-31T23:59:59Z",
+ "created_at": "2025-02-01T10:00:00Z",
+ "updated_at": "2025-02-01T10:00:00Z"
+}
+```
+
+## Invitation Events
+
+Events: `invitation.created`, `invitation.updated`, `invitation.deleted`
+
+```json
+{
+ "id": "inv_9xPq4wMn",
+ "email": "[email protected]",
+ "status": "pending",
+ "resource_type": "Spree::Store",
+ "resource_id": "str_9xPq2wMn",
+ "inviter_type": "Spree::AdminUser",
+ "inviter_id": "adm_8mXz3wPq",
+ "invitee_type": null,
+ "invitee_id": null,
+ "role_id": "role_2wMn9xPq",
+ "expires_at": "2025-02-15T10:00:00Z",
+ "accepted_at": null,
+ "created_at": "2025-01-15T10:00:00Z",
+ "updated_at": "2025-01-15T10:00:00Z"
+}
+```
diff --git a/docs/developer/cli/quickstart.mdx b/docs/developer/cli/quickstart.mdx
new file mode 100644
index 0000000000..319cc639c4
--- /dev/null
+++ b/docs/developer/cli/quickstart.mdx
@@ -0,0 +1,125 @@
+---
+title: Spree CLI
+sidebarTitle: Overview
+description: Manage your Spree Commerce project from the command line.
+---
+
+The Spree CLI (`@spree/cli`) manages Docker-based Spree projects created with [create-spree-app](/developer/create-spree-app/quickstart).
+
+## Installation
+
+The CLI is included automatically when you scaffold a project with `create-spree-app`. You can also install it globally:
+
+```bash
+npm install -g @spree/cli
+```
+
+Then run commands from your project directory:
+
+```bash
+spree dev
+```
+
+Or use `npx` without installing:
+
+```bash
+npx @spree/cli dev
+```
+
+## Commands
+
+### `spree init`
+
+First-run setup. Starts Docker services, seeds the database, generates an API key, and optionally loads sample data.
+
+```bash
+spree init
+spree init --no-sample-data # Skip sample data
+spree init --no-open # Skip opening browser
+```
+
+### `spree dev`
+
+Start services and stream logs.
+
+```bash
+spree dev
+```
+
+### `spree stop`
+
+Stop all services.
+
+```bash
+spree stop
+```
+
+### `spree update`
+
+Pull the latest Spree Docker image and recreate containers. Migrations run automatically on startup.
+
+```bash
+spree update
+```
+
+### `spree logs`
+
+Stream service logs.
+
+```bash
+spree logs # Web service (default)
+spree logs worker # Worker service
+```
+
+### `spree console`
+
+Open a Rails console.
+
+```bash
+spree console
+```
+
+### `spree open`
+
+Open the admin dashboard in the browser.
+
+```bash
+spree open
+```
+
+### `spree seed`
+
+Seed the database.
+
+```bash
+spree seed
+```
+
+### `spree sample-data`
+
+Load sample products, categories, and images.
+
+```bash
+spree sample-data
+```
+
+### `spree user create`
+
+Create an admin user. Prompts for email and password interactively, or pass them as flags:
+
+```bash
+spree user create
+spree user create --email [email protected] --password secret123
+```
+
+### `spree api-key`
+
+Manage Store and Admin API keys.
+
+```bash
+spree api-key list # List all keys
+spree api-key create # Interactive
+spree api-key create --name "Storefront" --type publishable # Store API key
+spree api-key create --name "Admin" --type secret # Admin API key
+spree api-key revoke <id> # Revoke a key
+```
diff --git a/docs/developer/contributing/developing-spree.mdx b/docs/developer/contributing/developing-spree.mdx
index e0e6167b74..6b6e8d11f2 100644
--- a/docs/developer/contributing/developing-spree.mdx
+++ b/docs/developer/contributing/developing-spree.mdx
@@ -43,15 +43,16 @@ All Spree models, controllers and other Ruby classes are namespaced by the `Spre
```bash
cd server
bin/setup
-bin/rails server
+bin/dev
```
`bin/setup` handles everything: installs Ruby (via [mise](https://mise.jdx.dev) if available, otherwise uses your system Ruby), system packages (libpq, vips), gems, and prepares the database.
-PostgreSQL must be running before you run `bin/setup`. If you don't have it installed locally, start it with Docker:
+PostgreSQL and Redis must be running before you run `bin/setup`. If you don't have them installed locally, start them with Docker:
```bash
docker run -d --name spree-postgres -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres:17-alpine
+docker run -d --name spree-redis -p 6379:6379 redis:7-alpine
```
By default the app connects to PostgreSQL at `localhost:5432` as user `postgres` with no password. Override with environment variables if needed:
@@ -64,6 +65,15 @@ Use `bin/setup --reset` to drop and recreate the database.
The app runs at [http://localhost:3000](http://localhost:3000). Admin Panel is at [http://localhost:3000/admin](http://localhost:3000/admin).
+**Emails in local dev:** By default emails are printed to the Rails log. To catch and preview emails with a web UI, run [Mailpit](https://mailpit.axllent.org) and set `SMTP_HOST`:
+
+```bash
+docker run -d --name mailpit -p 8025:8025 -p 1025:1025 axllent/mailpit
+SMTP_HOST=localhost bin/dev
+```
+
+Then open `http://localhost:8025` to see all outgoing emails.
+
### Running engine tests
Each engine has its own test suite. First install the shared dependencies at the `spree/` level, then navigate into the specific engine to set up and run its tests:
@@ -161,7 +171,7 @@ TypeScript developers don't need Ruby installed. Use Docker Compose from the rep
docker compose up -d
```
-This boots PostgreSQL and the Spree backend automatically. The API is available at `http://localhost:3000`.
+This boots PostgreSQL, Redis, Mailpit, and the Spree backend automatically. The API is available at `http://localhost:3000`. All outgoing emails are caught by Mailpit and viewable at `http://localhost:8025`.
Then install dependencies and start all packages in watch mode:
diff --git a/docs/developer/core-concepts/addresses.mdx b/docs/developer/core-concepts/addresses.mdx
index 5595c25fba..1256402e8d 100644
--- a/docs/developer/core-concepts/addresses.mdx
+++ b/docs/developer/core-concepts/addresses.mdx
@@ -1,145 +1,273 @@
---
title: Addresses
+description: Addresses, countries, states, and zones — how geography drives checkout, taxes, and shipping
---
-### Address Model Diagram
-
-```mermaid
-erDiagram
- Address {
- string firstname
- string lastname
- string address1
- string address2
- string city
- string zipcode
- string phone
- string state_name
- string company
- string label
- }
+## Overview
- Country {
- string name
- string iso
- string iso3
- string iso_name
- integer numcode
- }
+Geography is central to how Spree handles checkout, pricing, taxes, and shipping. The system works through a chain of related concepts:
- State {
- string name
- string abbr
- }
+```
+Markets → Countries → Zones → Tax Rates & Shipping Methods
+ ↘ States
+ ↘ Addresses
+```
- Zone {
- string name
- string description
- boolean default_tax
- string kind
- }
+- [**Markets**](/developer/core-concepts/markets) group countries into selling regions with their own currency and locale
+- **Countries** and **States** provide the geographic data for addresses
+- **Zones** group countries or states together to define where tax rates and shipping methods apply
+- **Addresses** tie a customer to a specific location, determining which zones — and therefore which taxes and shipping options — apply to their order
- ZoneMember {
- string zoneable_type
- }
+## Addresses
- User {
- string email
- integer ship_address_id
- integer bill_address_id
- }
+An address represents a shipping or billing location. Every order has a shipping address and a billing address, and customers can save multiple addresses in their address book.
- Address }o--|| Country : "belongs to"
- Address }o--o| State : "belongs to"
- Address }o--o| User : "belongs to"
- User ||--o{ Address : "has many"
- User }o--o| Address : "default ship"
- User }o--o| Address : "default bill"
- Order }o--|| Address : "ship_address"
- Order }o--|| Address : "bill_address"
- Country ||--o{ State : "has many"
- Zone ||--o{ ZoneMember : "has many"
- ZoneMember }o--o| Country : "member"
- ZoneMember }o--o| State : "member"
-```
+| Field | Description |
+|-------|-------------|
+| `firstname`, `lastname` | Contact name |
+| `address1`, `address2` | Street address |
+| `city` | City |
+| `zipcode` | Postal code (not required for all countries) |
+| `phone` | Phone number |
+| `company` | Company name (optional) |
+| `label` | User-facing label like "Home" or "Office" (optional, unique per customer) |
+| `country_iso` | Country (ISO alpha-2 code, e.g., `US`) |
+| `state_abbr` | State/province abbreviation (required for some countries, e.g., `CA`) |
-**Key relationships:**
-- **Address** stores shipping/billing information for [Orders](/developer/core-concepts/orders) and Users
-- **Country** and **State** provide geographic data for addresses
-- **Zone** groups countries or states for [tax](/developer/core-concepts/taxes) and [shipping](/developer/core-concepts/shipments) rules
-- **Zone Members** link zones to their geographic components
+Whether a state or zipcode is required depends on the country. For example, the US requires both, while Hong Kong requires neither. The API returns `states_required` and `zipcode_required` on each country so your frontend can adapt the form dynamically.
-The `Spree::Address` model is used to track address information, mainly for orders. Address information can also be tied to the `Spree.user_class` which by default is `Spree::User` ([More on Users](users)).
+### Customer Address Book
-Addresses have the following attributes:
+Customers can save multiple addresses and set a default for shipping and billing. When a customer completes checkout, the selected addresses are cloned onto the order — so editing an address later doesn't change past orders.
-| Name | Description | Example Value |
-|--------------------|---------------------------------------|---------------------|
-| `firstname` | The first name for the person at this address. | John |
-| `lastname` | The last name for the person at this address. | Doe |
-| `address1` | The address's first line. | 123 Main St |
-| `address2` | (Optional) The address's second line. | Apt 4 |
-| `city` | The city where the address is. | Springfield |
-| `zipcode` | The postal code. | 12345 |
-| `phone` | The phone number. | (123) 456-7890 |
-| `state_name` | The name for the state. | California |
-| `alternative_phone`| (Optional) The alternative phone number. | (098) 765-4321 |
-| `company` | (Optional) A company name. | Acme Corporation |
-| `country_id` | The ID for the country. | 1 |
-| `state_id` | (Optional) The ID for the state. | 2 |
-| `user_id` | (Optional) The ID of the user this address is associated with. | 10 |
-| `label` | (Optional) A label to identify the address. | Home |
+<CodeGroup>
+```typescript SDK
+// List addresses
+const { data: addresses } = await client.store.customer.addresses.list()
+// Create an address
+const address = await client.store.customer.addresses.create({
+ firstname: 'John',
+ lastname: 'Doe',
+ address1: '123 Main St',
+ city: 'Los Angeles',
+ country_iso: 'US',
+ state_abbr: 'CA',
+ zipcode: '90001',
+ phone: '555-0100',
+})
+// Update an address
+await client.store.customer.addresses.update('addr_xxx', { city: 'Brooklyn' })
-<Note>
-An address must always link to a `Spree::Country` object. It can optionally link to a `Spree::State` object, but only in the cases where the related country has no states listed. In that case, the state information is still required, and is kept within the `state_name` field on the address record. An easy way to get the state information for the address is to call `state_text` on that object.
-</Note>
+// Delete an address
+await client.store.customer.addresses.delete('addr_xxx')
-## Customers
+// Set as default shipping or billing address
+await client.store.customer.addresses.markAsDefault('addr_xxx', 'shipping')
+```
-Users can have multiple addresses and can manage them on the Checkout and Account page (or via API). Each `Spree::Address` object has a `user_id` column which links to the User.
+```bash cURL
+# List addresses
+curl 'https://api.mystore.com/api/v3/store/customer/addresses' \
+ -H 'Authorization: Bearer <jwt_token>'
+
+# Create an address
+curl -X POST 'https://api.mystore.com/api/v3/store/customer/addresses' \
+ -H 'Authorization: Bearer <jwt_token>' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "firstname": "John",
+ "lastname": "Doe",
+ "address1": "123 Main St",
+ "city": "Los Angeles",
+ "country_iso": "US",
+ "state_abbr": "CA",
+ "zipcode": "90001",
+ "phone": "555-0100"
+ }'
+
+# Update an address
+curl -X PATCH 'https://api.mystore.com/api/v3/store/customer/addresses/addr_xxx' \
+ -H 'Authorization: Bearer <jwt_token>' \
+ -H 'Content-Type: application/json' \
+ -d '{ "city": "Brooklyn" }'
+
+# Delete an address
+curl -X DELETE 'https://api.mystore.com/api/v3/store/customer/addresses/addr_xxx' \
+ -H 'Authorization: Bearer <jwt_token>'
+```
-Additionally in `Spree.user_class` there are `ship_address_id` and `bill_address_id` columns which indicate the default addresses for this User.
+</CodeGroup>
+
+### Checkout Addresses
+
+During checkout, you can either reference a saved address by ID or pass a new address inline:
+
+<CodeGroup>
+
+```typescript SDK
+// Use saved addresses
+await client.store.orders.update(orderId, {
+ ship_address_id: 'addr_xxx',
+ bill_address_id: 'addr_yyy',
+})
+
+// Or pass new addresses inline
+await client.store.orders.update(orderId, {
+ ship_address: {
+ firstname: 'John',
+ lastname: 'Doe',
+ address1: '123 Main St',
+ city: 'Los Angeles',
+ country_iso: 'US',
+ state_abbr: 'CA',
+ zipcode: '90001',
+ phone: '555-0100',
+ },
+})
+```
-## Checkout
+```bash cURL
+# Use a saved address
+curl -X PATCH 'https://api.mystore.com/api/v3/store/orders/or_xxx' \
+ -H 'Authorization: Bearer spree_pk_xxx' \
+ -H 'X-Spree-Order-Token: order_token' \
+ -H 'Content-Type: application/json' \
+ -d '{ "ship_address_id": "addr_xxx", "bill_address_id": "addr_yyy" }'
+
+# Or pass a new address inline
+curl -X PATCH 'https://api.mystore.com/api/v3/store/orders/or_xxx' \
+ -H 'Authorization: Bearer spree_pk_xxx' \
+ -H 'X-Spree-Order-Token: order_token' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "ship_address": {
+ "firstname": "John",
+ "lastname": "Doe",
+ "address1": "123 Main St",
+ "city": "Los Angeles",
+ "country_iso": "US",
+ "state_abbr": "CA",
+ "zipcode": "90001",
+ "phone": "555-0100"
+ }
+ }'
+```
-When a signed in User completes the Checkout Spree clones the selected Shipping and Billing Addresses and associates them with the Order. We do so that even if User modifies those addresses in the future their current state is preserved. Cloned addresses aren't associated to the User anymore. Originals will still be visible in their Address Books for future use.
+</CodeGroup>
-## Zones
+## Countries
-When an order's address is linked to a country or a state, that can ultimately affect different features of the order, including shipping availability and taxation. The way these effects work is through zones.
+Countries are the foundation of Spree's geographic system. They connect to [Markets](/developer/core-concepts/markets), contain states, and belong to zones.
-A zone is comprised of many different "zone members", which can either be a set of countries or a set of states.
+Each country includes metadata that drives address form behavior:
-Every order has a "tax zone", which indicates if a user should or shouldn't be taxed when placing an order. For more information, please see the [Taxes](taxes) guide.
+| Field | Description | Example |
+|-------|-------------|---------|
+| `iso` | ISO 3166-1 alpha-2 code | `US` |
+| `iso3` | ISO 3166-1 alpha-3 code | `USA` |
+| `name` | Country name | `United States` |
+| `states_required` | Whether the address form should show a state/province picker | `true` |
+| `zipcode_required` | Whether the address form should require a postal code | `true` |
-In addition to tax zones, orders also have shipping methods. These are provided to the user based on their address information, and once selected lock in how an order is going to be shipped to that user. For more information, please see the [Shipments](shipments) guide.
+### Which Countries Are Available?
-## Countries
+Only countries assigned to a [Market](/developer/core-concepts/markets) are available during checkout. This lets you control exactly where you sell.
+
+<CodeGroup>
-Countries within Spree are used as a container for states. Countries can be zone members, and also link to an address. The difference between one country and another on an address record can determine which tax rates and shipping methods are used for the order.
+```typescript SDK
+// List all countries available in this store
+const { data: countries } = await client.store.countries.list()
-Country data is provided by [Carmen gem](https://github.com/carmen-ruby/carmen) which is a library for manipulating country data.
+// Get a country with its states (for address form dropdowns)
+const usa = await client.store.countries.get('US', { include: 'states' })
+// usa.states => [{ name: "Alabama", abbr: "AL" }, { name: "Alaska", abbr: "AK" }, ...]
-`Spree::Country` model includes these attributes:
+// Get a country with its market (for currency/locale resolution)
+const germany = await client.store.countries.get('DE', { include: 'market' })
+// germany.market => { currency: "EUR", default_locale: "de", tax_inclusive: true }
+```
+
+```bash cURL
+# List all countries
+curl 'https://api.mystore.com/api/v3/store/countries' \
+ -H 'Authorization: Bearer spree_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'
+
+# Get a country with its market
+curl 'https://api.mystore.com/api/v3/store/countries/DE?include=market' \
+ -H 'Authorization: Bearer spree_pk_xxx'
+```
-| Name | Description | Example Value |
-|--------------------|---------------------------------------|---------------------|
-| `iso_name` | The ISO 3166-1 alpha-2 code for the country. | US |
-| `iso` | The ISO 3166-1 alpha-3 code for the country. | USA |
-| `iso_numeric` | The ISO 3166-1 numeric code for the country. | 840 |
-| `name` | The name of the country. | United States |
+</CodeGroup>
+
+Use the `states_required` and `zipcode_required` fields to build adaptive address forms — show a state picker only when needed, and skip the zipcode field for countries that don't use them.
## States
-States, or regions, provinces, or districts are used to scope address data slightly more than country. States are useful for tax purposes, as different states in a country may impose different tax rates on different products. In addition to this, different states may cause different tax rates and shipping methods to be used for an order, similar to how countries affect it also.
+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.
-## Related Documentation
+States are fetched via the country endpoint using `?include=states`:
+
+<CodeGroup>
+
+```typescript SDK
+const usa = await client.store.countries.get('US', { include: 'states' })
+
+// Build a state picker from the response
+usa.states.forEach(state => {
+ console.log(state.abbr, state.name) // "AL", "Alabama"
+})
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/countries/US?include=states' \
+ -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+</CodeGroup>
+
+For countries without predefined states, addresses accept a free-text `state_name` field instead of `state_abbr`.
+
+## Zones
+
+Zones group countries or states together for [tax](/developer/core-concepts/taxes) and [shipping](/developer/core-concepts/shipments) rules. A zone is either **country-based** or **state-based**.
+
+**Examples:**
+- **EU VAT** (country zone) — Germany, France, Italy, Spain, ... → applies EU VAT rates
+- **California** (state zone) — CA → applies California sales tax
+- **Domestic Shipping** (country zone) — US, CA → enables domestic shipping methods
+
+When a customer enters their address at checkout, Spree matches it against zones to determine:
+1. Which **tax rates** apply (see [Taxes](/developer/core-concepts/taxes))
+2. Which **shipping methods** are available (see [Shipments](/developer/core-concepts/shipments))
+
+Zones are configured in the admin dashboard — storefront developers don't interact with them directly via the API.
+
+### Tax Zones and Markets
-- [Users](/developer/core-concepts/users) - User accounts and address books
-- [Taxes](/developer/core-concepts/taxes) - How addresses affect taxation
-- [Shipments](/developer/core-concepts/shipments) - How addresses affect shipping
-- [Orders](/developer/core-concepts/orders) - Order billing and shipping addresses
+Each [Market](/developer/core-concepts/markets) resolves a tax zone from its default country. This means product prices display the correct tax treatment (inclusive or exclusive) before the customer enters an address — just from knowing their market.
+
+## How It All Fits Together
+
+Here's how geography flows through a typical checkout:
+
+1. **Customer visits the store** — their country is detected (from URL, geolocation, or selection)
+2. **Market resolved** — the country maps to a market, which sets the currency and locale
+3. **Products displayed** — prices use the market's currency and tax zone for correct formatting
+4. **Customer enters address** — the address form adapts based on `states_required` and `zipcode_required`
+5. **Zones matched** — the shipping address determines which tax rates and shipping methods apply
+6. **Order completed** — the address is cloned onto the order for permanent record
+
+## Related Documentation
+- [Markets](/developer/core-concepts/markets) — Multi-region commerce with currency, locale, and country grouping
+- [Taxes](/developer/core-concepts/taxes) — How zones and addresses affect taxation
+- [Shipments](/developer/core-concepts/shipments) — How zones and addresses affect shipping availability
+- [Orders](/developer/core-concepts/orders) — Order billing and shipping addresses
diff --git a/docs/developer/core-concepts/adjustments.mdx b/docs/developer/core-concepts/adjustments.mdx
index 878f4e9a9b..e27fcba1a5 100644
--- a/docs/developer/core-concepts/adjustments.mdx
+++ b/docs/developer/core-concepts/adjustments.mdx
@@ -1,10 +1,11 @@
---
title: Adjustments
+description: How taxes, promotions, and other price modifications are applied to orders
---
## Overview
-### Adjustment Model Diagram
+An Adjustment modifies the price of an [Order](/developer/core-concepts/orders), a [Line Item](/developer/core-concepts/orders#line-items), or a [Shipment](/developer/core-concepts/shipments). Adjustments can be positive (charges) or negative (credits).
```mermaid
erDiagram
@@ -19,34 +20,6 @@ erDiagram
string adjustable_type
}
- Order {
- string number
- decimal adjustment_total
- decimal total
- }
-
- LineItem {
- integer quantity
- decimal price
- decimal adjustment_total
- }
-
- Shipment {
- string number
- decimal cost
- decimal adjustment_total
- }
-
- TaxRate {
- string name
- decimal amount
- boolean included_in_price
- }
-
- PromotionAction {
- string type
- }
-
Order ||--o{ Adjustment : "has many"
Order ||--o{ LineItem : "has many"
Order ||--o{ Shipment : "has many"
@@ -62,164 +35,76 @@ erDiagram
- **Adjustable** is what's being adjusted (Order, LineItem, or Shipment)
- Positive amounts are charges, negative amounts are credits
-An `Adjustment` object tracks an adjustment to the price of an [Order](orders), an order's [Line Item](orders#line-items), or an order's [Shipments](shipments) within a Spree application.
-
-Adjustments can be either positive or negative. Adjustments with a positive value are sometimes referred to as "charges" while adjustments with a negative value are sometimes referred to as "credits." These are just terms of convenience since there is only one `Spree::Adjustment` model in a storefront which handles this by allowing either positive or negative values.
-
-Adjustments can either be considered included or additional. An "included" adjustment is an adjustment to the price of an item which is included in that price of an item. A good example of this is a GST/VAT tax. An "additional" adjustment is an adjustment to the price of the item on top of the original item price. A good example of that would be how sales tax is handled in countries like the United States.
+## Adjustment Types
-Adjustments have the following attributes:
+### Included vs Additional
-* `amount` The dollar amount of the adjustment.
-* `label`: The label for the adjustment to indicate what the adjustment is for.
-* `eligible`: Indicates if the adjustment is eligible for the thing it's adjusting.
-* `mandatory`: Indicates if this adjustment is mandatory; i.e that this adjustment _must_ be applied regardless of its eligibility rules.
-* `state`: Can either be `open` or `closed`. Once an adjustment is closed, it will not be automatically updated.
-* `included`: Whether or not this adjustment affects the final price of the item it is applied to. Used only for tax adjustments which may themselves be included in the price.
+- **Included** adjustments are part of the item's displayed price (e.g., VAT in European stores)
+- **Additional** adjustments are added on top of the item's price (e.g., US sales tax)
-Along with these attributes, an adjustment links to three polymorphic objects:
+### Sources
-* A source
-* An adjustable
+Adjustments are created by two sources:
-The _source_ is the source of the adjustment. Typically a `Spree::TaxRate` object or a `Spree::PromotionAction` object.
+| Source | Example | Typical Amount |
+|--------|---------|----------------|
+| [Tax Rate](/developer/core-concepts/taxes) | Sales tax, VAT | Positive (charge) |
+| [Promotion Action](/developer/core-concepts/promotions) | Coupon discount, free shipping | Negative (credit) |
-The _adjustable_ is the object being adjusted, which is either an order, line item or shipment.
+## Adjustment Attributes
-Adjustments can come from one of two locations within Spree's core:
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `amount` | The monetary value of the adjustment | `-10.00` |
+| `label` | Human-readable description | `10% off order` |
+| `eligible` | Whether the adjustment currently applies | `true` |
+| `mandatory` | If `true`, always applied regardless of eligibility rules | `false` |
+| `state` | `open` (auto-updated) or `closed` (locked) | `open` |
+| `included` | Whether the amount is included in the item's displayed price | `false` |
-* Tax Rates
-* Promotions
+## Adjustment Lifecycle
-An adjustment's `label` attribute can be used as a good indicator of where the adjustment is coming from.
+- **Open** adjustments are recalculated whenever the order is updated (e.g., items added/removed, address changed)
+- **Closed** adjustments are locked and will not be automatically recalculated
+- When a promotion becomes ineligible (e.g., item removed from cart), its adjustments are automatically removed
-## Adjustment Scopes
+## Store API
-There are some helper methods to return the different types of adjustments:
+Adjustments appear in order responses when you expand line items or shipments:
-```ruby
-scope :shipping, -> { where(adjustable_type: 'Spree::Shipment') }
-scope :is_included, -> { where(included: true) }
-scope :additional, -> { where(included: false) }
-```
-
-* `open`: All open adjustments.
-* `tax`: All adjustments which have a source that is a `Spree::TaxRate` object
-* `price`: All adjustments which adjust a `Spree::LineItem` object.
-* `shipping`: All adjustments which adjust a `Spree::Shipment` object.
-* `promotion`: All adjustments where the source is a `Spree::PromotionAction` object.
-* `optional`: All adjustments which are not `mandatory`.
-* `return_authorization`: All adjustments where the source is a `Spree::ReturnAuthorization`.
-* `eligible`: Adjustments which have been determined to be `eligible` for their adjustable. Useful for determining which adjustments are applying to the adjustable.
-* `charge`: Adjustments which _increase_ the price of their adjustable.
-* `credit`: Adjustments which _decrease_ the price of their adjustable.
-* `included`: Adjustments which are included in the object's price. Typically tax adjustments.
-* `additional`: Adjustments which modify the object's price. The default for all adjustments.
-
-These scopes can be called on either the `Spree::Adjustment` class itself, or on an `adjustments` association. For example, calling any one of these three is valid:
-
-```ruby
-Spree::Adjustment.eligible
-order.adjustments.eligible
-line_item.adjustments.eligible
-shipment.adjustments.eligible
-```
-
-## Adjustment Associations
+<CodeGroup>
-You are able to retrieve the specific adjustments of an Order, a Line Item or a Shipment.
-
-An order itself, much like line items and shipments, can have its own individual modifications. For instance, an order with over $100 of line items may have 10% off. To retrieve these adjustments on the order, call the `adjustments` association:
-
-```ruby
-order.adjustments
-```
-
-If you want to retrieve all the adjustments for all the line items, shipments and the order itself, call the `all_adjustments` method:
-
-```ruby
-order.all_adjustments
-```
-
-If you want to grab just the line item adjustments, call `line_item_adjustments`:
-
-```ruby
-order.line_item_adjustments
-```
+```typescript SDK
+const order = await client.store.orders.get('or_abc123', {
+ expand: ['line_items', 'shipments'],
+ orderToken: '<token>',
+})
-Similarly, if you want to grab the adjustments applied to shipments, call `shipment_adjustments`:
+// Line item adjustments (promotions, taxes)
+order.line_items?.forEach(item => {
+ item.adjustment_total // total adjustments on this item
+ item.additional_tax_total
+ item.included_tax_total
+})
-```ruby
-order.shipment_adjustments
+// Order-level totals
+order.adjustment_total // total of all adjustments
+order.promo_total // total promotional discounts
+order.additional_tax_total
+order.included_tax_total
```
-## Extending Adjustments
-
-### Creating a New Adjuster
-
-To create a new adjuster for Spree, create a new ruby object that inherits from `Spree::Adjustable::Adjuster::Base` and implements an `update` method:
-
-```ruby app/models/spree/adjustable/adjuster/my_adjuster.rb
-module Spree
- module Adjustable
- module Adjuster
- class MyAdjuster < Spree::Adjustable::Adjuster::Base
- def update
- ...
- #your ruby magic
- ...
- update_totals(some_total, my_other_total)
- end
-
- private
-
- # Note to persist your totals you need to update @totals
- # This is shown in a separate method for readability
- def update_totals(some_total, my_other_total)
- # if you want to keep track of your total,
- # you will need the column defined
- @totals[:total_you_want_to_track] += some_total
- @totals[:taxable_adjustment_total] += some_total
- @totals[:non_taxable_adjustment_total] += my_other_total
- end
- end
- end
- end
-end
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/orders/or_abc123?expand=line_items,shipments' \
+ -H 'Authorization: Bearer spree_pk_xxx' \
+ -H 'X-Spree-Order-Token: <token>'
```
-Next you need to add the class to spree `Spree.adjusters` so it is included whenever adjustments are updated Promotion and Tax are included by default:
-
-<Tabs>
- <Tab title="Spree 5.2+">
- ```ruby config/initializers/spree.rb
- Rails.application.config.after_initialize do
- Spree.adjusters = [
- Spree::Adjustable::Adjuster::MyAdjuster,
- Spree::Adjustable::Adjuster::Promotion,
- Spree::Adjustable::Adjuster::Tax
- ]
- end
- ```
- </Tab>
- <Tab title="Spree 5.1 and below">
- ```ruby config/initializers/spree.rb
- Rails.application.config.after_initialize do
- Rails.application.config.spree.adjusters = [
- Spree::Adjustable::Adjuster::MyAdjuster,
- Spree::Adjustable::Adjuster::Promotion,
- Spree::Adjustable::Adjuster::Tax
- ]
- end
- ```
- </Tab>
-</Tabs>
-
-That's it! Your custom adjuster is ready to go.
+</CodeGroup>
## Related Documentation
-- [Promotions](/developer/core-concepts/promotions) - Promotion-based adjustments
-- [Taxes](/developer/core-concepts/taxes) - Tax adjustments
-- [Shipments](/developer/core-concepts/shipments) - Shipping adjustments
-- [Orders](/developer/core-concepts/orders) - How adjustments affect order totals
+- [Promotions](/developer/core-concepts/promotions) — Promotion-based adjustments
+- [Taxes](/developer/core-concepts/taxes) — Tax adjustments
+- [Shipments](/developer/core-concepts/shipments) — Shipping adjustments
+- [Orders](/developer/core-concepts/orders) — How adjustments affect order totals
diff --git a/docs/developer/core-concepts/architecture.mdx b/docs/developer/core-concepts/architecture.mdx
index 20871ffbc4..df0b047be1 100644
--- a/docs/developer/core-concepts/architecture.mdx
+++ b/docs/developer/core-concepts/architecture.mdx
@@ -1,25 +1,16 @@
---
title: Architecture
-description: Understand how Spree's core models and systems work together
+description: How Spree's core models, APIs, and packages work together
---
-## System Requirements
+## Overview
-| Component | Requirement |
-|-----------|-------------|
-| **Ruby** | 3.2 or later |
-| **Rails** | 7.2 or later |
-| **Database** | PostgreSQL, MySQL, or SQLite |
-| **Image Processing** | libvips |
+Spree is a commerce engine built around interconnected models that represent the core concepts of commerce: products, orders, payments, and shipments. It adapts to your stack — use it as a headless API for any frontend, embed it into an existing application, or scale it from a single storefront to a global multi-vendor marketplace.
<Info>
- Spree works with any database supported by Rails. PostgreSQL and MySQL are recommended for production. SQLite is great for development and small-scale deployments. [Learn more about database configuration](/developer/deployment/database).
+ Spree supports PostgreSQL, MySQL, and SQLite. PostgreSQL is recommended for production. [Learn more about database configuration](/developer/deployment/database).
</Info>
-## Overview
-
-Spree is built around a set of interconnected models that represent the core concepts of e-commerce: products, orders, payments, and shipments. Understanding how these pieces fit together is essential for customizing and extending Spree.
-
## Core Commerce Flow
The following diagram shows how the main models interact during a typical customer purchase:
@@ -64,15 +55,15 @@ flowchart TB
**How it works:**
-1. **Catalog** - [Products](/developer/core-concepts/products) have [Variants](/developer/core-concepts/products#variants) (SKUs) with prices and inventory tracked at [Stock Locations](/developer/core-concepts/inventory#stock-locations)
+1. **Catalog** — [Products](/developer/core-concepts/products) have [Variants](/developer/core-concepts/products#variants) (SKUs) with prices and inventory tracked at [Stock Locations](/developer/core-concepts/inventory#stock-locations)
-2. **Shopping** - Customers add Variants to their cart, creating an [Order](/developer/core-concepts/orders) with Line Items
+2. **Shopping** — Customers add Variants to their cart, creating an [Order](/developer/core-concepts/orders) with Line Items
-3. **Checkout** - The Order collects [Addresses](/developer/core-concepts/addresses), calculates [Shipping](/developer/core-concepts/shipments) options, and processes [Payments](/developer/core-concepts/payments)
+3. **Checkout** — The Order collects [Addresses](/developer/core-concepts/addresses), calculates [Shipping](/developer/core-concepts/shipments) options, and processes [Payments](/developer/core-concepts/payments)
-4. **Fulfillment** - [Shipments](/developer/core-concepts/shipments) are created from Stock Locations, tracking individual [Inventory Units](/developer/core-concepts/inventory#inventory-units)
+4. **Fulfillment** — [Shipments](/developer/core-concepts/shipments) are created from Stock Locations, tracking individual [Inventory Units](/developer/core-concepts/inventory#inventory-units)
-5. **Pricing & Adjustments** - [Taxes](/developer/core-concepts/taxes) and [Promotions](/developer/core-concepts/promotions) create [Adjustments](/developer/core-concepts/adjustments) that modify order totals
+5. **Pricing & Adjustments** — [Taxes](/developer/core-concepts/taxes) and [Promotions](/developer/core-concepts/promotions) create [Adjustments](/developer/core-concepts/adjustments) that modify order totals
## Core Model Relationships
@@ -115,9 +106,22 @@ erDiagram
Promotion ||--o{ Adjustment : "creates"
```
+## APIs
+
+Spree exposes two REST APIs, both under API v3:
+
+| API | Purpose | Authentication |
+|-----|---------|----------------|
+| [**Store API**](/api-reference/introduction) | Customer-facing — cart, checkout, products, account | Publishable API key + JWT |
+| **Admin API** | Operational — manage products, orders, customers, settings | Secret API key |
+
+Both APIs use [prefixed IDs](/api-reference/introduction) (e.g., `prod_86Rf07xd4z`, `or_m3Rp9wXz`), flat JSON request/response structures, and full TypeScript types via the [@spree/sdk](/developer/sdk/quickstart).
+
+Events from both APIs can trigger [Webhooks](/developer/core-concepts/webhooks) to notify external systems in real time.
+
## Multi-Store Architecture
-Spree can work in [Multi-Store model](/developer/multi-store/quickstart) from a single installation. Each Store can have:
+Spree supports [multiple stores](/developer/multi-store/quickstart) from a single installation. Each Store can have:
- Its own domain and branding
- Different currencies and locales
@@ -142,43 +146,38 @@ Spree is designed to be customized without modifying core code. The main extensi
For most customizations, prefer **Events** and **Dependencies** over Decorators. They're easier to maintain and won't break during upgrades.
</Info>
-## Code Conventions
-
-Spree is built on [Ruby on Rails](https://rubyonrails.org) and follows Model-View-Controller (MVC) architecture. All Spree code is namespaced under `Spree::` to avoid conflicts with your application code.
-
-**Example: Product**
-
-| Component | Location | Class Name |
-|-----------|----------|------------|
-| Model | `core/app/models/spree/product.rb` | `Spree::Product` |
-| Admin Controller | `admin/app/controllers/spree/admin/products_controller.rb` | `Spree::Admin::ProductsController` |
-| API Serializer | `api/app/serializers/spree/v2/storefront/product_serializer.rb` | `Spree::V2::Storefront::ProductSerializer` |
-
## Packages
-Spree is distributed as a set of Ruby gems (packages). Most users run Spree in **headless mode** with a custom frontend built using the [Storefront API](/api-reference/storefront) or [Platform API](/api-reference/platform).
+Spree is distributed as a set of packages:
-**Core packages** (required):
+**Core (required):**
| Package | Purpose |
|---------|---------|
-| `spree` | Models, services, business logic, API and Webhooks |
+| `spree` | Models, services, business logic, Store API, Admin API, and Webhooks |
-**Optional packages:**
+**Optional:**
| Package | Purpose |
|---------|---------|
| `spree_admin` | Admin dashboard for managing your store |
| `spree_emails` | Transactional email templates (order confirmation, shipping, etc.) |
+**TypeScript packages:**
+
+| Package | Purpose |
+|---------|---------|
+| [`@spree/sdk`](/developer/sdk/quickstart) | TypeScript SDK for Store API and Admin API |
+| [`@spree/next`](/developer/storefront/nextjs/spree-next-package) | Next.js integration — server actions, caching, cookie-based auth |
+
<Info>
-For headless commerce, you only need `spree` package. Build your customer-facing frontend with any technology (Next.js, Nuxt, mobile apps) using the Store API and SDK.
+For headless commerce, you only need the `spree` package. Build your customer-facing frontend with any technology (Next.js, Nuxt, mobile apps) using the Store API and SDK.
</Info>
## Related Documentation
-- [Products](/developer/core-concepts/products) - Product catalog and variants
-- [Orders](/developer/core-concepts/orders) - Order lifecycle and state machine
-- [Payments](/developer/core-concepts/payments) - Payment processing
-- [Shipments](/developer/core-concepts/shipments) - Shipping and fulfillment
-- [Customization Quickstart](/developer/customization/quickstart) - How to extend Spree
+- [Products](/developer/core-concepts/products) — Product catalog and variants
+- [Orders](/developer/core-concepts/orders) — Order lifecycle and state machine
+- [Payments](/developer/core-concepts/payments) — Payment processing
+- [Shipments](/developer/core-concepts/shipments) — Shipping and fulfillment
+- [Customization Quickstart](/developer/customization/quickstart) — How to extend Spree
diff --git a/docs/developer/core-concepts/customers.mdx b/docs/developer/core-concepts/customers.mdx
new file mode 100644
index 0000000000..0dcb2a41d1
--- /dev/null
+++ b/docs/developer/core-concepts/customers.mdx
@@ -0,0 +1,180 @@
+---
+title: Customers
+description: Customer accounts — registration, authentication, profiles, and guest checkout
+---
+
+## Overview
+
+Customers interact with your store through the Store API. They can register, log in, manage their profile, and view order history.
+
+```mermaid
+erDiagram
+ Customer ||--o{ Order : "places"
+ Customer ||--o{ Address : "has many"
+ Customer ||--o{ Wishlist : "has many"
+ Customer ||--o{ StoreCredit : "has many"
+ Customer ||--o{ PaymentSource : "has many"
+
+ Customer {
+ string id
+ string email
+ string first_name
+ string last_name
+ }
+
+ Order {
+ string number
+ string state
+ }
+
+ Address {
+ string firstname
+ string lastname
+ string address1
+ string city
+ }
+
+ Wishlist {
+ string name
+ boolean is_default
+ }
+```
+
+## Registration
+
+<CodeGroup>
+
+```typescript SDK
+const { token, user } = await client.store.auth.register({
+ email: '[email protected]',
+ password: 'password123',
+ password_confirmation: 'password123',
+ first_name: 'John',
+ last_name: 'Doe',
+})
+// token => JWT token for subsequent authenticated requests
+// user => { id: "usr_xxx", email: "[email protected]", first_name: "John", ... }
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/store/auth/register' \
+ -H 'Authorization: Bearer spree_pk_xxx' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "email": "[email protected]",
+ "password": "password123",
+ "password_confirmation": "password123",
+ "first_name": "John",
+ "last_name": "Doe"
+ }'
+```
+
+</CodeGroup>
+
+## Login
+
+<CodeGroup>
+
+```typescript SDK
+const { token, user } = await client.store.auth.login({
+ email: '[email protected]',
+ password: 'password123',
+})
+// Use the token for authenticated requests
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/store/auth/login' \
+ -H 'Authorization: Bearer spree_pk_xxx' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "email": "[email protected]",
+ "password": "password123"
+ }'
+```
+
+</CodeGroup>
+
+The response includes a JWT `token` and a `user` object. Pass the token in subsequent requests via the `Authorization: Bearer <token>` header.
+
+## Token Refresh
+
+Refresh an expiring token to keep the session alive:
+
+<CodeGroup>
+
+```typescript SDK
+const { token } = await client.store.auth.refresh({
+ token: existingToken,
+})
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/store/auth/refresh' \
+ -H 'Authorization: Bearer <jwt_token>'
+```
+
+</CodeGroup>
+
+## Customer Profile
+
+<CodeGroup>
+
+```typescript SDK
+// Get current customer
+const customer = await client.store.customer.get()
+// {
+// id: "usr_xxx",
+// email: "[email protected]",
+// first_name: "John",
+// last_name: "Doe",
+// default_shipping_address: { ... },
+// default_billing_address: { ... },
+// addresses: [{ ... }, { ... }],
+// }
+
+// Update profile
+const updated = await client.store.customer.update({
+ first_name: 'Jonathan',
+ accepts_email_marketing: true,
+})
+```
+
+```bash cURL
+# Get current customer
+curl 'https://api.mystore.com/api/v3/store/customer' \
+ -H 'Authorization: Bearer <jwt_token>'
+
+# Update profile
+curl -X PATCH 'https://api.mystore.com/api/v3/store/customer' \
+ -H 'Authorization: Bearer <jwt_token>' \
+ -H 'Content-Type: application/json' \
+ -d '{ "first_name": "Jonathan", "accepts_email_marketing": true }'
+```
+
+</CodeGroup>
+
+## Customer Resources
+
+Authenticated customers have access to these resources:
+
+| Resource | Description |
+|----------|-------------|
+| [**Addresses**](/developer/core-concepts/addresses#customer-address-book) | Billing and shipping addresses with default selection |
+| [**Orders**](/developer/core-concepts/orders#order-history) | Past order history |
+| **Credit Cards** | Saved credit cards for checkout |
+| **Payment Sources** | Other saved payment methods (PayPal, Klarna, etc.) |
+| **Store Credits** | Balance assigned by the store, usable at checkout |
+| **Gift Cards** | Gift cards owned by or assigned to the customer |
+| **Wishlists** | Saved product lists |
+
+## Guest Checkout
+
+Customers don't need to register to purchase. Guest checkout uses an order token (`X-Spree-Order-Token`) to identify the cart. See [Orders — Cart](/developer/core-concepts/orders#cart) for details.
+
+## Related Documentation
+
+- [Addresses](/developer/core-concepts/addresses) — Customer address management
+- [Orders](/developer/core-concepts/orders) — Order history and checkout
+- [Authentication](/developer/customization/authentication) — Custom authentication setup
+- [Staff & Roles](/developer/core-concepts/staff-roles) — Admin users and permissions
diff --git a/docs/developer/core-concepts/events.mdx b/docs/developer/core-concepts/events.mdx
index baa4449670..c20f57bc6e 100644
--- a/docs/developer/core-concepts/events.mdx
+++ b/docs/developer/core-concepts/events.mdx
@@ -17,13 +17,13 @@ This pattern enables loose coupling between components and makes it easy to:
## How Events Work
-Spree's event system is built on top of [`ActiveSupport::Notifications`](https://api.rubyonrails.org/classes/ActiveSupport/Notifications.html) but provides a cleaner, more Rails-like API through:
+Spree's event system provides a clean API through:
1. **`Spree::Events`** - The main module for publishing and subscribing to events
2. **`Spree::Subscriber`** - Base class for creating event subscribers
3. **`Spree::Publishable`** - Concern that enables models to publish events
-When an event is published, all matching subscribers are notified. By default, subscribers run asynchronously via ActiveJob to avoid blocking the main request.
+When an event is published, all matching subscribers are notified. By default, subscribers run asynchronously via background jobs to avoid blocking the main request.
```mermaid
flowchart TB
@@ -36,7 +36,7 @@ flowchart TB
subgraph Event Adapter
D --> E[Find Matching Subscribers]
E --> F{Async?}
- F -->|Yes| G[Queue ActiveJob]
+ F -->|Yes| G[Queue Background Job]
F -->|No| H[Execute Immediately]
end
@@ -88,7 +88,7 @@ class MySubscriber < Spree::Subscriber
subscribes_to 'order.*' # All order events
subscribes_to '*.*' # All events (use sparingly!)
- # Run synchronously instead of via ActiveJob
+ # Run synchronously instead of via background job
subscribes_to 'order.complete', async: false
end
```
@@ -281,132 +281,80 @@ Spree::Events.publish(
## Event Serializers
-Event payloads are generated by dedicated serializer classes. Each model that publishes events needs a corresponding serializer in the `Spree::Events` namespace.
+Event payloads are generated using the same [Store API V3 serializers](/api-reference/introduction) used by the REST API. This means webhook payloads and API responses share the same schema, making it easy to reuse types in your integrations.
### How Serializers Work
-When a model publishes an event, Spree looks for a serializer class matching the model name:
+When a model publishes an event, Spree looks for a V3 serializer class matching the model name:
-- `Spree::Order` → `Spree::Events::OrderSerializer`
-- `Spree::Product` → `Spree::Events::ProductSerializer`
-- `Spree::Payment` → `Spree::Events::PaymentSerializer`
+- `Spree::Order` → `Spree::Api::V3::OrderSerializer`
+- `Spree::Product` → `Spree::Api::V3::ProductSerializer`
+- `Spree::Payment` → `Spree::Api::V3::PaymentSerializer`
-The serializer converts the model into a hash that becomes the event payload. This ensures consistent, controlled data in your events rather than exposing all model attributes.
+For STI models (e.g., `Spree::Exports::Products`), the serializer lookup walks up the class hierarchy until it finds a match (e.g., → `Spree::Api::V3::ExportSerializer`).
+
+If no serializer is found, a minimal fallback payload is returned:
+
+```json
+{ "id": "prod_86Rf07xd4z", "created_at": "2025-01-15T10:00:00Z", "updated_at": "2025-01-15T10:30:00Z" }
+```
### Built-in Serializers
-Spree includes serializers for all core models in [`app/serializers/spree/events/`](https://github.com/spree/spree/tree/main/core/app/serializers/spree/events):
+Spree includes V3 serializers for all core models in [`api/app/serializers/spree/api/v3/`](https://github.com/spree/spree/tree/main/api/app/serializers/spree/api/v3):
| Serializer | Model |
|------------|-------|
-| [`OrderSerializer`](https://github.com/spree/spree/blob/main/core/app/serializers/spree/events/order_serializer.rb) | Orders with totals, states, timestamps |
-| [`ProductSerializer`](https://github.com/spree/spree/blob/main/core/app/serializers/spree/events/product_serializer.rb) | Products with pricing and status |
-| [`PaymentSerializer`](https://github.com/spree/spree/blob/main/core/app/serializers/spree/events/payment_serializer.rb) | Payments with amounts and states |
-| [`ShipmentSerializer`](https://github.com/spree/spree/blob/main/core/app/serializers/spree/events/shipment_serializer.rb) | Shipments with tracking info |
-| [`LineItemSerializer`](https://github.com/spree/spree/blob/main/core/app/serializers/spree/events/line_item_serializer.rb) | Line items with quantity and pricing |
-| [`VariantSerializer`](https://github.com/spree/spree/blob/main/core/app/serializers/spree/events/variant_serializer.rb) | Variants with SKU and pricing |
-| ... | [And many more](https://github.com/spree/spree/tree/main/core/app/serializers/spree/events) |
+| `OrderSerializer` | Orders with totals, states, nested line items, shipments, payments, addresses |
+| `ProductSerializer` | Products with pricing, stock status, availability |
+| `PaymentSerializer` | Payments with amounts, states, nested payment method and source |
+| `ShipmentSerializer` | Shipments with tracking, nested shipping method and rates |
+| `LineItemSerializer` | Line items with quantity, pricing, nested option values |
+| `VariantSerializer` | Variants with SKU, pricing, nested option values |
+| `PriceSerializer` | Prices with amounts, currency, price list |
+| ... | [And many more](https://github.com/spree/spree/tree/main/api/app/serializers/spree/api/v3) |
-### Creating a Custom Serializer
+### Payload Context
-For custom models or to add attributes to existing events, create a serializer:
-
-```ruby app/serializers/spree/events/order_serializer.rb
-module Spree
- module Events
- class OrderSerializer < BaseSerializer
- protected
-
- def attributes
- {
- id: resource.id,
- number: resource.number,
- state: resource.state.to_s,
- total: money(resource.total),
- currency: resource.currency,
- email: resource.email,
- completed_at: timestamp(resource.completed_at),
- created_at: timestamp(resource.created_at),
- updated_at: timestamp(resource.updated_at)
- }
- end
- end
- end
-end
-```
-
-### BaseSerializer Helpers
-
-The `Spree::Events::BaseSerializer` provides helpful methods:
-
-```ruby
-class MySerializer < Spree::Events::BaseSerializer
- protected
-
- def attributes
- {
- id: resource.id, # Access the model via `resource`
- amount: money(resource.total), # Converts to decimal
- shipped_at: timestamp(resource.shipped_at), # ISO8601 format
- name: attribute(:name) # Safe attribute access (nil if missing)
- }
- end
-end
-```
+Event serializers receive specific context parameters that control what data is included:
-| Method | Description |
-|--------|-------------|
-| `resource` | The model instance being serialized |
-| `context` | Hash with event context (event_name, triggered_at) |
-| `money(amount)` | Converts money to decimal value |
-| `timestamp(time)` | Formats time as ISO8601 string |
-| `attribute(name)` | Safely gets attribute (returns nil if missing) |
+- **`store`** — Prefers the resource's store (e.g., `order.store`), falls back to `Spree::Current.store`
+- **`currency`** — Uses `Spree::Current.currency` (with full fallback chain)
+- **`user: nil`** — Events never include user-specific pricing
+- **`includes: []`** — Conditional associations are not included in event payloads
-### Overriding Built-in Serializers
+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.
-To customize the payload for existing events, create your own serializer that overrides Spree's:
+### Overriding Event Serializers
-```ruby app/serializers/spree/events/order_serializer.rb
-module Spree
- module Events
- class OrderSerializer < BaseSerializer
- protected
-
- def attributes
- {
- # Include standard attributes
- id: resource.id,
- number: resource.number,
- state: resource.state.to_s,
- total: money(resource.total),
-
- # Add custom attributes
- custom_field: resource.custom_field,
- loyalty_points: calculate_loyalty_points,
-
- # Include related data
- line_item_count: resource.line_items.count,
- shipping_method: resource.shipments.first&.shipping_method&.name
- }
- end
+To customize the payload for existing events, create a custom V3 serializer and configure it via dependencies:
- private
+```ruby app/serializers/my_app/order_serializer.rb
+module MyApp
+ class OrderSerializer < Spree::Api::V3::OrderSerializer
+ # Add custom attributes
+ attribute :loyalty_points do |order|
+ (order.total.to_f * 10).to_i
+ end
- def calculate_loyalty_points
- (resource.total.to_f * 10).to_i
- end
+ attribute :custom_field do |order|
+ order.custom_field
end
end
end
```
+```ruby config/initializers/spree.rb
+Spree.api.order_serializer = 'MyApp::OrderSerializer'
+```
+
<Warning>
When overriding serializers, make sure to include all attributes that webhooks and subscribers depend on. Removing attributes may break integrations.
</Warning>
### Serializers for Custom Models
-If you add a custom model that publishes events, you must create a serializer:
+If you add a custom model that publishes events, create a V3 serializer:
```ruby app/models/my_app/subscription.rb
module MyApp
@@ -421,39 +369,34 @@ module MyApp
end
```
-```ruby app/serializers/spree/events/subscription_serializer.rb
+```ruby app/serializers/spree/api/v3/subscription_serializer.rb
module Spree
- module Events
- class SubscriptionSerializer < BaseSerializer
- protected
-
- def attributes
- {
- id: resource.id,
- plan_name: resource.plan_name,
- status: resource.status,
- user_id: resource.user_id,
- renewed_at: timestamp(resource.renewed_at),
- expires_at: timestamp(resource.expires_at),
- created_at: timestamp(resource.created_at)
- }
+ module Api
+ module V3
+ class SubscriptionSerializer < BaseSerializer
+ typelize plan_name: :string, status: :string,
+ user_id: [:string, nullable: true],
+ renewed_at: [:string, nullable: true],
+ expires_at: [:string, nullable: true]
+
+ attributes :plan_name, :status,
+ renewed_at: :iso8601, expires_at: :iso8601,
+ created_at: :iso8601, updated_at: :iso8601
+
+ attribute :user_id do |subscription|
+ subscription.user&.prefixed_id
+ end
end
end
end
end
```
-If you try to publish an event without a serializer, Spree raises a helpful error:
-
-```
-Spree::Publishable::MissingSerializerError:
- Missing event serializer for MyApp::Subscription.
- Please create Spree::Events::SubscriptionSerializer that inherits from Spree::Events::BaseSerializer.
-```
+Models without a matching serializer will use a minimal fallback payload containing only `id`, `created_at`, and `updated_at`.
## Registering Subscribers
-Subscribers in `app/subscribers/` are automatically registered during Rails initialization.
+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:
@@ -473,7 +416,7 @@ end
## Synchronous vs Asynchronous
-By default, subscribers run asynchronously via `Spree::Events::SubscriberJob`. This prevents slow subscriber code from blocking HTTP requests.
+By default, subscribers run asynchronously via a background job. This prevents slow subscriber code from blocking HTTP requests.
For critical operations that must complete before the request finishes, use synchronous mode:
@@ -519,7 +462,7 @@ RSpec.describe MyApp::OrderCompletedSubscriber do
let(:event) do
Spree::Event.new(
name: 'order.complete',
- payload: Spree::Events::OrderSerializer.serialize(order)
+ payload: order.event_payload
)
end
@@ -677,7 +620,7 @@ The `Spree::Events::Adapters::Base` class defines the required interface:
| `publish(event_name, payload, metadata)` | Publish an event, return `Spree::Event` |
| `subscribe(pattern, subscriber, options)` | Register a subscriber for a pattern |
| `unsubscribe(pattern, subscriber)` | Remove a subscriber |
-| `activate!` | Called during Rails initialization |
+| `activate!` | Called during application initialization |
| `deactivate!` | Called during shutdown |
The base class also provides helper methods:
diff --git a/docs/developer/core-concepts/i18n.mdx b/docs/developer/core-concepts/i18n.mdx
deleted file mode 100644
index 5e880c1ea0..0000000000
--- a/docs/developer/core-concepts/i18n.mdx
+++ /dev/null
@@ -1,191 +0,0 @@
----
-title: Internationalization
-description: >-
- Spree is ready out of the box to make your brand a global one.
----
-
-## Overview
-
-With Spree you can use different currencies, languages, payment methods per region. You can translate the UI and have different translations for product descriptions, taxons, etc to improve conversions and customer satisfaction.
-
-## Store Default Locale
-
-Each [Store](stores) has their own `default_locale` attribute. Alongside that, you can also set `supported_locales` which will enable multi-language capabilities for that Store.
-
-You can change both in the Admin Panel in `Configurations -> Store` or via rails console / API.
-
-<Info>
-For locales, we use symbols such as `en`,`es-MX` etc - full list of supported locales is available in the [Spree I18n GitHub repository](https://github.com/spree-contrib/spree_i18n/tree/master/config/locales)..
-</Info>
-
-## Store Default Currency
-
-As with locale each [Store](stores) has their own `default_currency` attribute. Alongside that, you can also set `supported_currencies` which will enable multi-currency capabilities for that Store.
-
-You can change both in the Admin Panel in `Configurations -> Store` or via rails console / API.
-
-<Info>
-For currencies, we use [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) symbols, eg. `USD` , `CAD`, `EUR`
-</Info>
-
-## Resource Translations
-
-As of Spree 4.6, resources with user-facing content fields now have built in support for translations. Translation functionality is handled by the [Mobility gem](https://github.com/shioyama/mobility). Spree allows you to translate the following resources:
-
-```mermaid
-erDiagram
- spree_products ||--o{ spree_product_translations : "has many"
- spree_taxons ||--o{ spree_taxon_translations : "has many"
- spree_taxonomies ||--o{ spree_taxonomy_translations : "has many"
- spree_option_types ||--o{ spree_option_type_translations : "has many"
- spree_option_values ||--o{ spree_option_value_translations : "has many"
- spree_properties ||--o{ spree_property_translations : "has many"
- spree_product_properties ||--o{ spree_product_property_translations : "has many"
- spree_stores ||--o{ spree_store_translations : "has many"
-
- spree_products {
- bigint id PK
- string status
- datetime created_at
- }
-
- spree_product_translations {
- bigint id PK
- bigint spree_product_id FK
- string locale
- string name
- text description
- string slug
- string meta_title
- string meta_description
- string meta_keywords
- }
-
- spree_taxons {
- bigint id PK
- bigint taxonomy_id FK
- bigint parent_id FK
- }
-
- spree_taxon_translations {
- bigint id PK
- bigint spree_taxon_id FK
- string locale
- string name
- text description
- string permalink
- }
-```
-
-| Resource | Translatable Fields |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Product | `name`, `description`, `slug`, `meta_description`, `meta_keywords`, `meta_title` |
-| Taxon | `name`, `description`, `permalink` |
-| Taxonomy | `name` |
-| Option Type | `presentation` |
-| Option Value | `presentation` |
-| Property | `presentation` |
-| Product Property | `value` |
-| Store | `name`, `meta_description`, `meta_keywords`, `seo_title`, `facebook`, `twitter`, `instagram`, `customer_support_email`, `description`, `address`, `contact_phone` |
-
-Our translatable resources are configured with Mobility’s [Table Backend](https://github.com/shioyama/mobility#table-backend-like-globalize) storage strategy. The way this works is that each translatable resource has a corresponding translations table in the database, in which translation values are stored - for example, product translations are stored in `spree_product_translations`.
-
-<Info>
-You can read more about how to work with translations by reading [Mobility's usage docs](https://github.com/shioyama/mobility#usage).
-</Info>
-
-### Resource Translations Implementation
-
-Each translatable resource includes the `TranslatableResource` module, which sets the default scope for the resource to `i18n`. This makes it so that when querying the translatable resource on a translatable field, Mobility will know to search in the translation tables. Read more about querying translatable fields and the i18n scope in the [Mobility docs](https://github.com/shioyama/mobility#querying).
-
-Due to some shortcomings of the Mobility gem, not all Active Record Query Interface methods work with translations. This includes:
-
-* selecting `distinct` when ordering by a translated field raises an error. To work around this, explicitly select the translated field that you are ordering by. For example, instead of `Spree::Product.order(:name).distinct` do `Spree::Product.select(:name).order(:name).distinct`
-* calling `first_or_create` or `first_or_initialize` on a clause that checks for a translated field does not work correctly with Mobility. For example, the following line of code will not perform as expected: `Spree::Product.where(name: ‘Denim Shirt').first_or_create!` Instead, you’ll need to rewrite it as an if statement that calls either `first` or `create` like so:
-
-```ruby
-if Spree::Product.where(name: 'Denim Shirt').any?
- Spree::Product.where(name: 'Denim Shirt').first
-else
- Spree::Product.create!(name: 'Denim Shirt')
-end
-```
-
-* Joining on a resource with translations and then filtering by a translated field on the resource that you joined does not work correctly. For example, the following statement will not select the correct products: `Spree::Product.joins(:taxons).where(taxons: {name: "30% Off"})`. Instead, you can make use of the `join_translation_table` method in in the `TranslatableResourceScopes` Module. The above query can be rewritten like this:
-
-```ruby
-Spree::Product.joins(:taxons)
- .joins_translation_table(Spree::Taxon)
- .where(Spree::Taxon.translation_table_alias => {name: "30% Off"})
-```
-
-<Info>
- If you are using Spree version 4.5 or older and are currently unable to upgrade, you can install [Spree Globalize extension](https://github.com/spree-contrib/spree_globalize) to enable translations. This extension uses [Globalize](https://github.com/globalize/globalize) library under the hood. We do not recommend this approach and we will not be providing support for it. We recommend upgrading to Spree 4.6 or newer.
-</Info>
-
-## The `spree_i18n` project
-
-Spree now stores all of the translation information in a separate GitHub project known as [Spree I18n](https://github.com/spree/spree_i18n). This is a stand alone project with a large number of volunteer committers who maintain the locale files. This is basically the same approach followed by the Rails project which keeps their localizations in [rails-i18n](https://github.com/svenfuchs/rails-i18n).
-
-The project is actually a Spree extension. This extension contains translation files for the Spree UI in various languages.
-
-To install the Spree I18n extension, run the following command:
-
-```bash
-bundle add spree_i18n
-```
-
-### Translation Files
-
-Each language is stored in a YAML file located in `config/locales`. Each YAML file contains one top level key which is the language code for the translations contained within that file. The following is a snippet showing the basic layout of a locale file:
-
-```yaml
-pt-BR:
- spree:
- say_no: "Não"
- say_yes: "Sim"
-```
-
-All translations for Spree are "namespaced" within the `spree` key so that they don't conflict with translations from other parts of the parent application.
-
-Please submit Pull Requests or issues directly to [Spree I18n](https://github.com/spree/spree_i18n) for missing translations.
-
-### Localization Files
-
-Spree maintains its localization information in a YAML file using a naming convention similar to that of the Rails project. Each of the localization filenames contains a prefix representing the language code of the locale. For example, the Russian translation is contained in `config/locales/ru.yml`.
-
-Spree has over 43 locale files and counting. See the [GitHub Repository](https://github.com/spree-contrib/spree_i18n/tree/main/config/locales) for a complete list.
-
-### Required Files
-
-Each locale that you wish to support will require both a Rails and Spree translation. The required Spree translation files are available automatically when you install the `spree_i18n` gem.
-
-You don't need to copy any files from `spree_i18n` or `rails-i18n` for their translations to be available within your application. They are made available automatically, because both `spree_i18n` and `rails-i18n` are railties.
-
-## Translating Views
-
-When reviewing the source of any view in Spree you'll notice that all text is rendered by passing a string to a helper method similar to:
-
-```erb
-<%= Spree.t(:price) %>
-```
-
-The `Spree.t()` helper method looks up the currently configured locale and retrieves the translated value from the relevant locale YAML file. Assuming a default locale, this translation would be fetched from the en translations collated from the application, `spree_i18n` and `rails-i18n`. Its relative key within those translation files would need to be this:
-
-```yaml
-en:
- spree:
- price: Price
-```
-
-## Localizing Extensions
-
-[Spree extensions](/developer/customization/extensions) can contain their own `config/locales` directory where developers can include YAML files for each language they wish to support.
-
-We strongly urge all extension developers to ensure all customer facing text is rendered via the `Spree.t()` helper method even if they only include a single default language locale file (as other users can simply include the required YAML file and translations in their site extension).
-
-## Related Documentation
-
-- [Stores](/developer/core-concepts/stores) - Multi-store and multi-language configuration
-- [Products](/developer/core-concepts/products) - Product translations
-- [Extensions](/developer/customization/extensions) - Creating extensions with translations
diff --git a/docs/developer/core-concepts/images-assets.mdx b/docs/developer/core-concepts/images-assets.mdx
index c98f4d58f2..b6fcff6b05 100644
--- a/docs/developer/core-concepts/images-assets.mdx
+++ b/docs/developer/core-concepts/images-assets.mdx
@@ -1,589 +1,150 @@
---
title: Images & Assets
sidebarTitle: "Images & Assets"
+description: Product images, named variants, and how images are served via the Store API
---
-Spree uses [Rails Active Storage](https://guides.rubyonrails.org/active_storage_overview.html) for all file uploads and image handling. This guide covers how images are stored, processed, and displayed in Spree.
+## Overview
-## How Spree Stores Images
+Spree handles image uploads, processing, and delivery for product images and other assets. Images are automatically converted to WebP format and preprocessed into multiple sizes for optimal performance.
-Spree provides two storage service configurations:
+## Product Images
-| Service | Purpose | Example Models |
-|---------|---------|----------------|
-| `public_storage_service_name` | Public assets (images, logos) | Product images, Store logo, Taxon images |
-| `private_storage_service_name` | Private assets (exports, imports) | CSV exports, Digital downloads |
-
-### Configuration
-
-Configure storage services in your Spree initializer:
-
-```ruby config/initializers/spree.rb
-Spree.public_storage_service_name = :amazon_public # S3 bucket for public assets
-Spree.private_storage_service_name = :amazon_private # S3 bucket for private assets
-```
-
-If not configured, Spree uses the default Active Storage service from `config/storage.yml`.
-
-<Info>
- For production deployments, we recommend using cloud storage (S3, GCS, Azure) instead of local disk storage. See [Active Storage Configuration](/developer/deployment/assets) for details.
-</Info>
-
-## Adding Images to Your Models
-
-For most models, use Rails Active Storage directly with Spree's storage service:
-
-```ruby app/models/spree/brand.rb
-module Spree
- class Brand < Spree::Base
- # Public image (product photos, logos, etc.)
- has_one_attached :logo, service: Spree.public_storage_service_name
-
- # Multiple public images
- has_many_attached :gallery_images, service: Spree.public_storage_service_name
-
- # Private file (invoices, reports, etc.)
- has_one_attached :contract, service: Spree.private_storage_service_name
- end
-end
-```
-
-### Models Using Active Storage
-
-Most Spree models use Active Storage directly:
-
-| Model | Attachment | Type |
-|-------|------------|------|
-| `Spree::Store` | `logo`, `favicon_image`, `social_image`, `mailer_logo` | Public |
-| `Spree::Taxon` | `image`, `square_image` | Public |
-| `Spree::Post` | `image` | Public |
-| `Spree::User` | `avatar` | Public |
-| `Spree::PageSection` | `asset` | Public |
-| `Spree::PageBlock` | `asset` | Public |
-| `Spree::Digital` | `attachment` | Private |
-| `Spree::Export` | `attachment` | Private |
-| `Spree::Import` | `attachment` | Private |
-
-## Product & Variant Images
-
-Product images are a special case that use the `Spree::Image` model (a subclass of `Spree::Asset`). This provides additional features needed for e-commerce:
+Product images use the `Spree::Image` model, which provides:
- **Multiple images per variant** with ordering
- **Alt text** for accessibility and SEO
- **Position management** for image galleries
-- **Polymorphic association** to variants
-
-### How It Works
-
-```ruby
-# Images belong to variants, not products directly
-variant.images # => [Spree::Image, Spree::Image, ...]
-
-# Products access images through their variants
-product.images # => Images from master variant
-product.variant_images # => Images from all variants including master
+- **Preprocessed named variants** for fast delivery
-# Each image wraps an Active Storage attachment
-image = variant.images.first
-image.attachment # => ActiveStorage::Attached::One
-image.alt # => "Red T-Shirt Front View"
-image.position # => 1
-```
+Images belong to variants, not products directly. Product-level images are attached to the master variant.
-### Creating Product Images
-
-```ruby
-# Add image to a variant
-variant.images.create!(
- attachment: File.open('path/to/image.jpg'),
- alt: 'Product front view'
-)
-
-# Or using Active Storage's attach method
-image = variant.images.new(alt: 'Product side view')
-image.attachment.attach(
- io: File.open('path/to/image.jpg'),
- filename: 'side-view.jpg',
- content_type: 'image/jpeg'
-)
-image.save!
-```
+### Named Variant Sizes
-### Spree::Asset Class
-
-`Spree::Asset` is the base class for product images:
-
-```ruby
-# Key attributes and methods
-asset.attachment # ActiveStorage attachment
-asset.attached? # Check if file is attached
-asset.blob # ActiveStorage blob
-asset.filename # Original filename
-asset.key # Storage key
-asset.viewable # Parent record (e.g., Spree::Variant)
-asset.viewable_type # "Spree::Variant"
-asset.position # Order in gallery
-asset.alt # Alt text (Spree::Image only)
-```
-
-<Warning>
- `Spree::Asset` and `Spree::Image` are only used for product/variant images. For all other models, use Active Storage directly with `has_one_attached` or `has_many_attached`.
-</Warning>
-
-## Image Processing
-
-Spree uses [libvips](https://www.libvips.org/) for image processing. Images are automatically:
-
-- Converted to **WebP format** for optimal file size
-- **Preprocessed on upload** using named variants for common sizes for Products
-- **Processed on demand** for other models
-- **Cached** for subsequent requests
-
-### Installing libvips
-
-```bash
-# macOS
-brew install vips
-
-# Ubuntu/Debian
-apt-get install libvips
-
-# Alpine Linux
-apk add vips
-```
-
-### Preprocessed Named Variants
-
-<Warning>
- Preprocessed named variants are only available for product images (`Spree::Image`). For other models, images are processed on demand.
-</Warning>
-
-When an image is uploaded, Spree automatically generates optimized versions in the background, so they're ready to serve immediately without on-demand processing. You can still generate on-the-fly variants if you wish, but we recommend using the preprocessed named variants for optimal performance.
-
-#### Available Variant Sizes
+When an image is uploaded, Spree automatically generates optimized versions in the background:
| Name | Dimensions | Use Case |
|------|------------|----------|
-| `:mini` | 128×128 | Thumbnails, cart items |
-| `:small` | 256×256 | Product listings, galleries |
-| `:medium` | 400×400 | Product cards, category pages |
-| `:large` | 720×720 | Product detail pages |
-| `:xlarge` | 2000×2000 | Zoom, high-resolution displays |
-
-All variants are:
-- Cropped to fill the exact dimensions (`resize_to_fill`)
-- Converted to WebP format for smaller file sizes
-- Optimized with quality settings balanced for size and clarity
-
-#### Using Named Variants
-
-```ruby
-# In views - recommended approach
-<%= spree_image_tag product.images.first, variant: :medium %>
-
-# Get URL only
-<%= spree_image_url product.images.first, variant: :large %>
-
-# Command line (rails console)
-image.attachment.variant(:small)
-```
-
-<Tip>
- Always use named variants (`:mini`, `:small`, `:medium`, `:large`, `:xlarge`) instead of custom dimensions for product images. Named variants are preprocessed on upload, resulting in faster page loads.
-</Tip>
-
-#### Configuring Variant Sizes
-
-Customize variant dimensions in your Spree initializer:
-
-```ruby config/initializers/spree.rb
-Spree.configure do |config|
- config.product_image_variant_sizes = {
- mini: [128, 128],
- small: [256, 256],
- medium: [400, 400],
- large: [720, 720],
- xlarge: [2000, 2000]
- }
-end
-```
+| `mini` | 128x128 | Thumbnails, cart items |
+| `small` | 256x256 | Product listings, galleries |
+| `medium` | 400x400 | Product cards, category pages |
+| `large` | 720x720 | Product detail pages |
+| `xlarge` | 2000x2000 | Zoom, high-resolution displays |
-<Warning>
- Changing variant sizes only affects newly uploaded images. Existing images will retain their original variant dimensions until reprocessed.
-</Warning>
-
-#### Reprocessing Existing Images
-
-After changing variant sizes or upgrading Spree, reprocess existing images in background jobs:
-
-```ruby
-Spree::Image.find_each do |image|
- next unless image.attachment.attached?
-
- blob = image.attachment.blob
-
- %i[mini small medium large xlarge og_image].each do |variant_name|
- transformations = Spree::Image.attachment_reflections['attachment']
- .named_variants[variant_name]
- .transformations
-
- ActiveStorage::TransformJob.perform_later(blob, transformations)
- end
-end
-```
-
-Or process synchronously (slower but immediate)
-
-```ruby
-Spree::Image.find_each do |image|
- next unless image.attached?
- [:mini, :small, :medium, :large, :xlarge].each do |variant_name|
- image.attachment.variant(variant_name).processed
- end
-end
-```
-
-### Dynamic Variants
+All variants are cropped to fill the exact dimensions and converted to WebP format.
-For non-product images or custom dimensions, you can still generate variants on-the-fly:
+## Store API
-```ruby
-# Resize to fit within dimensions (maintains aspect ratio)
-spree_image_tag(image, width: 400, height: 400)
+### Thumbnails (Always Available)
-# Resize and crop to exact dimensions
-spree_image_tag(image, width: 200, height: 200, crop: true)
+Every product response includes a `thumbnail_url` field — ready to use without any expands. Similarly, each variant includes a `thumbnail` URL and an `image_count` counter.
-# Resize by width only
-spree_image_tag(image, width: 300, height: nil)
-
-# Resize by height only
-spree_image_tag(image, width: nil, height: 300)
-```
-
-<Info>
- Dynamic variants are generated on first request and cached.
-</Info>
-
-## Helpers
-
-Spree provides several helper methods for working with images. These are defined in [Spree::ImagesHelper](https://github.com/spree/spree/blob/main/core/app/helpers/spree/images_helper.rb) and are available in Admin, Storefront, and API.
-
-### `spree_image_tag`
-
-Generates an optimized image tag with automatic WebP conversion and retina support.
-
-```erb
-<%# Using preprocessed named variant (recommended for product images) %>
-<%= spree_image_tag(
- product.images.first,
- variant: :medium,
- loading: :lazy,
- class: 'product-image',
- alt: product.name
-) %>
-
-<%# Using custom dimensions (generates variant on-the-fly) %>
-<%= spree_image_tag(
- product.images.first,
- width: 400,
- height: 400,
- loading: :lazy,
- class: 'product-image',
- alt: product.name
-) %>
-```
+<CodeGroup>
-**Output:**
+```typescript SDK
+// List products — thumbnail_url is always included
+const { data: products } = await client.store.products.list({ limit: 12 })
-```html
-<img
- loading="lazy"
- class="product-image"
- alt="Red T-Shirt"
- src="https://example.com/rails/active_storage/representations/...">
+products.forEach(product => {
+ product.thumbnail_url // "https://cdn.../tote-front.webp" — no expand needed
+})
```
-**Features:**
-- Automatically scales dimensions by 2x for retina displays (when using width/height)
-- Converts to WebP format
-- Works with both `Spree::Asset` objects and Active Storage attachments
-- Supports preprocessed named variants for optimal performance
-
-**Parameters:**
-
-<ParamField body="image" type="Asset | Attachment" required>
- Spree::Asset or ActiveStorage attachment
-</ParamField>
-
-<ParamField body="variant" type="Symbol">
- Named variant (`:mini`, `:small`, `:medium`, `:large`, `:xlarge`). When set, `width`, `height`, and `format` are ignored.
-</ParamField>
-
-<ParamField body="width" type="Integer">
- Display width in pixels. Ignored if `variant` is set.
-</ParamField>
-
-<ParamField body="height" type="Integer">
- Display height in pixels. Ignored if `variant` is set.
-</ParamField>
-
-<ParamField body="format" type="Symbol">
- Output format, e.g., `:png`. Ignored if `variant` is set.
-</ParamField>
-
-<ParamField body="loading" type="Symbol">
- Loading strategy: `:lazy` or `:eager`
-</ParamField>
-
-<ParamField body="class" type="String">
- CSS classes for the image tag
-</ParamField>
-
-<ParamField body="alt" type="String">
- Alt text for accessibility
-</ParamField>
-
-<Tip>
- Use the `variant` parameter with named variants for product images. These are preprocessed on upload and load faster than dynamic width/height variants.
-</Tip>
-
-### `spree_image_url`
-
-Generates a URL for an image variant.
-
-```erb
-<%# Using preprocessed named variant (recommended) %>
-<%= spree_image_url(product.images.first, variant: :large) %>
-
-<%# Using custom dimensions %>
-<%= spree_image_url(product.images.first, width: 800, height: 600) %>
+```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'
```
-**Output:**
+</CodeGroup>
-```
-https://example.com/rails/active_storage/representations/proxy/...
-```
-
-**Parameters:**
-
-<ParamField body="image" type="Asset | Attachment" required>
- Spree::Asset or ActiveStorage attachment
-</ParamField>
-
-<ParamField body="variant" type="Symbol">
- Named variant (`:mini`, `:small`, `:medium`, `:large`, `:xlarge`). When set, `width`, `height`, and `format` are ignored.
-</ParamField>
-
-<ParamField body="width" type="Integer">
- Width in pixels. Ignored if `variant` is set.
-</ParamField>
-
-<ParamField body="height" type="Integer">
- Height in pixels. Ignored if `variant` is set.
-</ParamField>
-
-<ParamField body="format" type="Symbol">
- Output format, e.g., `:png`. Ignored if `variant` is set.
-</ParamField>
-
-<Info>
- URLs generated by this helper are static and can be cached by [CDNs](/developer/deployment/assets). Don't use this for private assets!
-</Info>
+<Warning>
+Avoid using `?expand=images` on listing pages. This loads **all** images for every product in the response. Use `thumbnail_url` instead and only expand full images on product detail pages.
+</Warning>
-### `spree_asset_aspect_ratio`
+### Full Images (On Demand)
-Returns the aspect ratio of an image for CSS layouts.
+On the product detail page, expand `images` and `variants` to get the full set of images with all named variant URLs:
-```erb
-<div style="aspect-ratio: <%= spree_asset_aspect_ratio(product.images.first) %>">
- <%= spree_image_tag(product.images.first, width: 400) %>
-</div>
-```
+<CodeGroup>
-**Returns:** Float (e.g., `1.5`, `0.75`, `1.0`)
-
-## Displaying Images
-
-### Product Images in Views
-
-```erb
-<%# Display primary product image using named variant %>
-<% if product.has_images? %>
- <%= spree_image_tag product.default_image,
- variant: :large,
- alt: product.name,
- class: 'product-main-image' %>
-<% end %>
-
-<%# Display image gallery with thumbnails %>
-<div class="product-gallery">
- <% product.variant_images.each do |image| %>
- <%= spree_image_tag image,
- variant: :small,
- alt: image.alt.presence || product.name,
- class: 'gallery-thumbnail' %>
- <% end %>
-</div>
-
-<%# High-resolution image for zoom %>
-<%= spree_image_tag product.default_image,
- variant: :xlarge,
- alt: product.name,
- class: 'product-zoom-image' %>
-```
+```typescript SDK
+const product = await client.store.products.get('spree-tote', {
+ expand: ['images', 'variants'],
+})
-### Active Storage Attachments
-
-```erb
-<%# Store logo %>
-<% if current_store.logo.attached? %>
- <%= spree_image_tag current_store.logo,
- width: 200,
- height: 60,
- alt: current_store.name %>
-<% end %>
-
-<%# Taxon image %>
-<% if taxon.image.attached? %>
- <%= spree_image_tag taxon.image,
- width: 400,
- height: 300,
- alt: taxon.name %>
-<% end %>
-
-<%# User avatar %>
-<% if user.avatar.attached? %>
- <%= spree_image_tag user.avatar,
- width: 48,
- height: 48,
- class: 'rounded-full' %>
-<% end %>
-```
+// Product-level images (from master variant)
+product.images // [{ url, mini_url, small_url, medium_url, large_url, xlarge_url, alt, position }, ...]
-### Checking for Attached Images
-
-```erb
-<%# For Spree::Asset/Image %>
-<% if product.has_images? %>
- <%= spree_image_tag product.default_image, width: 400 %>
-<% else %>
- <%= image_tag 'placeholder.png', width: 400 %>
-<% end %>
-
-<%# For Active Storage attachments %>
-<% if @brand.logo.attached? %>
- <%= spree_image_tag @brand.logo, width: 200 %>
-<% else %>
- <div class="placeholder">No logo</div>
-<% end %>
+// Each variant has its own thumbnail and image_count
+product.variants?.forEach(variant => {
+ variant.thumbnail // "https://cdn.../tote-red.webp" — always available
+ variant.image_count // 3 — quick check without loading images
+ variant.images // full image array (only with ?expand=images)
+})
```
-## Admin Dashboard
-
-In the admin dashboard, use the `spree_file_field` form helper for image uploads:
-
-```erb
-<%= form_with model: @brand do |f| %>
- <%= f.spree_file_field :logo,
- width: 300,
- height: 300,
- crop: true,
- help: "Recommended size: 300x300px" %>
-<% end %>
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=images,variants' \
+ -H 'Authorization: Bearer spree_pk_xxx'
```
-See the [Form Builder](/developer/admin/form-builder) and [Components](/developer/admin/components) documentation for more details.
+</CodeGroup>
-## API Serialization
-
-Product images are automatically serialized in API responses:
+**Response (image object):**
```json
{
- "data": {
- "id": "1",
- "type": "product",
- "attributes": {
- "name": "Red T-Shirt"
- },
- "relationships": {
- "images": {
- "data": [
- { "id": "1", "type": "image" }
- ]
- }
- }
- },
- "included": [
- {
- "id": "1",
- "type": "image",
- "attributes": {
- "position": 1,
- "alt": "Front view",
- "original_url": "https://...",
- "styles": [
- {
- "url": "https://...",
- "width": 650,
- "height": 870,
- "size": "650x870>"
- }
- ]
- }
- }
- ]
+ "id": "img_k5nR8xLq",
+ "position": 1,
+ "alt": "Front view",
+ "original_url": "https://cdn.example.com/images/original.jpg",
+ "mini_url": "https://cdn.example.com/images/mini.webp",
+ "small_url": "https://cdn.example.com/images/small.webp",
+ "medium_url": "https://cdn.example.com/images/medium.webp",
+ "large_url": "https://cdn.example.com/images/large.webp",
+ "xlarge_url": "https://cdn.example.com/images/xlarge.webp"
}
```
-## Best Practices
+### Image Fields Summary
-<Check>
- **Use appropriate storage services** - Public assets use `public_storage_service_name`, private files use `private_storage_service_name`
-</Check>
+| Field | Available on | Always Returned | Description |
+|-------|-------------|:---:|-------------|
+| `thumbnail_url` | Product | Yes | URL to the product's first image |
+| `thumbnail` | Variant | Yes | URL to the variant's first image |
+| `image_count` | Variant | Yes | Number of images (no extra query) |
+| `images` | Product, Variant | No | Full image array (requires `?expand=images`) |
-<Check>
- **Always provide alt text** - For accessibility and SEO, always include meaningful alt text
-</Check>
+## Image Processing
-<Check>
- **Use lazy loading** - Add `loading: :lazy` for images below the fold
-</Check>
+Spree uses [libvips](https://www.libvips.org/) for image processing. Images are automatically:
-<Check>
- **Specify dimensions** - Always provide width and height to prevent layout shifts
-</Check>
+- Converted to **WebP format** for optimal file size
+- **Preprocessed on upload** into all named variant sizes
+- **Cached** for subsequent requests
-<Check>
- **Use CDN in production** - Configure Active Storage to use a [CDN](/developer/deployment/assets) for faster delivery
-</Check>
+## Storage
-<Check>
- **Validate uploads** - Add file size and type validations to prevent abuse
-</Check>
+Spree supports two storage service types:
-```ruby
-# Example validation
-class Brand < Spree::Base
- has_one_attached :logo, service: Spree.public_storage_service_name
+| Service | Purpose | Examples |
+|---------|---------|---------|
+| Public storage | Product images, logos, taxon images | S3 public bucket, CDN |
+| Private storage | CSV exports, digital downloads | S3 private bucket |
- validate :acceptable_logo
+<Info>
+For production deployments, use cloud storage (S3, GCS, Azure) instead of local disk storage. See [Asset Deployment](/developer/deployment/assets) for configuration details.
+</Info>
- private
+## Best Practices
- def acceptable_logo
- return unless logo.attached?
+- **Use `thumbnail_url`** on listing pages — avoid loading full images via expand
+- **Always provide alt text** for accessibility and SEO
+- **Use named variant sizes** (`mini`, `small`, `medium`, `large`, `xlarge`) for optimal performance
+- **Use a CDN** in production for faster delivery
- if logo.blob.byte_size > 5.megabytes
- errors.add(:logo, 'must be less than 5MB')
- end
+## Related Documentation
- acceptable = ['image/jpeg', 'image/png', 'image/webp']
- unless acceptable.include?(logo.blob.content_type)
- errors.add(:logo, 'must be JPEG, PNG, or WebP')
- end
- end
-end
-```
+- [Products](/developer/core-concepts/products) — Product catalog and images
+- [Deployment — Assets](/developer/deployment/assets) — Storage and CDN configuration
diff --git a/docs/developer/core-concepts/inventory.mdx b/docs/developer/core-concepts/inventory.mdx
index c2dafc14a7..d250f59943 100644
--- a/docs/developer/core-concepts/inventory.mdx
+++ b/docs/developer/core-concepts/inventory.mdx
@@ -1,14 +1,15 @@
---
title: Inventory
+description: Stock locations, stock items, stock movements, and inventory tracking
---
## Overview
-In Spree each [Variant](/developer/core-concepts/products#variants) has a `StockItem`. This is the place where the inventory for that variant is stored. A Variant can have multiple `StockItems` if it is available in multiple `StockLocations`.
+Each [Variant](/developer/core-concepts/products#variants) has a `StockItem` that tracks its inventory at a specific location. A variant can have multiple stock items if it's available at multiple stock locations.
-Back-ordered, sold, or shipped products are stored as individual `InventoryUnit` objects so they can have relevant information attached to them.
+When products are sold or returned, individual `InventoryUnit` records track each unit through the fulfillment process.
-New products created in the system can be given a starting "on hand" inventory level. You can subsequently set new inventory levels and the correct things will happen, e.g. adding new on-hand inventory to an out-of-stock product that has some backorders will first fill the backorders then update the product with the remaining inventory count.
+Adding new inventory to an out-of-stock product that has backorders will first fill the backorders, then update the available count with the remainder.
### Inventory Model Diagram
@@ -73,16 +74,16 @@ erDiagram
### Stock Locations
-Stock Locations are the locations where your inventory is shipped from. Each `StockLocation` has many `stock_items` and `stock_movements`.
+Stock Locations are the physical locations where your inventory is stored and shipped from.
-Stock Locations can be created in the admin panel Configuration → Stock Locations or via Platform API.
+Stock Locations can be created in the Admin Panel under **Settings → Stock Locations**, or via the Admin API.
Stock Locations have several attributes that define their properties and behavior within the Spree system. Below is a table outlining these attributes:
| Attribute | Description | Example Value |
|-------------------|-----------------------------------------------------------------------------|---------------------|
-| `name` | The public name of the stock location. This is used on Storefront and Storefront API | Warehouse 1 |
-| `admin_name` | The name used internally for the stock location. This is not shown on the Storefront. | WH1 Domestic |
+| `name` | The public name of the stock location. This is returned in Store API | Warehouse 1 |
+| `admin_name` | The name used internally for the stock location. This is only returned in Admin API. | WH1 Domestic |
| `address1` | The primary address line for the stock location. | 5th avenue |
| `address2` | The secondary address line for the stock location. | Suite 100 |
| `city` | The city where the stock location is based. | New York |
@@ -115,7 +116,7 @@ Stock Items represent the inventory at a stock location for a specific variant.
Stock transfers allow you to move inventory in bulk from one stock location to another stock location. This is handy when you want to integrate with a POS system or other inventory management system. Or you can just rely on Spree being the source of truth for your inventory.
<Info>
-Stock Transfers can be created in the Admin dashboard or via the Platform API.
+Stock Transfers can be created in the Admin dashboard or via the Admin API.
</Info>
Here's the list of attributes for the Stock Transfer model:
@@ -177,24 +178,15 @@ Inventory Units states are:
* `shipped` - the inventory unit is shipped
<Note>
-As we noted before, when you add new Stock Items to a Variant (eg. via Admin Panel or Platform API), the first Inventory Units to fulfill are the backordered ones.
+As we noted before, when you add new Stock Items to a Variant (eg. via Admin Panel or Admin API), the first Inventory Units to fulfill are the backordered ones.
</Note>
-## Disabling inventory tracking
+## Disabling Inventory Tracking
-What if you don't need to track inventory? You can disable it for the entire application in `config/initializers/spree.rb` file which was generated during installation. Add the following line:
+If you don't need to track inventory, you can disable it:
-```ruby
-Spree::Config[:track_inventory_levels] = false
-```
-
-You can also disable tracking inventory on a Variant level, by simply updating Variant `track_inventory` column to `false`, eg.
-
-```ruby
-variant.update(track_inventory: false)
-```
-
-This can also be done via the Admin Panel or Platform API.
+- **Per variant** — set `track_inventory` to `false` on a specific variant via the Admin Panel or Admin API
+- **Globally** — disable inventory tracking for the entire store in your Spree configuration
## Related Documentation
diff --git a/docs/developer/core-concepts/markets.mdx b/docs/developer/core-concepts/markets.mdx
index 9fa73060be..d3731272dc 100644
--- a/docs/developer/core-concepts/markets.mdx
+++ b/docs/developer/core-concepts/markets.mdx
@@ -11,15 +11,15 @@ Markets let you segment a single [Store](/developer/core-concepts/stores) into d
- **Europe** — EUR, German, ships to DE, FR, AT, NL
- **United Kingdom** — GBP, English, ships to GB
-### Market Model Diagram
-
```mermaid
erDiagram
+ Store ||--o{ Market : "has many"
+ Market ||--o{ MarketCountry : "has many"
+ MarketCountry }o--|| Country : "belongs to"
+
Store {
string name
- string code
string url
- boolean default
}
Market {
@@ -29,357 +29,232 @@ erDiagram
string supported_locales
boolean tax_inclusive
boolean default
- integer position
- }
-
- MarketCountry {
- integer market_id
- integer country_id
}
Country {
string iso
string name
}
+```
- Store ||--o{ Market : "has many"
- Market ||--o{ MarketCountry : "has many"
- MarketCountry }o--|| Country : "belongs to"
+## Market Attributes
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `name` | Human-readable name, unique per store | `North America` |
+| `currency` | ISO 4217 currency code | `USD` |
+| `default_locale` | Default language for this market | `en` |
+| `supported_locales` | All locales available in this market | `["en", "es"]` |
+| `tax_inclusive` | Whether prices include tax (affects display and checkout calculation) | `false` |
+| `default` | Whether this is the fallback market when no country match is found | `true` |
+| `countries` | List of countries in this market | `[{ iso: "US" }, { iso: "CA" }]` |
+
+## How Markets Work
+
+When a customer visits your store, their country determines which market applies. The market then sets the currency, locale, and tax behavior for that session.
+
+```
+Customer's Country → Market → Currency + Locale + Tax Zone
```
-**Key relationships:**
-- A **Store** has many Markets — each market defines a selling region
-- A **Market** has many Countries through `MarketCountry` join records
-- A **Country** can belong to multiple Markets (across different stores)
-- Markets connect to the [Pricing](/developer/core-concepts/pricing) system via `Spree::Pricing::Context`
+The resolution chain:
-## Market Attributes
+1. Customer's country is detected (from URL, geolocation, `X-Spree-Country` header, or manual selection)
+2. Spree finds the market containing that country
+3. The market's currency and locale become the defaults for the session
+4. The market's tax zone determines whether prices are shown with or without tax
-| Attribute | Description | Example Value |
-|---------------------|---------------------------------------------------------------------------------------------------|------------------------|
-| `name` | Human-readable name for the market. Must be unique per store. | `North America` |
-| `currency` | ISO 4217 currency code used for this market. | `USD` |
-| `default_locale` | Default locale/language for this market. | `en` |
-| `supported_locales` | Comma-separated list of additional locales supported by this market. | `en,fr` |
-| `tax_inclusive` | Whether prices in this market include tax. Controls how prices are displayed and how tax is calculated during checkout. | `false` |
-| `default` | Whether this is the default market for the store. Only one market per store can be default. | `true` |
-| `position` | Sort order for market resolution priority. Lower numbers = higher priority. | `0` |
-| `deleted_at` | Soft-delete timestamp. Markets are never fully removed from the database. | `nil` |
+If no market matches the customer's country, the store's **default market** is used.
-## Default Market
+## Listing Markets
-`Spree::Current.market` provides per-request access to the current market. The fallback chain is:
+Fetch all markets for the current store, including their countries:
-1. Explicitly set market (e.g., resolved from the customer's country)
-2. The store's default market (`store.default_market`)
+<CodeGroup>
-```ruby
-# Spree::Current.market is available in controllers, models, and services
-Spree::Current.market
-# => #<Spree::Market name: "North America", currency: "USD", ...>
+```typescript SDK
+const { data: markets } = await client.store.markets.list()
+// [
+// {
+// id: "mkt_k5nR8xLq",
+// name: "North America",
+// currency: "USD",
+// default_locale: "en",
+// supported_locales: ["en", "es"],
+// tax_inclusive: false,
+// default: true,
+// countries: [
+// { iso: "US", name: "United States", states_required: true, zipcode_required: true },
+// { iso: "CA", name: "Canada", states_required: true, zipcode_required: true }
+// ]
+// },
+// ...
+// ]
+```
-# Set it explicitly per-request
-Spree::Current.market = eu_market
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/markets' \
+ -H 'Authorization: Bearer spree_pk_xxx'
```
-The default market for a store is determined by the `default` flag, falling back to the first market by position:
+</CodeGroup>
-```ruby
-store.default_market
-# => #<Spree::Market name: "North America", default: true, ...>
-```
+## Resolving a Market by Country
-## Currency and Locale
+When you know a customer's country (e.g., from geolocation or a country picker), resolve which market applies:
-When markets are configured, `Spree::Current.currency` derives from the current market rather than the store:
+<CodeGroup>
-```ruby
-# Fallback chain for currency:
-# 1. Explicitly set currency
-# 2. Current market's currency
-# 3. Store's default_currency
-Spree::Current.currency
-# => "USD" (from Spree::Current.market.currency)
+```typescript SDK
+const market = await client.store.markets.resolve('DE')
+// { id: "mkt_gbHJdmfr", name: "Europe", currency: "EUR", tax_inclusive: true, ... }
```
-Each market tracks its supported locales. Use `supported_locales_list` to get all available locales (always includes the `default_locale`):
-
-```ruby
-market = Spree::Market.find_by(name: 'Europe')
-market.supported_locales_list
-# => ["de", "en", "fr"]
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/markets/resolve?country=DE' \
+ -H 'Authorization: Bearer spree_pk_xxx'
```
-The store aggregates currencies and locales from all its markets:
+</CodeGroup>
-```ruby
-store.supported_currencies_list
-# => [#<Money::Currency USD>, #<Money::Currency EUR>, #<Money::Currency GBP>]
+Returns the market object on success, or `404` if no market contains that country.
-store.supported_locales_list
-# => ["de", "en", "fr"]
-```
+This is useful for building a country switcher — resolve the market to show the customer what currency and language they'll get.
-## Tax Zone Resolution
+## Countries in a Market
-Each market resolves a tax zone from its default country using `Spree::Zone.match`. This zone is used to determine the correct tax rate for browsing prices before a customer enters an address.
+List countries belonging to a specific market. Useful for populating address form dropdowns during checkout:
-```ruby
-market = Spree::Market.find_by(name: 'Europe')
-market.tax_zone
-# => #<Spree::Zone name: "EU_VAT", ...>
+<CodeGroup>
+
+```typescript SDK
+const { data: countries } = await client.store.markets.countries.list('mkt_k5nR8xLq')
+// [
+// { iso: "CA", name: "Canada", states_required: true, zipcode_required: true },
+// { iso: "US", name: "United States", states_required: true, zipcode_required: true }
+// ]
+
+// Get a country with its states (for address form dropdowns)
+const usa = await client.store.markets.countries.get('mkt_k5nR8xLq', 'US', {
+ include: 'states',
+})
```
-`Spree::Current.zone` uses the following fallback chain:
+```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'
-1. Explicitly set zone (e.g., from an order's shipping address)
-2. Current market's tax zone (`market.tax_zone`)
-3. Store's default tax zone
+# 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'
+```
-This means browsing prices automatically use the correct tax zone for the customer's market, even before they enter an address at checkout.
+</CodeGroup>
-## Finding a Market by Country
+You can also fetch countries flat (across all markets) or include the market on a country:
-Resolve which market a country belongs to using the class method:
+<CodeGroup>
-```ruby
-country = Spree::Country.find_by(iso: 'DE')
-market = Spree::Market.for_country(country, store: current_store)
-# => #<Spree::Market name: "Europe", currency: "EUR", ...>
+```typescript SDK
+// All countries across all markets
+const { data: countries } = await client.store.countries.list()
+
+// Get a country with its market details
+const germany = await client.store.countries.get('DE', { include: 'market' })
+// { iso: "DE", name: "Germany", market: { currency: "EUR", default_locale: "de", tax_inclusive: true } }
```
-Or via the store convenience method:
+```bash cURL
+# All countries across all markets
+curl 'https://api.mystore.com/api/v3/store/countries' \
+ -H 'Authorization: Bearer spree_pk_xxx'
-```ruby
-current_store.market_for_country(country)
-# => #<Spree::Market name: "Europe", currency: "EUR", ...>
+# Get a country with its market
+curl 'https://api.mystore.com/api/v3/store/countries/DE?include=market' \
+ -H 'Authorization: Bearer spree_pk_xxx'
```
-A country also has a `current_market` method that uses `Spree::Current.store`:
+</CodeGroup>
-```ruby
-country = Spree::Country.find_by(iso: 'DE')
-country.current_market
-# => #<Spree::Market name: "Europe", currency: "EUR", ...>
-```
+## Currency and Locale
-When multiple markets contain the same country, the one with the lowest `position` is returned.
+Each market defines a currency and set of supported locales. When a market is resolved, its currency and locale become the defaults for the session.
-## Countries Available for Checkout
+You can discover all available currencies and locales (aggregated from all markets) via dedicated endpoints:
-Markets determine which countries are available during checkout. The `countries_available_for_checkout` method on Store aggregates countries from all markets:
+<CodeGroup>
-```ruby
-current_store.countries_available_for_checkout
-# => [#<Spree::Country iso: "AT">, #<Spree::Country iso: "CA">, ...]
-```
+```typescript SDK
+const { data: currencies } = await client.store.currencies.list()
+// [{ iso_code: "USD", name: "US Dollar", symbol: "$" }, { iso_code: "EUR", name: "Euro", symbol: "€" }]
-## Creating Markets
+const { data: locales } = await client.store.locales.list()
+// [{ code: "en", name: "English" }, { code: "de", name: "German" }]
+```
-```ruby
-# Create a market with countries
-na_market = current_store.markets.create!(
- name: 'North America',
- currency: 'USD',
- default_locale: 'en',
- countries: [usa, canada],
- default: true
-)
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/currencies' \
+ -H 'Authorization: Bearer spree_pk_xxx'
-eu_market = current_store.markets.create!(
- name: 'Europe',
- currency: 'EUR',
- default_locale: 'de',
- supported_locales: 'de,en,fr',
- tax_inclusive: true,
- countries: [germany, france, austria, netherlands]
-)
+curl 'https://api.mystore.com/api/v3/store/locales' \
+ -H 'Authorization: Bearer spree_pk_xxx'
```
-<Info>
-When you run `rails db:seed`, Spree automatically creates a default market for each store
-</Info>
-
-## Store API
-
-The Store API provides endpoints for markets and countries. All endpoints require a publishable API key.
-
-### Markets Endpoints
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `GET` | `/api/v3/store/markets` | List all markets with nested countries |
-| `GET` | `/api/v3/store/markets/:id` | Get a single market by prefixed ID |
-| `GET` | `/api/v3/store/markets/resolve?country=:iso` | Resolve which market a country belongs to |
-| `GET` | `/api/v3/store/markets/:market_id/countries` | List countries in a market |
-| `GET` | `/api/v3/store/markets/:market_id/countries/:iso` | Get a country (supports `?include=states`) |
-
-### Countries Endpoints
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `GET` | `/api/v3/store/countries` | List all countries (flat, across all markets) |
-| `GET` | `/api/v3/store/countries/:iso` | Get a country by ISO code |
-
-Countries support optional includes via the `?include=` parameter:
-- `states` — include states/provinces (for address forms)
-- `market` — include the country's market with currency, locales, and tax settings
-
-<AccordionGroup>
- <Accordion title="List Markets">
-
- Returns all markets for the current store with their countries.
-
- ```bash
- curl -H "Authorization: Bearer spree_pk_xxx" \
- https://example.com/api/v3/store/markets
- ```
-
- ```json
- {
- "data": [
- {
- "id": "mkt_k5nR8xLq",
- "name": "North America",
- "currency": "USD",
- "default_locale": "en",
- "supported_locales": ["en", "es"],
- "tax_inclusive": false,
- "default": true,
- "countries": [
- { "iso": "US", "iso3": "USA", "name": "United States", "states_required": true, "zipcode_required": true },
- { "iso": "CA", "iso3": "CAN", "name": "Canada", "states_required": true, "zipcode_required": true }
- ]
- },
- {
- "id": "mkt_gbHJdmfr",
- "name": "Europe",
- "currency": "EUR",
- "default_locale": "de",
- "supported_locales": ["de", "en", "fr"],
- "tax_inclusive": true,
- "default": false,
- "countries": [
- { "iso": "DE", "iso3": "DEU", "name": "Germany", "states_required": false, "zipcode_required": true },
- { "iso": "FR", "iso3": "FRA", "name": "France", "states_required": false, "zipcode_required": true }
- ]
- }
- ]
- }
- ```
-
- </Accordion>
- <Accordion title="Resolve Market by Country">
-
- Determine which market applies for a given country ISO code. Useful for auto-selecting the correct currency and locale when a customer's location is known.
-
- ```bash
- curl -H "Authorization: Bearer spree_pk_xxx" \
- https://example.com/api/v3/store/markets/resolve?country=DE
- ```
-
- Returns the market object on success, or `404` if no market contains that country.
-
- </Accordion>
- <Accordion title="List Countries in a Market">
-
- Returns countries belonging to a specific market. Useful for populating address dropdowns during checkout.
-
- ```bash
- curl -H "Authorization: Bearer spree_pk_xxx" \
- https://example.com/api/v3/store/markets/mkt_k5nR8xLq/countries
- ```
-
- ```json
- {
- "data": [
- { "iso": "CA", "iso3": "CAN", "name": "Canada", "states_required": true, "zipcode_required": true },
- { "iso": "US", "iso3": "USA", "name": "United States", "states_required": true, "zipcode_required": true }
- ]
- }
- ```
-
- </Accordion>
- <Accordion title="Get Country with Market">
-
- Use `?include=market` on any country endpoint to get the market details alongside the country.
-
- ```bash
- curl -H "Authorization: Bearer spree_pk_xxx" \
- https://example.com/api/v3/store/countries/US?include=market
- ```
-
- ```json
- {
- "iso": "US",
- "iso3": "USA",
- "name": "United States",
- "states_required": true,
- "zipcode_required": true,
- "market": {
- "id": "mkt_k5nR8xLq",
- "name": "North America",
- "currency": "USD",
- "default_locale": "en",
- "supported_locales": ["en", "es"],
- "tax_inclusive": false,
- "default": true
- }
- }
- ```
+</CodeGroup>
- </Accordion>
-</AccordionGroup>
+See [Localization](/api-reference/store-api/localization) for details on how to pass locale, currency, and country headers in API requests.
-### SDK Usage
+## Tax Behavior
-```typescript
-import { createSpreeClient } from '@spree/sdk'
+The `tax_inclusive` flag on a market controls how prices are displayed and calculated:
-const client = createSpreeClient({ host: 'https://example.com' })
+- **`tax_inclusive: true`** (common in Europe) — the price shown to the customer already includes tax
+- **`tax_inclusive: false`** (common in the US) — tax is added at checkout on top of the displayed price
-// List all markets
-const { data: markets } = await client.store.markets.list()
+Each market also resolves a **tax zone** from its default country. This zone determines which tax rates apply when browsing products — before the customer enters a shipping address. Once the customer provides an address at checkout, the actual shipping address takes over for tax calculation.
-// Get a single market
-const market = await client.store.markets.get('mkt_k5nR8xLq')
+See [Taxes](/developer/core-concepts/taxes) for details on tax zones and rates.
-// Resolve market by country (e.g., from geolocation)
-const market = await client.store.markets.resolve('DE')
-// => { id: "mkt_gbHJdmfr", name: "Europe", currency: "EUR", tax_inclusive: true, ... }
+## Pricing Integration
-// List countries in a market (for checkout address forms)
-const { data: countries } = await client.store.markets.countries.list('mkt_k5nR8xLq')
+Markets integrate with the [Pricing](/developer/core-concepts/pricing) system, enabling market-specific pricing through **Price Lists** with a **Market Rule**. This lets you set different prices for the same product in different markets — beyond just currency conversion.
-// Get a country with states (for address forms)
-const country = await client.store.markets.countries.get('mkt_k5nR8xLq', 'US', { include: 'states' })
+For example, you could price a product at $29.99 in North America and €24.99 in Europe, rather than relying on exchange rate conversion.
-// Get a country with its market details
-const country = await client.store.countries.get('US', { include: 'market' })
-// => { iso: "US", ..., market: { currency: "USD", tax_inclusive: false, ... } }
-```
+See [Pricing — Price Rules](/developer/core-concepts/pricing#price-rules) for details on configuring market-specific price lists.
-## Pricing Integration
+## Setting Up Markets
-Markets integrate with the [Pricing](/developer/core-concepts/pricing) system through the `Spree::Pricing::Context`. The current market is automatically included in pricing resolution, enabling market-specific Price Lists via the **Market Rule**.
+Markets are managed in the admin dashboard under **Settings → Markets**. When you run `rails db:seed`, Spree automatically creates a default market for each store.
+
+To create markets programmatically:
```ruby
-# Market is automatically part of the pricing context
-context = Spree::Pricing::Context.new(
- variant: variant,
- currency: 'EUR',
- market: eu_market
+# North America market
+current_store.markets.create!(
+ name: 'North America',
+ currency: 'USD',
+ default_locale: 'en',
+ countries: [usa, canada],
+ default: true
)
-# Price Lists with a Market Rule targeting eu_market will apply
-price = variant.price_for(context)
+# Europe market with tax-inclusive pricing
+current_store.markets.create!(
+ name: 'Europe',
+ currency: 'EUR',
+ default_locale: 'de',
+ supported_locales: 'de,en,fr',
+ tax_inclusive: true,
+ countries: [germany, france, austria, netherlands]
+)
```
-See [Pricing — Market Rule](/developer/core-concepts/pricing#price-rules) for details on configuring market-specific price lists.
-
## Related Documentation
- [Stores](/developer/core-concepts/stores) — Multi-store setup and configuration
- [Pricing](/developer/core-concepts/pricing) — Price Lists, Price Rules, and the Pricing Context
- [Addresses](/developer/core-concepts/addresses) — Countries, States, and Zones
-- [Internationalization](/developer/core-concepts/i18n) — Locales, currencies, and translations
+- [Localization](/api-reference/store-api/localization) — Locale, currency, and country headers in API requests
+- [Translations](/developer/core-concepts/translations) — Resource and UI translations
diff --git a/docs/developer/core-concepts/metafields.mdx b/docs/developer/core-concepts/metafields.mdx
index 2e95ffff08..efb474ca90 100644
--- a/docs/developer/core-concepts/metafields.mdx
+++ b/docs/developer/core-concepts/metafields.mdx
@@ -1,18 +1,18 @@
---
title: Metafields
+description: Add custom structured data to products, orders, and other resources with type-safe metafields
---
## Overview
Metafields provide a flexible, type-safe system for adding custom structured data to Spree resources. Unlike [metadata](/developer/customization/metadata) which is simple JSON storage, metafields are schema-defined with strong typing, validation, and visibility controls.
-Metafields enable you to extend resources with custom attributes without modifying the database schema, making them ideal for:
+Use metafields for:
- Product specifications (manufacturer, material, dimensions)
- Custom business logic fields
- Integration data from external systems
-- User-specific custom attributes
-- Order metadata with validation
+- Order-specific custom attributes
<Note>
Metafields are available from Spree 5.2 onwards.
@@ -20,830 +20,180 @@ Metafields are available from Spree 5.2 onwards.
## Architecture
-The metafields system consists of two main models:
-
```mermaid
erDiagram
- spree_metafield_definitions ||--o{ spree_metafields : "defines schema for"
- spree_products ||--o{ spree_metafields : "has many"
- spree_variants ||--o{ spree_metafields : "has many"
- spree_orders ||--o{ spree_metafields : "has many"
+ MetafieldDefinition ||--o{ Metafield : "defines schema for"
+ Product ||--o{ Metafield : "has many"
+ Variant ||--o{ Metafield : "has many"
+ Order ||--o{ Metafield : "has many"
- spree_metafield_definitions {
- bigint id PK
+ MetafieldDefinition {
string namespace
string key
string name
string metafield_type
string resource_type
string display_on
- datetime created_at
}
- spree_metafields {
- bigint id PK
- bigint metafield_definition_id FK
+ Metafield {
string type
text value
string resource_type
- bigint resource_id
- datetime created_at
- }
-
- spree_products {
- bigint id PK
- string name
- }
-
- spree_variants {
- bigint id PK
- string sku
- }
-
- spree_orders {
- bigint id PK
- string number
}
```
```mermaid
flowchart LR
subgraph Definition
- A[MetafieldDefinition] --> B[namespace: properties]
- A --> C[key: manufacturer]
- A --> D[type: ShortText]
- A --> E[resource_type: Product]
- A --> F[display_on: both]
+ A[MetafieldDefinition] --> B["namespace: properties"]
+ A --> C["key: manufacturer"]
+ A --> D["type: ShortText"]
+ A --> E["resource_type: Product"]
+ A --> F["display_on: both"]
end
subgraph Instance
- G[Metafield] --> H[value: Wilson]
- G --> I[resource: Product #1]
- G --> J[definition_id: 1]
+ G[Metafield] --> H["value: Wilson"]
+ G --> I["resource: Product #1"]
end
A -.->|"defines schema"| G
```
-### MetafieldDefinition
-
-Defines the schema and rules for a metafield type. Think of it as a blueprint that specifies:
-
-- What data type the field contains
-- Which resource it can be attached to
-- Where it should be visible (admin, storefront, or both)
-- How it should be organized (namespace)
-
-```ruby
-# Example: Define a manufacturer field for products
-definition = Spree::MetafieldDefinition.create!(
- namespace: 'properties',
- key: 'manufacturer',
- name: 'Manufacturer',
- metafield_type: 'Spree::Metafields::ShortText',
- resource_type: 'Spree::Product',
- display_on: 'both'
-)
-```
-
-### Metafield
-
-Stores the actual data values according to a MetafieldDefinition:
-
-```ruby
-# Create a metafield instance with actual data
-product = Spree::Product.first
-metafield = product.metafields.create!(
- metafield_definition: definition,
- type: 'Spree::Metafields::ShortText',
- value: 'Wilson'
-)
-```
-
-<Info>
-Every model that includes the `Spree::Metafields` concern automatically gets `metafields`, `public_metafields`, and `private_metafields` associations.
-</Info>
+- **MetafieldDefinition** — the blueprint that defines the data type, target resource, and visibility
+- **Metafield** — stores the actual value for a specific resource instance
## Data Types
-Spree supports six data types for metafields:
-
-| Type | Class | Use Case | Example |
-|------|-------|----------|---------|
-| Short Text | `Spree::Metafields::ShortText` | Brief text fields | SKU codes, brand names, tags |
-| Long Text | `Spree::Metafields::LongText` | Longer text content | Care instructions, notes |
-| Rich Text | `Spree::Metafields::RichText` | Formatted HTML content | Product descriptions with formatting |
-| Number | `Spree::Metafields::Number` | Numeric values | Weight, quantity, ratings |
-| Boolean | `Spree::Metafields::Boolean` | True/false flags | Is featured, requires signature |
-| JSON | `Spree::Metafields::Json` | Structured data | Configuration, complex objects |
-
-### Type-Specific Behavior
-
-#### Short Text & Long Text
-
-```ruby
-# Automatically strips whitespace
-product.set_metafield('custom.sku', ' ABC-123 ')
-product.get_metafield('custom.sku').value # => "ABC-123"
-```
-
-#### Rich Text
-
-```ruby
-# Uses ActionText for rich HTML content
-product.set_metafield('custom.description', '<h1>Hello</h1><p>World</p>')
-metafield = product.get_metafield('custom.description')
-metafield.value.to_s # => "<h1>Hello</h1><p>World</p>"
-```
-
-#### Number
-
-```ruby
-# Returns BigDecimal for precision
-product.set_metafield('measurements.weight', '15.75')
-metafield = product.get_metafield('measurements.weight')
-metafield.serialize_value # => BigDecimal("15.75")
-```
-
-#### Boolean
-
-```ruby
-# Converts various inputs to boolean
-product.set_metafield('flags.featured', 'true')
-metafield = product.get_metafield('flags.featured')
-metafield.serialize_value # => true
-metafield.csv_value # => "Yes" (localized)
-```
-
-#### JSON
-
-```ruby
-# Validates JSON structure
-product.set_metafield('custom.config', '{"theme": "dark", "size": 12}')
-metafield = product.get_metafield('custom.config')
-metafield.serialize_value # => {"theme" => "dark", "size" => 12}
-```
+| Type | Description | Example Values |
+|------|-------------|----------------|
+| Short Text | Brief text fields | SKU codes, brand names, tags |
+| Long Text | Longer text content | Care instructions, notes |
+| Rich Text | Formatted HTML content | Product descriptions with formatting |
+| Number | Numeric values | Weight, quantity, ratings |
+| Boolean | True/false flags | Is featured, requires signature |
+| JSON | Structured data | Configuration, complex objects |
## Visibility Control
Metafields support three visibility levels via the `display_on` attribute:
-<CardGroup>
- <Card title="both" icon="eye">
- Visible in both admin panel and storefront. Use for public product specifications that need management.
- </Card>
- <Card title="front_end" icon="store">
- Visible only in storefront and Storefront API. Use for customer-facing data that shouldn't clutter admin.
- </Card>
- <Card title="back_end" icon="lock">
- Visible only in admin panel and Platform API. Use for internal notes, integration IDs, or sensitive data.
- </Card>
-</CardGroup>
-
-```ruby
-# Create a public metafield
-Spree::MetafieldDefinition.create!(
- key: 'brand',
- namespace: 'product',
- resource_type: 'Spree::Product',
- metafield_type: 'Spree::Metafields::ShortText',
- display_on: 'both'
-)
-
-# Create an internal-only metafield
-Spree::MetafieldDefinition.create!(
- key: 'supplier_id',
- namespace: 'integration',
- resource_type: 'Spree::Product',
- metafield_type: 'Spree::Metafields::ShortText',
- display_on: 'back_end'
-)
-```
+| Visibility | Store API | Admin API | Use Case |
+|------------|:---------:|:---------:|----------|
+| `both` | Yes | Yes | Public product specifications |
+| `front_end` | Yes | No | Customer-facing data |
+| `back_end` | No | Yes | Internal notes, integration IDs |
-### Scopes for Filtering
-
-```ruby
-# Get only public metafields
-product.public_metafields
+## Supported Resources
-# Get only admin metafields
-product.private_metafields
+Metafields can be attached to most Spree resources including Products, Variants, Orders, Line Items, Taxons, Payments, Shipments, Gift Cards, Store Credits, and more.
-# Query definitions
-Spree::MetafieldDefinition.available_on_front_end
-Spree::MetafieldDefinition.available_on_back_end
-```
+<Info>
+Custom resources can also support metafields. See the [Customization Quickstart](/developer/customization/quickstart) for details.
+</Info>
## Namespaces
-Namespaces organize metafields into logical groups, preventing key conflicts and improving organization:
+Namespaces organize metafields into logical groups and prevent key conflicts:
-```ruby
-# Product properties
-product.set_metafield('properties.material', '100% Cotton')
-product.set_metafield('properties.fit', 'Regular')
-
-# Integration data
-product.set_metafield('shopify.product_id', '12345')
-product.set_metafield('google.category_id', '5432')
-
-# Custom business logic
-product.set_metafield('custom.requires_approval', 'true')
-```
+| Namespace | Example Keys | Purpose |
+|-----------|-------------|---------|
+| `properties` | `manufacturer`, `material`, `fit` | Product specifications |
+| `shopify` | `product_id`, `variant_id` | Integration data |
+| `flags` | `featured`, `requires_approval` | Feature flags |
+| `custom` | `gift_message`, `delivery_notes` | Business-specific fields |
<Info>
-Namespace and key are automatically normalized: `'My Custom Namespace'` becomes `'my_custom_namespace'`.
+Namespace and key are automatically normalized to snake_case.
</Info>
-## Supported Resources
-
-The following resources support metafields by default:
-
-<AccordionGroup>
- <Accordion title="Core Commerce">
- - `Spree::Product`
- - `Spree::Variant`
- - `Spree::Order`
- - `Spree::LineItem`
- - `Spree::OptionType`
- - `Spree::OptionValue`
- </Accordion>
-
- <Accordion title="Catalog">
- - `Spree::Taxon`
- - `Spree::Taxonomy`
- - `Spree::Asset`
- - `Spree::Image`
- </Accordion>
-
- <Accordion title="Payments & Shipping">
- - `Spree::Payment`
- - `Spree::PaymentMethod`
- - `Spree::PaymentSource`
- - `Spree::CreditCard`
- - `Spree::Shipment`
- - `Spree::ShippingMethod`
- </Accordion>
-
- <Accordion title="Fulfillment">
- - `Spree::CustomerReturn`
- - `Spree::Refund`
- - `Spree::StockItem`
- - `Spree::StockTransfer`
- </Accordion>
-
- <Accordion title="Marketing">
- - `Spree::Promotion`
- - `Spree::GiftCard`
- - `Spree::StoreCredit`
- </Accordion>
-
- <Accordion title="Content">
- - `Spree::Post`
- - `Spree::PostCategory`
- </Accordion>
-
- <Accordion title="Other">
- - `Spree::Store`
- - `Spree::CustomDomain`
- - `Spree::Address`
- - `Spree::NewsletterSubscriber`
- - `Spree::TaxRate`
- - `Spree.user_class`
- </Accordion>
-</AccordionGroup>
-
-## CRUD Operations
-
-### Creating Metafields
-
-#### Method 1: Using `set_metafield` (Recommended)
-
-The simplest way to create or update metafields:
-
-```ruby
-product = Spree::Product.first
-
-# Creates definition if it doesn't exist, then creates/updates metafield
-product.set_metafield('properties.manufacturer', 'Wilson')
-product.set_metafield('properties.material', '90% Cotton 10% Elastan')
-product.set_metafield('properties.fit', 'Loose')
-```
-
-#### Method 2: Using Nested Attributes
-
-Useful when working with forms:
-
-```ruby
-product.update(
- metafields_attributes: [
- {
- metafield_definition_id: manufacturer_definition.id,
- type: 'Spree::Metafields::ShortText',
- value: 'Wilson'
- },
- {
- metafield_definition_id: material_definition.id,
- type: 'Spree::Metafields::ShortText',
- value: '100% Cotton'
- }
- ]
-)
-```
-
-#### Method 3: Direct Creation
-
-For full control:
-
-```ruby
-# First, create or find the definition
-definition = Spree::MetafieldDefinition.find_or_create_by!(
- namespace: 'custom',
- key: 'brand',
- resource_type: 'Spree::Product'
-) do |d|
- d.name = 'Brand'
- d.metafield_type = 'Spree::Metafields::ShortText'
- d.display_on = 'both'
-end
-
-# Then create the metafield
-product.metafields.create!(
- metafield_definition: definition,
- type: definition.metafield_type,
- value: 'Nike'
-)
-```
-
-### Reading Metafields
-
-```ruby
-# Get a specific metafield
-metafield = product.get_metafield('properties.manufacturer')
-metafield.value # => "Wilson"
-metafield.name # => "Manufacturer"
-metafield.key # => "properties.manufacturer"
-
-# Check if metafield exists
-product.has_metafield?('properties.manufacturer') # => true
-product.has_metafield?(definition) # => true
-
-# Get all metafields
-product.metafields # All metafields
-product.public_metafields # Front-end visible only
-product.private_metafields # Back-end only
-
-# Access serialized value
-metafield = product.get_metafield('properties.is_featured')
-metafield.value # => "true" (string)
-metafield.serialize_value # => true (boolean)
-```
+## Store API
-### Updating Metafields
+Metafields with `display_on` set to `both` or `front_end` are included in Store API responses when you request the `metafields` expand:
-```ruby
-# Method 1: Using set_metafield (creates or updates)
-product.set_metafield('properties.manufacturer', 'New Brand')
+<CodeGroup>
-# Method 2: Using nested attributes
-product.update(
- metafields_attributes: [
- {
- id: existing_metafield.id,
- metafield_definition_id: definition.id,
- value: 'Updated Value'
- }
- ]
-)
+```typescript SDK
+const product = await client.store.products.get('spree-tote', {
+ expand: ['metafields'],
+})
-# Method 3: Direct update
-metafield = product.get_metafield('properties.manufacturer')
-metafield.update!(value: 'Updated Brand')
+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"
+})
```
-### Deleting Metafields
-
-```ruby
-# Method 1: Set value to blank (auto-destroys)
-product.update(
- metafields_attributes: [
- {
- id: metafield.id,
- value: '' # Automatically marked for destruction
- }
- ]
-)
-
-# Method 2: Explicit destroy flag
-product.update(
- metafields_attributes: [
- {
- id: metafield.id,
- _destroy: true
- }
- ]
-)
-
-# Method 3: Direct deletion
-metafield = product.get_metafield('properties.manufacturer')
-metafield.destroy
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=metafields' \
+ -H 'Authorization: Bearer spree_pk_xxx'
```
-<Warning>
-When a metafield value is set to blank via nested attributes, it's automatically marked for destruction. This is intentional behavior to prevent empty metafields.
-</Warning>
-
-## Querying by Metafields
-
-Spree provides helpful scopes for querying resources by metafield values:
-
-```ruby
-# Find products with specific metafield key
-products = Spree::Product.with_metafield_key('properties.manufacturer')
+</CodeGroup>
-# Find products with specific metafield key and value
-products = Spree::Product.with_metafield_key_value('properties.fit', 'Loose')
-
-# Find products with specific metafield (by definition)
-products = Spree::Product.with_metafield(manufacturer_definition)
-
-# Complex queries using joins
-Spree::Product
- .joins(:metafields)
- .where(
- spree_metafields: {
- metafield_definition_id: definition.id
- }
- )
- .where("spree_metafields.value ILIKE ?", "%cotton%")
-```
-
-## API Integration
-
-### Platform API
-
-Metafields are automatically included in Platform API responses:
+**Response:**
```json
{
- "data": {
- "id": "1",
- "type": "product",
- "attributes": {
- "name": "Spree T-Shirt",
- // ... other attributes
- },
- "relationships": {
- "metafields": {
- "data": [
- {
- "id": "1",
- "type": "metafield"
- }
- ]
- }
- }
- },
- "included": [
+ "id": "prod_86Rf07xd4z",
+ "name": "Spree T-Shirt",
+ "metafields": [
{
- "id": "1",
- "type": "metafield",
- "attributes": {
- "name": "Manufacturer",
- "key": "properties.manufacturer",
- "type": "Spree::Metafields::ShortText",
- "display_on": "both",
- "value": "Wilson"
- }
- }
- ]
-}
-```
-
-### Storefront API
-
-Only public metafields (with `display_on` set to `both` or `front_end`) are included:
-
-```json
-{
- "data": {
- "id": "1",
- "type": "product",
- "attributes": {
- "name": "Spree T-Shirt"
+ "id": "mf_k5nR8xLq",
+ "name": "Manufacturer",
+ "key": "properties.manufacturer",
+ "type": "short_text",
+ "value": "Wilson"
},
- "relationships": {
- "metafields": {
- "data": [
- {
- "id": "1",
- "type": "metafield"
- }
- ]
- }
- }
- },
- "included": [
{
- "id": "1",
- "type": "metafield",
- "attributes": {
- "name": "Manufacturer",
- "key": "properties.manufacturer",
- "type": "Spree::Metafields::ShortText",
- "value": "Wilson"
- }
+ "id": "mf_m3Rp9wXz",
+ "name": "Material",
+ "key": "properties.material",
+ "type": "short_text",
+ "value": "100% Cotton"
}
]
}
```
<Note>
-The `display_on` attribute is intentionally excluded from Storefront API responses for security reasons.
+The `display_on` attribute is intentionally excluded from Store API responses for security.
</Note>
## Admin Panel Management
### Managing Definitions
-Navigate to **Settings → Metafield Definitions** in the admin panel:
-
-1. Click "New Metafield Definition"
-2. Select the resource type (Product, Variant, Order, etc.)
-3. Enter namespace and key
-4. Choose the data type
-5. Set visibility (both, front_end, back_end)
-6. Save
+Navigate to **Settings → Metafield Definitions** in the Admin Panel to create and manage metafield definitions. Select the resource type, enter namespace and key, choose the data type, and set visibility.
### Managing Values
-When editing a resource (e.g., a product), metafields appear in a dedicated section:
-
-1. Edit any resource that has metafield definitions
-2. Scroll to the "Metafields" section
-3. Fill in values for each defined metafield
-4. Save
-
-<Info>
-The admin panel automatically builds empty metafield forms for all definitions, making it easy to add values.
-</Info>
-
-## Validation
-
-### MetafieldDefinition Validations
-
-```ruby
-validates :namespace, :key, :name, :resource_type, presence: true
-validates :metafield_type, presence: true,
- inclusion: { in: available_types }
-validates :resource_type,
- inclusion: { in: available_resources }
-validates :key, uniqueness: {
- scope: [:resource_type, :namespace],
- message: 'must be unique per resource type and namespace'
-}
-```
-
-### Metafield Validations
-
-```ruby
-validates :metafield_definition, :type, :resource, :value, presence: true
-validates :metafield_definition_id, uniqueness: {
- scope: [:resource_type, :resource_id],
- message: 'already exists for this resource'
-}
-validate :type_must_match_metafield_definition
-```
-
-Type-specific validations are also applied:
-
-```ruby
-# Number metafields
-validates :value, numericality: true
-
-# JSON metafields
-validate :value_must_be_valid_json
-
-# Boolean metafields
-normalizes :value, with: ->(value) { value.to_b.to_s }
-```
-
-## Configuration
-
-### Adding Custom Metafield Types
-
-Create a custom metafield type:
-
-```ruby
-# app/models/spree/metafields/url.rb
-module Spree
- module Metafields
- class Url < Spree::Metafield
- validates :value, format: { with: URI::DEFAULT_PARSER.make_regexp }
+When editing a resource (e.g., a product), metafields appear in a dedicated section. The admin panel automatically builds forms for all defined metafields.
- normalizes :value, with: ->(value) { value.to_s.strip }
+## Metafields vs Metadata
- def serialize_value
- URI.parse(value)
- rescue URI::InvalidURIError
- value
- end
- end
- end
-end
-```
-
-Register it in an initializer:
-
-```ruby config/initializers/spree.rb
-Spree.metafields.types << 'Spree::Metafields::Url'
-```
-
-### Enabling Metafields for Custom Resources
-
-```ruby config/initializers/spree.rb
-Spree.metafields.enabled_resources << 'Spree::Brand'
-```
-
-```ruby app/models/spree/brand.rb
-module Spree
- class Brand < Spree::Base
- include Spree::Metafields
- end
-end
-```
+| Feature | Metafields | Metadata |
+|---------|-----------|----------|
+| Structure | Strongly typed, schema-defined | Flat key-value JSON |
+| Validation | Type-specific validation | None |
+| Visibility | Configurable (front/back/both) | Write-only in Store API |
+| Admin UI | Dedicated management forms | JSON preview |
+| Data Types | 6 specific types | Any JSON-serializable data |
+| Organization | Namespaced (`namespace.key`) | Flat structure |
-## Metafields vs Metadata vs Product Properties
+**Use Metafields** when you need type validation, visibility control, admin UI forms, or organized namespacing.
-Understanding when to use each:
-
-| Feature | Metafields | Metadata | Product Properties (Legacy) |
-|---------|-----------|----------|----------------------------|
-| **Available Since** | Spree 5.2+ | All versions | Pre-5.2 (deprecated) |
-| **Recommended For** | New projects | Integration data, tracking | Legacy projects only |
-| **Structure** | Strongly typed, schema-defined | Stripe-style flat key-value | Product-specific properties |
-| **Validation** | Type-specific validation | None | Name/value pairs |
-| **Visibility** | Configurable (front/back/both) | Write-only in Store API, readable in Admin API | Always public |
-| **API Access** | Auto-included in API | Writable on cart, line items, orders | Auto-included in API |
-| **Admin UI** | Dedicated management UI | Viewable in JSON preview | Dedicated UI |
-| **Organization** | Namespaced (namespace.key) | Flat structure | Property-based |
-| **Data Types** | 6 specific types with serialization | Any JSON-serializable data | Text only |
-| **Querying** | Built-in query scopes | Manual JSON queries | Built-in queries |
-| **Resources** | Any enabled resource | Any resource | Products only |
-
-### When to Use Metafields
-
-- **New projects starting with Spree 5.2+**
-- You need type validation (numbers, booleans, URLs)
-- Different visibility for different audiences
-- Data appears in admin UI forms
-- You want query-optimized custom fields
-- You need organized namespacing
-- You want to extend multiple resource types
-
-### When to Use Metadata
-
-- Storing external system IDs (Stripe, ERP, CRM)
-- Tracking attribution data (UTM parameters, referral source)
-- Write-and-forget data for backend systems
-- Integration payloads that don't need validation or admin UI
-
-### When to Use Product Properties (Legacy)
-
-- **Existing projects upgrading from pre-5.2** that aren't ready to migrate
-- You need backward compatibility until Spree 6.0
-- You must enable via `config.product_properties_enabled = true`
+**Use Metadata** for external system IDs, tracking attribution, or simple write-and-forget data.
<Warning>
-Product Properties are deprecated and will be removed in Spree 6.0. For new projects, always use Metafields. For existing projects, plan to migrate using the [migration rake task](/developer/upgrades/5.1-to-5.2#3-migrate-to-metafields-or-keep-using-properties).
+Product Properties are deprecated and will be removed in Spree 6.0. For new projects, always use Metafields. For existing projects, plan to migrate using the [migration guide](/developer/upgrades/5.1-to-5.2#3-migrate-to-metafields-or-keep-using-properties).
</Warning>
-## Common Use Cases
-
-### Product Specifications
-
-```ruby
-# Define specifications namespace
-manufacturer_def = Spree::MetafieldDefinition.create!(
- namespace: 'specifications',
- key: 'manufacturer',
- name: 'Manufacturer',
- resource_type: 'Spree::Product',
- metafield_type: 'Spree::Metafields::ShortText',
- display_on: 'both'
-)
-
-warranty_def = Spree::MetafieldDefinition.create!(
- namespace: 'specifications',
- key: 'warranty_years',
- name: 'Warranty (Years)',
- resource_type: 'Spree::Product',
- metafield_type: 'Spree::Metafields::Number',
- display_on: 'both'
-)
-
-# Set values
-product.set_metafield('specifications.manufacturer', 'Sony')
-product.set_metafield('specifications.warranty_years', '2')
-```
-
-### Integration with External Systems
-
-```ruby
-# Store Shopify IDs (admin only)
-Spree::MetafieldDefinition.create!(
- namespace: 'shopify',
- key: 'product_id',
- name: 'Shopify Product ID',
- resource_type: 'Spree::Product',
- metafield_type: 'Spree::Metafields::ShortText',
- display_on: 'back_end'
-)
-
-product.set_metafield('shopify.product_id', '12345678')
-
-# Query products by Shopify ID
-Spree::Product.with_metafield_key_value('shopify.product_id', '12345678')
-```
-
-### Feature Flags
-
-```ruby
-# Create feature flag definitions
-Spree::MetafieldDefinition.create!(
- namespace: 'flags',
- key: 'featured',
- name: 'Featured Product',
- resource_type: 'Spree::Product',
- metafield_type: 'Spree::Metafields::Boolean',
- display_on: 'back_end'
-)
-
-# Set flags
-product.set_metafield('flags.featured', 'true')
-
-# Query featured products
-featured_products = Spree::Product
- .with_metafield_key('flags.featured')
- .joins(:metafields)
- .where(spree_metafields: { value: 'true' })
-```
-
-### Custom Order Data
-
-```ruby
-# Store gift message (visible to admins)
-Spree::MetafieldDefinition.create!(
- namespace: 'custom',
- key: 'gift_message',
- name: 'Gift Message',
- resource_type: 'Spree::Order',
- metafield_type: 'Spree::Metafields::LongText',
- display_on: 'back_end'
-)
-
-order.set_metafield('custom.gift_message', 'Happy Birthday!')
-
-# Store delivery instructions (visible to customers)
-Spree::MetafieldDefinition.create!(
- namespace: 'delivery',
- key: 'instructions',
- name: 'Delivery Instructions',
- resource_type: 'Spree::Order',
- metafield_type: 'Spree::Metafields::LongText',
- display_on: 'both'
-)
-
-order.set_metafield('delivery.instructions', 'Leave at front door')
-```
-
-## Best Practices
-
-1. **Use Descriptive Namespaces**: Group related metafields (e.g., `specifications.*`, `integration.*`, `custom.*`)
-
-2. **Choose Appropriate Visibility**: Don't expose internal data to the storefront
-
-3. **Validate Data Types**: Use the correct metafield type for your data
-
-4. **Keep Keys Consistent**: Use snake_case for keys, they're automatically normalized
-
-5. **Document Custom Types**: If creating custom metafield types, document their behavior
-
-6. **Query Efficiently**: Use the provided scopes instead of custom joins when possible
-
-7. **Handle Missing Values**: Always check if `get_metafield` returns nil
-
-8. **Use Set Metafield for Simplicity**: Prefer `set_metafield` over manual creation
-
-9. **Consider Performance**: Eager load metafields when displaying many resources:
-
-```ruby
-# ✅ Good - eager loads metafields
-products = Spree::Product.includes(:metafields).limit(20)
-
-# ❌ Bad - N+1 queries
-products = Spree::Product.limit(20)
-products.each { |p| p.metafields.to_a }
-```
+## Related Documentation
-10. **Migrate from Properties**: If upgrading from pre-5.2, use the [migration rake task](/developer/upgrades/5.1-to-5.2#3-migrate-to-metafields-or-keep-using-properties)
+- [Metadata](/developer/customization/metadata) — Simple key-value metadata
+- [Products](/developer/core-concepts/products) — Product catalog
+- [Events](/developer/core-concepts/events) — Subscribe to metafield events
diff --git a/docs/developer/core-concepts/orders.mdx b/docs/developer/core-concepts/orders.mdx
index 5ed899efa0..3c3d836980 100644
--- a/docs/developer/core-concepts/orders.mdx
+++ b/docs/developer/core-concepts/orders.mdx
@@ -1,254 +1,343 @@
---
title: Orders
+description: Order lifecycle, checkout flow, line items, payments, and shipments
---
## Overview
-The `Order` model is one of the key models in Spree. It provides a central place around which to collect information about a customer order - including line items, adjustments, payments, addresses, return authorizations, and shipments.
-
-### Order Model Diagram
+An order is the central model connecting a customer to their purchase. It collects line items, addresses, shipments, payments, and adjustments into a single transaction that flows through a checkout state machine from cart to completion.
```mermaid
erDiagram
+ Order ||--o{ LineItem : "has many"
+ Order ||--o{ Shipment : "has many"
+ Order ||--o{ Payment : "has many"
+ Order ||--o{ Adjustment : "has many"
+ Order }o--|| Address : "ship_address"
+ Order }o--|| Address : "bill_address"
+ Order }o--|| User : "belongs to"
+ Order }o--|| Store : "belongs to"
+ LineItem }o--|| Variant : "belongs to"
+ Shipment }o--|| StockLocation : "ships from"
+ Payment }o--|| PaymentMethod : "belongs to"
+
Order {
string number
string state
string email
- decimal item_total
- decimal adjustment_total
+ string currency
decimal total
- decimal payment_total
- decimal shipment_total
string payment_state
string shipment_state
- datetime completed_at
- string currency
}
LineItem {
integer quantity
decimal price
- decimal adjustment_total
}
Shipment {
string number
string state
string tracking
- datetime shipped_at
}
Payment {
- string number
decimal amount
string state
- string response_code
}
-
- Adjustment {
- decimal amount
- string label
- boolean eligible
- string state
- boolean included
- }
-
- Order ||--o{ LineItem : "has many"
- Order ||--o{ Shipment : "has many"
- Order ||--o{ Payment : "has many"
- Order ||--o{ Adjustment : "has many"
- Order ||--o{ ReturnAuthorization : "has many"
- Order ||--o{ OrderPromotion : "has many"
- Order }o--|| Address : "ship_address"
- Order }o--|| Address : "bill_address"
- Order }o--|| User : "belongs to"
- Order }o--|| Store : "belongs to"
- LineItem }o--|| Variant : "belongs to"
- LineItem ||--o{ Adjustment : "has many"
- Shipment ||--o{ InventoryUnit : "has many"
- Shipment ||--o{ Adjustment : "has many"
- Shipment }o--|| StockLocation : "ships from"
- Payment }o--|| PaymentMethod : "belongs to"
```
**Key relationships:**
-- **Order** is the central model connecting customers to their purchases
- **Line Items** link orders to [Variants](/developer/core-concepts/products#variants) (what was purchased)
-- **[Shipments](/developer/core-concepts/shipments)** handle fulfillment from [Stock Locations](/developer/core-concepts/inventory#stock-locations)
+- **[Shipments](/developer/core-concepts/shipments)** handle fulfillment from stock locations
- **[Payments](/developer/core-concepts/payments)** track payment attempts and their states
- **[Adjustments](/developer/core-concepts/adjustments)** apply taxes, promotions, and shipping costs
- **[Addresses](/developer/core-concepts/addresses)** store billing and shipping information
-### Order Attributes
-
-| Attribute | Description |
-|-------------------------|--------------------------------------------------------------------------------------------------|
-| `number` | The unique identifier for this order. It begins with the letter R and ends in a 9-digit number. This number is shown to the users, and can be used to find the order by calling `Spree::Order.find_by(number: number)`. |
-| `item_total` | The sum of all the line items for this order. |
-| `adjustment_total` | The sum of all adjustments on this order. |
-| `total` | The result of the sum of the `item_total` and the `adjustment_total`. |
-| `payment_total` | The total value of all finalized payments. |
-| `shipment_total` | The total value of all shipments' costs. |
-| `additional_tax_total` | The sum of all shipments' and line items' `additional_tax`. |
-| `included_tax_total` | The sum of all shipments' and line items' `included_tax`. |
-| `promo_total` | The sum of all shipments', line items' and promotions' `promo_total`. |
-| `state` | The current state of the order. To read more about the states an order goes through, read [The Order State Machine](orders#the-order-state-machine) section of this guide. |
-| `email` | The email address for the user who placed this order. Stored in case this order is for a guest user. |
-| `user_id` | The ID for the corresponding user record for this order. Stored only if the order is placed by a signed-in user. |
-| `completed_at` | The timestamp of when the order was completed. |
-| `bill_address_id` | The ID for the related `Address` object with billing address information. |
-| `ship_address_id` | The ID for the related `Address` object with shipping address information. |
-| `shipping_method_id` | The ID for the related `ShippingMethod` object. |
-| `created_by_id` | The ID of object that created this order. |
-| `shipment_state` | The current shipment state of the order. It takes into account all shipments. Described below in [Order Shipment states section](orders#order-shipment-states). |
-| `payment_state` | The current payment state of the order. It takes into account all payments. Described below in [Order Payment states section](orders#order-payment-states). |
-| `special_instructions` | Any special instructions for the store to do with this order. Will only appear if `Spree::Config[:shipping_instructions]` is set to `true`. |
-| `currency` | The currency for this order, eg. `USD` |
-| `last_ip_address` | The last IP address used to update this order in the frontend. |
-| `channel` | The channel specified when importing orders from other stores. e.g. amazon. |
-| `item_count` | The total value of line items' quantity. |
-| `approver_id` | The ID of user that approved this order. |
-| `confirmation_delivered`| Boolean value indicating that confirmation email was delivered. |
-| `token` | The token stored corresponding to token stored in cookies. |
-| `canceler_id` | The ID of user that canceled this order. |
-| `store_id` | The ID of `Store` in which this order was created. |
-
-## Order methods
-
-Here is a list of methods you may find useful:
-
-| Method | Description |
-|-----------------------------|-----------------------------------------------------------------------------------------------|
-| `outstanding_balance` | The outstanding balance for the order, calculated by taking the `total` and subtracting `payment_total`. |
-| `display_item_total` | A "pretty" version of `item_total`. If `item_total` was `10.0`, `display_item_total` would be `$10.00`. |
-| `display_adjustment_total` | Same as above, except for `adjustment_total`. |
-| `display_total` | Same as above, except for `total`. |
-| `display_outstanding_balance` | Same as above, except for `outstanding_balance`. |
-
-To see all available methods, please check the [Order model source code](https://github.com/spree/spree/blob/main/core/app/models/spree/order.rb).
-
-## The Order State Machine
-
-Each Order flows through a state machine, beginning at a `cart` state and ending up at a `complete` state.
-
-<Note>
-This is the default order flow and can be adjusted or overhauled completely.
-
-More on this topic at [Customizing Checkout page](../customization/checkout).
-</Note>
-
-The default states are as follows:
+## Order Attributes
+
+The API returns these key fields on every order:
+
+| Attribute | Description |
+|-----------|-------------|
+| `number` | Unique order number (e.g., `R123456789`), shown to customers |
+| `state` | Current checkout state (`cart`, `address`, `delivery`, `payment`, `confirm`, `complete`) |
+| `email` | Customer's email address |
+| `currency` | Order currency (e.g., `USD`) |
+| `item_count` | Total number of items |
+| `item_total` / `display_item_total` | Sum of line item prices |
+| `ship_total` / `display_ship_total` | Shipping cost |
+| `tax_total` / `display_tax_total` | Total tax |
+| `promo_total` / `display_promo_total` | Total discount from promotions |
+| `adjustment_total` / `display_adjustment_total` | Sum of all adjustments (tax + shipping + promos) |
+| `total` / `display_total` | Final order total |
+| `payment_state` | Payment status (`balance_due`, `paid`, `credit_owed`, `failed`, `void`) |
+| `shipment_state` | Shipment status (`pending`, `ready`, `partial`, `shipped`, `backorder`) |
+| `completed_at` | Timestamp when the order was placed |
+
+The `display_*` fields return formatted strings with currency symbols (e.g., `"$15.99"`).
+
+## Cart
+
+A cart is simply an order in the `cart` state. Guest carts are identified by a cart token; authenticated users' carts are linked to their account.
+
+<CodeGroup>
+
+```typescript SDK
+// Create a cart
+const cart = await client.store.cart.create()
+// cart.token => "abc123" (save this for guest checkout)
+
+// Get existing cart
+const cart = await client.store.cart.get()
+
+// Add an item
+const updatedOrder = await client.store.orders.lineItems.create(cart.id, {
+ variant_id: 'var_xxx',
+ quantity: 2,
+})
+
+// Update quantity
+await client.store.orders.lineItems.update(cart.id, 'li_xxx', {
+ quantity: 3,
+})
+
+// Remove an item
+await client.store.orders.lineItems.delete(cart.id, 'li_xxx')
+```
+
+```bash cURL
+# Create a cart
+curl -X POST 'https://api.mystore.com/api/v3/store/cart' \
+ -H 'Authorization: Bearer spree_pk_xxx'
+
+# Get existing cart
+curl 'https://api.mystore.com/api/v3/store/cart' \
+ -H 'Authorization: Bearer spree_pk_xxx' \
+ -H 'X-Spree-Order-Token: abc123'
+
+# Add an item
+curl -X POST 'https://api.mystore.com/api/v3/store/orders/or_xxx/line_items' \
+ -H 'Authorization: Bearer spree_pk_xxx' \
+ -H 'X-Spree-Order-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/orders/or_xxx/line_items/li_xxx' \
+ -H 'Authorization: Bearer spree_pk_xxx' \
+ -H 'X-Spree-Order-Token: abc123' \
+ -H 'Content-Type: application/json' \
+ -d '{ "quantity": 3 }'
+
+# Remove an item
+curl -X DELETE 'https://api.mystore.com/api/v3/store/orders/or_xxx/line_items/li_xxx' \
+ -H 'Authorization: Bearer spree_pk_xxx' \
+ -H 'X-Spree-Order-Token: abc123'
+```
+
+</CodeGroup>
+
+Every line item mutation returns the full updated order with recalculated totals.
+
+## Checkout Flow
+
+The checkout is a state machine that advances the order through a series of steps. Each step collects required information before allowing the order to proceed.
<Steps>
<Step title="cart">
- Initial state, you can treat it as a draft order
+ Customer has items in their cart. This is the starting state.
</Step>
<Step title="address">
- Buyer started the checkout process and is on the address step
+ Customer provides shipping and billing addresses.
</Step>
<Step title="delivery">
- Buyer has added Shipping and Billing addresses, now he or she needs to select a delivery option
+ Customer selects a shipping rate for each shipment.
</Step>
<Step title="payment">
- Buyer selected delivery option, now he or she needs to add a payment option
-
- <Note>
- Only available if `Order#payment_required?` returns `true`. For most orders it will be `true`, but if the order is paid entirely with [Store Credit](store-credit) it will be `false`.
- </Note>
+ Customer provides payment. Skipped if the order is fully covered by store credit.
</Step>
<Step title="confirm">
- Buyer added payment option, now he or she needs to confirm the order
-
- <Note>
- Only available if `Order#confirmation_required?` returns `true`
- </Note>
+ Customer reviews and confirms the order.
</Step>
<Step title="complete">
- Order was placed. It will set the `completed_at` date to the current time.
+ Order is placed. `completed_at` is set and fulfillment begins.
</Step>
</Steps>
-Assuming that an order meets the criteria for the next state, you will be able to transition it to the next state by calling `next` on that object, eg.
-
-```ruby
-order = Spree::Order.find_by(number: 'R123456')
-order.next
+Advance to the next step with `next`. If the order doesn't meet the requirements for the next state (e.g., missing address), the API returns an error.
+
+<CodeGroup>
+
+```typescript SDK
+// Set addresses
+await client.store.orders.update(orderId, {
+ email: '[email protected]',
+ ship_address: {
+ firstname: 'John', lastname: 'Doe',
+ address1: '123 Main St', city: 'Los Angeles',
+ country_iso: 'US', state_abbr: 'CA', zipcode: '90001',
+ phone: '555-0100',
+ },
+})
+
+// Advance to delivery
+await client.store.orders.next(orderId)
+
+// Get shipments and select a shipping rate
+const { data: shipments } = await client.store.orders.shipments.list(orderId)
+await client.store.orders.shipments.update(orderId, shipments[0].id, {
+ selected_shipping_rate_id: 'sr_xxx',
+})
+
+// Advance to payment
+await client.store.orders.next(orderId)
+
+// Create a payment session (e.g., Stripe)
+const session = await client.store.orders.paymentSessions.create(orderId, {
+ payment_method_id: 'pm_xxx',
+})
+// session.external_data.client_secret => use with Stripe.js
+
+// Complete the payment session after provider confirmation
+await client.store.orders.paymentSessions.complete(orderId, session.id)
+
+// Complete the order
+await client.store.orders.complete(orderId)
```
-If this returns `false`, then the order does _not_ meet the criteria. To work out why it cannot transition, check the result of an `errors` method call.
-
-### Order Shipment states
+```bash cURL
+# Set addresses
+curl -X PATCH 'https://api.mystore.com/api/v3/store/orders/or_xxx' \
+ -H 'Authorization: Bearer spree_pk_xxx' \
+ -H 'X-Spree-Order-Token: abc123' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "email": "[email protected]",
+ "ship_address": {
+ "firstname": "John", "lastname": "Doe",
+ "address1": "123 Main St", "city": "Los Angeles",
+ "country_iso": "US", "state_abbr": "CA", "zipcode": "90001",
+ "phone": "555-0100"
+ }
+ }'
+
+# Advance to next step
+curl -X PATCH 'https://api.mystore.com/api/v3/store/orders/or_xxx/next' \
+ -H 'Authorization: Bearer spree_pk_xxx' \
+ -H 'X-Spree-Order-Token: abc123'
+
+# Select a shipping rate
+curl -X PATCH 'https://api.mystore.com/api/v3/store/orders/or_xxx/shipments/shp_xxx' \
+ -H 'Authorization: Bearer spree_pk_xxx' \
+ -H 'X-Spree-Order-Token: abc123' \
+ -H 'Content-Type: application/json' \
+ -d '{ "selected_shipping_rate_id": "sr_xxx" }'
+
+# Complete the order
+curl -X PATCH 'https://api.mystore.com/api/v3/store/orders/or_xxx/complete' \
+ -H 'Authorization: Bearer spree_pk_xxx' \
+ -H 'X-Spree-Order-Token: abc123'
+```
-Alongside the global Order state there's also `shipment_state` column which indicates the state of all shipments. Order can have multiple shipments.
+</CodeGroup>
-| State | Description |
-|-----------|-------------|
-| `shipped` | all Shipments are in the `shipped` state |
-| `partial` | at least one Shipment has a state of `shipped` and there is another Shipment with a state other than `shipped` or there are [InventoryUnits](inventory) associated with the order that have a state of `sold` but are not associated with a Shipment |
-| `ready` | all Shipments are in the `ready` state |
-| `backorder` | there is backordered inventory associated with an order |
-| `pending` | all Shipments are in the `pending` state |
+## Coupon Codes
-For more on this please go to [Shipment States page](shipments).
+Apply or remove promotional coupon codes during checkout:
-### Order Payment states
+<CodeGroup>
-Alongside the global Order state there's also `payment_state` column which indicates the state of all payments. Order can have multiple payments.
+```typescript SDK
+// Apply a coupon
+await client.store.orders.couponCodes.apply(orderId, 'SAVE20')
-| State | Description |
-|--------------|-----------------------------------------------------|
-| `paid` | `payment_total` is equal to `total` |
-| `balance_due`| `payment_total` is less than `total` |
-| `credit_owed`| `payment_total` is greater than `total` |
-| `failed` | most recent payment is in the `failed` state |
-| `void` | order is canceled and `payment_total` is equal to `zero` |
+// Remove a coupon
+await client.store.orders.couponCodes.remove(orderId, 'promo_xxx')
+```
-For more on this please go to [Payment States page](payments).
+```bash cURL
+# Apply a coupon
+curl -X POST 'https://api.mystore.com/api/v3/store/orders/or_xxx/coupon_codes' \
+ -H 'Authorization: Bearer spree_pk_xxx' \
+ -H 'X-Spree-Order-Token: abc123' \
+ -H 'Content-Type: application/json' \
+ -d '{ "code": "SAVE20" }'
+
+# Remove a coupon
+curl -X DELETE 'https://api.mystore.com/api/v3/store/orders/or_xxx/coupon_codes/promo_xxx' \
+ -H 'Authorization: Bearer spree_pk_xxx' \
+ -H 'X-Spree-Order-Token: abc123'
+```
-## Line Items
+</CodeGroup>
-Line items are used to keep track of items within the context of an order. These records provide a link between orders and [Variants](/developer/core-concepts/products#variants).
+## Order History
-<Warning>
-When a variant is added to an order, the price of that item is tracked along with the line item to preserve that data. If the variant's price were to change, then the line item would still have a record of the price at the time of ordering.
-</Warning>
+Authenticated customers can view their past orders:
-## Addresses
+<CodeGroup>
-An order can link to two `Address` objects. The shipping address indicates where the order's products should be shipped to. This address is used to determine which shipping methods are available for an order.
+```typescript SDK
+// List past orders
+const { data: orders } = await client.store.customer.orders.list()
-The billing address indicates where the user who's paying for the order is located. This can alter the tax rate for the order, which in turn can change how much the final order total can be.
+// Get a specific order with details
+const order = await client.store.orders.get('or_xxx', {
+ expand: ['line_items', 'shipments', 'payments'],
+})
+```
-For more information about addresses, please read the [Addresses](/developer/core-concepts/addresses) guide.
+```bash cURL
+# List past orders
+curl 'https://api.mystore.com/api/v3/store/customer/orders' \
+ -H 'Authorization: Bearer <jwt_token>'
-## Adjustments
+# Get a specific order
+curl 'https://api.mystore.com/api/v3/store/orders/or_xxx?expand=line_items,shipments,payments' \
+ -H 'Authorization: Bearer <jwt_token>'
+```
-Adjustments are used to affect an order's final cost, either by decreasing it ([Promotions](/developer/core-concepts/promotions)) or by increasing it ([Shipping](/developer/core-concepts/shipments), [Taxes](/developer/core-concepts/taxes)).
+</CodeGroup>
-For more information about adjustments, please see the [Adjustments](adjustments) guide.
+## Line Items
-## Payments
+Line items represent individual products in an order. Each line item links to a [Variant](/developer/core-concepts/products#variants) and tracks the quantity and price at the time of purchase.
-Payment records are used to track payment information about an order. Each Order can hold multiple payments, eg. one for each credit card or debit card and one for the store credit.
+When a variant is added to an order, the price is locked on the line item. If the variant's price changes later, existing orders are unaffected.
-For more information, please read the [Payments](payments) guide.
+## Adjustments
-## Return Authorizations
+[Adjustments](/developer/core-concepts/adjustments) modify an order's total — promotions decrease it, taxes and shipping increase it. Adjustments can be applied at the order level, the line item level, or the shipment level.
-An order can have many `ReturnAuthorization` objects. These records keeps track of which items have been authorized for return and how the user will be compensated -- either via exchanging the items or a reimbursement.
+## Payment States
-## Updating an Order
+| State | Description |
+|-------|-------------|
+| `balance_due` | Payment total is less than the order total |
+| `paid` | Payment total equals the order total |
+| `credit_owed` | Payment total exceeds the order total (refund pending) |
+| `failed` | Most recent payment attempt failed |
+| `void` | Order was canceled and payments voided |
-If you change any aspect of an `Order` object within code and you wish to update the order's totals -- including associated adjustments and shipments -- call the `update_with_updater!` method on that object, which calls out to the [OrderUpdater](https://github.com/spree/spree/blob/main/core/app/models/spree/order_updater.rb) class.
+## Shipment States
-For example, if you create or modify an existing payment for the order which would change the order's `payment_state` to a different value, calling `update_with_updater!` will cause the `payment_state` to be recalculated for that order.
+| State | Description |
+|-------|-------------|
+| `pending` | All shipments are pending |
+| `ready` | All shipments are ready to ship |
+| `partial` | At least one shipment is shipped, others are not |
+| `shipped` | All shipments have been shipped |
+| `backorder` | Some inventory is on backorder |
-Another example is if a `LineItem` within the order had its price changed. Calling `update_with_updater!` will cause the totals for the order to be updated, the adjustments for the order to be recalculated, and then a final total to be established.
+For more details, see [Shipments](/developer/core-concepts/shipments) and [Payments](/developer/core-concepts/payments).
## Related Documentation
-- [Payments](/developer/core-concepts/payments) - Payment processing for orders
-- [Shipments](/developer/core-concepts/shipments) - Order fulfillment and shipping
-- [Promotions](/developer/core-concepts/promotions) - Discounts and promotions
-- [Checkout Customization](/developer/customization/checkout) - Customizing the checkout flow
-- [Events](/developer/core-concepts/events) - Subscribe to order events
+- [Payments](/developer/core-concepts/payments) — Payment processing and payment sessions
+- [Shipments](/developer/core-concepts/shipments) — Fulfillment and shipping rates
+- [Addresses](/developer/core-concepts/addresses) — Billing and shipping addresses
+- [Promotions](/developer/core-concepts/promotions) — Discounts and coupon codes
+- [Checkout Customization](/developer/customization/checkout) — Customizing the checkout flow
+- [Events](/developer/core-concepts/events) — Subscribe to order events (e.g., `order.completed`)
diff --git a/docs/developer/core-concepts/payments.mdx b/docs/developer/core-concepts/payments.mdx
index 2f60e62e59..891b947811 100644
--- a/docs/developer/core-concepts/payments.mdx
+++ b/docs/developer/core-concepts/payments.mdx
@@ -12,7 +12,7 @@ The `Payment` model in Spree tracks payments against [Orders](orders). Payments
When a payment is created, it is given a unique, 8-character identifier. This is used when sending the payment details to the payment processor. Without this identifier, some payment gateways mistakenly reported duplicate payments.
-### Payment Model Diagram
+### Payment Architecture Diagram
```mermaid
erDiagram
@@ -23,7 +23,7 @@ erDiagram
string response_code
string avs_response
string source_type
- integer source_id
+ string source_id
}
PaymentMethod {
@@ -35,14 +35,37 @@ erDiagram
integer position
}
+ PaymentSession {
+ string status
+ decimal amount
+ string currency
+ string external_id
+ json external_data
+ datetime expires_at
+ }
+
+ PaymentSetupSession {
+ string status
+ string external_id
+ string external_client_secret
+ json external_data
+ }
+
+ PaymentSource {
+ string type
+ string gateway_payment_profile_id
+ }
+
CreditCard {
string last_digits
string cc_type
integer month
integer year
string name
- string gateway_customer_profile_id
- string gateway_payment_profile_id
+ }
+
+ GatewayCustomer {
+ string profile_id
}
StoreCredit {
@@ -62,12 +85,21 @@ erDiagram
}
Order ||--o{ Payment : "has many"
+ Order ||--o{ PaymentSession : "has many"
Payment }o--|| PaymentMethod : "belongs to"
Payment }o--o| CreditCard : "source"
+ Payment }o--o| PaymentSource : "source"
Payment }o--o| StoreCredit : "source"
+ Payment ||--o| PaymentSession : "linked via response_code"
Payment ||--o{ LogEntry : "has many"
Payment ||--o{ Refund : "has many"
+ PaymentMethod ||--o{ PaymentSession : "has many"
+ PaymentMethod ||--o{ PaymentSetupSession : "has many"
+ PaymentMethod ||--o{ GatewayCustomer : "has many"
PaymentMethod }o--|| Store : "belongs to"
+ PaymentSetupSession }o--o| PaymentSource : "creates"
+ PaymentSetupSession }o--|| Customer : "belongs to"
+ GatewayCustomer }o--|| Customer : "belongs to"
CreditCard }o--|| Customer : "belongs to"
StoreCredit }o--|| Customer : "belongs to"
Refund }o--|| Payment : "belongs to"
@@ -76,39 +108,194 @@ erDiagram
**Key relationships:**
- **Payment** tracks each payment attempt against an [Order](/developer/core-concepts/orders)
-- **Payment Method** defines how payments are processed (Stripe, PayPal, Check, etc.)
-- **Source** is polymorphic - can be a Credit Card, Store Credit, or other payment sources
+- **Payment Method** defines how payments are processed (Stripe, Adyen, PayPal, Check, etc.)
+- **Payment Session** manages the gateway-side payment lifecycle (e.g., Stripe PaymentIntent, Adyen Session)
+- **Payment Setup Session** manages saving payment methods for future use without an immediate charge (e.g., Stripe SetupIntent)
+- **Source** is polymorphic - can be a Credit Card, Payment Source (for alternative methods like Klarna, iDEAL), or Store Credit
+- **Gateway Customer** stores the provider-specific customer profile (e.g., Stripe Customer ID)
- **Log Entries** record gateway responses for debugging
- **Refunds** track money returned to customers
-## Payment States
+## Payment Methods
+
+Payment methods represent the different options a customer has for making a payment. Most sites will accept credit card payments through a payment gateway, but there are other options. Spree also comes with built-in support for a Check payment, which can be used to represent any offline payment. Gateway providers such as Stripe, Adyen, and PayPal provide a wide range of payment methods, including credit cards, bank transfers, buy-now-pay-later, and digital wallets (Apple Pay, Google Pay, etc.).
+
+A `PaymentMethod` can have the following attributes:
+
+| Attribute | Description | Example |
+|--------------|-----------------------------------------------------------------------------------------------|------------------------|
+| `type` | The payment method type | `Check` |
+| `name` | The visible name for this payment method | `Check` |
+| `description`| The description for this payment method | `Pay by check.` |
+| `active` | Whether or not this payment method is active. Set it `false` to hide it in the Store API. | `true` |
+| `display_on` | Determines where the payment method can be visible. Values can be `front` for Store API, `back` for admin panel only or `both` for both. | `both` |
+| `position` | The position of the payment method in lists. Lower numbers appear first. | `1` |
+
+<Info>
+Each payment method is associated to a Store, so you can decide which Payment Method will appear on which Store. This allows you to create different experiences for your customers in different countries.
+</Info>
+
+### Session-based vs Legacy Payment Methods
+
+Payment methods indicate whether they use the modern session-based flow via the `session_required?` method:
+
+| Method | Description | Default |
+|--------|-------------|---------|
+| `session_required?` | Returns `true` if this payment method requires a Payment Session for processing. | `false` |
+| `setup_session_supported?` | Returns `true` if this payment method supports saving payment methods for future use (Payment Setup Sessions). | `false` |
+| `payment_session_class` | Returns the STI subclass of `Spree::PaymentSession` for this gateway (e.g., `Spree::PaymentSessions::Stripe`). | `nil` |
+| `payment_setup_session_class` | Returns the STI subclass of `Spree::PaymentSetupSession` for this gateway. | `nil` |
+
+Modern gateways like Stripe and Adyen set `session_required?` to `true`. The Store API serializer includes this as the `session_required` field so your frontend knows which flow to use.
+
+## Payment Flow
+
+Modern payment gateways (Stripe, Adyen, PayPal) use a two-phase approach: first a **Payment Session** is created with the gateway, then after the customer completes payment on the frontend, Spree creates a **Payment** record to track the result. This ensures full PCI compliance, 3D Secure support, and compatibility with all payment method types.
-A payment can go through many different states:
+```mermaid
+sequenceDiagram
+ participant Frontend
+ participant Spree API
+ participant Payment Provider
+
+ rect rgb(240, 245, 255)
+ note right of Frontend: Phase 1: Payment Session
+ Frontend->>Spree API: Create Payment Session
+ Spree API->>Payment Provider: Create session (PaymentIntent/Session)
+ Payment Provider-->>Spree API: Session ID + client_secret
+ Spree API-->>Frontend: PaymentSession (pending)
+ end
+
+ rect rgb(240, 255, 240)
+ note right of Frontend: Phase 2: Customer Pays
+ Frontend->>Payment Provider: Collect payment (using client_secret)
+ Note over Frontend,Payment Provider: 3DS challenge handled here if needed
+ Payment Provider-->>Frontend: Payment result
+ end
+
+ rect rgb(255, 245, 240)
+ note right of Frontend: Phase 3: Payment Created
+ alt Webhook-driven completion
+ Payment Provider->>Spree API: Webhook (payment succeeded)
+ Spree API->>Spree API: Create Payment (completed)
+ else Client-driven completion
+ Frontend->>Spree API: Complete Payment Session
+ Spree API->>Payment Provider: Verify result
+ Spree API->>Spree API: Create Payment (completed)
+ end
+ Spree API-->>Frontend: Order completed
+ end
+```
<Steps>
- <Step title="checkout">
- Checkout has not been completed
- </Step>
- <Step title="processing">
- The payment is being processed (temporary – intended to prevent double submission)
+ <Step title="Create Payment Session">
+ The frontend calls the API to create a Payment Session for a specific payment method and order. Spree calls the gateway to create a provider-side session (e.g., Stripe PaymentIntent, Adyen Session) and returns the session data including a `client_secret` for the frontend SDK.
</Step>
- <Step title="pending">
- The payment has been processed but is not yet complete (ex. authorized but not captured)
+ <Step title="Customer pays on the frontend">
+ The frontend uses the gateway's JavaScript SDK (e.g., Stripe.js, Adyen Drop-in) with the `client_secret` to securely collect payment details. Card data never touches your server - it goes directly to the payment provider, ensuring **PCI compliance**. If the payment requires **3D Secure** authentication, the gateway SDK automatically presents the challenge.
</Step>
- <Step title="failed">
- The payment was rejected (ex. credit card was declined)
- </Step>
- <Step title="void">
- The payment should not be counted against the order
- </Step>
- <Step title="completed">
- The payment is completed. Only payments in this state count against the order total
+ <Step title="Payment is created and order is completed">
+ After the customer completes payment, the session is completed either via a webhook from the provider or by the frontend calling the complete endpoint. Spree creates a `Payment` record (in `completed` or `pending` state depending on auto-capture settings), creates the appropriate payment source (Credit Card, Klarna, etc.), and completes the order.
</Step>
</Steps>
-## Payment Attributes
+### Payment Session
+
+A `PaymentSession` (`Spree::PaymentSession`) represents a server-side session with the payment gateway. It is the entry point for every payment attempt and holds the provider-specific data needed by the frontend SDK.
+
+#### Attributes
+
+| Attribute | Description | Example Value |
+|-----------|-------------|---------------|
+| `status` | Current session state: `pending`, `processing`, `completed`, `failed`, `canceled`, `expired` | `completed` |
+| `amount` | The payment amount | `99.99` |
+| `currency` | ISO currency code | `USD` |
+| `external_id` | The provider-side session ID (e.g., Stripe PaymentIntent ID) | `pi_3ABC123` |
+| `external_data` | Provider-specific data including `client_secret` for frontend SDK | `{"client_secret": "pi_3ABC_secret_xyz"}` |
+| `customer_external_id` | The provider's customer ID | `cus_ABC123` |
+| `expires_at` | When the session expires | `2025-01-01T12:00:00Z` |
+
+#### States
+
+```mermaid
+stateDiagram-v2
+ [*] --> pending
+ pending --> processing
+ pending --> completed
+ pending --> failed
+ pending --> canceled
+ pending --> expired
+ processing --> completed
+ processing --> failed
+ processing --> canceled
+ processing --> expired
+```
+
+#### API
+
+**Create a Payment Session:**
+
+```typescript
+const options = { orderToken: cart.token }
+
+// Create a payment session for the selected payment method
+const session = await client.store.orders.paymentSessions.create(cart.id, {
+ payment_method_id: 'pm_xyz789',
+ amount: '99.99', // Optional, defaults to order total
+ external_data: {}, // Optional, provider-specific data
+}, options)
+
+// The session contains provider-specific data for the frontend SDK
+console.log(session.external_id) // e.g. 'pi_3ABC123' (Stripe PaymentIntent ID)
+console.log(session.external_data.client_secret) // Use with Stripe.js or Adyen Drop-in
+```
+
+**Response shape (`StorePaymentSession`):**
+
+```json
+{
+ "id": "ps_abc123",
+ "status": "pending",
+ "amount": "99.99",
+ "currency": "USD",
+ "external_id": "pi_3ABC123",
+ "external_data": {
+ "client_secret": "pi_3ABC123_secret_xyz"
+ },
+ "customer_external_id": "cus_ABC123",
+ "expires_at": "2025-01-01T12:00:00Z",
+ "payment_method_id": "pm_xyz789",
+ "order_id": "or_ABC123",
+ "payment": null
+}
+```
+
+**Update a Payment Session** (e.g., after order total changes):
+
+```typescript
+const updated = await client.store.orders.paymentSessions.update(
+ cart.id, session.id,
+ { amount: '149.99' },
+ options
+)
+```
+
+**Complete a Payment Session** (after customer confirms payment on the frontend):
+
+```typescript
+const completed = await client.store.orders.paymentSessions.complete(
+ cart.id, session.id,
+ { session_result: '...', external_data: {} },
+ options
+)
+console.log(completed.status) // 'completed'
+```
+
+### Payment
-Here's the list of attributes for the `Spree::Payment` model:
+Once a Payment Session is completed, Spree creates a `Payment` record (`Spree::Payment`) to track the result. The Payment is linked to the session via `response_code` matching the session's `external_id`.
+
+#### Attributes
| Attribute | Description | Example Value |
|-------------------|-----------------------------------------------------------------------------|---------------------|
@@ -118,133 +305,196 @@ Here's the list of attributes for the `Spree::Payment` model:
| `amount` | The amount of the payment. | `99.99` |
| `payment_method_id`| The ID of the payment method used. | `2` |
| `state` | The current state of the payment (e.g., processing, completed, failed). | `completed` |
-| `response_code` | The response code returned by the payment processor. | `AUTH_123456` |
+| `response_code` | The gateway transaction ID. Links to the Payment Session's `external_id`. | `pi_3ABC123` |
| `avs_response` | The address verification system response code. | `D` |
-## Payment Methods
+#### Payment States
-Payment methods represent the different options a customer has for making a payment. Most sites will accept credit card payments through a payment gateway, but there are other options. Spree also comes with built-in support for a Check payment, which can be used to represent any offline payment. Gateway providers such as Stripe, Braintree, and PayPal provide a wide range of payment methods, including credit cards, bank transfers, buy-now-pay-later, and digital wallets (Apple Pay, Google Pay, etc.).
+After a Payment Session completes, the resulting Payment transitions through these states:
-A `PaymentMethod` can have the following attributes:
+```mermaid
+stateDiagram-v2
+ [*] --> checkout
+ checkout --> processing : process!
+ processing --> completed : purchase! succeeds
+ processing --> pending : authorize! succeeds
+ processing --> failed : payment declined
+ pending --> completed : capture!
+ pending --> void : void!
+ completed --> void : void!
+ checkout --> void : void!
+```
-| Attribute | Description | Example |
-|--------------|-----------------------------------------------------------------------------------------------|------------------------|
-| `type` | The subclass of `Spree::PaymentMethod` this payment method represents. Uses rails single table inheritance feature. | `Spree::PaymentMethod::Check` |
-| `name` | The visible name for this payment method | `Check` |
-| `description`| The description for this payment method | `Pay by check.` |
-| `active` | Whether or not this payment method is active. Set it `false` to hide it in frontend. | `true` |
-| `display_on` | Determines where the payment method can be visible. Values can be `front` for Storefront, `back` for Admin Panel only or `both` for both. | `both` |
-| `position` | The position of the payment method in lists. Lower numbers appear first. | `1` |
+| State | Description |
+|-------|-------------|
+| `checkout` | Initial state. The payment has been created but not yet processed. |
+| `processing` | The payment is being processed (temporary - prevents double submission). |
+| `pending` | The payment has been authorized but not yet captured. Awaiting manual or scheduled capture. |
+| `failed` | The payment was rejected (e.g., card declined, insufficient funds). |
+| `void` | The payment has been voided and should not be counted against the order. |
+| `completed` | The payment has been captured. Only payments in this state count against the order total. |
-<Info>
-Each payment method is associated to a Store, so you can decide which Payment Method will appear on which Store. This allows you to create different experiences for your customers in different countries.
-</Info>
+With **auto-capture** enabled (default for most gateways), the Payment goes directly from `checkout` → `processing` → `completed`. With **manual capture**, it stops at `pending` until an admin captures it.
-## Payment Processing
+#### Order Payment States
-Payment processing in Spree supports many different gateways, but also attempts to comply with the API provided by the [active_merchant](https://github.com/shopify/active_merchant) gem where possible.
+Each payment update also recalculates the order's `payment_state`:
-### Gateway Options
+| Payment State | Description |
+|---------------|-------------|
+| `balance_due` | Payment is required for this order |
+| `failed` | The last payment for the order failed |
+| `credit_owed` | This order has been paid for in excess of its total |
+| `paid` | This order has been paid for in full |
+
+<Warning>
+You may want to keep tabs on the number of orders with a `payment_state` of `failed`. A sudden increase could indicate a problem with your payment gateway and most likely a serious problem affecting customer satisfaction. Check the latest `log_entries` for the most recent payments if this is happening.
+</Warning>
-For every gateway action, a list of gateway options are passed through.
+### Log Entries
-| Gateway Option | Description |
-|--------------------|-----------------------------------------------------------------------------------------------|
-| `email` and `customer` | The email address related to the order |
-| `ip` | The last IP address for the order |
-| `order_id` | The Order's `number` attribute, plus the `identifier` for each payment, generated when the payment is first created |
-| `shipping` | The total shipping cost for the order, in cents |
-| `tax` | The total tax cost for the order, in cents |
-| `subtotal` | The item total for the order, in cents |
-| `currency` | The 3-character currency code for the order |
-| `discount` | The promotional discount applied to the order |
-| `billing_address` | A hash containing billing address information |
-| `shipping_address` | A hash containing shipping address information |
+Responses from payment gateways are stored as log entries for debugging purposes. These can be viewed in the Admin Panel on the payment detail page.
-The billing address and shipping address data is as follows:
+## Payment Sources
-| Attribute | Description |
-|-------------|-----------------------------------------------------------------------------------------------|
-| `name` | The combined `first_name` and `last_name` from the address |
-| `address1` | The first line of the address information |
-| `address2` | The second line of address information |
-| `city` | The city of the address |
-| `state` | An abbreviated version of the state name or, failing that, the state name itself, from the related `State` object. If that fails, the `state_name` attribute from the address. |
-| `country` | The ISO name for the country. For example, United States of America is "US", Australia is "AU". |
-| `phone` | The phone number associated with the address |
+Payment sources represent the actual instrument used for a payment. They are created automatically when a Payment Session completes.
-### Credit card data
+### Credit Cards (`Spree::CreditCard`)
-Spree stores only necessary non-sensitive credit card information as a `Spree::CreditCard` record with the following attributes:
+Stores non-sensitive credit card information. With modern gateways, the actual card data is tokenized by the provider - Spree only stores reference IDs and display information.
| Attribute | Description | Example Value |
|---------------------|-----------------------------------------------------------------------------------------------|------------------------|
-| `month` | The month the credit card expires. Stored as an integer (1-12). | `6` |
-| `year` | The year the credit card expires. Stored as a four-digit integer (e.g., 2024). | `2024` |
+| `month` | The month the credit card expires. | `6` |
+| `year` | The year the credit card expires. | `2026` |
| `cc_type` | The type of credit card (e.g., visa, mastercard). | `visa` |
| `last_digits` | The last four digits of the credit card number. | `1234` |
-| `name` | The name of the credit card holder as it appears on the card. | `John Doe` |
-| `gateway_customer_profile_id` | The customer profile identifier from the payment gateway. Useful for recurring transactions.| `cust_123456789` |
-| `gateway_payment_profile_id` | The payment profile identifier from the payment gateway. | `paym_987654321` |
+| `name` | The name of the credit card holder. | `John Doe` |
+| `gateway_payment_profile_id` | The payment token from the gateway (e.g., Stripe `pm_xxx`, Adyen `storedPaymentMethodId`). | `pm_1ABC123` |
<Note>
-We don't store the full credit card number, only the last 4 digits and the card type. This is a security precaution to protect the cardholder's privacy. For any post-purchase operations we authenticate the card using the `gateway_customer_profile_id` and `gateway_payment_profile_id`.
+Spree never stores full credit card numbers. With modern gateways, card data is collected entirely by the gateway's frontend SDK (e.g., Stripe.js, Adyen Drop-in) and never touches your server. Spree only stores the tokenized reference (`gateway_payment_profile_id`) returned by the provider.
</Note>
-### Processing Walkthrough
+### Payment Sources
-When an order is completed in Spree, each `Payment` object associated with the order has the `process!` method called on it unless `payment_required?` for the order returns `false`, in order to attempt to automatically fulfill the payment required for the order. If the payment method requires a source (e.g., `Spree::CreditCard`), and the payment has a source associated with it, then Spree will attempt to process the payment. Otherwise, the payment will need to be processed manually.
+A generic payment source model for non-card payment methods such as digital wallets, bank transfers, and buy-now-pay-later services. Gateway integrations create subtypes for each payment method type (e.g., Klarna, Afterpay, iDEAL, Apple Pay, Google Pay, PayPal).
-If the `PaymentMethod` object is configured to auto-capture payments, then the `Payment#purchase!` method will be called, which will call `PaymentMethod#purchase` like this:
+### Gateway Customers (`Spree::GatewayCustomer`)
-```ruby
-payment_method.purchase(<amount>, <source>, <gateway options>)
-```
+Maps a Spree customer to their provider-specific customer profile. This enables features like saved payment methods, recurring billing, and customer-level fraud detection.
-If the payment is _not_ configured to auto-capture payments, the `Payment#authorize!` method will be called, with the same arguments as the `purchase` method above:
+| Attribute | Description | Example Value |
+|-----------|-------------|---------------|
+| `profile_id` | The provider's customer ID (encrypted at rest) | `cus_ABC123` |
+| `payment_method_id` | The gateway this customer belongs to | `1` |
+| `user_id` | The Spree user | `42` |
-```ruby
-payment_method.authorize(<amount>, <source>, <gateway options>)
-```
+Each customer has at most one `GatewayCustomer` record per payment method. The `profile_id` is encrypted using Active Record Encryption when available.
-How the payment is actually put through depends on the `PaymentMethod` sub-class' implementation of the `purchase` and `authorize` methods.
+## Payment Setup Sessions
-The returned object from both the `purchase` and `authorize` methods on the payment method objects must be an [ActiveMerchant::Billing::Response](https://github.com/activemerchant/active_merchant/blob/master/lib/active_merchant/billing/response.rb) object. This response object is then stored in YAML in the `spree_log_entries` table. Log entries can be retrieved with a call to the `log_entries` association on any `Payment` object, eg.
+Payment Setup Sessions (`Spree::PaymentSetupSession`) allow customers to save payment methods for future use **without making an immediate payment**. This maps to concepts like Stripe's SetupIntent - a secure way to collect and tokenize payment details for later charges.
-```ruby
-payment.log_entries
+### Use Cases
+
+- Saving a credit card to the customer's account for faster future checkouts
+- Authorizing a payment method for subscription billing
+- Adding a payment method during account onboarding (before any purchase)
+
+### How Payment Setup Sessions Work
+
+```mermaid
+sequenceDiagram
+ participant Frontend
+ participant Spree API
+ participant Payment Provider
+
+ Frontend->>Spree API: Create Payment Setup Session
+ Spree API->>Payment Provider: Create setup session (SetupIntent)
+ Payment Provider-->>Spree API: Session ID + client_secret
+ Spree API-->>Frontend: PaymentSetupSession (pending)
+
+ Frontend->>Payment Provider: Collect card details (using client_secret)
+ Note over Frontend,Payment Provider: 3DS verification if needed
+
+ Frontend->>Spree API: Complete Payment Setup Session
+ Spree API->>Payment Provider: Verify setup result
+ Spree API->>Spree API: Create PaymentSource (saved card)
+ Spree API-->>Frontend: Completed PaymentSetupSession
```
-If the `purchase!` route is taken and is successful, the payment is marked as `completed`. If it fails, it is marked as `failed`. If the `authorize!` method is successful, the payment is transitioned to the `pending` state so that it can be manually captured later by calling the `capture!` method. If it is unsuccessful, it is also transitioned to the `failed` state.
+### Payment Setup Session Attributes
-Once a payment has been saved, it also updates the order. This may trigger the `payment_state` to change, which would reflect the current payment state of the order. The possible states are:
+| Attribute | Description | Example Value |
+|-----------|-------------|---------------|
+| `status` | Current session state: `pending`, `processing`, `completed`, `failed`, `canceled`, `expired` | `completed` |
+| `external_id` | The provider-side session ID (e.g., Stripe SetupIntent ID) | `seti_ABC123` |
+| `external_client_secret` | Client secret for the frontend SDK | `seti_ABC123_secret_xyz` |
+| `external_data` | Provider-specific data | `{}` |
+| `payment_source_id` | The saved payment source created after completion | `ps_xyz789` |
+| `payment_source_type` | The type of saved payment source | `Spree::CreditCard` |
-| Payment State | Description |
-|---------------|-------------|
-| `balance_due` | Payment is required for this order |
-| `failed` | The last payment for the order failed |
-| `credit_owed` | This order has been paid for in excess of its total |
-| `paid` | This order has been paid for in full |
+### Payment Setup Session API
-<Warning>
-You may want to keep tabs on the number of orders with a `payment_state` of `failed`. A sudden increase in the number of such orders could indicate a problem with your credit card gateway and most likely indicates a serious problem affecting customer satisfaction. You should check the latest `log_entries` for the most recent payments in the store if this is happening.
-</Warning>
+<Note>
+Payment Setup Sessions require customer authentication. The customer must be logged in.
+</Note>
-### Log Entries
+**Create a Payment Setup Session:**
-Responses from payment gateways within Spree are typically [ActiveMerchant::Billing::Response](https://github.com/activemerchant/active_merchant/blob/master/lib/active_merchant/billing/response.rb) objects. When Spree handles a response from a payment gateway, it will serialize the object as YAML and store it in the database as a log entry for a payment. These responses can be useful for debugging why a payment has failed.
+```typescript
+const options = { token: jwtToken }
-You can get a list of these log entries by calling the `log_entries` on any `Spree::Payment` object. To get the `ActiveMerchant::Billing::Response` out of these `Spree::LogEntry` objects, call the `details` method:
+// Create a setup session for saving a payment method
+const setupSession = await client.store.customer.paymentSetupSessions.create({
+ payment_method_id: 'pm_xyz789',
+ external_data: {},
+}, options)
-```ruby
-payment.log_entries.first.details
+// Use the client secret with the gateway's frontend SDK
+console.log(setupSession.external_client_secret) // e.g. 'seti_ABC123_secret_xyz'
```
-## Supported Gateways
+**Response shape (`StorePaymentSetupSession`):**
+
+```json
+{
+ "id": "pss_abc123",
+ "status": "pending",
+ "external_id": "seti_ABC123",
+ "external_client_secret": "seti_ABC123_secret_xyz",
+ "external_data": {},
+ "payment_method_id": "pm_xyz789",
+ "payment_source_id": null,
+ "payment_source_type": null,
+ "customer_id": "usr_def456"
+}
+```
-### Spree Team maintained gateways
+**Get a Payment Setup Session:**
+
+```typescript
+const session = await client.store.customer.paymentSetupSessions.get('pss_abc123', options)
+```
+
+**Complete a Payment Setup Session** (after the customer completes setup on the frontend using the gateway SDK and `external_client_secret`):
+
+```typescript
+const completed = await client.store.customer.paymentSetupSessions.complete(
+ 'pss_abc123',
+ { external_data: {} },
+ options
+)
+console.log(completed.status) // 'completed'
+console.log(completed.payment_source_id) // e.g. 'ps_xyz789' - the saved payment method
+```
+
+Spree will verify the result with the provider and create a saved payment source (e.g., `Spree::CreditCard`) that can be used for future payments.
+
+## Supported Gateways
-Spree team maintains several payment gateways integrations. All of these gateways are **fully PCI compliant**, using native gateway SDKs/UIs, meaning no sensitive data is stored or processed through Spree.
+Spree team maintains several payment gateway integrations. All of these gateways are **fully PCI compliant**, using native gateway SDKs, meaning no sensitive payment data is stored or processed through Spree.
<Card title="Stripe" href="/integrations/payments/stripe" icon="link">
Stripe integration, supports all Stripe payment methods, including credit cards, bank transfers, Apple Pay, Google Pay, Klarna, Afterpay, and more. Also supports quick checkout.
@@ -258,95 +508,37 @@ Spree team maintains several payment gateways integrations. All of these gateway
Native PayPal integration, supports PayPal, PayPal Credit, and PayPal Pay Later.
</Card>
-### Community maintained gateways
-
-There are also community-maintained extensions for other payment gateways combined in the [Spree Gateway](https://github.com/spree/spree_gateway) gem. This gem currently supports the following gateways:
-
-* Authorize.net
-* BanWire
-* Bambora previously Beanstream
-* Braintree
-* CyberSource
-* ePay
-* eWay
-* maxipago
-* MasterCard Payment Gateway Service formerly MiGS
-* Moneris
-* PayJunction
-* Payflow
-* Paymill
-* Pin Payments
-* QuickPay
-* sage Pay
-* SecurePay
-* Spreedly
-* USAePay
-* Worldpay previously Cardsave
-
-With the `spree_gateway` gem included in your application's `Gemfile`, these gateways will be selectable in the admin backend for payment methods.
+## Payment Events
-<Info>
- These are just some of the gateways which are supported by the Active Merchant gem. You can see a [list of all the Active Merchant gateways on that project's GitHub page](https://github.com/activemerchant/active_merchant\#supported-payment-gateways).
-</Info>
-
-## Adding your custom Payment Method
-
-In order to make your own custom Payment Method show up on the backend list of available payment methods, you need to add it to the spree config list of payment methods first.
-
-First, create a new model inheriting from `Spree::PaymentMethod` in your `app/models` directory:
-
-```ruby
-class FancyPaymentMethod < Spree::PaymentMethod
-end
-```
-
-Next, add your custom gateway to the list of available payment methods in `config/initializers/spree.rb`:
+Spree publishes events throughout the payment lifecycle that you can subscribe to:
-<Tabs>
- <Tab title="Spree 5.2+">
- ```ruby config/initializers/spree.rb
- Rails.application.config.after_initialize do
- Spree.payment_methods << FancyPaymentMethod
- end
- ```
- </Tab>
- <Tab title="Spree 5.1 and below">
- ```ruby config/initializers/spree.rb
- Rails.application.config.after_initialize do
- Rails.application.config.spree.payment_methods << FancyPaymentMethod
- end
- ```
- </Tab>
-</Tabs>
-
-## Payment Method visibility
-
-We've mentioned before that a `PaymentMethod` can have a `display_on` attribute. This attribute can have the following values: `front`, `back`, or `both`. For more granular control which Payment Methods should be available in which Store, you can override the `available_for_store?` method in your `PaymentMethod` subclass.
+### Payment Events
+| Event | Description |
+|-------|-------------|
+| `payment.paid` | Payment was completed |
+| `order.paid` | Order is fully paid |
-```ruby
-class FancyPaymentMethod < Spree::PaymentMethod
- def available_for_store?(store)
- store.supported_currencies.include?('EUR')
- end
-end
-```
-
-Above code will make the payment method available only for stores that support the EUR currency.
+### Payment Session Events
+| Event | Description |
+|-------|-------------|
+| `payment_session.processing` | Session is being processed |
+| `payment_session.completed` | Session completed successfully |
+| `payment_session.failed` | Session processing failed |
+| `payment_session.canceled` | Session was canceled |
+| `payment_session.expired` | Session expired |
-If you want more control you can specify `available_for_order?` method to control Payment Method visibility for specific Order, eg.
-
-```ruby
-class FancyPaymentMethod < Spree::PaymentMethod
- def available_for_order?(order)
- order.total > 100 && order.currency == 'USD'
- end
-end
-```
+### Payment Setup Session Events
+| Event | Description |
+|-------|-------------|
+| `payment_setup_session.completed` | Setup completed, payment source saved |
+| `payment_setup_session.failed` | Setup failed |
+| `payment_setup_session.canceled` | Setup was canceled |
-This code will make the payment method available only for orders with a total greater than 100 and currency USD.
+See [Events](/developer/core-concepts/events) for more details on subscribing to events.
## Related Documentation
+- [Build a Custom Payment Method](/developer/how-to/custom-payment-method) - Step-by-step guide to creating your own payment gateway integration
- [Orders](/developer/core-concepts/orders) - Order management and state machine
- [Checkout Customization](/developer/customization/checkout) - Customizing the checkout flow
-- [Events](/developer/core-concepts/events) - Subscribe to payment events
\ No newline at end of file
+- [Events](/developer/core-concepts/events) - Subscribe to payment events
diff --git a/docs/developer/core-concepts/pricing.mdx b/docs/developer/core-concepts/pricing.mdx
index f0ccdde4d0..e0bb439a1e 100644
--- a/docs/developer/core-concepts/pricing.mdx
+++ b/docs/developer/core-concepts/pricing.mdx
@@ -9,515 +9,159 @@ Spree's pricing system supports both simple single-currency pricing and advanced
## Prices
-`Price` objects track a price for a particular currency and variant combination. For instance, a [Variant](/developer/core-concepts/products#variants) may be available for $15 (`15 USD`) and €7 (`7 Euro`).
+Each variant has one or more `Price` records — one per currency. The API automatically returns the correct price based on the current currency and [Market](/developer/core-concepts/markets) context.
-`Price` object contains 3 important attributes:
-
-| Attribute | Description | Example Value |
-|-------------------|-----------------------------------------------------------------------------------------------|-----------------------|
-| `amount` | The current selling price of the variant in the specified currency. | `99.90` |
-| `compare_at_amount` | The recommended retail price of the variant in the specified currency. This can be used to display crossed out prices in the storefront. | `129.90` |
-| `currency` | The ISO code for the currency in which the `amount` and `compare_at_amount` are denominated. | `USD` |
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `amount` | Current selling price | `99.90` |
+| `compare_at_amount` | Original/compare price for strikethrough display | `129.90` |
+| `currency` | ISO 4217 currency code | `USD` |
<Warning>
-If a product doesn't have a price in the selected currency it won't show up in the Storefront and Storefront API by default.
+If a product doesn't have a price in the selected currency, it won't appear in Store API responses by default.
</Warning>
-To fetch a list of currencies that given product is available in, call `prices` to get a list of related `Price` objects:
+### Fetching Prices via API
-```ruby
-product.prices
-=> [#<Spree::Price id: 2 ...]
-```
+The Store API returns the resolved price (including Price List rules) for the current currency and market context:
-To find a list of currencies that Variant is available in, call `prices` to get a list of related `Price` objects:
+<CodeGroup>
-```ruby
-product.default_variant.prices
-=> [#<Spree::Price id: 2 ...]
-```
+```typescript SDK
+// Product price is included by default
+const product = await client.store.products.get('spree-tote')
+console.log(product.price) // "15.99" — resolved for current currency
+console.log(product.original_price) // "19.99" — compare-at price (if set)
-To find Product price in a selected currency via [ISO symbol](https://www.iban.com/currency-codes):
-
-```ruby
-product.price_in('EUR')
-=> #<Spree::Price id: 232, variant_id: 232, amount: 0.8499e2, currency: "EUR", deleted_at: nil, created_at: "2021-08-16 19:41:55.888522000 +0000", updated_at: "2021-08-16 19:41:55.888522000 +0000", compare_at_amount: nil, preferences: nil>
+// Each variant has its own price
+const detailed = await client.store.products.get('spree-tote', {
+ expand: ['variants'],
+})
+detailed.variants?.forEach(variant => {
+ console.log(variant.price) // "15.99"
+ console.log(variant.original_price) // "19.99"
+})
```
-<Note>
-If there's no price set for requested currency this will return a new Price object with the currency set to the requested currency. It will not be a persisted object.
-</Note>
-
-To find Variant's price in a selected currency:
+```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'
-```ruby
-product.default_variant.price_in('EUR')
-=> #<Spree::Price id: 232, variant_id: 232, amount: 0.8499e2, currency: "EUR", deleted_at: nil, created_at: "2021-08-16 19:41:55.888522000 +0000", updated_at: "2021-08-16 19:41:55.888522000 +0000", compare_at_amount: nil, preferences: nil>
+# With variants
+curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=variants' \
+ -H 'Authorization: Bearer spree_pk_xxx'
```
-There are also other helpful methods available such as:
-
-<AccordionGroup>
- <Accordion title="Getting amount (number)">
-
- ```ruby
- product.default_variant.amount_in('EUR')
- => 0.8499e2
- ```
-
- </Accordion>
- <Accordion title="Getting amount (string)">
-
- ```ruby
- product.default_variant.amount_in('EUR').to_s
- => "84.99"
- ```
-
- </Accordion>
- <Accordion title="Displaying price with currency symbol">
-
- ```ruby
- product.price_in('EUR').display_amount.to_s
- => "€84.99"
- ```
-
- </Accordion>
-</AccordionGroup>
-
-<Info>
-Spree behind the scenes uses [Ruby Money gem](https://github.com/RubyMoney/money) with some [additional](https://github.com/spree/spree/blob/main/core/app/models/concerns/spree/display_money.rb) [tweaks](https://github.com/spree/spree/blob/main/core/lib/spree/money.rb).
-</Info>
+</CodeGroup>
## Price Lists
-<Info>
-Price Lists are available as of Spree 5.2.
-</Info>
-
-Price Lists allow you to create different pricing strategies for your products based on various conditions such as [markets](/developer/core-concepts/markets), customer zones, specific users, or order quantities. This enables advanced pricing scenarios like:
+Price Lists allow you to create different pricing strategies based on various conditions. This enables advanced pricing scenarios like:
-- **Market-based pricing** - Different prices for different [Markets](/developer/core-concepts/markets) (e.g., North America vs Europe)
-- **Regional pricing** - Different prices for different geographic zones
-- **Wholesale/B2B pricing** - Special prices for business customers
-- **Volume discounts** - Tiered pricing based on quantity purchased
-- **Promotional pricing** - Time-limited special offers
-- **VIP customer pricing** - Exclusive prices for specific users
+- **Market-based pricing** — different prices for different [Markets](/developer/core-concepts/markets) (e.g., North America vs Europe)
+- **Regional pricing** — different prices for different geographic zones
+- **Wholesale/B2B pricing** — special prices for business customers
+- **Volume discounts** — tiered pricing based on quantity purchased
+- **Promotional pricing** — time-limited special offers
+- **VIP customer pricing** — exclusive prices for specific customers
### How Price Lists Work
-Each Price List contains a collection of prices for specific variants and currencies. When a customer views a product or adds it to their cart, Spree's pricing resolver determines which price to use based on:
+When a customer views a product, Spree's pricing resolver determines which price to use:
-1. **Price List priority** - Price Lists are ordered by position; higher priority lists are checked first
-2. **Status** - Only `active` or `scheduled` Price Lists are considered
-3. **Date range** - The current time must fall within `starts_at` and `ends_at` (if set)
-4. **Price Rules** - All configured rules must match (or any, depending on `match_policy`)
+1. **Price List priority** — Price Lists are ordered by position; higher priority lists are checked first
+2. **Status** — only `active` or `scheduled` Price Lists are considered
+3. **Date range** — the current time must fall within `starts_at` and `ends_at` (if set)
+4. **Price Rules** — all configured rules must match (or any, depending on `match_policy`)
-If no applicable Price List is found, the base price (price without a Price List) is used.
+If no applicable Price List is found, the base price is used.
### Price List Attributes
-| Attribute | Description |
-|-----------------|-------------------------------------------------------------------------------------------------|
-| `name` | Human-readable name for the Price List |
-| `status` | Current status: `draft`, `active`, `scheduled`, or `inactive` |
-| `starts_at` | Optional start date/time when the Price List becomes applicable |
-| `ends_at` | Optional end date/time when the Price List stops being applicable |
-| `match_policy` | How rules are evaluated: `all` (every rule must match) or `any` (at least one rule must match) |
-| `position` | Priority order for evaluation (lower numbers = higher priority) |
+| Attribute | Description |
+|-----------|-------------|
+| `name` | Human-readable name for the Price List |
+| `status` | `draft`, `active`, `scheduled`, or `inactive` |
+| `starts_at` | Optional start date when the Price List becomes applicable |
+| `ends_at` | Optional end date when the Price List stops being applicable |
+| `match_policy` | How rules are evaluated: `all` (every rule must match) or `any` (at least one) |
+| `position` | Priority order (lower numbers = higher priority) |
## Price Rules
Price Rules define conditions that must be met for a Price List to apply. Spree includes five built-in rule types:
-<AccordionGroup>
- <Accordion title="Market Rule">
-
- Applies the Price List based on the current [Market](/developer/core-concepts/markets). This is the recommended approach for regional pricing when using Markets.
-
- ```ruby
- # Example: Create a Price List for the European market
- price_list = Spree::PriceList.create!(
- name: 'EU Market Pricing',
- store: current_store,
- status: 'active',
- match_policy: 'all'
- )
-
- eu_market = Spree::Market.find_by!(name: 'Europe')
- price_list.price_rules.create!(
- type: 'Spree::PriceRules::MarketRule',
- preferences: { market_ids: [eu_market.id] }
- )
- ```
-
- If `market_ids` is empty, the rule matches any market. If the pricing context has no market, the rule does not match.
-
- </Accordion>
- <Accordion title="Zone Rule">
-
- Applies the Price List based on the customer's tax/shipping zone. Useful for regional or country-specific pricing when not using Markets.
-
- ```ruby
- # Example: Create a Price List for EU customers
- price_list = Spree::PriceList.create!(
- name: 'EU Pricing',
- store: current_store,
- status: 'active',
- match_policy: 'all'
- )
-
- eu_zone = Spree::Zone.find_by!(name: 'EU')
- price_list.price_rules.create!(
- type: 'Spree::PriceRules::ZoneRule',
- preferences: { zone_ids: [eu_zone.id] }
- )
- ```
-
- </Accordion>
- <Accordion title="User Rule">
-
- Applies the Price List to specific users. Useful for VIP customers, wholesale accounts, or B2B pricing.
-
- ```ruby
- # Example: Create a VIP Price List
- price_list = Spree::PriceList.create!(
- name: 'VIP Customers',
- store: current_store,
- status: 'active',
- match_policy: 'all'
- )
-
- # Find users tagged with 'VIP'
- vip_user_ids = Spree.user_class.tagged_with('VIP').pluck(:id)
-
- price_list.price_rules.create!(
- type: 'Spree::PriceRules::UserRule',
- preferences: { user_ids: vip_user_ids }
- )
- ```
-
- </Accordion>
- <Accordion title="Customer Group Rule">
-
- Applies the Price List to members of specific customer groups. Useful for wholesale tiers, loyalty programs, or membership-based pricing.
-
- ```ruby
- # Example: Create a wholesale Price List
- price_list = Spree::PriceList.create!(
- name: 'Wholesale Pricing',
- store: current_store,
- status: 'active',
- match_policy: 'all'
- )
-
- wholesale_group = Spree::CustomerGroup.find_by!(name: 'Wholesale')
- price_list.price_rules.create!(
- type: 'Spree::PriceRules::CustomerGroupRule',
- preferences: { customer_group_ids: [wholesale_group.id] }
- )
- ```
-
- </Accordion>
- <Accordion title="Volume Rule">
-
- Applies the Price List based on quantity purchased. Useful for bulk discounts or tiered pricing.
-
- ```ruby
- # Example: Create volume-based pricing tiers
- # Tier 1: 10-49 units
- tier1 = Spree::PriceList.create!(
- name: 'Bulk Tier 1 (10-49)',
- store: current_store,
- status: 'active',
- position: 2
- )
- tier1.price_rules.create!(
- type: 'Spree::PriceRules::VolumeRule',
- preferences: { min_quantity: 10, max_quantity: 49 }
- )
-
- # Tier 2: 50+ units (higher priority)
- tier2 = Spree::PriceList.create!(
- name: 'Bulk Tier 2 (50+)',
- store: current_store,
- status: 'active',
- position: 1
- )
- tier2.price_rules.create!(
- type: 'Spree::PriceRules::VolumeRule',
- preferences: { min_quantity: 50, max_quantity: nil }
- )
- ```
-
- </Accordion>
-</AccordionGroup>
-
-### Creating Custom Price Rules
-
-You can create custom Price Rules by subclassing `Spree::PriceRule`:
-
-```ruby
-# app/models/spree/price_rules/membership_rule.rb
-module Spree
- module PriceRules
- class MembershipRule < Spree::PriceRule
- preference :membership_levels, :array, default: []
-
- def applicable?(context)
- return false unless context.user
- return true if preferred_membership_levels.empty?
-
- preferred_membership_levels.include?(context.user.membership_level)
- end
-
- def self.description
- 'Apply pricing based on membership level'
- end
- end
- end
-end
-```
-
-Then register it in your initializer:
-
-```ruby
-# config/initializers/spree.rb
-Rails.application.config.after_initialize do
- Rails.application.config.spree.pricing.rules << Spree::PriceRules::MembershipRule
-end
-```
-
-## Pricing Context
-
-The `Spree::Pricing::Context` object carries all the information needed to resolve the correct price. It encapsulates the current pricing scenario and is used by the `Spree::Pricing::Resolver` to find the best applicable price.
-
-### Context Attributes
-
-| Attribute | Type | Required | Default | Description |
-|------------|---------------------|----------|---------------------|-------------------------------------------------------------------------------------------------|
-| `variant` | `Spree::Variant` | Yes | - | The variant for which to resolve the price |
-| `currency` | `String` | Yes | - | ISO 4217 currency code (e.g., `'USD'`, `'EUR'`) |
-| `store` | `Spree::Store` | No | `Spree::Current.store` | The store context; Price Lists are scoped to stores |
-| `zone` | `Spree::Zone` | No | `Spree::Current.zone` | The tax/shipping zone for zone-based pricing rules. Falls back to `Spree::Zone.default_tax` if not set. |
-| `market` | `Spree::Market` | No | `Spree::Current.market` | The current [Market](/developer/core-concepts/markets) for market-based pricing rules. Falls back to the store's default market. |
-| `user` | User class | No | `nil` | The current user; used by User Rules for customer-specific pricing |
-| `quantity` | `Integer` | No | `nil` | The quantity being purchased; used by Volume Rules for tiered pricing |
-| `date` | `Time` | No | `Time.current` | The date/time for price resolution; used to check Price List date ranges |
-| `order` | `Spree::Order` | No | `nil` | The current order; provides additional context for price resolution |
-
-### Understanding the Market and Zone Attributes
-
-The `market` attribute is the primary way to scope pricing geographically. [Markets](/developer/core-concepts/markets) bundle a set of countries with a currency and locale, making them the natural unit for regional pricing.
-
-**How market is resolved:**
-- `Spree::Current.market` is set per-request, typically based on the customer's country
-- Falls back to the store's default market if not explicitly set
-- The Market Rule on Price Lists uses this attribute to match market-specific prices
-
-```ruby
-# Market is automatically available in the pricing context
-Spree::Current.market # => #<Spree::Market name: "Europe", currency: "EUR">
-
-context = Spree::Pricing::Context.new(variant: variant, currency: 'EUR')
-context.market # => Spree::Current.market
-```
-
-<Note>
-The `zone` attribute is still available for zone-based pricing via the Zone Rule. Zones are primarily used for tax and shipping calculations, while Markets are the recommended approach for regional pricing. Both can be used together — for example, a Market Rule for currency-based pricing and a Zone Rule for state-level tax-inclusive pricing.
-</Note>
-
-### Creating a Context
-
-There are several ways to create a pricing context:
+| Rule | Description | Use Case |
+|------|-------------|----------|
+| **Market Rule** | Matches based on the current [Market](/developer/core-concepts/markets) | Regional pricing across markets |
+| **Zone Rule** | Matches based on the customer's geographic zone | Country or state-level pricing |
+| **User Rule** | Matches specific customer accounts | VIP customers, wholesale accounts |
+| **Customer Group Rule** | Matches members of customer groups | Loyalty tiers, membership pricing |
+| **Volume Rule** | Matches based on quantity purchased | Bulk discounts, tiered pricing |
-<AccordionGroup>
- <Accordion title="From an Order (recommended)">
+### Market Rule
- The most common approach during checkout. Automatically extracts all relevant information from the order:
+The recommended approach for regional pricing when using Markets. Applies the Price List when the customer is in one of the specified markets.
- ```ruby
- context = Spree::Pricing::Context.from_order(variant, order)
+**Example:** Price a product at $29.99 in North America and €24.99 in Europe, rather than relying on exchange rate conversion.
- # This is equivalent to:
- context = Spree::Pricing::Context.new(
- variant: variant,
- currency: order.currency,
- store: order.store,
- zone: order.tax_zone || order.store.checkout_zone,
- user: order.user,
- quantity: order.line_items.find_by(variant: variant)&.quantity,
- order: order
- )
- ```
+### Zone Rule
- </Accordion>
- <Accordion title="From Currency (simple)">
+Applies based on the customer's geographic zone. Useful for regional or country-specific pricing when not using Markets.
- For basic price lookups when you only need currency-based pricing:
+### User Rule
- ```ruby
- context = Spree::Pricing::Context.from_currency(variant, 'USD')
+Limits the Price List to specific customer accounts. Useful for VIP customers, employee pricing, or wholesale accounts.
- # This is equivalent to:
- context = Spree::Pricing::Context.new(
- variant: variant,
- currency: 'USD'
- )
- ```
+### Customer Group Rule
- </Accordion>
- <Accordion title="Manual Construction">
+Applies to members of specific customer groups. Useful for wholesale tiers, loyalty programs, or membership-based pricing.
- For full control over all pricing parameters:
+### Volume Rule
- ```ruby
- context = Spree::Pricing::Context.new(
- variant: variant,
- currency: 'EUR',
- store: Spree::Store.find_by!(code: 'eu-store'),
- zone: Spree::Zone.find_by!(name: 'EU'),
- market: Spree::Market.find_by!(name: 'Europe'),
- user: current_user,
- quantity: 10,
- date: 1.week.from_now # Preview future pricing
- )
- ```
+Applies based on quantity purchased. Supports `min_quantity` and `max_quantity` to create tiered pricing:
- </Accordion>
-</AccordionGroup>
+| Tier | Quantity | Price |
+|------|----------|-------|
+| Base | 1–9 | $10.00 |
+| Bulk Tier 1 | 10–49 | $8.50 |
+| Bulk Tier 2 | 50+ | $7.00 |
-### Resolving the Price
-
-Once you have a context, use the `Spree::Pricing::Resolver` to find the best price:
-
-```ruby
-resolver = Spree::Pricing::Resolver.new(context)
-price = resolver.resolve # Returns a Spree::Price object
-
-# The resolver:
-# 1. Finds all applicable Price Lists (active/scheduled, within date range)
-# 2. Filters by Price Rules (market, zone, user, quantity, etc.)
-# 3. Returns the first matching price (by Price List position)
-# 4. Falls back to the base price if no Price List applies
-```
-
-<Note>
-Price resolution results are cached for 15 minutes using the context's cache key. The cache key includes all context attributes (including market), so different scenarios are cached separately.
-</Note>
-
-## Getting Prices: `price_for` vs `price_in`
-
-Spree provides two methods for fetching variant prices. Understanding when to use each is important for correct pricing behavior.
-
-### `price_for` (Recommended)
-
-The `price_for` method resolves prices using the full Price List system. It considers all applicable Price Lists, rules, and returns the best matching price. **This is the recommended method for most use cases.**
-
-```ruby
-# Using a Pricing Context object
-context = Spree::Pricing::Context.from_order(variant, order)
-price = variant.price_for(context)
-
-# Using an options hash (context is built automatically)
-price = variant.price_for(
- currency: 'USD',
- store: Spree::Current.store,
- zone: order.tax_zone,
- user: current_user,
- quantity: 5
-)
-
-# Display the resolved price
-price.display_amount.to_s # => "$89.99"
-```
-
-**Use `price_for` when:**
-- Displaying prices to customers in the storefront
-- Calculating line item prices during checkout
-- You need market-based, zone-based, user-based, or volume-based pricing
-- You want prices from active Price Lists to apply
-
-### `price_in` (Base Prices Only)
-
-The `price_in` method returns only the **base price** (prices without a Price List) for a given currency. It bypasses the Price List system entirely.
-
-```ruby
-# Get the base price in USD
-base_price = variant.price_in('USD')
-base_price.amount # => 99.99
-```
-
-**Use `price_in` when:**
-- You specifically need the base price, ignoring all Price Lists
-- Managing prices in the admin interface
-- Importing/exporting base pricing data
-- Backward compatibility with pre-5.2 code
-
-<Warning>
-`price_in` is maintained for backward compatibility. For customer-facing pricing, always use `price_for` to ensure Price Lists are applied correctly.
-</Warning>
-
-### Comparison
-
-| Method | Price Lists | Rules Applied | Use Case |
-|------------|-------------|---------------|-----------------------------------|
-| `price_for`| Yes | Yes | Storefront, checkout, customer-facing |
-| `price_in` | No | No | Admin, base price management |
-
-```ruby
-# Example: Same variant, different results
-variant = Spree::Variant.find(1)
+<Info>
+Custom Price Rules can be created for specialized pricing logic. See the [Customization Quickstart](/developer/customization/quickstart) for details.
+</Info>
-# Base price (no Price Lists)
-variant.price_in('USD').amount # => 100.00
+## Pricing Context
-# Resolved price (with VIP Price List applied)
-context = Spree::Pricing::Context.new(
- variant: variant,
- currency: 'USD',
- user: vip_customer
-)
-variant.price_for(context).amount # => 80.00 (20% VIP discount)
-```
+When resolving prices, Spree considers the full context of the request:
-## Managing Price List Products
+| Context | Source | Description |
+|---------|--------|-------------|
+| Currency | Market or request header | The currency to price in |
+| Market | Customer's country | The [Market](/developer/core-concepts/markets) for market-based rules |
+| Zone | Customer's address | The geographic zone for zone-based rules |
+| Customer | JWT authentication | The logged-in customer for user-based rules |
+| Quantity | Cart line item | The quantity for volume-based rules |
+| Date | Current time | For time-based Price List scheduling |
-Products can be added to a Price List, which creates placeholder prices for all variants:
+The Store API automatically builds this context from the request headers (`X-Spree-Currency`, `X-Spree-Country`) and authentication state. You don't need to construct it manually — just make API requests and the correct price is resolved.
-```ruby
-price_list = Spree::PriceList.find(1)
+<Info>
+Price resolution results are cached for 15 minutes. Different context combinations are cached separately.
+</Info>
-# Add products to the Price List
-price_list.add_products([product1.id, product2.id])
+## Time-Based Pricing
-# Update prices for the Price List
-price_list.prices.each do |price|
- price.update(amount: calculate_special_price(price.variant))
-end
+Price Lists support scheduling through `starts_at` and `ends_at` attributes. Scheduled Price Lists automatically become applicable when the current time falls within their date range — no manual activation needed.
-# Remove products from the Price List
-price_list.remove_products([product1.id])
-```
+**Example:** A Black Friday sale Price List with `starts_at: 2025-11-28 00:00` and `ends_at: 2025-11-28 23:59` will automatically activate and deactivate.
-## Time-Based Pricing
+## Managing Price Lists
-Price Lists support scheduling through `starts_at` and `ends_at` attributes:
-
-```ruby
-# Create a Black Friday sale
-black_friday = Spree::PriceList.create!(
- name: 'Black Friday 2025',
- store: current_store,
- status: 'scheduled',
- starts_at: Time.zone.parse('2025-11-28 00:00'),
- ends_at: Time.zone.parse('2025-11-28 23:59'),
- position: 1 # Highest priority
-)
-```
+Price Lists are managed in the Admin Panel under **Products → Price Lists**, or via the Admin API.
-<Note>
-Scheduled Price Lists automatically become applicable when the current time falls within their date range. They don't need to be manually activated.
-</Note>
+Each Price List contains prices for specific variants and currencies. Products can be added to a Price List, and individual variant prices set within it.
## Related Documentation
diff --git a/docs/developer/core-concepts/products.mdx b/docs/developer/core-concepts/products.mdx
index 51e0d4365c..e4d96b0153 100644
--- a/docs/developer/core-concepts/products.mdx
+++ b/docs/developer/core-concepts/products.mdx
@@ -1,40 +1,43 @@
---
title: Products
+description: Products, variants, option types, images, prices, and categories
---
## Overview
-`Product` records track unique products within your store. These differ from [Variants](#variants), which track the unique variations of a product. For instance, a product that's a T-shirt would have variants denoting its different colors and sizes. Together, Products and Variants describe what is for sale.
+A product represents something you sell. Each product has one or more **variants** — the actual purchasable items with their own SKU, price, and inventory. For example, a "T-Shirt" product might have variants for each size and color combination.
+
+Products are organized into categories using **taxonomies** and **taxons**, and can be filtered, sorted, and searched via the Store API.
<Info>
-Note that as of version 4.6, certain product fields are translatable (read more about this in [Internationalization](/developer/core-concepts/i18n#resource-translations)).
+Product names, descriptions, slugs, and SEO fields are [translatable](/developer/core-concepts/translations#resource-translations).
</Info>
-### Product Model Diagram
-
```mermaid
erDiagram
+ Product ||--o{ Variant : "has many"
+ Product }o--o{ OptionType : "has many"
+ Product ||--o{ Classification : "has many"
+ Variant ||--o{ Price : "has many"
+ Variant ||--o{ StockItem : "has many"
+ Variant ||--o{ Image : "has many"
+ Variant }o--o{ OptionValue : "has many"
+ OptionType ||--o{ OptionValue : "has many"
+ Taxon ||--o{ Classification : "has many"
+ Taxonomy ||--o{ Taxon : "has many"
+
Product {
string name
string slug
string status
text description
datetime available_on
- datetime discontinue_on
- string meta_title
- string meta_description
}
Variant {
string sku
- string barcode
- decimal weight
- decimal height
- decimal width
- decimal depth
boolean is_master
- boolean track_inventory
- decimal cost_price
+ decimal weight
}
Price {
@@ -46,251 +49,341 @@ erDiagram
OptionType {
string name
string presentation
- integer position
}
OptionValue {
string name
string presentation
- integer position
}
+```
- Taxon {
- string name
- string permalink
- text description
- integer position
- }
+## Product Attributes
+
+| Attribute | Description | Translatable |
+|-----------|-------------|:---:|
+| `name` | Product name | Yes |
+| `description` | Full product description | Yes |
+| `slug` | URL-friendly identifier (e.g., `spree-tote`) | Yes |
+| `status` | `draft`, `active`, or `archived` | No |
+| `available_on` | Date the product becomes available for sale | No |
+| `discontinue_on` | Date the product is no longer available | No |
+| `meta_title` | Custom SEO title | Yes |
+| `meta_description` | SEO description | Yes |
+| `meta_keywords` | SEO keywords | Yes |
+| `purchasable` | Whether the product can be added to cart | No |
+| `in_stock` | Whether any variant has stock available | No |
+| `price` | Default variant's price in the current currency | No |
+| `thumbnail_url` | URL to the product's first image — always returned, no expand needed | No |
+| `tags` | Array of tag strings for filtering | No |
+
+## Listing Products
+
+<CodeGroup>
+
+```typescript SDK
+// List products with pagination
+const { data: products, meta } = await client.store.products.list({
+ limit: 12,
+ page: 1,
+})
+
+// Filter by price range and availability
+const filtered = await client.store.products.list({
+ price_gte: 10,
+ price_lte: 50,
+ in_stock: true,
+})
+
+// Search by keyword
+const results = await client.store.products.list({
+ multi_search: 'tote bag',
+})
+
+// Sort products
+const sorted = await client.store.products.list({
+ sort: 'price_high_to_low', // or: price_low_to_high, newest, name_a_z, name_z_a
+})
+```
- Taxonomy {
- string name
- integer position
- }
+```bash cURL
+# List products
+curl 'https://api.mystore.com/api/v3/store/products?limit=12&page=1' \
+ -H 'Authorization: Bearer spree_pk_xxx'
- Product ||--o{ Variant : "has many"
- Product }o--o{ OptionType : "has many"
- Product ||--o{ Classification : "has many"
- Product ||--o{ ProductProperty : "has many"
- Product }o--|| ShippingCategory : "belongs to"
- Product }o--|| TaxCategory : "belongs to"
- Variant ||--o{ Price : "has many"
- Variant ||--o{ StockItem : "has many"
- Variant ||--o{ Image : "has many"
- Variant }o--o{ OptionValue : "has many"
- OptionType ||--o{ OptionValue : "has many"
- Taxon ||--o{ Classification : "has many"
- Taxonomy ||--o{ Taxon : "has many"
- Property ||--o{ ProductProperty : "has many"
+# 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'
+
+# Search
+curl 'https://api.mystore.com/api/v3/store/products?q[multi_search]=tote+bag' \
+ -H 'Authorization: Bearer spree_pk_xxx'
```
-**Key relationships:**
-- **Product** has one master Variant and many regular Variants
-- **Variants** represent purchasable items with SKU, price, and [inventory](/developer/core-concepts/inventory)
-- **Option Types** (e.g., Size, Color) define variant options
-- **Option Values** (e.g., Small, Red) are assigned to variants
-- **Taxons** (via Classifications) organize products into categories
-- **Properties** store additional product attributes (e.g., Material, Brand)
-- **[Shipping Category](/developer/core-concepts/shipments)** and **[Tax Category](/developer/core-concepts/taxes)** determine shipping and tax rules
-
-Products have the following attributes:
-
-| Attribute | Description | Translatable |
-|-------------------|-------------------------------------------------------------------------------------------------------|--------------|
-| `name` | Short name for the product | Yes |
-| `description` | The most elegant, poetic turn of phrase for describing your product's benefits and features | Yes |
-| `slug` | SEO slug based on the product name that is placed into the URL for the product. We use a library called [friendly_id](https://github.com/norman/friendly_id) to generate them | Yes |
-| `status` | The status of the product. Can be `draft`, `active`, `archived`. Defaults to `draft`. | No |
-| `available_on` | The first date the product becomes available for sale online in your shop | No |
-| `discontinue_on` | Date when the product will become unavailable for sale online in your shop | No |
-| `deleted_at` | The date the product is marked as deleted. We don't remove products entirely, only soft deleting them using a library called `paranoia` | No |
-| `meta_title` | Optional title used for search engines instead of `name` | Yes |
-| `meta_description`| A description targeted at search engines for search engine optimization (SEO) | Yes |
-| `meta_keywords` | Several words and short phrases separated by commas, also targeted at search engines | Yes |
-
-To understand how variants come to be, you must first understand option types and option values.
+</CodeGroup>
-## Option Types and Option Values
+See [Querying](/api-reference/store-api/querying) for the full list of filtering, sorting, and pagination options.
-Option types denote the different options for a variant.
+## Getting a Product
-A typical option type would be a `size`, with that option type's values being something such as `Small`, `Medium` and `Large`.
+<CodeGroup>
-Another typical option type could be a `color`, such as `Red`, `Green`, or `Blue`.
+```typescript SDK
+// Get by slug
+const product = await client.store.products.get('spree-tote')
-A product can be assigned many option types, but must be assigned at least one if you wish to create variants for that product
+// Get with included relations
+const detailed = await client.store.products.get('spree-tote', {
+ expand: ['variants', 'images', 'option_types', 'taxons'],
+})
+// detailed.variants => [{ id: "var_xxx", sku: "TOTE-S-R", price: { amount: "15.99", currency: "USD" }, ... }]
+// detailed.images => [{ id: "img_xxx", url: "https://cdn...", position: 1 }]
+// detailed.option_types => [{ name: "size", presentation: "Size", option_values: [...] }]
+```
-<Info>
-The `name` and `presentation` fields for option types are translatable as of version 4.6.
-</Info>
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=variants,images,option_types,taxons' \
+ -H 'Authorization: Bearer spree_pk_xxx'
+```
-## Variants
+</CodeGroup>
-`Variant` records track the individual variants of a `Product`. Variants are of two types: master variants and normal variants.
+## Product Filters
-Variant records can track some individual properties regarding a variant, such as height, width, depth, and cost price. These properties are unique to each variant, and so are different from [Product Properties](#product-properties), which apply to all variants of that product.
+Get available filter options for building a faceted search UI. Returns price ranges, option values, and taxons with counts:
-| Attribute | Description | Example Value |
-|--------------------|-----------------------------------------------------------------------------------------------|------------------------|
-| `sku` | Unique identifier for each variant | `123TSHRT-M-G` |
-| `barcode` | Barcode code | `` |
-| `barcode` | A unique code that represents a variant, often used for scanning purposes. | `123456789` |
-| `weight` | The weight of the variant | 2 |
-| `height` | The height of the variant | 150 |
-| `width` | The width of the variant | 150 |
-| `depth` | The depth of the variant | 100 |
-| `is_master` | Indicates if the variant is a master variant | `false` |
-| `track_inventory` | Indicates if the inventory is tracked for this variant | `true` |
-| `cost_price` | The cost price of the variant | 5.00 |
-| `cost_currency` | The currency of the cost price | `USD` |
-| `discontinue_on` | Date when the variant will become unavailable for sale | 2023-12-31 18:00 |
+<CodeGroup>
-### Master Variants
+```typescript SDK
+const filters = await client.store.products.filters()
+// {
+// option_types: [{ name: "size", option_values: [{ name: "Small", count: 12 }, ...] }],
+// price_range: { min: 9.99, max: 199.99 },
+// taxons: [{ id: "txn_xxx", name: "Clothing", count: 45 }],
+// }
-Every single product has a master variant, which tracks basic information such as a count on hand, a price and a <Tooltip tip="Stock Keeping Unit - In inventory management, a stock keeping unit (abbreviated as SKU) is the unit of measure in which the stocks of a material are managed.">SKU</Tooltip>.
+// Scoped to a specific taxon
+const taxonFilters = await client.store.products.filters({
+ taxon_id_eq: 'txn_xxx',
+})
+```
-Whenever a product is created, a master variant for that product will be created too.
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products/filters' \
+ -H 'Authorization: Bearer spree_pk_xxx'
-<Info>
-Logic behind is implemented in the `after_initialize` callback of the `Spree::Product` model in a [ensure_master](https://github.com/spree/spree/blob/d3927a3f646f0b4e72b137bf72606c885ec59829/core/app/models/spree/product.rb#L132) method.
-</Info>
+# Scoped to a taxon
+curl 'https://api.mystore.com/api/v3/store/products/filters?taxon_id_eq=txn_xxx' \
+ -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+</CodeGroup>
+
+## Variants
-Master variants are automatically created along with a product and exist for the sole purpose of having a consistent API when associating variants and [line items](orders#line-items). If there were no master variant, then line items would need to track a polymorphic association which would either be a product or a variant.
+Variants are the purchasable units of a product. Each variant has its own SKU, price, inventory, and images, and is defined by a unique combination of option values.
+
+| Attribute | Description |
+|-----------|-------------|
+| `sku` | Unique stock keeping unit |
+| `barcode` | Barcode (UPC, EAN, etc.) |
+| `price` | Price in the current currency |
+| `original_price` | Compare-at price for showing discounts |
+| `weight`, `height`, `width`, `depth` | Dimensions for shipping calculations |
+| `in_stock` | Whether stock is available |
+| `backorderable` | Whether the variant can be ordered when out of stock |
+| `option_values` | The option values that define this variant (e.g., Size: Small, Color: Red) |
+
+### Master Variant
+
+Every product has a **master variant** that holds default pricing and inventory. If a product has no option types (e.g., a book with no size/color), the master variant is the only purchasable variant.
### Regular Variants
-Variants which are not the master variant are unique based on a [option type and option value](#option-types-and-option-values) combinations.
+When a product has option types, each unique combination of option values creates a variant. For example, a T-shirt with sizes (S, M, L) and colors (Red, Green) has 6 variants:
-For instance, you may be selling a product which is a Baseball Jersey, which comes in the sizes "Small", "Medium" and "Large", as well as in the colors of "Red", "Green". For this combination of sizes and colors, you would be able to create 9 unique variants:
+| SKU | Size | Color |
+|-----|------|-------|
+| `TEE-S-R` | Small | Red |
+| `TEE-S-G` | Small | Green |
+| `TEE-M-R` | Medium | Red |
+| `TEE-M-G` | Medium | Green |
+| `TEE-L-R` | Large | Red |
+| `TEE-L-G` | Large | Green |
-| SKU | Size | Color |
-|-----------|-------|-------|
-| SKU-S-R | Small | Red |
-| SKU-S-G | Small | Green |
-| SKU-M-R | Medium| Red |
-| SKU-M-G | Medium| Green |
-| SKU-L-R | Large | Red |
-| SKU-L-G | Large | Green |
+The product's `default_variant_id` points to the first non-master variant (or the master variant if none exist).
+
+## Option Types and Option Values
-### Default Variant
+Option types define the axes of variation for a product (e.g., Size, Color, Material). Option values are the specific choices within each type (e.g., Small, Medium, Large).
-This all can sound complex and confusing, so we'll simplify things for you.
+A product must have at least one option type to have multiple variants. Option types and their values are included in the product response when requested:
-To get the default Variant for a product, you can call:
+<CodeGroup>
-```ruby
-product.default_variant
+```typescript SDK
+const product = await client.store.products.get('spree-tee', {
+ expand: ['option_types'],
+})
+
+product.option_types?.forEach(optionType => {
+ console.log(optionType.presentation) // "Size"
+ optionType.option_values.forEach(value => {
+ console.log(value.presentation) // "Small", "Medium", "Large"
+ })
+})
```
-How this works?
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products/spree-tee?expand=option_types' \
+ -H 'Authorization: Bearer spree_pk_xxx'
+```
-* If a product has multiple Variants it will return the first non-master Variant based on their sort position set in the Admin Panel or Platform API.
-* If there are no non-master Variants it will return the Master Variant
+</CodeGroup>
-So you can easily rely on this method to get the default Variant for a product.
+<Info>
+Option type `name` and `presentation` fields are translatable.
+</Info>
## Images
-Images can be associated to the Product (via master variant) or to the individual Variants.
+Images can be attached to the product (via the master variant) or to individual variants. When displaying a product, show the images for the selected variant, falling back to the product-level images.
-Product images can be fetched via:
+### Thumbnails
-```ruby
-product.images
-```
+Every product response includes a `thumbnail_url` field — the URL to the first image, ready to use without any expands. Similarly, each variant includes a `thumbnail` URL and an `image_count` counter.
-To get all images for product and all it's variants, call `variant_images` on the product:
+Use these fields for product listing pages to avoid loading all images:
-```ruby
-product.variant_images
-```
+<CodeGroup>
-To fetch individual variant images, call `images` on the variant:
+```typescript SDK
+// List products — thumbnail_url is always included
+const { data: products } = await client.store.products.list({ limit: 12 })
-```ruby
-product.default_variant.images
+products.forEach(product => {
+ product.thumbnail_url // "https://cdn.../tote-front.jpg" — no expand needed
+})
```
-Image order is determined by the `position` attribute, which is an integer. By default, images are ordered from left to right.
-
-<Info>
-Under the hood we use [Rails Active Storage](https://guides.rubyonrails.org/active_storage_overview.html) to handle image storage and manipulation. See the [Images & Assets](/developer/core-concepts/images-assets) guide for more details on image processing, helpers, and best practices.
-</Info>
+```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'
+```
-## Product Properties
+</CodeGroup>
<Warning>
-**Product Properties are deprecated as of Spree 5.2.** This feature was the default way to add custom attributes to products prior to Spree 5.2, but has been replaced by [Metafields](/developer/core-concepts/metafields).
+Avoid using `?expand=images` on listing pages. This loads **all** images for every product in the response, which is unnecessary when you only need a thumbnail. Use `thumbnail_url` instead and only expand full images on the product detail page.
+</Warning>
-For **new projects**, use [Metafields](/developer/core-concepts/metafields) instead. Product Properties will be removed in Spree 6.0.
+### All Images
-For **existing projects**, Properties are still supported for backward compatibility but require enabling via `config.product_properties_enabled = true`. See the [upgrade guide](/developer/upgrades/5.1-to-5.2#3-migrate-to-metafields-or-keep-using-properties) for migration instructions.
-</Warning>
+On the product detail page, expand `images` and `variants` to get the full set of images. Images are ordered by `position`:
-Product properties track individual attributes for a product that don't apply to all products. These are typically additional information about the item. For instance, a T-Shirt may have properties representing information about the kind of material used, as well as the type of fit the shirt is.
+<CodeGroup>
-A `Property` should not be confused with an [`OptionType`](#option-types-and-option-values), which is used when defining [Variants](#variants) for a product.
+```typescript SDK
+const product = await client.store.products.get('spree-tote', {
+ expand: ['images', 'variants'],
+})
-You can retrieve the value for a property on a `Product` object by calling the `property` method on it and passing through that property's name:
+// Product-level images (from master variant)
+product.images // [{ url: "https://cdn.../tote-front.jpg", position: 1 }, ...]
-```ruby
-product.property("material")
-=> "100% Cotton"
+// Each variant has its own thumbnail and image_count
+product.variants?.forEach(variant => {
+ variant.thumbnail // "https://cdn.../tote-red.jpg" — always available
+ variant.image_count // 3 — quick check without loading images
+ variant.images // full image array (only when ?expand=images)
+})
```
-You can set a property on a product by calling the `set_property` method:
-
-```ruby
-product.set_property("material", "100% cotton")
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=images,variants' \
+ -H 'Authorization: Bearer spree_pk_xxx'
```
-If this property doesn't already exist, a new `Property` instance with this name will be created on the fly.
+</CodeGroup>
-<Info>
-As of version 4.6, product property `value` fields are translatable.
-</Info>
+| Field | Available on | Always returned | Description |
+|-------|-------------|:---:|-------------|
+| `thumbnail_url` | Product | Yes | URL to the product's first image |
+| `thumbnail` | Variant | Yes | URL to the variant's first image |
+| `image_count` | Variant | Yes | Number of images (counter cache — no DB query) |
+| `images` | Product, Variant | No | Full image array (requires `?expand=images`) |
## Prices
-`Price` objects track a price for a particular currency and variant combination. For instance, a [Variant](#variants) may be available for $15 (`15 USD`) and €7 (`7 Euro`).
+Each variant can have multiple prices — one per currency, plus additional prices from [Price Lists](/developer/core-concepts/pricing) that apply conditionally based on market, geography, customer segment, or quantity.
-Each variant can have multiple prices — a base price per currency, plus additional prices from Price Lists that apply conditionally based on rules like [market](/developer/core-concepts/markets), geography, customer segment, or quantity.
+The API automatically returns the correct price based on the current currency and market context:
-For full details on Prices, Price Lists, Price Rules, and the Pricing Context, see the dedicated [Pricing](/developer/core-concepts/pricing) guide.
+| Field | Description |
+|-------|-------------|
+| `price` | Current selling price |
+| `original_price` | Compare-at price (for showing strikethrough discounts) |
-## Prototypes
+See the [Pricing](/developer/core-concepts/pricing) guide for details on Price Lists, Price Rules, and market-specific pricing.
-A prototype is a useful way to share common `OptionType` and `Property` combinations amongst many different products. They work as a product template to speed up the creation of new products.
+## Taxons and Taxonomies
-For instance, if you're creating a lot of clothing products, you may wish to maintain the "Size" and "Color" option types, as well as a "Fitting Type" property.
+Taxonomies provide a flexible way to categorize products. A **taxonomy** is a hierarchical category tree, and a **taxon** is a node within that tree.
-## Taxons and Taxonomies
+For example:
+- **Categories** (taxonomy) → Clothing → T-Shirts, Dresses
+- **Brands** (taxonomy) → Nike, Adidas, Puma
+- **Collections** (taxonomy) → Summer 2025, Best Sellers
-Taxonomies provide a simple, yet robust way of categorizing products by enabling store administrators to define as many separate structures as needed.
+Products can belong to multiple taxons across different taxonomies.
-When working with Taxonomies there are two key terms to understand:
+<CodeGroup>
-* `Taxonomy` – a hierarchical list which is made up of individual Taxons. Each taxonomy relates to one `Taxon`, which is its root node.
-* `Taxon` – a single child node which exists at a given point within a `Taxonomy`. Each `Taxon` can contain many (or no) sub / child taxons. Store administrators can define as many Taxonomies as required, and link a product to multiple Taxons from each Taxonomy.
+```typescript SDK
+// List taxonomies
+const { data: taxonomies } = await client.store.taxonomies.list()
-By default, both Taxons and Taxonomies are ordered by their `position` attribute.
+// List taxons (categories)
+const { data: taxons } = await client.store.taxons.list()
-<Note>
-Taxons use the [Nested set model](http://en.wikipedia.org/wiki/Nested_set_model) for their hierarchy. The `lft` and `rgt` columns in the `spree_taxons` table represent the locations within the hierarchy of the item. This logic is handled by the [awesome nested set](https://github.com/collectiveidea/awesome_nested_set) gem.
-</Note>
+// Get a taxon by permalink
+const taxon = await client.store.taxons.get('categories/clothing')
-Taxons link to products through an intermediary model called `Classification`. This model exists so that when a product is deleted, all of the links from that product to its taxons are deleted automatically. A similar action takes place when a taxon is deleted; all of the links to products are deleted automatically.
+// List products in a taxon
+const { data: products } = await client.store.taxons.products.list('categories/clothing', {
+ limit: 12,
+})
+```
-<Note>
-Storefront uses `spree.nested_taxons_path` helper method to generate full taxon URLs, which will use the taxon's permalink, eg.
+```bash cURL
+# List taxonomies
+curl 'https://api.mystore.com/api/v3/store/taxonomies' \
+ -H 'Authorization: Bearer spree_pk_xxx'
-```ruby
-taxon = Spree::Taxon.find_by(permalink: 'clothes/dresses')
-spree.nested_taxons_path(taxon)
+# List taxons
+curl 'https://api.mystore.com/api/v3/store/taxons' \
+ -H 'Authorization: Bearer spree_pk_xxx'
+
+# Get a taxon by permalink
+curl 'https://api.mystore.com/api/v3/store/taxons/categories/clothing' \
+ -H 'Authorization: Bearer spree_pk_xxx'
+
+# List products in a taxon
+curl 'https://api.mystore.com/api/v3/store/taxons/categories/clothing/products?limit=12' \
+ -H 'Authorization: Bearer spree_pk_xxx'
```
-which will output `/t/categories/clothes/dresses`.
-</Note>
+</CodeGroup>
<Info>
-As of version 4.6, the taxon `name` and `description` fields are translatable.
+Taxon `name` and `description` fields are translatable.
</Info>
+
+## Related Documentation
+
+- [Pricing](/developer/core-concepts/pricing) — Price Lists, Price Rules, and market-specific pricing
+- [Inventory](/developer/core-concepts/inventory) — Stock management and backorders
+- [Images & Assets](/developer/core-concepts/images-assets) — Image management
+- [Translations](/developer/core-concepts/translations) — Translating product content
+- [Search & Filtering](/developer/core-concepts/search-filtering) — Full-text search and Ransack filtering
+- [Querying](/api-reference/store-api/querying) — API filtering, sorting, and pagination
diff --git a/docs/developer/core-concepts/promotions.mdx b/docs/developer/core-concepts/promotions.mdx
index 7b07fabdff..89354b673f 100644
--- a/docs/developer/core-concepts/promotions.mdx
+++ b/docs/developer/core-concepts/promotions.mdx
@@ -265,183 +265,60 @@ Set the `code` attribute directly on the promotion. The `usage_limit` controls h
### Multi-Code Promotions
-For bulk-generated codes, each code is stored in the `spree_coupon_codes` table:
+For bulk-generated codes, each code tracks its usage state:
| Attribute | Description | Example |
|-----------|-------------|---------|
| `code` | The unique code | `SUMMER22A0F62A230BD919` |
-| `promotion_id` | Associated promotion | 123 |
-| `order_id` | Order that used the code | 456 |
| `state` | Usage state | `unused`, `used` |
-## Custom Promotion Rules
+## Applying Coupon Codes via Store API
-You can create custom rules to implement business-specific eligibility logic.
+Customers apply coupon codes during checkout via the Store API:
-### Step 1: Create the Rule Class
+<CodeGroup>
-```bash
-mkdir -p app/models/spree/promotion/rules
-```
-
-```ruby app/models/spree/promotion/rules/minimum_quantity.rb
-module Spree
- class Promotion
- module Rules
- class MinimumQuantity < Spree::PromotionRule
- preference :quantity, :integer, default: 5
-
- def applicable?(promotable)
- promotable.is_a?(Spree::Order)
- end
-
- def eligible?(order, options = {})
- total_quantity = order.line_items.sum(&:quantity)
-
- if total_quantity >= preferred_quantity
- true
- else
- eligibility_errors.add(:base, "Order must contain at least #{preferred_quantity} items")
- false
- end
- end
- end
- end
- end
-end
-```
-
-The `eligible?` method should return `true` or `false`. Use `eligibility_errors` to provide feedback to customers about why the promotion didn't apply.
-
-### Step 2: Register the Rule
-
-<Tabs>
- <Tab title="Spree 5.2+">
- ```ruby config/initializers/spree.rb
- Rails.application.config.after_initialize do
- Spree.promotions.rules << Spree::Promotion::Rules::MinimumQuantity
- end
- ```
- </Tab>
- <Tab title="Spree 5.1 and below">
- ```ruby config/initializers/spree.rb
- Rails.application.config.after_initialize do
- Rails.application.config.spree.promotions.rules << Spree::Promotion::Rules::MinimumQuantity
- end
- ```
- </Tab>
-</Tabs>
-
-### Step 3: Create the Admin Partial
-
-```bash
-touch app/views/spree/admin/promotions/rules/_minimum_quantity.html.erb
-```
-
-```erb app/views/spree/admin/promotions/rules/_minimum_quantity.html.erb
-<div class="row mb-3">
- <%= f.spree_number_field :preferred_quantity, label: Spree.t(:minimum_quantity) %>
-</div>
-```
-
-### Step 4: Add Translations
-
-```yaml config/locales/en.yml
-en:
- spree:
- minimum_quantity: Minimum Quantity
- promotion_rule_types:
- minimum_quantity:
- name: Minimum Quantity
- description: Order must contain at least X items
-```
-
-### Step 5: Restart Your Application
-
-After restarting, the new rule will be available in the Admin > Promotions interface.
-
-## Custom Promotion Actions
-
-You can create custom actions to implement business-specific promotion behaviors.
-
-### Step 1: Create the Action Class
-
-```bash
-mkdir -p app/models/spree/promotion/actions
-```
+```typescript SDK
+// Apply a coupon code to the order
+const order = await client.store.orders.couponCodes.apply('or_abc123', 'SUMMER20', {
+ orderToken: '<token>',
+})
-```ruby app/models/spree/promotion/actions/add_loyalty_points.rb
-module Spree
- module Promotion
- module Actions
- class AddLoyaltyPoints < Spree::PromotionAction
- preference :points, :integer, default: 100
-
- def perform(options = {})
- order = options[:order]
- return false unless order.user.present?
-
- # Add loyalty points to the user
- order.user.add_loyalty_points(preferred_points, source: promotion)
- true
- end
- end
- end
- end
-end
+// Remove a coupon code
+await client.store.orders.couponCodes.remove('or_abc123', 'SUMMER20', {
+ orderToken: '<token>',
+})
```
-The `perform` method should return `true` if the action was successfully applied, `false` otherwise.
-
-### Step 2: Register the Action
-
-<Tabs>
- <Tab title="Spree 5.2+">
- ```ruby config/initializers/spree.rb
- Rails.application.config.after_initialize do
- Spree.promotions.actions << Spree::Promotion::Actions::AddLoyaltyPoints
- end
- ```
- </Tab>
- <Tab title="Spree 5.1 and below">
- ```ruby config/initializers/spree.rb
- Rails.application.config.after_initialize do
- Rails.application.config.spree.promotions.actions << Spree::Promotion::Actions::AddLoyaltyPoints
- end
- ```
- </Tab>
-</Tabs>
-
-### Step 3: Add Translations
-
-```yaml config/locales/en.yml
-en:
- spree:
- promotion_action_types:
- add_loyalty_points:
- name: Add Loyalty Points
- description: Awards loyalty points to the customer
+```bash cURL
+# Apply a coupon code
+curl -X POST 'https://api.mystore.com/api/v3/store/orders/or_abc123/coupon_codes' \
+ -H 'Authorization: Bearer spree_pk_xxx' \
+ -H 'X-Spree-Order-Token: <token>' \
+ -H 'Content-Type: application/json' \
+ -d '{ "coupon_code": "SUMMER20" }'
```
-### Step 4: Restart Your Application
+</CodeGroup>
-After restarting, the new action will be available in the Admin > Promotions interface.
+Automatic promotions are applied without any customer action — they are evaluated on every order update.
## Promotion Flow
-Understanding how promotions are evaluated and applied:
+How promotions are evaluated and applied:
-1. **Order Update** - When an order is updated, the system checks all eligible promotions
-2. **Eligibility Check** - For each promotion:
+1. **Order Update** — When an order is updated, the system checks all eligible promotions
+2. **Eligibility Check** — For each promotion:
- Check if within `starts_at` and `expires_at` range
- Check if under `usage_limit`
- Evaluate all rules based on `match_policy` (all or any)
-3. **Action Execution** - If eligible, each action's `perform()` method is called
-4. **Tracking** - Applied promotions are recorded in `spree_order_promotions`
-5. **Re-evaluation** - Eligibility is re-checked on every order update; adjustments from ineligible promotions are removed
+3. **Action Execution** — If eligible, each action is applied
+4. **Tracking** — Applied promotions are recorded on the order
+5. **Re-evaluation** — Eligibility is re-checked on every order update; adjustments from ineligible promotions are removed
## Related Documentation
+- [Build Custom Promotion Rules & Actions](/developer/how-to/custom-promotion) - Step-by-step guide to creating custom rules and actions
- [Calculators](/developer/core-concepts/calculators) - Learn about promotion calculators
- [Orders](/developer/core-concepts/orders) - Understanding order processing
- [Customization Quickstart](/developer/customization/quickstart) - Overview of customization options
diff --git a/docs/developer/core-concepts/reports.mdx b/docs/developer/core-concepts/reports.mdx
index a012902c3b..2e4bb91fe6 100644
--- a/docs/developer/core-concepts/reports.mdx
+++ b/docs/developer/core-concepts/reports.mdx
@@ -95,219 +95,6 @@ The Products Performance report aggregates sales metrics by product for the spec
- `promo_total` - Total promotion discounts
- `total` - Total revenue
-## Creating Custom Reports
-
-To create a custom report, you need three components:
-
-1. A report class that defines the data query
-2. A line item class that formats each row
-3. Registration in `Spree.reports`
-
-### Step 1: Create the Report Class
-
-Create a new report class that inherits from `Spree::Report`:
-
-```ruby app/models/spree/reports/customer_orders.rb
-module Spree
- module Reports
- class CustomerOrders < Spree::Report
- # Define the scope of records to include in the report
- def line_items_scope
- store.orders.complete.where(
- completed_at: date_from..date_to,
- currency: currency
- ).includes(:user, :bill_address)
- end
- end
- end
-end
-```
-
-The `line_items_scope` method must return an `ActiveRecord::Relation` that defines what records appear in the report. This method has access to:
-
-- `store` - The current store
-- `date_from` - Report start date
-- `date_to` - Report end date
-- `currency` - Report currency
-- `vendor` - Vendor (if multi-vendor is enabled)
-
-### Step 2: Create the Line Item Class
-
-Create a corresponding line item class that transforms each record into report columns:
-
-```ruby app/models/spree/report_line_items/customer_orders.rb
-module Spree
- module ReportLineItems
- class CustomerOrders < Spree::ReportLineItem
- # Define attributes that will become columns
- attribute :order_number, :string
- attribute :completed_at, :string
- attribute :customer_email, :string
- attribute :customer_name, :string
- attribute :item_count, :integer
- attribute :total, :string
-
- # Map record fields to report columns
- def order_number
- record.number
- end
-
- def completed_at
- record.completed_at.strftime('%Y-%m-%d %H:%M')
- end
-
- def customer_email
- record.email
- end
-
- def customer_name
- record.bill_address&.full_name
- end
-
- def item_count
- record.line_items.sum(:quantity)
- end
-
- def total
- Spree::Money.new(record.total, currency: currency)
- end
- end
- end
-end
-```
-
-**Important notes:**
-- The class name must match the report class name (e.g., `Reports::CustomerOrders` -> `ReportLineItems::CustomerOrders`)
-- Use `attribute` to define columns with their types
-- Each attribute needs a corresponding method that extracts/formats data from `record`
-- `record` is a single item from `line_items_scope`
-- Use `Spree::Money` for currency formatting
-- `currency` and `store` are delegated from the report
-
-### Step 3: Register the Report
-
-Add your report to the registry in an initializer:
-
-```ruby config/initializers/spree.rb
-Rails.application.config.after_initialize do
- Spree.reports << Spree::Reports::CustomerOrders
-end
-```
-
-### Step 4: Add Translations
-
-Add the report name translation:
-
-```yaml config/locales/en.yml
-en:
- spree:
- report_names:
- customer_orders: Customer Orders
-```
-
-Also add translations for any custom column headers:
-
-```yaml config/locales/en.yml
-en:
- spree:
- order_number: Order Number
- completed_at: Completed At
- customer_email: Customer Email
- customer_name: Customer Name
- item_count: Item Count
- total: Total
-```
-
-## Advanced Customization
-
-### Complex Queries with Aggregations
-
-For reports that aggregate data, you can use SQL directly:
-
-```ruby app/models/spree/reports/revenue_by_category.rb
-module Spree
- module Reports
- class RevenueByCategory < Spree::Report
- def line_items_scope
- line_items_sql = Spree::LineItem
- .joins(:order)
- .where(
- spree_orders: {
- completed_at: date_from..date_to,
- currency: currency
- }
- )
- .select(
- "spree_line_items.variant_id",
- "SUM(spree_line_items.quantity) as quantity",
- "SUM(spree_line_items.pre_tax_amount) as revenue"
- )
- .group(:variant_id)
- .to_sql
-
- store.taxons
- .where(depth: 1) # Top-level categories
- .joins("LEFT JOIN spree_products_taxons ON spree_products_taxons.taxon_id = spree_taxons.id")
- .joins("LEFT JOIN spree_variants ON spree_variants.product_id = spree_products_taxons.product_id")
- .joins("LEFT JOIN (#{line_items_sql}) AS line_items ON line_items.variant_id = spree_variants.id")
- .select(
- "spree_taxons.*",
- "COALESCE(SUM(line_items.quantity), 0) AS total_quantity",
- "COALESCE(SUM(line_items.revenue), 0.0) AS total_revenue"
- )
- .group("spree_taxons.id")
- end
- end
- end
-end
-```
-
-### Custom Summary Section
-
-Override `to_partial_path` to use a custom template with a summary:
-
-```ruby app/models/spree/reports/customer_orders.rb
-module Spree
- module Reports
- class CustomerOrders < Spree::Report
- def summary
- {
- total_orders: line_items_scope.count,
- total_revenue: line_items_scope.sum(:total),
- average_order_value: line_items_scope.average(:total)
- }
- end
- end
- end
-end
-```
-
-### Multi-Vendor Support
-
-If you're using Spree Multi-Vendor, filter by vendor:
-
-```ruby app/models/spree/reports/vendor_sales.rb
-module Spree
- module Reports
- class VendorSales < Spree::Report
- def line_items_scope
- scope = store.line_items.where(
- order: Spree::Order.complete.where(
- completed_at: date_from..date_to,
- currency: currency
- )
- )
-
- # Filter by vendor if one is selected
- scope = scope.where(vendor_id: vendor.id) if defined?(vendor) && vendor.present?
-
- scope
- end
- end
- end
-end
-```
-
## How Reports Work Internally
### Generation Flow
@@ -385,288 +172,6 @@ def to_csv
end
```
-## Testing Custom Reports
-
-Testing custom reports ensures they correctly query data and format output. Here's how to write comprehensive specs for your reports.
-
-### Testing the Report Class
-
-Test that your report's `line_items_scope` returns the correct records:
-
-```ruby spec/models/spree/reports/customer_orders_spec.rb
-require 'rails_helper'
-
-RSpec.describe Spree::Reports::CustomerOrders, type: :model do
- let(:store) { create(:store) }
- let(:user) { create(:admin_user) }
-
- subject(:report) do
- described_class.new(
- store: store,
- user: user,
- currency: 'USD',
- date_from: 1.month.ago,
- date_to: Time.current
- )
- end
-
- describe '#line_items_scope' do
- let!(:completed_order) do
- create(:completed_order_with_totals, store: store, currency: 'USD', completed_at: 1.week.ago)
- end
-
- let!(:incomplete_order) do
- create(:order, store: store, currency: 'USD', state: 'cart')
- end
-
- let!(:other_currency_order) do
- create(:completed_order_with_totals, store: store, currency: 'EUR', completed_at: 1.week.ago)
- end
-
- let!(:old_order) do
- create(:completed_order_with_totals, store: store, currency: 'USD', completed_at: 2.months.ago)
- end
-
- it 'returns only completed orders within the date range and currency' do
- scope = report.line_items_scope
-
- expect(scope).to include(completed_order)
- expect(scope).not_to include(incomplete_order)
- expect(scope).not_to include(other_currency_order)
- expect(scope).not_to include(old_order)
- end
- end
-
- describe '#line_items' do
- let!(:order) do
- create(:completed_order_with_totals, store: store, currency: 'USD', completed_at: 1.week.ago)
- end
-
- it 'returns ReportLineItem objects' do
- items = report.line_items
- expect(items).to all(be_a(Spree::ReportLineItems::CustomerOrders))
- end
-
- it 'respects the limit option' do
- create(:completed_order_with_totals, store: store, currency: 'USD', completed_at: 2.days.ago)
- items = report.line_items(limit: 1)
- expect(items.length).to eq(1)
- end
- end
-
- describe 'registration' do
- it 'is registered in Spree.reports' do
- expect(Spree.reports).to include(described_class)
- end
- end
-
- describe '#line_item_class' do
- it 'resolves to the correct ReportLineItem class' do
- expect(report.line_item_class).to eq(Spree::ReportLineItems::CustomerOrders)
- end
- end
-
- describe '.report_type' do
- it 'returns the underscored class name' do
- expect(described_class.report_type).to eq('customer_orders')
- end
- end
-end
-```
-
-### Testing the ReportLineItem Class
-
-Test that your line item correctly formats each record:
-
-```ruby spec/models/spree/report_line_items/customer_orders_spec.rb
-require 'rails_helper'
-
-RSpec.describe Spree::ReportLineItems::CustomerOrders, type: :model do
- let(:store) { create(:store) }
- let(:user) { create(:admin_user) }
- let(:bill_address) { create(:address) }
- let(:order) do
- create(:completed_order_with_totals,
- store: store,
- currency: 'USD',
- completed_at: 1.week.ago,
- bill_address: bill_address)
- end
-
- let(:report) do
- Spree::Reports::CustomerOrders.new(
- store: store,
- user: user,
- currency: 'USD',
- date_from: 1.month.ago,
- date_to: Time.current
- )
- end
-
- subject(:line_item) { described_class.new(record: order, report: report) }
-
- describe '#order_number' do
- it 'returns the order number' do
- expect(line_item.order_number).to eq(order.number)
- end
- end
-
- describe '#completed_at' do
- it 'returns formatted completion date' do
- expect(line_item.completed_at).to eq(order.completed_at.strftime('%Y-%m-%d %H:%M'))
- end
- end
-
- describe '#customer_email' do
- it 'returns the order email' do
- expect(line_item.customer_email).to eq(order.email)
- end
- end
-
- describe '#customer_name' do
- it 'returns the billing address full name' do
- expect(line_item.customer_name).to eq(bill_address.full_name)
- end
-
- context 'when no billing address' do
- let(:bill_address) { nil }
-
- it 'returns nil' do
- order.update_column(:bill_address_id, nil)
- order.reload
- expect(line_item.customer_name).to be_nil
- end
- end
- end
-
- describe '#item_count' do
- it 'returns the sum of line item quantities' do
- expected_count = order.line_items.sum(&:quantity)
- expect(line_item.item_count).to eq(expected_count)
- end
- end
-
- describe '#total' do
- it 'returns a Spree::Money formatted total' do
- result = line_item.total
- expect(result).to be_a(Spree::Money)
- expect(result.money.to_f).to eq(order.total.to_f)
- end
- end
-
- describe '.headers' do
- it 'returns headers for all attributes' do
- headers = described_class.headers
- header_names = headers.map { |h| h[:name] }
-
- expect(header_names).to eq(%i[order_number completed_at customer_email customer_name item_count total])
- end
- end
-
- describe '.csv_headers' do
- it 'returns string keys for CSV output' do
- expect(described_class.csv_headers).to eq(%w[order_number completed_at customer_email customer_name item_count total])
- end
- end
-
- describe '#to_csv' do
- it 'returns an array of values for CSV row' do
- csv_row = line_item.to_csv
-
- expect(csv_row.length).to eq(6)
- expect(csv_row[0]).to eq(order.number)
- expect(csv_row[1]).to eq(order.completed_at.strftime('%Y-%m-%d %H:%M'))
- expect(csv_row[2]).to eq(order.email)
- end
- end
-end
-```
-
-### Testing Reports with Aggregations
-
-For reports that use SQL aggregations, mock the virtual attributes:
-
-```ruby spec/models/spree/report_line_items/revenue_by_category_spec.rb
-require 'rails_helper'
-
-RSpec.describe Spree::ReportLineItems::RevenueByCategory, type: :model do
- let(:store) { create(:store) }
- let(:user) { create(:admin_user) }
- let(:taxonomy) { create(:taxonomy, store: store) }
- let(:taxon) { create(:taxon, taxonomy: taxonomy, parent: taxonomy.root) }
-
- let(:report) do
- Spree::Reports::RevenueByCategory.new(
- store: store,
- user: user,
- currency: 'USD',
- date_from: 1.month.ago,
- date_to: Time.current
- )
- end
-
- # Mock the aggregated query result with virtual attributes
- let(:record) do
- double(
- 'AggregatedTaxon',
- id: taxon.id,
- name: taxon.name,
- products: taxon.products,
- total_quantity: 25,
- total_revenue: 1250.00,
- total_tax: 100.00,
- total_promo: -50.00
- )
- end
-
- subject(:line_item) { described_class.new(record: record, report: report) }
-
- describe '#category_name' do
- it 'returns the taxon name' do
- expect(line_item.category_name).to eq(taxon.name)
- end
- end
-
- describe '#quantity' do
- it 'returns the total quantity as integer' do
- expect(line_item.quantity).to eq(25)
- end
- end
-
- describe '#revenue' do
- it 'returns a Spree::Money formatted revenue' do
- result = line_item.revenue
- expect(result).to be_a(Spree::Money)
- expect(result.money.to_f).to eq(1250.00)
- end
- end
-end
-```
-
-### Running the Tests
-
-Run your report specs with:
-
-```bash
-# Run all report specs
-bundle exec rspec spec/models/spree/reports/ spec/models/spree/report_line_items/
-
-# Run a specific report spec
-bundle exec rspec spec/models/spree/reports/customer_orders_spec.rb
-
-# Run with documentation format for detailed output
-bundle exec rspec spec/models/spree/reports/ --format documentation
-```
-
-### Key Testing Patterns
-
-1. **Test scope filtering**: Verify `line_items_scope` returns only records matching date range, currency, and store
-2. **Test line item resolution**: Ensure `line_item_class` resolves to the correct presenter class
-3. **Test registration**: Confirm your report is in `Spree.reports`
-4. **Test attribute formatting**: Verify each attribute method returns correctly formatted data
-5. **Test CSV output**: Check `headers`, `csv_headers`, and `to_csv` return expected values
-6. **Test edge cases**: Handle nil values gracefully (e.g., missing addresses)
-
## Configuration
### Report Preview Limit
@@ -694,3 +199,8 @@ Report access is controlled by CanCanCan. By default, only users with the `:mana
# Example: Allow all admins to view reports
can :manage, Spree::Report
```
+
+## Related Documentation
+
+- [Build a Custom Report](/developer/how-to/custom-report) - Step-by-step guide to creating custom reports
+- [Events](/developer/core-concepts/events) - How report generation uses the events system
diff --git a/docs/developer/core-concepts/search-filtering.mdx b/docs/developer/core-concepts/search-filtering.mdx
index 176bf32d15..917385c868 100644
--- a/docs/developer/core-concepts/search-filtering.mdx
+++ b/docs/developer/core-concepts/search-filtering.mdx
@@ -1,585 +1,240 @@
---
title: Search & Filtering
-description: "Learn how to search, filter and sort resources in Spree"
+description: "Search, filter, and sort products and other resources via the Store API"
---
## Overview
-Spree uses the [Ransack](https://activerecord-hackery.github.io/ransack/) gem to provide powerful search, filtering, and sorting capabilities throughout the platform. Ransack is integrated into:
+Spree provides powerful search, filtering, and sorting capabilities for products and other resources. The Store API supports:
-- **Admin Dashboard** - For filtering and searching resources in index views
-- **Platform API** - For filtering collections via API requests
+- Full-text search across product names, descriptions, and SKUs
+- Attribute-based filtering (price range, availability, stock status)
+- Category and taxon filtering
+- Faceted search with filter counts
+- Flexible sorting options
-Ransack allows you to build complex queries using URL parameters or API filters, supporting operations like:
+## Product Search
-- Exact matches (`eq`)
-- Partial matches (`cont`, `start`, `end`)
-- Comparisons (`gt`, `lt`, `gteq`, `lteq`)
-- NULL checks (`null`, `not_null`)
-- Date ranges and much more
+Use the `multi_search` parameter for full-text search across product fields:
-## Security Model
+<CodeGroup>
-Spree uses a whitelist-based security model for Ransack to prevent unauthorized database queries. By default, models can only be searched on:
-
-- `id`
-- `name`
-- `created_at`
-- `updated_at`
-
-Additional attributes, associations, and scopes must be explicitly whitelisted in each model.
+```typescript SDK
+const { data: products } = await client.store.products.list({
+ multi_search: 'tote bag',
+ limit: 12,
+})
+```
-## Making Models Searchable
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products?q[multi_search]=tote+bag&limit=12' \
+ -H 'Authorization: Bearer spree_pk_xxx'
+```
-To enable searching on additional fields, inherit from `Spree::Base` and configure whitelisted attributes:
+</CodeGroup>
-### Basic Configuration
+## Filtering Products
-```ruby
-module Spree
- class Brand < Spree::Base
- # Allow searching by these attributes
- self.whitelisted_ransackable_attributes = %w[sku status available_on]
+### By Price Range
- # Allow searching through these associations
- self.whitelisted_ransackable_associations = %w[variants taxons master]
+<CodeGroup>
- # Allow filtering by these scopes
- self.whitelisted_ransackable_scopes = %w[active available in_stock]
- end
-end
+```typescript SDK
+const { data: products } = await client.store.products.list({
+ price_gte: 20,
+ price_lte: 100,
+})
```
-<Info>
-The attributes `id`, `name`, `created_at`, and `updated_at` are always searchable by default and don't need to be explicitly whitelisted.
-</Info>
+```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'
+```
-### Real-World Examples
+</CodeGroup>
-Here are examples from Spree's core models:
+### By Availability
-#### User Model
+<CodeGroup>
-```ruby
-module Spree::UserMethods
- included do
- self.whitelisted_ransackable_associations = %w[bill_address ship_address addresses tags spree_roles]
- self.whitelisted_ransackable_attributes = %w[id email first_name last_name accepts_email_marketing]
- self.whitelisted_ransackable_scopes = %w[multi_search]
- end
-end
+```typescript SDK
+const { data: products } = await client.store.products.list({
+ in_stock: true,
+})
```
-#### Price Model
-
-```ruby
-module Spree
- class Price < Spree.base_class
- self.whitelisted_ransackable_attributes = %w[amount compare_at_amount]
- end
-end
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products?q[in_stock]=true' \
+ -H 'Authorization: Bearer spree_pk_xxx'
```
-## Admin Dashboard Integration
+</CodeGroup>
-The `Spree::Admin::ResourceController` automatically integrates Ransack for all admin resources.
+### By Category (Taxon)
-### How It Works
+<CodeGroup>
-The `ResourceController` at [admin/app/controllers/spree/admin/resource_controller.rb:242-254](https://github.com/spree/spree/blob/main/admin/app/controllers/spree/admin/resource_controller.rb#L242-L254) implements:
+```typescript SDK
+// Products in a specific category
+const { data: products } = await client.store.taxons.products.list('categories/clothing', {
+ limit: 12,
+})
-```ruby
-# keeping this as @search for backwards compatibility
-# @return [Ransack::Search]
-def search_collection
- @search ||= begin
- params[:q] ||= {}
- params[:q][:s] ||= collection_default_sort if collection_default_sort.present?
- scope.ransack(params[:q])
- end
-end
-
-# Returns the filtered and paginated ransack results
-# @return [ActiveRecord::Relation]
-def collection
- @collection ||= search_collection.result(distinct: true).page(params[:page]).per(params[:per_page])
-end
+// Or filter by taxon ID
+const { data: products } = await client.store.products.list({
+ taxon_id_eq: 'txn_xxx',
+})
```
-### Controller Configuration
-
-When building admin controllers, you can customize the search behavior:
-
-```ruby
-module Spree
- module Admin
- class BrandsController < ResourceController
- # Set default sort order
- def collection_default_sort
- 'name asc'
- end
-
- # Eager load associations to avoid N+1 queries
- def collection_includes
- [:logo_attachment]
- end
-
- # Customize the base scope (optional)
- def scope
- super.active
- end
- end
- end
-end
-```
+```bash cURL
+# Products in a category
+curl 'https://api.mystore.com/api/v3/store/taxons/categories/clothing/products?limit=12' \
+ -H 'Authorization: Bearer spree_pk_xxx'
-### Filters View
-
-Admin index views typically include a filters partial (`_filters.html.erb`) that builds search forms:
-
-```erb
-<%= search_form_for @search, url: spree.admin_brands_path, method: :get do |f| %>
- <div class="row">
- <div class="col-md-4">
- <%= f.label :name_cont, Spree.t(:name) %>
- <%= f.search_field :name_cont, class: 'form-control' %>
- </div>
-
- <div class="col-md-4">
- <%= f.label :active_eq, Spree.t(:status) %>
- <%= f.select :active_eq,
- [[Spree.t(:active), true], [Spree.t(:inactive), false]],
- { include_blank: Spree.t(:all) },
- class: 'form-control' %>
- </div>
-
- <div class="col-md-4">
- <%= f.label :created_at_gteq, Spree.t(:created_from) %>
- <%= f.date_field :created_at_gteq, class: 'form-control' %>
- </div>
- </div>
-
- <div class="form-actions">
- <%= f.submit Spree.t(:search), class: 'btn btn-primary' %>
- <%= link_to Spree.t(:clear), spree.admin_brands_path, class: 'btn btn-secondary' %>
- </div>
-<% end %>
+# Filter by taxon ID
+curl 'https://api.mystore.com/api/v3/store/products?q[taxon_id_eq]=txn_xxx' \
+ -H 'Authorization: Bearer spree_pk_xxx'
```
-## Platform API Integration
+</CodeGroup>
-The Platform API uses Ransack via the `filter` parameter for all collection endpoints.
+### By Tags
-### API Controller Implementation
+<CodeGroup>
-From [api/app/controllers/spree/api/v2/platform/resource_controller.rb:57-61](https://github.com/spree/spree/blob/main/api/app/controllers/spree/api/v2/platform/resource_controller.rb#L57-L61):
+```typescript SDK
+const { data: products } = await client.store.products.list({
+ tags_cont: 'sale',
+})
+```
-### API Usage Examples
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products?q[tags_cont]=sale' \
+ -H 'Authorization: Bearer spree_pk_xxx'
+```
-#### Basic Filtering
+</CodeGroup>
-Filter products by name:
+## Sorting
-```bash
-GET /api/v2/platform/products?filter[name_cont]=shirt
-```
+<CodeGroup>
-Filter users by email:
+```typescript SDK
+// Sort by price (low to high)
+const sorted = await client.store.products.list({
+ sort: 'price_low_to_high',
+})
-```bash
-GET /api/v2/platform/users?filter[email_eq][email protected]
+// Available sort options:
+// price_low_to_high, price_high_to_low, newest, name_a_z, name_z_a
```
-#### Advanced Filtering
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products?sort=price_low_to_high' \
+ -H 'Authorization: Bearer spree_pk_xxx'
+```
-Filter products by multiple criteria:
+</CodeGroup>
-```bash
-GET /api/v2/platform/products?filter[status_eq]=active&filter[price_gteq]=20&filter[price_lteq]=100
-```
+## Product Filters (Faceted Search)
-Filter through associations:
+Get available filter options for building a faceted search UI. Returns option values, price ranges, and taxons with counts:
-```bash
-GET /api/v2/platform/products?filter[taxons_name_cont]=shirts
-```
+<CodeGroup>
-Filter by date ranges:
+```typescript SDK
+const filters = await client.store.products.filters()
+// {
+// option_types: [{ name: "size", option_values: [{ name: "Small", count: 12 }, ...] }],
+// price_range: { min: 9.99, max: 199.99 },
+// taxons: [{ id: "txn_xxx", name: "Clothing", count: 45 }],
+// }
-```bash
-GET /api/v2/platform/orders?filter[created_at_gteq]=2024-01-01&filter[created_at_lteq]=2024-12-31
+// Scoped to a specific category
+const taxonFilters = await client.store.products.filters({
+ taxon_id_eq: 'txn_xxx',
+})
```
-#### Using Scopes
+```bash cURL
+# All filters
+curl 'https://api.mystore.com/api/v3/store/products/filters' \
+ -H 'Authorization: Bearer spree_pk_xxx'
-If a model defines `whitelisted_ransackable_scopes`, you can filter using them:
-
-```bash
-GET /api/v2/platform/products?filter[in_stock]=true
+# Scoped to a taxon
+curl 'https://api.mystore.com/api/v3/store/products/filters?taxon_id_eq=txn_xxx' \
+ -H 'Authorization: Bearer spree_pk_xxx'
```
-<Warning>
-Only attributes, associations, and scopes explicitly whitelisted in models can be used for filtering. Attempting to filter on non-whitelisted fields will be silently ignored for security reasons.
-</Warning>
+</CodeGroup>
-## Search Predicates
+## Filtering Other Resources
-Ransack provides numerous predicates (matchers) for building complex queries. Here are the most commonly used ones in Spree:
+The Store API uses query parameters prefixed with `q[]` for filtering any resource collection. Common filter predicates:
### Equality Predicates
| Predicate | Description | Example |
|-----------|-------------|---------|
-| `eq` | Equals | `name_eq=Nike` |
-| `not_eq` | Not equals | `status_not_eq=archived` |
-| `in` | In array | `id_in[]=1&id_in[]=2&id_in[]=3` |
-| `not_in` | Not in array | `status_not_in[]=draft&status_not_in[]=archived` |
+| `eq` | Equals | `q[status_eq]=active` |
+| `not_eq` | Not equals | `q[status_not_eq]=archived` |
+| `in` | In array | `q[id_in][]=1&q[id_in][]=2` |
### String Predicates
| Predicate | Description | Example |
|-----------|-------------|---------|
-| `cont` | Contains | `name_cont=shirt` |
-| `not_cont` | Does not contain | `name_not_cont=vintage` |
-| `start` | Starts with | `email_start=admin` |
-| `end` | Ends with | `[email protected]` |
-| `i_cont` | Case-insensitive contains | `name_i_cont=SHIRT` |
+| `cont` | Contains | `q[name_cont]=shirt` |
+| `start` | Starts with | `q[name_start]=spree` |
+| `end` | Ends with | `q[email_end][email protected]` |
+| `i_cont` | Case-insensitive contains | `q[name_i_cont]=SHIRT` |
### Comparison Predicates
| Predicate | Description | Example |
|-----------|-------------|---------|
-| `gt` | Greater than | `price_gt=50` |
-| `gteq` | Greater than or equal | `quantity_gteq=10` |
-| `lt` | Less than | `price_lt=100` |
-| `lteq` | Less than or equal | `created_at_lteq=2024-12-31` |
+| `gt` | Greater than | `q[price_gt]=50` |
+| `gteq` | Greater than or equal | `q[quantity_gteq]=10` |
+| `lt` | Less than | `q[price_lt]=100` |
+| `lteq` | Less than or equal | `q[created_at_lteq]=2025-12-31` |
### NULL Predicates
| Predicate | Description | Example |
|-----------|-------------|---------|
-| `null` | Is NULL | `deleted_at_null=true` |
-| `not_null` | Is not NULL | `published_at_not_null=true` |
-| `blank` | Is NULL or empty | `description_blank=true` |
-| `present` | Is not NULL and not empty | `image_present=true` |
-
-### Date/Time Predicates
-
-```ruby
-# Products created this year
-products?filter[created_at_gteq]=2024-01-01
-
-# Orders completed today
-orders?filter[completed_at_gteq]=2024-01-15&filter[completed_at_lteq]=2024-01-15
-
-# Products available before a date
-products?filter[available_on_lteq]=2024-12-31
-```
-
-## Sorting
-
-### Admin Dashboard Sorting
-
-Ransack handles sorting via the `s` parameter in the `q` hash:
-
-```ruby
-# In controller
-params[:q][:s] = 'created_at desc' # Sort by created_at descending
-params[:q][:s] = 'name asc' # Sort by name ascending
-```
-
-In views, use `sort_link` helper:
-
-```erb
-<%= sort_link(@search, :name, Spree.t(:name)) %>
-<%= sort_link(@search, :created_at, Spree.t(:created_at)) %>
-<%= sort_link(@search, :status, Spree.t(:status)) %>
-```
-
-### Platform API Sorting
-
-The Platform API uses the standard JSON:API `sort` parameter:
-
-```bash
-# Sort by name ascending
-GET /api/v2/platform/products?sort=name
-
-# Sort by created_at descending
-GET /api/v2/platform/products?sort=-created_at
-
-# Multiple sorts
-GET /api/v2/platform/products?sort=status,-created_at
-```
-
-<Info>
-Platform API sorting is handled separately from Ransack's filter parameter and follows JSON:API conventions.
-</Info>
-
-## Extending Ransackable Configuration
-
-If you need to add custom ransackable attributes, associations, or scopes to Spree's built-in models without using decorators, use the `Spree.ransack` configuration API.
-
-### Adding Custom Configuration
-
-Add the following to your initializer (e.g., `config/initializers/spree.rb`):
-
-```ruby
-Rails.application.config.after_initialize do
- # Add a custom searchable attribute to Products
- Spree.ransack.add_attribute(Spree::Product, :vendor_id)
-
- # Add a custom searchable scope to Products
- Spree.ransack.add_scope(Spree::Product, :by_vendor)
-
- # Add a custom searchable association to Products
- Spree.ransack.add_association(Spree::Product, :vendor)
-
- # Add multiple configurations for Orders
- Spree.ransack.add_attribute(Spree::Order, :custom_reference)
- Spree.ransack.add_scope(Spree::Order, :high_value)
- Spree.ransack.add_association(Spree::Order, :sales_rep)
-end
-```
+| `null` | Is NULL | `q[deleted_at_null]=true` |
+| `not_null` | Is not NULL | `q[published_at_not_null]=true` |
+| `present` | Is not NULL and not empty | `q[image_present]=true` |
<Info>
-The `Spree.ransack` API only allows adding new searchable fields. It does not support removing default configurations to prevent accidentally breaking core functionality.
+Only attributes explicitly allowed by each resource can be used for filtering. Attempting to filter on unsupported fields will be silently ignored.
</Info>
-### Available Methods
-
-| Method | Description | Example |
-|--------|-------------|---------|
-| `add_attribute` | Add a searchable attribute | `Spree.ransack.add_attribute(Spree::Product, :vendor_id)` |
-| `add_scope` | Add a searchable scope | `Spree.ransack.add_scope(Spree::Product, :featured)` |
-| `add_association` | Add a searchable association | `Spree.ransack.add_association(Spree::Product, :vendor)` |
-
-### Complete Example
-
-Here's an example of extending Products with a vendor relationship:
-
-```ruby
-# app/models/vendor.rb
-class Vendor < ApplicationRecord
- has_many :products, class_name: 'Spree::Product'
-end
-
-# db/migrate/xxx_add_vendor_to_spree_products.rb
-class AddVendorToSpreeProducts < ActiveRecord::Migration[7.0]
- def change
- add_reference :spree_products, :vendor
- end
-end
-
-# config/initializers/spree.rb
-Rails.application.config.after_initialize do
- Spree.ransack.add_attribute(Spree::Product, :vendor_id)
- Spree.ransack.add_association(Spree::Product, :vendor)
-end
-```
-
-Now you can search products by vendor:
-
-```bash
-# Filter by vendor_id
-GET /api/v2/platform/products?filter[vendor_id_eq]=123
-
-# Filter by vendor name (through association)
-GET /api/v2/platform/products?filter[vendor_name_cont]=acme
-```
-
-## Custom Implementation Examples
-
-### Example 1: Brand Resource
+## Pagination
-From the admin resources guide:
+All list endpoints support pagination:
-```ruby
-module Spree
- class Brand < Spree.base_class
- include Spree::RansackableAttributes
+<CodeGroup>
- # Enable searching
- self.whitelisted_ransackable_attributes = %w[name slug status published_at]
- self.whitelisted_ransackable_scopes = %w[published with_logo]
-
- # Scopes that can be used in searches
- scope :published, -> { where(status: 'published') }
- scope :with_logo, -> { includes(:logo_attachment).where.not(logo_attachment: { blob: nil }) }
- end
-end
+```typescript SDK
+const { data: products, meta } = await client.store.products.list({
+ page: 1,
+ limit: 24,
+})
+// meta.total_count => 150
+// meta.total_pages => 7
```
-Controller:
-
-```ruby
-module Spree
- module Admin
- class BrandsController < ResourceController
- def collection_default_sort
- 'name asc'
- end
- end
- end
-end
-```
-
-### Example 2: Custom Search Scope
-
-```ruby
-module Spree
- class Product < Spree.base_class
- # Custom search scope
- scope :multi_search, ->(query) {
- where('name ILIKE ? OR description ILIKE ?', "%#{query}%", "%#{query}%")
- }
-
- # Whitelist the scope
- self.whitelisted_ransackable_scopes = %w[multi_search]
- end
-end
-```
-
-Usage in admin:
-
-```ruby
-# Search across multiple fields
-products?q[multi_search]=keyword
-```
-
-## Best Practices
-
-### 1. Always Whitelist Searchable Fields
-
-```ruby
-# ✅ Good - explicit whitelist
-self.whitelisted_ransackable_attributes = %w[name email status]
-
-# ❌ Bad - exposes all columns
-# Never override ransackable_attributes without proper authorization
-```
-
-### 2. Include Default Timestamps
-
-The default ransackable attributes include `created_at` and `updated_at`, so you don't need to whitelist them:
-
-```ruby
-# ❌ Redundant
-self.whitelisted_ransackable_attributes = %w[name created_at updated_at]
-
-# ✅ Better
-self.whitelisted_ransackable_attributes = %w[name]
-```
-
-### 3. Use Scopes for Complex Filters
-
-```ruby
-# ✅ Good - encapsulate complex logic in scopes
-scope :premium, -> { where('price >= ?', 100).where(featured: true) }
-self.whitelisted_ransackable_scopes = %w[premium]
-
-# ❌ Bad - exposing internal implementation details
-self.whitelisted_ransackable_attributes = %w[price featured]
-```
-
-### 4. Use Appropriate Predicates
-
-Choose predicates that match your use case:
-
-```ruby
-# ✅ Good - case-insensitive search for user input
-name_i_cont=search_term
-
-# ✅ Good - exact match for status
-status_eq=active
-
-# ❌ Bad - expensive LIKE queries on large datasets
-id_cont=123 # Use id_eq instead
-```
-
-### 5. Sanitize User Input
-
-When building search forms, use Ransack's helpers to prevent injection:
-
-```erb
-<%# ✅ Good - uses search_form_for helper %>
-<%= search_form_for @search do |f| %>
- <%= f.search_field :name_cont %>
-<% end %>
-
-<%# ❌ Bad - raw params manipulation %>
-<%= text_field_tag 'q[name_cont]', params[:q][:name_cont] %>
-```
-
-### 6. Test Ransackable Configuration
-
-Always test that your ransackable configuration works as expected:
-
-```ruby
-# spec/models/spree/brand_spec.rb
-RSpec.describe Spree::Brand, type: :model do
- describe 'ransackable attributes' do
- it 'includes whitelisted attributes' do
- expect(described_class.ransackable_attributes)
- .to include('id', 'name', 'status', 'created_at', 'updated_at')
- end
- end
-
- describe 'ransackable scopes' do
- it 'includes whitelisted scopes' do
- expect(described_class.ransackable_scopes).to include('published', 'with_logo')
- end
- end
-end
-```
-
-## Troubleshooting
-
-### Fields Not Searchable
-
-If you can't search by a field, check:
-
-1. Is it whitelisted in `whitelisted_ransackable_attributes`?
-2. Are you using the correct predicate (e.g., `_cont` for partial match)?
-
-### Associations Not Searchable
-
-For searching through associations:
-
-1. Whitelist the association in `whitelisted_ransackable_associations`
-2. Ensure the associated model also whitelists its attributes
-3. Use the correct syntax: `association_field_predicate`
-
-Example:
-
-```ruby
-# Search for products through taxon names
-products?q[taxons_name_cont]=shirts
-```
-
-### Scopes Not Working
-
-For scope filtering:
-
-1. Define the scope in your model
-2. Whitelist it in `whitelisted_ransackable_scopes`
-3. Pass a value (usually `true`) when filtering
-
-```ruby
-# Model
-scope :in_stock, -> { where('quantity > 0') }
-self.whitelisted_ransackable_scopes = %w[in_stock]
-
-# Usage
-products?q[in_stock]=true
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products?page=1&limit=24' \
+ -H 'Authorization: Bearer spree_pk_xxx'
```
-## Additional Resources
+</CodeGroup>
-- [Ransack Search Matchers](https://activerecord-hackery.github.io/ransack/getting-started/search-matches/)
-- [Platform API Documentation](/developer/api/v2/platform)
+See [Querying](/api-reference/store-api/querying) for the full list of filtering, sorting, and pagination options.
## Related Documentation
-- [Admin Tables](/developer/admin/tables) - Customize admin list views with sorting and filtering
-- [Decorators](/developer/customization/decorators) - Add searchable attributes without decorators
-- [Customization Quickstart](/developer/customization/quickstart) - Overview of all customization options
+- [Products](/developer/core-concepts/products) — Product catalog and listing
+- [Querying](/api-reference/store-api/querying) — API filtering, sorting, and pagination reference
diff --git a/docs/developer/core-concepts/shipments.mdx b/docs/developer/core-concepts/shipments.mdx
index dfc97fcc68..f5586d5e86 100644
--- a/docs/developer/core-concepts/shipments.mdx
+++ b/docs/developer/core-concepts/shipments.mdx
@@ -1,13 +1,25 @@
---
title: Shipments
+description: Shipping methods, rates, split shipments, and fulfillment
---
## Overview
-### Shipment Model Diagram
+A shipment represents a package being sent to a customer from a [Stock Location](/developer/core-concepts/inventory#stock-locations). Each order can have one or more shipments — Spree automatically splits orders into multiple shipments when items need to ship from different locations or require different shipping methods.
```mermaid
erDiagram
+ Order ||--o{ Shipment : "has many"
+ Shipment ||--o{ ShippingRate : "has many"
+ Shipment ||--o{ InventoryUnit : "has many"
+ Shipment }o--|| StockLocation : "ships from"
+ Shipment }o--|| ShippingMethod : "selected method"
+ ShippingMethod ||--o{ ShippingRate : "has many"
+ ShippingMethod }o--o{ Zone : "serves"
+ ShippingMethod }o--o{ ShippingCategory : "handles"
+ ShippingMethod }o--o{ Store : "available in"
+ Product }o--|| ShippingCategory : "belongs to"
+
Shipment {
string number
string tracking
@@ -18,50 +30,14 @@ erDiagram
ShippingMethod {
string name
- string display_on
string tracking_url
integer position
}
- ShippingCategory {
- string name
- }
-
ShippingRate {
decimal cost
boolean selected
}
-
- Zone {
- string name
- string description
- string kind
- }
-
- InventoryUnit {
- string state
- }
-
- StockLocation {
- string name
- boolean active
- boolean default
- }
-
- Order ||--o{ Shipment : "has many"
- Shipment ||--o{ ShippingRate : "has many"
- Shipment ||--o{ InventoryUnit : "has many"
- Shipment }o--|| StockLocation : "ships from"
- Shipment }o--|| ShippingMethod : "selected method"
- Shipment ||--o{ Adjustment : "has many"
- ShippingMethod ||--o{ ShippingRate : "has many"
- ShippingMethod }o--o{ Zone : "serves"
- ShippingMethod }o--o{ ShippingCategory : "handles"
- ShippingMethod ||--|| Calculator : "has one"
- ShippingMethod }o--o{ Store : "available in"
- Product }o--|| ShippingCategory : "belongs to"
- Variant ||--o{ InventoryUnit : "has many"
- StockLocation ||--o{ StockItem : "has many"
```
**Key relationships:**
@@ -70,437 +46,169 @@ erDiagram
- **Shipping Rate** represents the calculated cost for a method
- **[Zone](/developer/core-concepts/addresses#zones)** defines geographic regions for shipping availability
- **Shipping Category** groups products with similar shipping requirements
-- **Inventory Units** track individual items within each shipment
-
-This guide explains how Spree represents shipping options and how it calculates expected costs, and shows how you can configure the system with your own shipping methods. After reading it you should know:
-* how shipments and shipping are implemented in Spree
-* how to specify your shipping structure
-* how split shipments work
-* how to configure products for special shipping treatment
-* how to capture shipping instructions
+## Shipment Attributes
-Spree uses a very flexible and effective system to calculate shipping, accommodating the full range of shipment pricing: from simple flat rate to complex product-type- and weight-dependent calculations.
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `number` | Unique shipment identifier | `H12345678901` |
+| `tracking` | Carrier tracking number | `1Z999AA10123456784` |
+| `state` | Current shipment state | `shipped` |
+| `cost` | Shipping cost | `9.99` |
+| `shipped_at` | When the shipment was shipped | `2025-07-21T14:36:00Z` |
+| `stock_location` | Where items ship from | `Warehouse NYC` |
+| `selected_shipping_rate` | The rate chosen by the customer | `{ cost: 9.99, name: "UPS Ground" }` |
-The Shipment model is used to track how items are delivered to the buyer.
-
-Shipments have the following attributes:
-
-| Attribute | Description | Example Value |
-|--------------------|-----------------------------------------------------------------------------------------------|------------------------------|
-| `number` | The unique identifier for this shipment. It begins with the letter H and ends in an 11-digit number. This number is shown to the users, and can be used to find the order by calling `Spree::Shipment.find_by(number: number)`. | H12345678901 |
-| `tracking` | The identifier given for the shipping provider i.e. FedEx, UPS, etc. | 1Z999AA10123456784 |
-| `shipped_at` | The time when the shipment was shipped. | 2021-07-21T14:36:00.000Z |
-| `state` | The current state of the shipment. | `shipped` |
-| `stock_location_id`| The ID of the [Stock Location](/developer/core-concepts/inventory#stock-locations) where the items for this shipment will be sourced from. | 3 |
-
-A shipment can go through many different states, as illustrated below.
-
-An explanation of the different states:
+## Shipment States
<Steps>
<Step title="pending">
- The shipment has backordered inventory units and/or the order is not paid for.
+ The shipment has backordered inventory or the order is not yet paid.
</Step>
<Step title="ready">
- The shipment has _no_ backordered inventory units and the order is paid for.
+ All items are in stock and the order is paid. Ready to ship.
</Step>
<Step title="shipped">
- The shipment is on its way to the buyer.
+ The shipment is on its way to the customer.
</Step>
<Step title="canceled">
- When an order is cancelled, all of its shipments will also be cancelled. When this happens, all items in the shipment will be restocked. If an order is "resumed", then the shipment will also be resumed.
+ The shipment was canceled. All items are restocked.
</Step>
</Steps>
-Explaining each piece of the shipment world inside of Spree separately and how each piece fits together can be a cumbersome task. Fortunately, using a few simple examples makes it much easier to grasp. In that spirit, the examples are shown first in this guide.
-
-## Examples
-
-### Simple Setup
-
-Consider you sell T-shirts to the US and Europe and ship from a single location, and you work with 2 deliverers:
-
-* USPS Ground to US
-* FedEx to EU
-
-and their pricing is as follow:
-
-* USPS charges $5 for one T-shirt and $2 for each additional one
-* FedEx charges $10 each, regardless of the quantity
-
-To achieve this setup you need the following configuration:
-
-* Shipping Categories: All your products are the same, so you only need to define one default shipping category. Each of your products would then need to be assigned to this shipping category.
-* 1 [Stock Location](/developer/core-concepts/inventory#stock-locations): You are shipping all items from the same location, so you can use the default.
-* 2 Shipping Methods Configuration-&gt;Shipping Methods as follows:
-
-| Name | Zone | Calculator |
-| ---: | ---: | ---: |
-| USPS Ground | US | Flexi Rate$5,$2 |
-| FedEx | EU_VAT | FlatRate-per-item$10 |
-
-### Advanced Setup
-
-Consider you sell products to a single zone US and you ship from 2 [Stock Locations](/developer/core-concepts/inventory#stock-locations):
+## Selecting Shipping Rates
-* New York
-* Los Angeles
+During checkout, after the customer provides a shipping address, Spree calculates available shipping rates for each shipment. The customer must select a rate before proceeding.
-and you work with 3 deliverers Shipping Methods:
+<CodeGroup>
-* FedEx
-* DHL
-* US postal service
+```typescript SDK
+// Get shipments with available shipping rates
+const order = await client.store.orders.get(orderId, {
+ expand: ['shipments'],
+})
-and your products can be classified into 3 Shipping Categories:
+// Each shipment has available shipping rates
+order.shipments?.forEach(shipment => {
+ console.log(shipment.number) // "H12345678901"
+ console.log(shipment.shipping_rates) // [{ id: "sr_xxx", name: "UPS Ground", cost: "9.99", selected: true }, ...]
+})
-* Light
-* Regular
-* Heavy
-
-and their pricing is as follow:
-
-FedEx charges:
-
-* $10 for all light items regardless of how many you have
-* $2 per regular item
-* $20 for the first heavy item and $15 for each additional one
-
-DHL charges:
-
-* $5 per item if it's light or regular
-* $50 per item if it's heavy
-
-USPS charges:
-
-* $8 per item if it's light or regular
-* $20 per item if it's heavy
-
-To achieve this setup you need the following configuration:
-
-* 4 Shipping Categories: Default, Light, Regular and Heavy
-* 3 Shipping Methods Configuration-&gt;Shipping Methods: FedEx, DHL, USPS
-* 2 [Stock Locations](/developer/core-concepts/inventory#stock-locations) (Configuration -> Stock Locations): New York, Los Angeles
-
-| S. Category / S. Method | DHL | FedEx | USPS |
-| ---: | ---: | ---: | ---: |
-| Light | Per Item $5 | Flat Rate $10 | Per Item $8 |
-| Regular | Per Item $5 | Per Item $2 | Per Item $8 |
-| Heavy | Per Item $50 | Flexi Rate$20,$15 | Per Item $20 |
-
-## Design & Functionality
-
-To properly leverage Spree's shipping system's flexibility you must understand a few key concepts:
-
-* Shipping Methods
-* Zones
-* Shipping Categories
-* Calculators through Shipping Rates
-
-### Shipping Methods
-
-Shipping methods are the actual services used to send the product. For example:
-
-* UPS Ground
-* UPS One Day
-* FedEx 2Day
-* FedEx Overnight
-* DHL International
+// Select a shipping rate
+await client.store.orders.shipments.update(orderId, shipment.id, {
+ selected_shipping_rate_id: 'sr_xxx',
+})
+```
-Each shipping method is only applicable to a specific `Zone`. For example, you wouldn't be able to get a package delivered internationally using a domestic-only shipping method. You can't ship from Dallas, USA to Rio de Janeiro, Brazil using UPS Ground a US-only carrier.
+```bash cURL
+# Get shipments
+curl 'https://api.mystore.com/api/v3/store/orders/or_xxx?expand=shipments' \
+ -H 'Authorization: Bearer spree_pk_xxx' \
+ -H 'X-Spree-Order-Token: abc123'
+
+# Select a shipping rate
+curl -X PATCH 'https://api.mystore.com/api/v3/store/orders/or_xxx/shipments/shp_xxx' \
+ -H 'Authorization: Bearer spree_pk_xxx' \
+ -H 'X-Spree-Order-Token: abc123' \
+ -H 'Content-Type: application/json' \
+ -d '{ "selected_shipping_rate_id": "sr_xxx" }'
+```
-If you are using shipping categories, these can be used to qualify or disqualify a given shipping method.
+</CodeGroup>
- Shipping methods can now have multiple shipping categories assigned to them. This allows the shipping methods available to an order to be determined by the shipping categories of the items in a shipment.
+## Shipping Methods
-### Zones
+Shipping methods represent the carrier services available to customers (e.g., UPS Ground, FedEx Overnight, DHL International). Each shipping method is scoped to:
-Zones serve as a mechanism for grouping geographic areas together into a single entity. You can read all about how to configure and use Zones in the [Zones Guide](/developer/core-concepts/addresses#zones).
+- **[Zones](/developer/core-concepts/addresses#zones)** — geographic regions where the method is available
+- **Shipping Categories** — product groups the method handles
+- **[Stores](/developer/core-concepts/stores)** — which stores offer this method
-The Shipping Address entered during checkout will define the zone the customer is in and limit the Shipping Methods available to him.
+Only methods whose zone matches the customer's shipping address are offered at checkout.
### Shipping Categories
-Shipping Categories are useful if you sell products whose shipping pricing vary depending on the type of product TVs and Mugs, for instance.
-
- For simple setups, where shipping for all products is priced the same ie. T-shirt-only shop, all products would be assigned to the default shipping category for the store.
-
-Some examples of Shipping Categories would be:
+Shipping categories group products with similar shipping requirements. For example:
-* Light for lightweight items like stickers
-* Regular
-* Heavy for items over a certain weight
+- **Light** — lightweight items like stickers
+- **Regular** — standard products
+- **Heavy** — items over a certain weight
+- **Oversized** — large items requiring special handling
-Shipping Categories are created in the admin interface `Configuration` -&gt; `Shipping Categories` and then assigned to products `Products` -&gt; `Edit`.
-
-During checkout, the shipping categories of the products in your order will determine which calculator will be used to price its shipping for each Shipping Method.
+Each product is assigned a shipping category. Shipping methods can be restricted to handle only certain categories, and the shipping cost calculator uses the category to determine pricing.
### Calculators
-A Calculator is the component responsible for calculating the shipping price for each available Shipping Method.
-
-Spree ships with 5 default Calculators:
-
-* Flat rate per order
-* Flat rate per item/product
-* Flat percent
-* Flexible rate
-* Price sack
-
-Flexible rate is defined as a flat rate for the first product, plus a different flat rate for each additional product.
-
-You can define your own calculator if you have more complex needs. In that case, check out the [Calculators Guide](calculators).
-
-## UI
-
-### What the Customer Sees
-
-In the standard system, there is no mention of shipping until the checkout phase.
-
-After entering a shipping address, the system displays the available shipping options and their costs for each shipment in the order. Only the shipping options whose zones include the _shipping_ address are presented.
-
-The customer must choose a shipping method for each shipment before proceeding to the next stage. At the confirmation step, the shipping cost will be shown and included in the order's total.
-
- You can enable collection of extra _shipping instructions_ by setting the option \`Spree::Config.shipping_instructions\` to \`true\`. This is set to \`false\` by default. See \[Shipping Instructions\]\#shipping-instructions below.
-
-### What the Order's Administrator Sees
-
-`Shipment` objects are created during checkout for an order. Initially each records just the shipping method and the order it applies to. The administrator can update the record with the actual shipping cost and a tracking code, and may also once only confirm the dispatch. This confirmation causes a shipping date to be set as the time of confirmation.
-
-## Advanced Shipping Methods
-
-Spree comes with a set of calculators that should fit most of the shipping situations that may arise. If the calculators that come with Spree are not enough for your needs, you might want to use an extension - if one exists to meet your needs - or create a custom one.
-
-### Extensions
-
-There are a few Spree extensions which provide additional shipping methods, including special support for fees imposed by common carriers, or support for bulk orders. See the [Spree Extension Registry](https://github.com/spree-contrib) for the latest information.
-
-### Writing Your Own
-
-For more detailed information, check out the section on [Calculators](calculators).
-
-Your calculator should accept an array of `LineItem` objects and return a cost. It can look at any reachable data, but typically uses the address, the order and the information from variants which are contained in the line_items.
-
-## Product Configuration
-
-Store administrators can assign products to specific ShippingCategories or include extra information in variants to enable the calculator to determine results.
-
-Each product has a `ShippingCategory`, which adds product-specific information to the calculations beyond the standard information from the shipment. Standard information includes:
-
-* Destination address
-* Variants and quantities
-* Weight and dimension information, if given, for a variant
-
-`ShippingCategory` is basically a wrapper for a string. One use is to code up specific rates, eg. "Fixed $20" or "Fixed $40", from which a calculator could extract imposed prices and not go through its other calculations.
-
-### Variant Configuration
-
-Variants can be specified with weight and dimension information. Some shipping method calculators will use this information if it is present.
-
-## Filtering Shipping Methods On Criteria Other Than the Zone
-
-Ordinarily, it is the zone of the shipping address that determines which shipping methods are displayed to a customer at checkout. Here is how the availability of a shipping method is determined:
-
-```ruby
-class Spree::Stock::Estimator
- def shipping_methods(package)
- shipping_methods = package.shipping_methods
- shipping_methods.delete_if { |ship_method| !ship_method.calculator.available?(package.contents) }
- shipping_methods.delete_if { |ship_method| !ship_method.include?(order.ship_address) }
- shipping_methods.delete_if { |ship_method| !(ship_method.calculator.preferences[:currency].nil? || ship_method.calculator.preferences[:currency] == currency) }
- shipping_methods
- end
-end
-```
-
-Unless overridden, the calculator's `available?` method returns `true` by default. It is, therefore, the zone of the destination address that filters out the shipping methods in most cases. However, in some circumstances it may be necessary to filter out additional shipping methods.
+Each shipping method uses a [Calculator](/developer/core-concepts/calculators) to determine the cost. Spree includes these built-in calculators:
-Consider the case of the USPS First Class domestic shipping service, which is not offered if the weight of the package is greater than 13oz. Even though the USPS API does not return the option for First Class in this instance, First Class will appear as an option in the checkout view with an unfortunate value of 0, since it has been set as a Shipping Method.
+| Calculator | Description |
+|------------|-------------|
+| Flat rate per order | Same cost regardless of items |
+| Flat rate per item | Fixed cost per item |
+| Flat percent | Percentage of the order total |
+| Flexible rate | One rate for the first item, another for each additional |
+| Price sack | Tiered pricing based on order total |
-To ensure that First Class shipping is not available for orders that weigh more than 13oz, the calculator's `available?` method must be overridden as follows:
-
-```ruby
-class Calculator::Usps::FirstClassMailParcels < Calculator::Usps::Base
- def self.description
- "USPS First-Class Mail Parcel"
- end
-
- def available?(order)
- multiplier = 1.3
- weight = order.line_items.inject(0) do |weight, line_item|
- weight + (line_item.variant.weight ? (line_item.quantity * line_item.variant.weight * multiplier) : 0)
- end
- #if weight in ounces > 13, then First Class Mail is not available for the order
- weight > 13 ? false : true
- end
-end
-```
+You can create custom calculators for more complex pricing. See the [Calculators guide](/developer/core-concepts/calculators).
## Split Shipments
-### Introduction
-
-Split shipments are a feature for more complex Spree applications that require sophisticated shipping and warehouse logic. This includes detailed inventory management and allows for shipping from multiple locations.
-
-### Creating Proposed Shipments
-
-This section steps through the basics of what is involved in determining shipments for an order. There are a lot of pieces that make up this process. They are explained in detail in the [Components of Split Shipments](#components-of-split-shipments) section of this guide.
-
-The process of determining shipments for an order is triggered by calling `create_proposed_shipments` on an `Order` object while transitioning to the `delivery` state during checkout. This process will first delete any existing shipments for an order and then determine the possible shipments available for that order.
-
-`create_proposed_shipments` will initially call `Spree::Stock::Coordinator.new(@order).packages`. This will return an array of packages. In order to determine which items belong in which package when they are being built, Spree uses an object called a `Splitter`, described in more detail [below](#the-packer).
-
-After obtaining the array of available packages, they are converted to shipments on the order object. Shipping rates are determined and inventory units are created during this process as well.
-
-At this point, the checkout process can continue to the delivery step.
-
-## Components of Split Shipments
-
-This section describes the four main components that power split shipments: [The Coordinator](#the-coordinator), [The Packer](#the-packer), [The Prioritizer](#the-prioritizer), and [The Estimator](#the-estimator).
-
-### The Coordinator
-
-The `Spree::Stock::Coordinator` is the starting point for determining shipments when calling `create_proposed_shipments` on an order. Its job is to go through each [Stock Location](/developer/core-concepts/inventory#stock-locations) available and determine what can be shipped from that location.
-
-The `Spree::Stock::Coordinator` will ultimately return an array of packages which can then be easily converted into shipments for an order by calling `to_shipment` on them.
-
-### The Packer
-
-A `Spree::Stock::Packer` object is an important part of the `create_proposed_shipments` process. Its job is to determine possible packages for a given [Stock Location](/developer/core-concepts/inventory#stock-locations) and order. It uses rules defined in classes known as `Splitters` to determine what packages can be shipped from a [Stock Location](/developer/core-concepts/inventory#stock-locations).
-
-For example, we may have two splitters for a stock location. One splitter has a rule that any order weighing more than 50lbs should be shipped in a separate package from items weighing less. Our other splitter is a catch-all for any item weighing less than 50lbs. So, given one item in an order weighing 60lbs and two items weighing less, the Packer would use the rules defined in our splitters to come up with two separate packages: one containing the single 60lb item, the other containing our other two items.
+When items in an order ship from different stock locations or have different shipping categories, Spree automatically splits the order into multiple shipments.
-#### Default Splitters
-
-Spree comes with two default splitters which are run in sequence. This means that the first splitter takes the packages array from the order, and each subsequent splitter takes the output of the splitter that came before it.
-
-Let's take a look at what the default splitters do:
-
-**Shipping Category Splitter**
-
-Splits an order into packages based on items' shipping categories. This means that each package will only have items that all belong to the same shipping category.
-
-**Weight Splitter**
-
-Splits an order into packages based on a weight threshold. This means that each package has a mass weight. If a new item is added to the order and it causes a package to go over the weight threshold, a new package will be created so that all packages weigh less than the threshold. You can set the weight threshold by changing `Spree::Stock::Splitter::Weight.threshold` (defaults to `150`) in an initializer.
-
-#### Custom Splitters
-
-Note that splitters can be customized, and creating your own can be done with relative ease. By inheriting from `Spree::Stock::Splitter::Base`, you can create your own splitter.
-
-For an example of a simple splitter, take a look at Spree's [weight based splitter](https://github.com/spree/spree/blob/235e470b242225d7c75c7c4c4c033ee3d739bb36/core/app/models/spree/stock/splitter/weight.rb). This splitter pulls items with a weight greater than 150 into their own shipment.
-
-After creating your splitter, you need to add it to the array of splitters Spree uses. To do this, add the following to your application's spree initializer `spree.rb` file:
+```mermaid
+flowchart TB
+ A[Order with 3 items] --> B{Stock check}
+ B --> C["Item A & B: NYC Warehouse"]
+ B --> D["Item C: LA Warehouse"]
+ C --> E["Shipment 1: UPS Ground"]
+ D --> F["Shipment 2: FedEx 2Day"]
+```
-<Tabs>
- <Tab title="Spree 5.2+">
- ```ruby config/initializers/spree.rb
- Rails.application.config.after_initialize do
- Spree.stock_splitters << Spree::Stock::Splitter::CustomSplitter
- end
- ```
- </Tab>
- <Tab title="Spree 5.1 and below">
- ```ruby config/initializers/spree.rb
- Rails.application.config.after_initialize do
- Rails.application.config.spree.stock_splitters << Spree::Stock::Splitter::CustomSplitter
- end
- ```
- </Tab>
-</Tabs>
+### How Splitting Works
-You can also completely override the splitters used in Spree, rearrange them, etc. To do this, add the following to your `spree.rb` file:
+1. When an order reaches the delivery step, Spree evaluates where each item is in stock
+2. Items are grouped by stock location and shipping category
+3. Each group becomes a separate shipment with its own shipping rates
+4. The customer selects a shipping rate for each shipment independently
-<Tabs>
- <Tab title="Spree 5.2+">
- ```ruby config/initializers/spree.rb
- Rails.application.config.after_initialize do
- Spree.stock_splitters = [
- Spree::Stock::Splitter::CustomSplitter,
- Spree::Stock::Splitter::ShippingCategory
- ]
- end
- ```
- </Tab>
- <Tab title="Spree 5.1 and below">
- ```ruby config/initializers/spree.rb
- Rails.application.config.after_initialize do
- Rails.application.config.spree.stock_splitters = [
- Spree::Stock::Splitter::CustomSplitter,
- Spree::Stock::Splitter::ShippingCategory
- ]
- end
- ```
- </Tab>
-</Tabs>
+### Weight Splitting
-Or if you don't want to split packages just set the option above to an empty array. e.g. a store with the following configuration in spree.rb won't have any package splitted.
+By default, Spree also splits shipments when a package exceeds a weight threshold (default: 150 units). This prevents individual packages from being too heavy.
-<Tabs>
- <Tab title="Spree 5.2+">
- ```ruby config/initializers/spree.rb
- Rails.application.config.after_initialize do
- Spree.stock_splitters = []
- end
- ```
- </Tab>
- <Tab title="Spree 5.1 and below">
- ```ruby config/initializers/spree.rb
- Rails.application.config.after_initialize do
- Rails.application.config.spree.stock_splitters = []
- end
- ```
- </Tab>
-</Tabs>
+<Info>
+Split shipment behavior is customizable. See the [Customization Quickstart](/developer/customization/quickstart) for details on creating custom splitting rules.
+</Info>
-If you want to add different splitters for each [Stock Location](/developer/core-concepts/inventory#stock-locations), you need to decorate the `Spree::Stock::Coordinator` class and override the `splitters` method.
+## Examples
-### The Prioritizer
+### Simple Setup
-A `Spree::Stock::Prioritizer` object will decide which `StockLocation` should ship which package from an order. The prioritizer will attempt to come up with the best shipping situation available to the user.
+A store selling T-shirts to the US and Europe with 2 carriers:
-By default, the prioritizer will first select packages where the items are on hand. Then it will try to find packages where items are backordered. During this process, the `Spree::Stock::Adjuster` is also used to ensure each package has the correct number of items.
+| Method | Zone | Pricing |
+|--------|------|---------|
+| USPS Ground | US | $5 first item + $2 each additional |
+| FedEx | EU | $10 per item |
-The prioritizer is also a customization point. If you want to customize which packages should take priority for the order during this process, you can override the `sort_packages` method in `Spree::Stock::Prioritizer`.
+This requires:
+- 1 shipping category (default)
+- 1 stock location
+- 2 shipping methods with appropriate zones and calculators
-#### Customizing the Adjuster
-
-The `Adjuster` visits each package in an order and ensures the correct number of items are in each package. To customize this functionality, you need to do two things:
-
-1. Subclass the [Spree::Stock::Adjuster](https://github.com/spree/spree/blob/main/core/app/models/spree/stock/adjuster.rb) class and override the the `adjust` method to get the desired functionality.
-2. Override the `prioritize_packages` method in the `Spree::Stock::Coordinator`, passing in your custom adjuster class to the `Prioritizer` initializer.
-
-<Warning>
- Decorators should be used as a last resort as they can make upgrades difficult. See [Decorators](/developer/customization/decorators) for more information and alternatives.
-</Warning>
-
-For example, if your adjuster was called `Spree::Stock::CustomAdjuster`, you would do the following in `app/models/spree/stock/coordinator_decorator.rb`:
-
-```ruby app/models/spree/stock/coordinator_decorator.rb
-module Spree
- module Stock
- module CoordinatorDecorator
- def prioritize_packages(packages)
- prioritizer = Prioritizer.new(order, packages, Spree::Stock::CustomAdjuster)
- prioritizer.prioritized_packages
- end
- end
-
- Coordinator.prepend(CoordinatorDecorator)
- end
-end
-```
+### Advanced Setup
-### The Estimator
+A store shipping from 2 locations (New York, Los Angeles) with 3 carriers and 3 shipping categories:
-The `Spree::Stock::Estimator` loops through the packages created by the packer in order to calculate and attach shipping rates to them. This information is then returned to the user so they can select shipments for their order and complete the checkout process.
+| Category / Method | DHL | FedEx | USPS |
+|:-|:-|:-|:-|
+| Light | $5/item | $10 flat | $8/item |
+| Regular | $5/item | $2/item | $8/item |
+| Heavy | $50/item | $20 + $15/add'l | $20/item |
## Related Documentation
-- [Orders](/developer/core-concepts/orders) - Order management and state machine
-- [Inventory](/developer/core-concepts/inventory) - Stock locations and inventory management
-- [Calculators](/developer/core-concepts/calculators) - Shipping rate calculators
-- [Addresses](/developer/core-concepts/addresses) - Shipping address and zones
-- [Events](/developer/core-concepts/events) - Subscribe to shipment events
-
+- [Orders](/developer/core-concepts/orders) — Checkout flow and shipping rate selection
+- [Inventory](/developer/core-concepts/inventory) — Stock locations and inventory management
+- [Calculators](/developer/core-concepts/calculators) — Shipping rate calculators
+- [Addresses](/developer/core-concepts/addresses) — Shipping address and zones
+- [Events](/developer/core-concepts/events) — Subscribe to shipment events (e.g., `shipment.shipped`)
diff --git a/docs/developer/core-concepts/slugs.mdx b/docs/developer/core-concepts/slugs.mdx
index 47d86010cb..6c2a29ee37 100644
--- a/docs/developer/core-concepts/slugs.mdx
+++ b/docs/developer/core-concepts/slugs.mdx
@@ -1,850 +1,115 @@
---
title: Slugs
+description: SEO-friendly URL identifiers for products, categories, and other resources
---
## Overview
-Spree uses the [FriendlyId](https://github.com/norman/friendly_id) library to generate SEO-friendly URLs for resources like products, taxons, stores, and more. Instead of accessing resources via database IDs (e.g., `/products/123`), FriendlyId enables clean, readable URLs based on resource names (e.g., `/products/spree-tshirt`).
+Spree generates SEO-friendly URL slugs for resources like products, taxons, and stores. Instead of accessing resources by ID, you can use clean, readable URLs based on resource names.
-Slugs are URL-safe strings derived from resource attributes (typically the `name` field) that:
+Both the Store API and Admin API accept slugs or IDs interchangeably for resource lookups.
-- Improve SEO by including relevant keywords in URLs
-- Enhance user experience with readable, memorable URLs
-- Maintain URL consistency across translations
-- Preserve historical URLs through slug history
+<CodeGroup>
-Slugs are primarily used in:
+```typescript SDK
+// Both work — slug or ID
+const product = await client.store.products.get('spree-tote')
+const product = await client.store.products.get('prod_86Rf07xd4z')
-- **Storefront**: Product pages, category pages (taxons), blog posts, and other customer-facing pages
-- **API**: Both Platform API and Storefront API accept slugs or IDs interchangeably for resource lookups
-
-<Info>
-Spree integrates FriendlyId with [Mobility](https://github.com/shioyama/mobility) for internationalization and [Paranoia](https://github.com/rubysherpas/paranoia) for soft-delete support, making slugs translation-aware and deletion-safe.
-</Info>
-
-## Core Concepts
-
-### Slug Generation
-
-Slugs are automatically generated from resource attributes using the `to_url` method (provided by the [Stringex](https://github.com/rsl/stringex) gem). This method:
-
-- Converts strings to lowercase
-- Replaces spaces and special characters with hyphens
-- Removes invalid URL characters
-- Ensures URL safety
-
-```ruby
-# Example slug generation
-"Spree T-Shirt".to_url # => "spree-t-shirt"
-"Café & Restaurant".to_url # => "cafe-and-restaurant"
-```
-
-### Slug Candidates
-
-When FriendlyId generates a slug, it tries multiple "candidate" patterns to ensure uniqueness. If the first candidate is taken, it tries the next pattern, and so on.
-
-[Spree::Base](https://github.com/spree/spree/blob/main/core/app/models/spree/base.rb) provides a default `slug_candidates` method that all models inherit:
-
-```ruby
-def slug_candidates
- if defined?(deleted_at) && deleted_at.present?
- [
- ['deleted', :name],
- ['deleted', :name, :uuid_for_friendly_id]
- ]
- else
- [
- [:name],
- [:name, :uuid_for_friendly_id]
- ]
- end
-end
-```
-
-For products, the slug candidates are customized to include SKU:
-
-```ruby
-# Product slug candidates (from core/app/models/spree/product/slugs.rb:66-78)
-[
- [:name], # Try product name first
- [:name, :sku], # If taken, append SKU
- [:name, :uuid_for_friendly_id] # If still taken, append UUID
-]
-
-# Example progression:
-# 1st attempt: "spree-tshirt"
-# 2nd attempt: "spree-tshirt-TSHIRT-001" (includes SKU)
-# 3rd attempt: "spree-tshirt-a1b2c3d4-e5f6-..." (includes UUID)
-```
-
-### Reserved Words
-
-FriendlyId prevents using certain reserved words that would conflict with application routes:
-
-```ruby
-# From core/config/initializers/friendly_id.rb
-RESERVED_WORDS = %w(
- new edit index session login logout users admin
- stylesheets assets javascripts images
-)
-```
-
-## Models with Slugs
-
-### Product
-
-Products use the [Spree::Product::Slugs](https://github.com/spree/spree/blob/main/core/app/models/spree/product/slugs.rb) concern which provides comprehensive slug handling with translation support.
-
-```ruby
-include Spree::Product::Slugs
-```
-
-**Configuration:**
-- **Slug column**: `slug`
-- **Slug source**: `name`
-- **Modules**: `:history`, `:slugged`, `:scoped`, `:mobility`
-- **Scope**: `spree_base_uniqueness_scope` (typically `store_id`)
-- **Limit**: 255 characters
-
-**Key features:**
-- Translatable slugs (different slug per locale)
-- Slug history preserved when changed
-- Soft-delete slug renaming with `deleted-` prefix
-- Automatic fallback to SKU or UUID for uniqueness
-
-```ruby
-# Creating a product with a slug
-product = Spree::Product.create!(
- name: 'Spree T-Shirt',
- stores: [store]
-)
-product.slug # => "spree-t-shirt"
-
-# Accessing by slug
-Spree::Product.friendly.find('spree-t-shirt')
-
-# Setting a custom slug
-product.update!(slug: 'custom-rails-shirt')
-
-# Translated slugs
-product.set_friendly_id('t-shirt-spree', :fr)
-product.save!
+// Taxons use permalink slugs
+const taxon = await client.store.taxons.get('categories/clothing')
```
-### Taxon
+```bash cURL
+# By slug
+curl 'https://api.mystore.com/api/v3/store/products/spree-tote' \
+ -H 'Authorization: Bearer spree_pk_xxx'
-Taxons use a custom implementation with hierarchical permalink generation. Unlike products, taxons use `permalink` as their slug column.
-
-```ruby
-# core/app/models/spree/taxon.rb:33
-friendly_id :permalink, slug_column: :permalink, use: :history
+# By ID
+curl 'https://api.mystore.com/api/v3/store/products/prod_86Rf07xd4z' \
+ -H 'Authorization: Bearer spree_pk_xxx'
```
-**Configuration:**
-- **Slug column**: `permalink` (not `slug`)
-- **Modules**: `:history` only
-- **Hierarchical**: Includes parent path
-
-**Key features:**
-- Parent path included in permalink (e.g., `categories/clothing/t-shirts`)
-- Automatically regenerates when parent changes
-- Translation support via custom implementation
-- Helper methods: `slug` and `slug=` alias to `permalink`
-
-```ruby
-# Creating a taxon
-taxonomy = store.taxonomies.first
-root = taxonomy.root
-clothing = root.children.create!(name: 'Clothing', taxonomy: taxonomy)
-tshirts = clothing.children.create!(name: 'T-Shirts', taxonomy: taxonomy)
-
-clothing.permalink # => "clothing"
-tshirts.permalink # => "clothing/t-shirts"
-tshirts.slug # => "clothing/t-shirts" (aliased)
-
-# When parent changes, children update automatically
-clothing.update!(name: 'Apparel')
-tshirts.reload.permalink # => "apparel/t-shirts"
-```
+</CodeGroup>
-### Store
+## Slug Generation
-Stores use `code` as their slug column, and the slug is used for internal routing and multi-store identification.
+Slugs are automatically generated from resource names:
-```ruby
-# core/app/models/spree/store.rb:24
-friendly_id :slug_candidates, use: [:slugged, :history], slug_column: :code
-```
+| Input | Generated Slug |
+|-------|---------------|
+| `Spree T-Shirt` | `spree-t-shirt` |
+| `Café & Restaurant` | `cafe-and-restaurant` |
+| `Summer Collection 2025` | `summer-collection-2025` |
-**Configuration:**
-- **Slug column**: `code` (not `slug`)
-- **Modules**: `:slugged`, `:history`
-- **Reserved codes**: Admin, default, app, api, www, cdn, files, assets, checkout, etc.
-
-**Key features:**
-- Code is parameterized from store name
-- Uniqueness enforced across soft-deleted stores
-- History tracking for code changes
-- Custom validation against reserved words
-
-```ruby
-# Creating a store
-store = Spree::Store.create!(
- name: 'My Awesome Store',
- url: 'mystore.example.com',
- default_currency: 'USD',
- default_country: Spree::Country.find_by(iso: 'US')
-)
-store.code # => "my-awesome-store"
-
-# Code is read-only after creation (doesn't regenerate on name change)
-store.update!(name: 'My Better Store')
-store.code # => "my-awesome-store" (unchanged)
-```
+If a slug already exists, Spree appends the SKU or a unique identifier to ensure uniqueness.
-### Other Models
+## Models with Slugs
-Other Spree models that use FriendlyId:
+| Resource | Slug Column | Translatable | Hierarchical |
+|----------|-------------|:---:|:---:|
+| Product | `slug` | Yes | No |
+| Taxon | `permalink` | Yes | Yes |
+| Store | `code` | No | No |
+| Post | `slug` | Yes | No |
-- **Pages** (`Spree::Page`): Uses `slug` column with history
-- **Posts** (`Spree::Post`): Uses `slug` column with history and translations
-- **Post Categories** (`Spree::PostCategory`): Uses `slug` column with history
-- **Policies** (`Spree::Policy`): Uses `slug` column with history
+### Taxon Permalinks
-## Internationalization
+Taxon slugs include the full parent path, making them hierarchical:
-Spree integrates FriendlyId with Mobility for multi-language slug support using the `friendly_id-mobility` gem.
-
-### Translatable Models
-
-Products, Posts, and Post Categories support translatable slugs:
-
-```ruby
-# Products include TranslatableResourceSlug concern
-include Spree::TranslatableResourceSlug
-
-# Each translation has its own slug
-product = Spree::Product.create!(
- name: 'Red Shoes',
- stores: [store]
-)
-product.slug # => "red-shoes" (default locale)
-
-# Add French translation
-product.translations.create!(
- locale: :fr,
- name: 'Chaussures Rouges',
- slug: nil # Auto-generated from name
-)
-
-# Access localized slugs
-I18n.with_locale(:fr) do
- product.slug # => "chaussures-rouges"
-end
-
-# Or use the helper method
-product.localized_slugs_for_store(store)
-# => {
-# "en" => "red-shoes",
-# "fr" => "chaussures-rouges"
-# }
```
-
-### Translation Slug Generation
-
-When creating translations, slugs are automatically generated with this priority:
-
-1. **Custom slug** - If provided, it's normalized (e.g., `'Custom Slug!'` → `'custom-slug'`)
-2. **Translated name** - Generated from the translation's name field
-3. **Fallback to default** - Uses default locale's name if translation name is blank
-
-```ruby
-# Example from core/app/models/spree/product/slugs.rb:29-36
-def generate_slug
- if name.blank? && slug.blank?
- translated_model.name.to_url # Use default locale name
- elsif slug.blank?
- name.to_url # Use translation name
- else
- slug.to_url # Use custom slug
- end
-end
+categories → "categories"
+categories/clothing → "categories/clothing"
+categories/clothing/t-shirts → "categories/clothing/t-shirts"
```
-### Translation Uniqueness
-
-Slugs must be unique within the same locale but can be duplicated across locales:
-
-```ruby
-# Same slug in different locales - OK
-product1.translations.create!(locale: :fr, slug: 'tshirt')
-product2.translations.create!(locale: :es, slug: 'tshirt') # ✅ Allowed
-
-# Duplicate slug in same locale - Auto-fixed with UUID
-product1.translations.create!(locale: :fr, slug: 'tshirt')
-product2.translations.create!(locale: :fr, slug: 'tshirt') # ❌ "tshirt-<uuid>"
-```
+When a parent taxon is renamed, all child permalinks update automatically.
## Slug History
-FriendlyId's history feature preserves old slugs when they change, ensuring existing URLs continue to work. This is critical for:
-
-- SEO (avoiding broken links)
-- Bookmarks and external references
-- Graceful URL migration
-
-```ruby
-product = Spree::Product.create!(name: 'Original Name', stores: [store])
-product.slug # => "original-name"
-
-# Change the name (generates new slug)
-product.update!(name: 'New Name', slug: nil)
-product.slug # => "new-name"
-
-# Old slug still works (redirects to new slug)
-Spree::Product.friendly.find('original-name') # => Still finds the product
-
-# View slug history
-product.slugs.pluck(:slug)
-# => ["original-name", "new-name"]
-```
-
-### Slug History Table
-
-FriendlyId maintains a separate `friendly_id_slugs` table:
-
-```ruby
-# Schema
-create_table :friendly_id_slugs do |t|
- t.string :slug, null: false
- t.integer :sluggable_id, null: false
- t.string :sluggable_type, limit: 50
- t.string :scope
- t.string :locale # Added by Spree for multi-language
- t.datetime :created_at
- t.datetime :deleted_at # Added by Spree for soft-delete
-end
-```
-
-## Soft Deletes and Slugs
-
-Spree extends FriendlyId to work with soft-deleted records (using Paranoia gem). When a resource is deleted:
-
-1. The record is marked as deleted (`deleted_at` timestamp)
-2. The slug is prefixed with `deleted-` and a UUID
-3. Slug history records are also soft-deleted
-4. Original slug becomes available for new records
-
-```ruby
-product = Spree::Product.create!(name: 'Test Product', stores: [store])
-product.slug # => "test-product"
-
-# Soft delete the product
-product.destroy!
-
-# Slug is renamed with deleted prefix
-product.slug # => "deleted-test-product-a1b2c3d4-..."
-
-# Original slug is now available
-new_product = Spree::Product.create!(name: 'Test Product', stores: [store])
-new_product.slug # => "test-product" ✅
-```
-
-### Restoration
-
-When restoring a soft-deleted record, the slug is regenerated:
-
-```ruby
-product.restore(recursive: true)
-product.slug # => "test-product" (original slug restored if available)
-```
-
-### Implementation
-
-```ruby
-# From core/app/models/spree/product/slugs.rb:93-107
-def punch_slugs
- return if new_record? || frozen?
-
- self.slug = nil
- set_slug
- update_column(:slug, slug)
-
- new_slug = ->(rec) { "deleted-#{rec.slug}-#{uuid_for_friendly_id}"[..254] }
-
- # Update both translations and slug history
- translations.with_deleted.each { |rec| rec.update_columns(slug: new_slug.call(rec)) }
- slugs.with_deleted.each { |rec| rec.update_column(:slug, new_slug.call(rec)) }
-end
-```
-
-## Working with Slugs
-
-### Finding by Slug
-
-Use the `friendly` scope to find records by slug:
-
-```ruby
-# Find by slug
-product = Spree::Product.friendly.find('spree-tshirt')
-
-# Find by ID still works
-product = Spree::Product.friendly.find(123)
-
-# Find by historical slug (auto-redirects)
-product = Spree::Product.friendly.find('old-slug-name')
-```
-
-### Setting Custom Slugs
-
-You can override auto-generated slugs:
-
-```ruby
-# Auto-generated slug
-product = Spree::Product.create!(
- name: 'Spree T-Shirt',
- stores: [store]
-)
-product.slug # => "spree-t-shirt"
-
-# Custom slug
-product.update!(slug: 'rails-tshirt')
-product.slug # => "rails-tshirt"
-
-# Reset to auto-generate (set to nil)
-product.update!(slug: nil)
-product.slug # => "spree-t-shirt" (regenerated from name)
-```
-
-### Slug Normalization
-
-Slugs are automatically normalized on validation:
-
-```ruby
-product = Spree::Product.new(
- name: 'Test',
- slug: 'Hey//Joe', # Invalid format
- stores: [store]
-)
-product.valid?
-product.slug # => "hey-joe" (normalized)
-```
-
-### Checking Slug Availability
-
-```ruby
-# Check if a slug is available
-Spree::Product.slug_available?('my-slug', product.id) # => true/false
-
-# Ensure slug uniqueness manually
-def ensure_unique_slug(candidate)
- return candidate if Spree::Product.slug_available?(candidate, id)
-
- "#{candidate}-#{SecureRandom.uuid}"
-end
-```
-
-### Localized Slug Retrieval
+When a slug changes (e.g., a product is renamed), Spree preserves the old slug. Requests using old slugs still find the resource, enabling:
-For multi-store, multi-language applications:
+- **SEO continuity** — no broken links when names change
+- **Bookmark compatibility** — saved URLs keep working
+- **Graceful URL migration** — old links resolve automatically
-```ruby
-# Get all localized slugs for a store
-product.localized_slugs_for_store(store)
-# => {
-# "en" => "ruby-tshirt",
-# "fr" => "tshirt-ruby",
-# "es" => "camiseta-ruby"
-# }
-```
-
-## Adding Slugs to Custom Models
-
-To add FriendlyId slugs to your custom models, inherit from `Spree::Base` which provides the base slug functionality.
-
-### Basic Implementation
-
-```ruby
-# app/models/spree/brand.rb
-module Spree
- class Brand < Spree::Base
- extend FriendlyId
- friendly_id :slug_candidates, use: [:slugged, :history]
-
- validates :name, presence: true
- validates :slug, presence: true, uniqueness: true
-
- # slug_candidates is already defined in Spree::Base
- # No need to override unless you need custom behavior
- end
-end
-```
-
-<Info>
-Models inheriting from `Spree::Base` automatically get the `slug_candidates` and `uuid_for_friendly_id` methods. You only need to override `slug_candidates` if you need custom slug generation logic (like Product does with SKU).
-</Info>
-
-### With Translation Support
-
-```ruby
-# app/models/spree/brand.rb
-module Spree
- class Brand < Spree::Base
- extend FriendlyId
- include Spree::TranslatableResource
- include Spree::TranslatableResourceSlug
-
- translates :name, :slug
- friendly_id :slug_candidates,
- use: [:history, :slugged, :scoped, :mobility],
- scope: spree_base_uniqueness_scope
-
- validates :name, presence: true
- validates :slug, presence: true,
- uniqueness: { scope: spree_base_uniqueness_scope }
-
- # Inherited slug_candidates from Spree::Base work for most cases
- # Override only if needed for custom logic
- end
-end
-```
-
-### With Soft Deletes
-
-```ruby
-# app/models/spree/brand.rb
-module Spree
- class Brand < Spree::Base
- extend FriendlyId
- acts_as_paranoid
-
- friendly_id :slug_candidates, use: [:slugged, :history]
-
- validates :name, presence: true
- validates :slug, presence: true, uniqueness: { conditions: -> { with_deleted } }
-
- after_destroy :rename_slug_on_delete
- after_restore :regenerate_slug_on_restore
-
- private
-
- def rename_slug_on_delete
- return if new_record?
-
- new_slug = "deleted-#{slug}-#{uuid_for_friendly_id}"[..254]
- update_column(:slug, new_slug)
- end
-
- def regenerate_slug_on_restore
- self.slug = nil
- save!
- end
-
- # slug_candidates inherited from Spree::Base handles deleted records
- end
-end
-```
-
-## Routing
-
-Spree uses `:id` as the route parameter for all resources, but the `.friendly` finder allows both IDs and slugs to work interchangeably.
-
-### Default Spree Routes
-
-```ruby
-# Spree's default routes use :id parameter
-# GET /products/:id -> handles both numeric IDs and slugs
-
-# Both of these URLs work:
-# /products/123 (finds by ID)
-# /products/ruby-tshirt (finds by slug)
-```
-
-### Custom Resources with Slugs
-
-```ruby
-# config/routes.rb
-Spree::Core::Engine.routes.draw do
- resources :brands, only: [:show]
-end
-```
-
-<Warning>
-Always use `:id` as the route parameter, not `:slug`. This allows FriendlyId's `.friendly` finder to accept both numeric IDs and slugs, maintaining backward compatibility.
-</Warning>
-
-### Controller Implementation
-
-```ruby
-# app/controllers/spree/brands_controller.rb
-module Spree
- class BrandsController < Spree::StoreController
- def show
- # Use .friendly to find by both ID and slug
- @brand = Spree::Brand.friendly.find(params[:id])
-
- # Optional: Redirect if using old ID or non-canonical slug
- redirect_if_legacy_path
- end
-
- private
-
- def redirect_if_legacy_path
- # If an old id or a numeric id was used to find the record,
- # do a 301 redirect that uses the current friendly id.
- if params[:id] != @brand.friendly_id
- redirect_to brand_path(@brand), status: :moved_permanently
- end
- end
- end
-end
-```
-
-### Storefront Examples
-
-```ruby
-# From storefront/app/controllers/spree/products_controller.rb:43-45
-def load_product
- @product ||= find_with_fallback_default_locale do
- current_store.products.friendly.find(params[:id])
- end
-end
-
-# From storefront/app/controllers/spree/taxons_controller.rb:22-24
-def load_taxon
- @taxon ||= find_with_fallback_default_locale do
- current_store.taxons.friendly.find(params[:id])
- end
-end
-```
-
-`find_with_fallback_default_locale` is a helper method that is used to find a resource in the current locale or the default store locale.
-
-### API Routes
-
-Both Storefront API and Platform API accept slugs or IDs:
-
-```ruby
-# From api/app/controllers/spree/api/v2/storefront/products_controller.rb:20
-@resource ||= find_with_fallback_default_locale do
- scope.includes(variants: variant_includes, master: variant_includes)
- .friendly.find(params[:id])
-end
-
-# API Examples:
-# GET /api/v2/storefront/products/123
-# GET /api/v2/storefront/products/spree-tshirt
-```
-
-## Best Practices
-
-### 1. Always Use the `friendly` Scope
-
-```ruby
-# ✅ Good - handles both slugs and IDs
-product = Spree::Product.friendly.find(params[:id])
-
-# ❌ Bad - only works with IDs
-product = Spree::Product.find(params[:id])
-```
-
-### 2. Set Slugs to `nil` to Regenerate
-
-```ruby
-# ✅ Good - regenerates slug from name
-product.update!(slug: nil)
-
-# ❌ Bad - keeps old slug even if name changed
-product.update!(name: 'New Name') # slug unchanged
-```
-
-### 3. Validate Slug Uniqueness with Scope
-
-```ruby
-# Always use the appropriate scope
-validates :slug,
- presence: true,
- uniqueness: {
- scope: spree_base_uniqueness_scope, # eg [:tenant_id]
- case_sensitive: true
- }
-```
-
-### 4. Eager Load Slugs When Needed
-
-```ruby
-# ✅ Good - includes slug history
-products = Spree::Product.includes(:slugs)
-
-# For routing, slug history isn't needed
-products = Spree::Product.all # Just uses slug column
-```
-
-### 5. Preserve Slug History
-
-```ruby
-# ✅ Good - maintains URL consistency
-product.update!(name: 'New Name', slug: nil) # Old slug still works
-
-# ❌ Bad - breaks existing URLs
-product.update!(slug: 'completely-different') # Old slug breaks
-```
-
-### 6. Handle Locale-Specific Slugs
-
-```ruby
-# ✅ Good - provide translations
-product.translations.create!(
- locale: :fr,
- name: 'Nom Français',
- slug: nil # Auto-generates
-)
-
-# ❌ Bad - reusing English slug
-product.translations.create!(
- locale: :fr,
- name: 'Nom Français',
- slug: product.slug # Not SEO-friendly for French
-)
-```
-
-### 7. Use Route Helpers with :id Parameter
-
-```ruby
-# ✅ Good - uses Spree routes with :id parameter
-spree.product_path(product) # Works with both slug and ID
-# Generates: /products/ruby-tshirt (uses slug automatically)
-
-# ✅ Good - explicit slug
-spree.product_path(product.slug)
-# Generates: /products/ruby-tshirt
-
-# ✅ Good - explicit ID
-spree.product_path(product.id)
-# Generates: /products/123
-
-# ❌ Bad - manual URL construction
-"/products/#{product.slug}" # Doesn't handle edge cases
-
-# ❌ Bad - using :slug as route parameter
-resources :products, param: :slug # Don't do this - breaks ID lookup
-```
-
-### 8. Test Slug Behavior
-
-```ruby
-# Example spec
-RSpec.describe Spree::Brand, type: :model do
- describe 'slugs' do
- it 'generates slug from name' do
- brand = create(:brand, name: 'Test Name')
- expect(brand.slug).to eq('test-name')
- end
-
- it 'ensures slug uniqueness' do
- create(:brand, name: 'Test')
- duplicate = create(:brand, name: 'Test')
- expect(duplicate.slug).to match(/test-.+/)
- end
-
- it 'preserves old slugs in history' do
- brand = create(:brand, name: 'Original')
- brand.update!(name: 'Changed', slug: nil)
-
- expect(brand.slug).to eq('changed')
- expect(brand.slugs.pluck(:slug)).to include('original')
- end
- end
-end
-```
-
-## Troubleshooting
-
-### Slug Not Updating When Name Changes
-
-**Problem**: Changing a product's name doesn't update the slug.
-
-**Solution**: Explicitly set slug to `nil` to trigger regeneration:
-
-```ruby
-product.update!(name: 'New Name', slug: nil)
-```
+## Internationalization
-### Duplicate Slug Errors
+Products, taxons, and posts support localized slugs — a different slug per locale:
-**Problem**: Getting uniqueness validation errors on slug.
+<CodeGroup>
-**Solution**: Check if you're properly scoping uniqueness:
+```typescript SDK
+// English
+const product = await client.store.products.get('red-shoes')
-```ruby
-# Ensure correct scope in validation
-validates :slug,
- uniqueness: {
- scope: spree_base_uniqueness_scope,
- case_sensitive: true
- }
+// French (with locale header)
+const product = await client.store.products.get('chaussures-rouges', {
+ locale: 'fr',
+})
```
-### Slugs Not Working After Restore
+```bash cURL
+# English
+curl 'https://api.mystore.com/api/v3/store/products/red-shoes' \
+ -H 'Authorization: Bearer spree_pk_xxx'
-**Problem**: Restored products have `deleted-` prefix in slug.
-
-**Solution**: Ensure you have the `after_restore` callback:
-
-```ruby
-after_restore :regenerate_slug
-
-def regenerate_slug
- self.slug = nil
- save!
-end
+# French
+curl 'https://api.mystore.com/api/v3/store/products/chaussures-rouges' \
+ -H 'Authorization: Bearer spree_pk_xxx' \
+ -H 'X-Spree-Locale: fr'
```
-### Translation Slugs Not Generated
+</CodeGroup>
-**Problem**: Translation slugs are blank or invalid.
+Slugs are unique within the same locale but can be duplicated across different locales.
-**Solution**: Ensure you're setting slugs correctly in Translation model:
+## Reserved Words
-```ruby
-# In your Translation class
-before_validation :set_slug
+Spree prevents certain words from being used as slugs to avoid route conflicts: `new`, `edit`, `index`, `login`, `logout`, `admin`, and others.
-def set_slug
- self.slug = generate_slug
-end
-
-def generate_slug
- if name.blank? && slug.blank?
- translated_model.name.to_url
- elsif slug.blank?
- name.to_url
- else
- slug.to_url
- end
-end
-```
+## Related Documentation
-## Reference
-
-### Key Files
-
-- `core/app/models/spree/product/slugs.rb` - Product slug implementation
-- `core/app/models/spree/taxon.rb` - Taxon permalink implementation (lines 33, 230-365)
-- `core/app/models/spree/store.rb` - Store code implementation (lines 24, 543-568)
-- `core/app/models/concerns/spree/translatable_resource_slug.rb` - Translation helper
-- `core/config/initializers/friendly_id.rb` - Global FriendlyId config
-- `core/lib/friendly_id/paranoia.rb` - Paranoia integration
-
-### Useful Methods
-
-| Method | Description |
-|--------|-------------|
-| `Model.friendly.find(slug)` | Find by slug or ID |
-| `resource.slug` | Get current slug |
-| `resource.slug = 'custom'` | Set custom slug |
-| `resource.slugs` | Access slug history |
-| `resource.localized_slugs_for_store(store)` | Get all locale slugs |
-| `Model.slug_available?(slug, id)` | Check slug availability |
-| `resource.friendly_id` | Current friendly ID |
-| `resource.set_friendly_id(slug, locale)` | Set slug for locale |
+- [Products](/developer/core-concepts/products) — Product catalog
+- [Translations](/developer/core-concepts/translations) — Multi-language content
+- [Querying](/api-reference/store-api/querying) — API resource lookup
diff --git a/docs/developer/core-concepts/staff-roles.mdx b/docs/developer/core-concepts/staff-roles.mdx
new file mode 100644
index 0000000000..34ea12d35f
--- /dev/null
+++ b/docs/developer/core-concepts/staff-roles.mdx
@@ -0,0 +1,125 @@
+---
+title: Staff & Roles
+description: Admin users, roles, invitations, and permissions
+---
+
+## Overview
+
+Admin users manage the store via the Admin Panel. They have roles that control what they can access.
+
+```mermaid
+erDiagram
+ AdminUser ||--o{ RoleUser : "has many"
+ RoleUser }o--|| Role : "belongs to"
+ RoleUser }o--|| Store : "scoped to"
+ AdminUser ||--o{ Invitation : "invites"
+
+ AdminUser {
+ string id
+ string email
+ }
+
+ RoleUser {
+ string role_id
+ string resource_type
+ string resource_id
+ }
+
+ Role {
+ string name
+ }
+
+ Invitation {
+ string email
+ string status
+ string token
+ datetime expires_at
+ }
+```
+
+## Roles
+
+Admin users can have different roles that control their permissions:
+
+| Role | Description |
+|------|-------------|
+| `admin` | Full access to all Admin Panel features |
+
+<Info>
+You can create custom roles with specific permissions. See the [Customize Permissions guide](/developer/customization/permissions) for details.
+</Info>
+
+## Creating Admin Users
+
+Use the Spree CLI to create admin users:
+
+```bash
+spree user create
+```
+
+The CLI will prompt you for the email and password. You can also pass them directly:
+
+```bash
+spree user create --email [email protected] --password secret123
+```
+
+The created user gets the `admin` role on the default store.
+
+## Inviting Admin Users
+
+You can invite new admins through the Admin Panel or programmatically.
+
+**Via Admin Panel:**
+
+1. Navigate to **Settings → Users**
+2. Click **Invite User**
+3. Enter the email address and select a role
+4. Click **Send Invitation**
+
+The invitee receives an email with an invitation link. If they already have an account, they log in to accept. Otherwise, they create an account first.
+
+```mermaid
+flowchart TB
+ A[Admin creates invitation] --> B[Invitation email sent]
+ B --> C[Invitee clicks link]
+ C --> D{Has account?}
+ D -->|Yes| E[Log in]
+ D -->|No| F[Create account]
+ E --> G[Accept invitation]
+ F --> G
+ G --> H[Role assigned to store]
+```
+
+### Invitation Details
+
+| Attribute | Description |
+|-----------|-------------|
+| `email` | Invitee's email address |
+| `token` | Secure token for the invitation link |
+| `status` | `pending` or `accepted` |
+| `expires_at` | Expiration date (default: 2 weeks) |
+| `resource` | The store being granted access to |
+| `role` | The role to assign upon acceptance |
+
+### Invitation Events
+
+The invitation system publishes [events](/developer/core-concepts/events) you can subscribe to:
+
+| Event | Description |
+|-------|-------------|
+| `invitation.created` | Invitation was created (triggers email) |
+| `invitation.accepted` | Invitation was accepted and role assigned |
+| `invitation.resent` | Invitation was resent to the invitee |
+
+## Permissions
+
+Spree uses [CanCanCan](https://github.com/CanCanCommunity/cancancan) for authorization. Permissions apply to both customers (Store API access) and admins (Admin Panel access).
+
+See the [Customize Permissions guide](/developer/customization/permissions) for details on creating custom roles and permission sets.
+
+## Related Documentation
+
+- [Customers](/developer/core-concepts/customers) — Customer accounts and authentication
+- [Stores](/developer/core-concepts/stores) — Multi-store setup
+- [Permissions](/developer/customization/permissions) — Roles and authorization
+- [Events](/developer/core-concepts/events) — Subscribe to invitation events
diff --git a/docs/developer/core-concepts/store-credits-gift-cards.mdx b/docs/developer/core-concepts/store-credits-gift-cards.mdx
index d053402d57..2a7038f4d2 100644
--- a/docs/developer/core-concepts/store-credits-gift-cards.mdx
+++ b/docs/developer/core-concepts/store-credits-gift-cards.mdx
@@ -1,5 +1,6 @@
---
title: Store Credits & Gift Cards
+description: Stored value mechanisms for refunds, loyalty rewards, and gifting
---
## Overview
@@ -32,49 +33,34 @@ Store Credits are monetary values assigned directly to a customer's account. The
```mermaid
erDiagram
- spree_store_credits ||--o{ spree_store_credit_events : "has many"
- spree_store_credits ||--o{ spree_payments : "source for"
- spree_store_credits }o--|| spree_users : "belongs to"
- spree_store_credits }o--|| spree_stores : "belongs to"
- spree_store_credits }o--o| spree_store_credit_categories : "belongs to"
- spree_store_credits }o--o| spree_store_credit_types : "belongs to"
- spree_store_credits }o--o| spree_admin_users : "created by"
-
- spree_store_credits {
- bigint id PK
- bigint user_id FK
- bigint store_id FK
- bigint category_id FK
- bigint type_id FK
- bigint created_by_id FK
+ StoreCredit ||--o{ StoreCreditEvent : "has many"
+ StoreCredit ||--o{ Payment : "source for"
+ StoreCredit }o--|| User : "belongs to"
+ StoreCredit }o--|| Store : "belongs to"
+ StoreCredit }o--o| StoreCreditCategory : "belongs to"
+ StoreCredit }o--o| StoreCreditType : "belongs to"
+
+ StoreCredit {
decimal amount
decimal amount_used
decimal amount_authorized
string currency
string memo
- datetime deleted_at
}
- spree_store_credit_categories {
- bigint id PK
+ StoreCreditCategory {
string name
}
- spree_store_credit_types {
- bigint id PK
+ StoreCreditType {
string name
integer priority
}
- spree_store_credit_events {
- bigint id PK
- bigint store_credit_id FK
+ StoreCreditEvent {
string action
decimal amount
string authorization_code
- decimal user_total_amount
- bigint originator_id
- string originator_type
}
```
@@ -124,7 +110,7 @@ Every action on a store credit is recorded as an event for audit purposes:
### Assigning Store Credits
-#### Via Admin Panel
+Store credits are managed in the Admin Panel:
1. Navigate to **Customers** in the Admin Panel
2. Select a customer
@@ -133,41 +119,7 @@ Every action on a store credit is recorded as an event for audit purposes:
5. Enter the amount, category, and optional memo
6. Click **Create**
-#### Via Code
-
-```ruby
-customer = Spree.user_class.find_by(email: "[email protected]")
-store = Spree::Store.default
-admin = Spree.admin_user_class.first
-
-store_credit = Spree::StoreCredit.create!(
- user: customer,
- store: store,
- amount: 50.00,
- currency: store.default_currency,
- category: Spree::StoreCreditCategory.first,
- created_by: admin,
- memo: "Loyalty reward"
-)
-```
-
-### Store Credit Methods
-
-```ruby
-store_credit = customer.store_credits.first
-
-# Check remaining balance
-store_credit.amount_remaining
-# => 75.00
-
-# Check if editable (no amount used or authorized)
-store_credit.editable?
-# => true
-
-# Get total available store credit for a customer
-customer.total_available_store_credit
-# => 75.00
-```
+Store credits can also be created via the Admin API.
### Store Credit Events
@@ -186,18 +138,12 @@ Gift Cards are stored value codes created by admins that can be shared and redee
```mermaid
erDiagram
- spree_gift_cards }o--|| spree_stores : "belongs to"
- spree_gift_cards }o--o| spree_users : "belongs to"
- spree_gift_cards }o--o| spree_admin_users : "created by"
- spree_gift_cards }o--o| spree_gift_card_batches : "belongs to"
- spree_gift_cards ||--o{ spree_store_credits : "originator for"
-
- spree_gift_cards {
- bigint id PK
- bigint store_id FK
- bigint user_id FK
- bigint created_by_id FK
- bigint gift_card_batch_id FK
+ GiftCard }o--|| Store : "belongs to"
+ GiftCard }o--o| User : "belongs to"
+ GiftCard }o--o| GiftCardBatch : "belongs to"
+ GiftCard ||--o{ StoreCredit : "originator for"
+
+ GiftCard {
string code
string state
decimal amount
@@ -208,10 +154,7 @@ erDiagram
datetime redeemed_at
}
- spree_gift_card_batches {
- bigint id PK
- bigint store_id FK
- bigint created_by_id FK
+ GiftCardBatch {
string prefix
integer codes_count
decimal amount
@@ -268,7 +211,7 @@ flowchart TB
### Creating Gift Cards
-#### Single Gift Card via Admin Panel
+#### Single Gift Card
1. Navigate to **Gift Cards** in the Admin Panel
2. Click **Create Gift Card**
@@ -276,29 +219,12 @@ flowchart TB
4. Click **Create**
5. Share the generated code with the recipient
-#### Single Gift Card via Code
-
-```ruby
-store = Spree::Store.default
-admin = Spree.admin_user_class.first
-
-gift_card = Spree::GiftCard.create!(
- store: store,
- amount: 50.00,
- created_by: admin,
- expires_at: 1.year.from_now
-)
-
-gift_card.code
-# => "a1b2c3d4e5f6"
-```
+Gift cards can also be created via the Admin API.
-### Batch Gift Card Generation
+#### Batch Gift Card Generation
For promotions or bulk distribution, you can create multiple gift cards at once using Gift Card Batches:
-#### Via Admin Panel
-
1. Navigate to **Gift Cards** in the Admin Panel
2. Click **Create Batch**
3. Enter:
@@ -308,31 +234,8 @@ For promotions or bulk distribution, you can create multiple gift cards at once
- **Expiration** - Optional expiration date
4. Click **Create**
-#### Via Code
-
-```ruby
-store = Spree::Store.default
-admin = Spree.admin_user_class.first
-
-batch = Spree::GiftCardBatch.create!(
- store: store,
- prefix: "PROMO",
- codes_count: 100,
- amount: 25.00,
- created_by: admin,
- expires_at: 6.months.from_now
-)
-
-# Gift cards are generated automatically
-batch.gift_cards.count
-# => 100
-
-batch.gift_cards.first.code
-# => "promoa1b2c3"
-```
-
<Info>
-Large batches are processed in the background via `Spree::GiftCards::BulkGenerateJob` to avoid timeout issues.
+Large batches are processed in the background to avoid timeout issues.
</Info>
### Redeeming Gift Cards
@@ -348,27 +251,27 @@ When a gift card is applied to an order:
- The gift card is marked as redeemed (or partially redeemed)
- No Store Credit is created for guest checkouts
-#### Via Storefront API
-
-```bash
-# Apply gift card to current order (works for guests and registered customers)
-POST /api/v2/storefront/cart/apply_gift_card
-{
- "gift_card_code": "abc1234def"
-}
-```
+Gift cards are applied using the same coupon codes endpoint as promotion codes. The endpoint automatically detects whether the code is a promotion coupon or a gift card.
-#### Via Code
+<CodeGroup>
-```ruby
-gift_card = Spree::GiftCard.find_by(code: "abc1234def")
-order = Spree::Order.find_by(number: "R123456")
+```typescript SDK
+// Apply gift card code to order (works for guests and registered customers)
+const order = await client.store.orders.couponCodes.apply('or_abc123', 'abc1234def', {
+ bearerToken: '<token>',
+})
+```
-# Apply gift card to order
-order.gift_card = gift_card
-order.save!
+```bash cURL
+# Apply gift card to order (works for guests and registered customers)
+curl -X POST 'https://api.mystore.com/api/v3/store/orders/or_abc123/coupon_codes' \
+ -H 'Authorization: Bearer spree_pk_xxx' \
+ -H 'Content-Type: application/json' \
+ -d '{ "coupon_code": "abc1234def" }'
```
+</CodeGroup>
+
### Gift Card Events
The gift card system publishes lifecycle events:
@@ -417,7 +320,7 @@ When a registered customer has multiple store credits, they are applied in order
## Related Documentation
-- [Payments](/developer/core-concepts/payments) - Payment processing and methods
-- [Orders](/developer/core-concepts/orders) - Order management
-- [Users](/developer/core-concepts/users) - Customer management
-- [Events](/developer/core-concepts/events) - Event system and subscribers
+- [Payments](/developer/core-concepts/payments) — Payment processing and methods
+- [Orders](/developer/core-concepts/orders) — Order management
+- [Customers](/developer/core-concepts/customers) — Customer management
+- [Events](/developer/core-concepts/events) — Event system and subscribers
diff --git a/docs/developer/core-concepts/stores.mdx b/docs/developer/core-concepts/stores.mdx
index d7cc66fdba..0e5af2150a 100644
--- a/docs/developer/core-concepts/stores.mdx
+++ b/docs/developer/core-concepts/stores.mdx
@@ -1,103 +1,89 @@
---
title: Stores
+description: The central model in Spree — every resource is scoped to a store
---
## Overview
-The `Spree::Store` model is the center of the Spree ecosystem.
-
-### Store Model Diagram
+The Store is the central model in Spree. Every resource — products, orders, markets, payment methods, taxonomies — is scoped to a store. Most setups use a single store, but Spree supports [multi-store](/developer/multi-store/quickstart) configurations where each store operates independently with its own catalog, branding, and checkout.
```mermaid
erDiagram
+ Store ||--o{ Market : "has many"
+ Store ||--o{ Order : "has many"
+ Store }o--o{ Product : "has many"
+ Store }o--o{ PaymentMethod : "has many"
+ Store }o--o{ ShippingMethod : "has many"
+ Store ||--o{ Taxonomy : "has many"
+ Store ||--o{ StockLocation : "has many"
+
Store {
string name
string code
string url
boolean default
- string mail_from_address
string customer_support_email
}
- Order {
- string number
+ Market {
+ string name
string currency
- string state
- decimal total
+ string default_locale
}
Product {
string name
string status
- datetime available_on
- }
-
- PaymentMethod {
- string name
- string type
- boolean active
- string display_on
- }
-
- ShippingMethod {
- string name
- string display_on
}
- Taxonomy {
- string name
- integer position
+ Order {
+ string number
+ string state
}
+```
- Market {
- string name
- string currency
- string default_locale
- boolean default
- }
+## Store Attributes
+
+| Attribute | Description |
+|-----------|-------------|
+| `name` | Store name, displayed in the browser title and throughout the site |
+| `code` | Unique identifier for the store |
+| `url` | Primary URL of the store |
+| `meta_description` | SEO description |
+| `meta_keywords` | SEO keywords |
+| `seo_title` | Custom SEO title |
+| `customer_support_email` | Email for customer support inquiries |
+| `mail_from_address` | Sender address for transactional emails |
+| `favicon_image_url` | URL to the store's favicon |
+| `logo_image_url` | URL to the store's logo |
+| `social_image_url` | URL to the store's social sharing image |
+| `facebook`, `twitter`, `instagram` | Social media links |
+| `payment_methods` | Payment methods available in this store |
+
+## Fetching Store Information
+
+Use the store endpoint to get the current store's configuration — useful for rendering logos, SEO metadata, and footer content:
+
+<CodeGroup>
+
+```typescript SDK
+const store = await client.store.store.get()
+// {
+// name: "My Store",
+// url: "https://mystore.com",
+// logo_image_url: "https://cdn.mystore.com/logo.png",
+// customer_support_email: "[email protected]",
+// payment_methods: [{ id: "pm_xxx", name: "Stripe", kind: "card" }],
+// ...
+// }
+```
- Store ||--o{ Market : "has many"
- Store ||--o{ Order : "has many"
- Store }o--o{ Product : "has many"
- Store }o--o{ PaymentMethod : "has many"
- Store }o--o{ ShippingMethod : "has many"
- Store ||--o{ StockLocation : "has many"
- Store ||--o{ Taxonomy : "has many"
- Store ||--o{ Menu : "has many"
- Store ||--o{ CmsPage : "has many"
- Store ||--o{ WebhookEndpoint : "has many"
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/store' \
+ -H 'Authorization: Bearer spree_pk_xxx'
```
-**Key relationships:**
-- **Store** is the central model - all commerce data is scoped to a store
-- Each store has one or more [Markets](/developer/core-concepts/markets) that define geographic selling regions with their own currency and locale
-- Each store has its own [Orders](/developer/core-concepts/orders), [Products](/developer/core-concepts/products), [Payment Methods](/developer/core-concepts/payments), and [Shipping Methods](/developer/core-concepts/shipments)
-- Stores can have different currencies, locales, and configurations
-- Content (Menus, CMS Pages) and [Webhooks](/developer/core-concepts/webhooks) are also store-specific
-
-### Store attributes
-
-| Attribute | Description | Example Value |
-|--------------------------|-----------------------------------------------------------------------------|---------------|
-| `name` | The name of the store, typically displayed in the browser title bar and throughout the site. | Spree Demo Site |
-| `code` | A unique code to identify the store. | `spree-001` |
-| `meta_description` | A brief description of the store for SEO purposes. | An exclusive selection of high-quality products. |
-| `meta_keywords` | Relevant keywords associated with the store for SEO. | fashion, electronics, books |
-| `seo_title` | A custom SEO title for the store. | Shop the Best Deals Online - Spree Store |
-| `mail_from_address` | The email address used for sending emails from the store. | [email protected] |
-| `default` | Indicates if the store is the default store. | `true` |
-| `customer_support_email` | The email address for customer support inquiries. | [email protected] |
-| `facebook` | The store's Facebook page URL. | spree |
-| `twitter` | The store's Twitter handle. | @spreecommerce |
-| `instagram` | The store's Instagram profile URL. | https://www.instagram.com/spree |
-| `description` | A detailed description of the store. | Your one-stop shop for everything you need. |
-| `address` | The physical address of the store. | 123 Example St, San Francisco, CA |
-| `contact_phone` | The contact phone number for the store. | `+1 234-567-8900` |
-| `new_order_notifications_email` | The email address to send notifications of new orders. | [email protected] |
-
-### Accessing Store in code
-
-To access the current store you can use `current_store` in controllers or `Spree::Store.current` in models/services/jobs.
+</CodeGroup>
## Markets
@@ -107,22 +93,29 @@ To access the current store you can use `current_store` in controllers or `Spree
- **Europe** — EUR, German, ships to DE, FR, AT, NL
- **United Kingdom** — GBP, English, ships to GB
-For full details on creating and managing markets, see the [Markets](/developer/core-concepts/markets) guide.
+See the [Markets](/developer/core-concepts/markets) guide for details.
+
+## Store Resources
+
+Each store has its own set of resources. This means products, orders, and promotions in one store are completely separate from another.
-## Store resources
+| Resource | Relationship |
+|----------|-------------|
+| [**Markets**](/developer/core-concepts/markets) | A store has many markets, each defining a geographic region with its own currency and locale |
+| [**Orders**](/developer/core-concepts/orders) | An order belongs to one store |
+| [**Products**](/developer/core-concepts/products) | A product can be available in multiple stores |
+| [**Payment Methods**](/developer/core-concepts/payments) | A payment method can be available in multiple stores |
+| [**Shipping Methods**](/developer/core-concepts/shipments) | A shipping method can be available in multiple stores |
+| [**Taxonomies**](/developer/core-concepts/products#taxons-and-taxonomies) | A taxonomy belongs to one store |
+| [**Promotions**](/developer/core-concepts/promotions) | A promotion can apply to multiple stores |
-Each Store can have its own resources. For example, a Store can have its own Products, Taxonomies, Promotions, etc.
+## Multi-Store Setup
-| Resource | Relationship |
-| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| [**Market**](markets) | One Store has many Markets, each defining a geographic region with its own currency and locale |
-| [**Order**](orders) | One Order belongs to one Store |
-| [**Product**](products) | One Product can be associated with many Store(s), you can pick and choose in which Store(s) each Product will be available |
-| [**Payment Method**](payments) | One Payment Method can be associated with many Store(s), you can select in which Stores given Payment Method will be available on Checkout |
-| [**Taxonomy**](products#taxons-and-taxonomies) | One Taxonomy belongs to one Store |
-| [**Promotion**](promotions) | One Promotion can be associated with multiple Stores |
-| **Store Credit** | One Store Credit belongs to and can be used in one Store |
+To run multiple stores from a single Spree installation, see the [Multi-Store guide](/developer/multi-store/quickstart). Each store gets its own domain, branding, catalog, and checkout — while sharing the same admin dashboard and infrastructure.
-## Multi-store setup
+## Related Documentation
-To enable multiple stores please follow our [Multi Store guide](/developer/multi-store/quickstart)
+- [Markets](/developer/core-concepts/markets) — Multi-region commerce within a store
+- [Products](/developer/core-concepts/products) — Product catalog
+- [Orders](/developer/core-concepts/orders) — Order management and checkout
+- [Multi-Store](/developer/multi-store/quickstart) — Running multiple stores
diff --git a/docs/developer/core-concepts/taxes.mdx b/docs/developer/core-concepts/taxes.mdx
index 72ce40b9e3..f9be95c397 100644
--- a/docs/developer/core-concepts/taxes.mdx
+++ b/docs/developer/core-concepts/taxes.mdx
@@ -1,213 +1,139 @@
---
title: Taxes
-description: Learn how to configure taxes in Spree
+description: Tax categories, tax rates, zones, and how Spree calculates taxes at checkout
---
## Overview
-Spree represents taxes for an order by using Tax Categories and Tax Rates.
-
-### Tax Model Diagram
+Spree uses Tax Categories and Tax Rates to calculate taxes for orders. Products are assigned to tax categories, and tax rates define the percentage charged within specific geographic [Zones](/developer/core-concepts/addresses#zones).
```mermaid
erDiagram
+ TaxCategory ||--o{ TaxRate : "has many"
+ TaxCategory ||--o{ Product : "has many"
+ TaxRate }o--|| Zone : "applies in"
+ TaxRate ||--o{ Adjustment : "creates"
+ Zone ||--o{ ZoneMember : "has many"
+
TaxCategory {
string name
boolean is_default
string tax_code
- string description
}
TaxRate {
string name
decimal amount
boolean included_in_price
- boolean show_rate_in_label
}
Zone {
string name
- string description
- boolean default_tax
string kind
}
-
- ZoneMember {
- string zoneable_type
- integer zoneable_id
- }
-
- Adjustment {
- decimal amount
- string label
- boolean included
- boolean eligible
- string state
- }
-
- TaxCategory ||--o{ TaxRate : "has many"
- TaxCategory ||--o{ Product : "has many"
- TaxCategory ||--o{ ShippingMethod : "has many"
- TaxRate }o--|| Zone : "belongs to"
- TaxRate }o--|| TaxCategory : "belongs to"
- TaxRate ||--|| Calculator : "has one"
- TaxRate ||--o{ Adjustment : "creates"
- Zone ||--o{ ZoneMember : "has many"
- ZoneMember }o--o| Country : "member"
- ZoneMember }o--o| State : "member"
```
**Key relationships:**
- **Tax Category** groups products for tax purposes (e.g., "Clothing", "Food", "Digital")
- **Tax Rate** defines the percentage and rules for a Tax Category within a [Zone](/developer/core-concepts/addresses#zones)
- **Zone** defines geographic regions (countries or states) where taxes apply
-- **[Calculator](/developer/core-concepts/calculators)** computes the tax amount
- **[Adjustments](/developer/core-concepts/adjustments)** are created on orders/line items to apply taxes
-## Tax Categories and Rates
+## Tax Categories
-Spree represents taxes for an order by using Tax Categories and Tax Rates.
+Tax categories group products by how they're taxed. Common examples:
-Products within Spree can be linked to Tax Categories, which are then used to influence the taxation rate for the products when they are purchased. One Tax Category can be set to being the default for the entire system, which means that if a product doesn't have a related tax category, then this default tax category would be used.
+- **Clothing** — standard tax rate
+- **Food** — reduced or exempt rate
+- **Digital** — different rules per jurisdiction
-Here's the list of Tax Category attributes:
+Each product is assigned a tax category. One category can be set as the default for products that don't have an explicit assignment.
-| Attribute | Description | Example Value |
-|-------------------|--------------------------------------------------------------|-------------------------------|
-| `name` | The name of the tax category. | Clothing |
-| `is_default` | Indicates if this is the default tax category. | `true` |
-| `tax_code` | The tax code associated with the tax category. | `1257L` |
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `name` | Category name | `Clothing` |
+| `is_default` | Whether this is the default category | `true` |
+| `tax_code` | Code from your tax provider (e.g., Stripe, Avalara) | `1257L` |
-<Note>
- Tax code is a unique identifier for the tax category. It's used to identify the tax category in the backend. This value can originate from the tax provider (eg. Stripe, Avalara) or be generated by Spree.
-</Note>
+## Tax Rates
-A `tax_category` can have many `tax_rates`, which indicate the rate at which the products belonging to a specific tax category will be taxed at.
+Tax rates define the percentage charged for a specific tax category within a geographic zone.
-`Spree::TaxRate` object includes these attributes:
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `name` | Rate name | `California Sales Tax` |
+| `amount` | Tax percentage as a decimal | `0.08` (8%) |
+| `included_in_price` | Whether tax is included in the displayed price | `false` |
+| `zone` | Geographic region where this rate applies | `US` |
+| `tax_category` | Products this rate applies to | `Clothing` |
-| Attribute | Description | Example Value |
-|----------------------|-----------------------------------------------------------------------------|---------------------|
-| `amount` | The tax rate amount as a decimal. This will be presented as a percentage. | `0.08` |
-| `zone_id` | The ID of the zone this tax rate applies to. | `1` |
-| `tax_category_id` | The ID of the tax category this tax rate is associated with. | `2` |
-| `included_in_price` | Indicates if the tax is included in the price (true) or added on top (false). | `false` |
-| `name` | The name of the tax rate. | California Sales Tax |
-| `show_rate_in_label` | Indicates if the tax rate (8%) should be shown in the label. | `true` |
+## Tax Types
-A tax rate links to a particular Zone see [Addresses](/developer/core-concepts/addresses) for more information about zones. When an order is placed in a specific zone, any of the products for that order which have a tax zone that matches the order's tax zone will be taxed.
+### Sales Tax (tax-exclusive)
-The standard sales tax policies commonly found in the USA can be modeled as well as Value Added Tax VAT which is commonly used in Europe. These are not the only types of tax rules that you can model in Spree. Once you obtain a sufficient understanding of the basic concepts you should be able to model the tax rules of your country or jurisdiction.
+Common in the United States. The displayed price does **not** include tax — tax is added at checkout based on the shipping address.
-<Note>
-Taxation within the United States can get exceptionally complex, with different states, countries and even cities having different taxation rates. If you are shipping interstate within the United States, we would strongly advise you to use the [Spree Avatax](https://github.com/spree-contrib/spree_avatax_official) or [Spree TaxJar](https://github.com/spree-contrib/spree_taxjar) extension so that you get correct tax rates.
-</Note>
+**Example:** A $17.99 item with 5% sales tax:
+- Displayed price: **$17.99**
+- Tax at checkout: **$0.90**
+- Order total: **$18.89**
-## Basic Examples
+### Value Added Tax / VAT (tax-inclusive)
-Let's say you need to charge 5% tax for all items that ship to New York and 6% on only clothing items that ship to Pennsylvania. This will mean you need to construct two different zones: one zone containing just the state of New York and another zone consisting of the single state of Pennsylvania.
+Common in Europe and many other countries. The displayed price **already includes** tax. When shipping outside the tax zone, the tax is removed from the price.
-Here's another hypothetical scenario. You would like to charge 10% tax on all electronic items and 5% tax on everything else. This tax should apply to all countries in the European Union EU. In this case you would construct just a single zone consisting of all the countries in the EU. The fact that you want to charge two different rates depending on the type of good does not mean you need two zones.
+**Example:** A £17.99 item with 5% VAT included:
+- Displayed price: **£17.99** (includes £0.86 VAT)
+- If shipped outside VAT zone: price reduces to **£17.13**
- Please see the [Addresses guide](/developer/core-concepts/addresses) for more information on constructing a zone.
+<Info>
+The `tax_inclusive` setting on [Markets](/developer/core-concepts/markets) controls whether prices are displayed with or without tax for each geographic region.
+</Info>
## Default Tax Zone
-Spree also has the concept of a default tax zone. When a user is adding items to their cart we do not yet know where the order will be shipped to, and so it's assumed that the cart is within the default tax zone until later. In some cases we may want to estimate the tax for the order by assuming the order falls within a particular tax zone.
+Spree uses a default tax zone to estimate taxes before the customer enters a shipping address. This is important for stores with tax-inclusive pricing (VAT) — it determines which tax rate is assumed in the displayed price.
-Why might we want to do this? The primary use case for this is for countries where there is already tax included in the price. In the EU, for example, most products have a Value Added Tax VAT included in the price. There are cases where it may be desirable to show the portion of the product price that includes tax. In order to calculate this tax amount we need to know the zone and corresponding Tax Rate that was assumed in the price.
-
-We may also reduce the order total by the tax amount if the order is being shipped outside the tax jurisdiction. Again, this requires us to know the zone assumed in making the original tax calculation so that the tax amount can be backed out.
-
-## Shipping vs. Billing Address
-
-Most tax jurisdictions base the tax on the shipping address of where the order is being shipped to. So in these cases the shipping address is used when determining the tax zone. Spree does, however, allow you to use the billing address to determine the zone.
-
-To determine tax based on billing address instead of shipping address you will need to add this line to your `config/initializers/spree.rb`
-
-```ruby
-Spree::Config[:tax_using_ship_address] = false
-```
+If the customer's shipping address is outside the default tax zone, the assumed tax is removed and the correct rate for their zone is applied.
- `Spree::Zone.match` is a method used to determine the most applicable zone for taxation. In the case of multiple matches, the closer match will be used, with State zone matches having priority over Country zone matches.
+## Tax Calculation at Checkout
-## Calculators
+During checkout, taxes are calculated based on the shipping address:
-In order to charge tax in Spree you also need a `Spree::Calculator`. In most cases you should be able to use Spree's [DefaultTax calculator](https://github.com/spree/spree/blob/main/core/app/models/spree/calculator/default_tax.rb). It is suitable for both sales tax and price-inclusive tax scenarios. For more information, please read the [Calculators guide](calculators).
+1. The customer's shipping address determines their [Zone](/developer/core-concepts/addresses#zones)
+2. Spree finds matching tax rates for that zone and the product's tax category
+3. Tax [Adjustments](/developer/core-concepts/adjustments) are created on line items
+4. The order total is updated
<Note>
- The `DefaultTax` calculator uses the item total exclusive of shipping when computing sales tax.
+For complex tax requirements (interstate US sales, international VAT), consider using automated tax calculation. The [Stripe Tax integration](/integrations/payments/stripe) handles this automatically.
</Note>
-## Tax Types
-
-There are two basic types of tax that a store owner might need to contend with. In the United States and some other countries store owners sometimes need to charge what is known as "sales tax." In the European Union EU and other countries stores owners need to deal with "tax inclusive" pricing which is often called Value Added Tax VAT.
-
-Most taxes can be considered one of these two types. For instance, in Australia customers pay a Goods and Services Tax GST. This is basically equivalent to VAT in Europe.
-
-In some cases you may need to charge one type of tax for orders falling within one zone and another type of tax for orders falling within a different zone. There are even some rare situations where you may need to charge both types of tax in the same zone. Spree supports all of these scenarios.
-
-### Sales Tax
-
-Sales tax is the default tax type for any tax rate in Spree.
-
-Let's take an example of a sales tax situation for the United States. Imagine that we have a zone that covers all of North America and that the zone is used for a tax rate which applies a 5% tax on products with the tax category of "Clothing".
-
-If the customer purchases a single clothing item for $17.99 and they live in the United States which is within the North America zone we defined they are eligible to pay sales tax.
-
-The sales tax calculation is $17.99 x 5% for a total tax of $0.8995, which is rounded up to two decimal places, to $0.90. This tax amount is then applied to the order as an adjustment.
-
-See the [Adjustments Guide](/developer/core-concepts/adjustments) if you need more information on adjustments.
-
-If the quantity of the item is changed to 2, then the tax amount doubles: $17.99 x 2 x 0.05 is $1.799, which is again rounded up to two decimal places, applying a tax adjustment of $1.80.
-
-Let's now assume that we have another product that's a coffee mug, which doesn't have the "Clothing" tax category applied to it. Let's also assume this product costs $13.99, and there's no default tax category set up for the system. Under these circumstances, the coffee mug will not be taxed when it's added to the order.
-
-Finally, if the taxable address either the shipping or billing, depending on the `Spree::Config[:tax_using_ship_address]` setting is changed for the order to outside this taxable zone, then the tax adjustment on the order will be removed. If the address is changed back, the tax rate will be applied once more.
-
-### Tax Included
-
-Many jurisdictions have what is commonly referred to as a Value Added Tax VAT. In these cases the tax is typically applied to the price. This means that prices for items are "inclusive of tax" and no additional tax needs to be applied during checkout.
-
-In the case of tax inclusive pricing the store owner can enter all prices inclusive of tax if their home country is the default zone. If there is no default zone set, any taxes that are included in the price will be added to the net prices on the fly depending on the current order's tax zone.
-
-If the current order's tax zone is outside the default zone, prices will be shown and used with only the included taxes for that zone applied. If there is no VAT for that zone for example when the current order's shipping address is outside the EU, the net price will be shown and used.
-
- Keep in mind that each order records the price a customer paid including the tax as part of the line item record. This means you don't have to worry about changing prices or tax rates affecting older orders.
-
-When tax is included in the price there is no order adjustment needed unlike the sales tax case. Stores are, however, typically interested in showing the amount of tax the user paid. These totals are for informational purposes only and do not affect the order total.
-
-Let's start by looking at an example where there is a 5% included on all products and it's included in the price. We'll further assume that this tax should only apply to orders within the United Kingdom UK.
-
-In the case where the order address is within the UK and we purchase a single clothing item for £17.99 we see an order total of £17.99. The tax rate adjustment applied is £17.99 x 5%, which is £0.8995, and that is rounded up to two decimal places, becoming £0.90.
-
-Now let's increase the quantity on the item from 1 to 2. The order total changes to £35.98 with a tax total of £1.799, which is again rounded up to now being £1.80.
-
-Next we'll add a different clothing item costing £19.99 to our order. Since both items are clothing and taxed at the same rate, they can be reduced to a single total, which means there's a single adjustment still applied to the order, calculated like this: £17.99 + £19.99 x 0.05 = £1.899, rounded up to two decimal places: £1.90.
-
-Now let's assume an additional tax rate of 10% on a "Consumer Electronics" tax category. When we add a product with this tax category to our order with a price of £16.99, there will be a second adjustment added to the order, with a calculated total of £16.99 x 10%, which is £1.699. Rounded up, it's £1.70.
-
-Finally, if the order's address is changed to being outside this tax zone, then there will be two negative adjustments applied to remove these tax rates from the order.
-
-### Additional Examples
+## Managing Taxes
-#### Differing VATs for different product categories depending on the customer's zone
+Tax categories and rates are managed in the Admin Panel under **Settings → Taxes**, or via the Admin API.
-As of January 1st, 2015, digital products sold within the EU must have the VAT of the receiving country applied. Physical products must have the seller's VAT applied. In order to set this up, please proceed as follows:
+### Common Configurations
-1. Create zones for all EU countries and a zone for all EU countries except your home zone.
-2. Mark your home zone as the default zone so you can conveniently enter gross prices.
-3. Create a tax category "Digital products", and a tax category "Physical products".
-4. Add tax rates that are "included in tax" for the tax category "Physical goods" for all EU countries.
-5. Add two tax rates for the tax category "Physical products": 1. One for your home country, with your home country's VAT 2. One for the rest of the EU, also with your home country's VAT
+**US store with state-level sales tax:**
+- Create zones for each taxable state
+- Create tax rates per zone (e.g., 8.25% for California, 6.25% for Texas)
+- Set `included_in_price: false`
-If you change the tax zone of the current order by changing the relevant address, prices will now be shown and used including the correct VAT for the current order.
+**EU store with VAT:**
+- Create a zone for EU countries
+- Create tax rates per country (e.g., 19% Germany, 20% France)
+- Set `included_in_price: true`
+- Set the EU zone as the default tax zone
-All of the examples in this guide are meant to be used for illustrative purposes. They are not meant to be used as definitive interpretations of tax law. You should consult your accountant or attorney for guidance on how much tax to collect and under what circumstances.
+**Digital products in the EU:**
+- Create a "Digital" tax category
+- Add tax rates for each EU country using the customer's country VAT rate
+- Physical products use the seller's country VAT rate
## Related Documentation
-- [Addresses](/developer/core-concepts/addresses) - Zones and address-based taxation
-- [Adjustments](/developer/core-concepts/adjustments) - Tax adjustments
-- [Calculators](/developer/core-concepts/calculators) - Tax rate calculators
-- [Orders](/developer/core-concepts/orders) - How taxes affect order totals
\ No newline at end of file
+- [Markets](/developer/core-concepts/markets) — Tax-inclusive pricing per market
+- [Addresses](/developer/core-concepts/addresses) — Zones and address-based taxation
+- [Adjustments](/developer/core-concepts/adjustments) — Tax adjustments
+- [Orders](/developer/core-concepts/orders) — How taxes affect order totals
diff --git a/docs/developer/core-concepts/translations.mdx b/docs/developer/core-concepts/translations.mdx
new file mode 100644
index 0000000000..cb7d30b5d1
--- /dev/null
+++ b/docs/developer/core-concepts/translations.mdx
@@ -0,0 +1,124 @@
+---
+title: Translations
+description: Translate product content and other resources into multiple languages
+---
+
+## Overview
+
+Spree supports two types of translations:
+
+1. **Resource Translations** — translatable content fields on models like Products, Taxons, and Stores (e.g., product name, description, slug)
+2. **UI Translations** — interface strings used in the admin panel (e.g., button labels, flash messages)
+
+For configuring which locales and currencies are available in your store, see [Markets](/developer/core-concepts/markets). Markets control locale and currency assignment per geographic region.
+
+## Resource Translations
+
+Resources with user-facing content fields have built-in support for translations. Each translatable resource has a corresponding translations table in the database — for example, product translations are stored in `spree_product_translations`.
+
+```mermaid
+erDiagram
+ Product ||--o{ ProductTranslation : "has many"
+ Taxon ||--o{ TaxonTranslation : "has many"
+ Store ||--o{ StoreTranslation : "has many"
+
+ Product {
+ string id PK
+ string status
+ }
+
+ ProductTranslation {
+ string id PK
+ string product_id FK
+ string locale
+ string name
+ text description
+ string slug
+ string meta_title
+ string meta_description
+ }
+
+ TaxonTranslation {
+ string id PK
+ string taxon_id FK
+ string locale
+ string name
+ text description
+ string permalink
+ }
+```
+
+### Translatable Fields
+
+| Resource | Translatable Fields |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Product | `name`, `description`, `slug`, `meta_description`, `meta_keywords`, `meta_title` |
+| Taxon | `name`, `description`, `permalink` |
+| Taxonomy | `name` |
+| Option Type | `presentation` |
+| Option Value | `presentation` |
+| Property | `presentation` |
+| Product Property | `value` |
+| Store | `name`, `meta_description`, `meta_keywords`, `seo_title`, `facebook`, `twitter`, `instagram`, `customer_support_email`, `description`, `address`, `contact_phone` |
+
+### Store API
+
+To retrieve translated content, pass the locale via the `X-Spree-Locale` header or the SDK `locale` option:
+
+<CodeGroup>
+
+```typescript SDK
+// Fetch product in French
+const product = await client.store.products.get('spree-tote', {
+ locale: 'fr',
+})
+
+product.name // "Sac Spree"
+product.description // "Un sac fourre-tout élégant..."
+product.slug // "sac-spree"
+
+// List taxons in German
+const { data: taxons } = await client.store.taxons.list({}, {
+ locale: 'de',
+})
+```
+
+```bash cURL
+# Fetch product in French
+curl 'https://api.mystore.com/api/v3/store/products/spree-tote' \
+ -H 'Authorization: Bearer spree_pk_xxx' \
+ -H 'X-Spree-Locale: fr'
+```
+
+</CodeGroup>
+
+Slugs are also localized — a product can have different slugs per locale. See [Slugs](/developer/core-concepts/slugs#internationalization) for details.
+
+### Managing Translations
+
+Translations are managed in the Admin Panel. When editing a product, taxon, or other translatable resource, switch the locale selector to enter content in each language.
+
+Translations can also be managed via the Admin API.
+
+## UI Translations
+
+Spree stores UI translation strings in a separate project: [Spree I18n](https://github.com/spree/spree_i18n). This is a community-maintained project with locale files for 43+ languages.
+
+To install UI translations:
+
+```bash
+bundle add spree_i18n
+```
+
+Once installed, all translation files are available automatically — no need to copy any files.
+
+<Info>
+The full list of supported locales is available in the [Spree I18n GitHub repository](https://github.com/spree-contrib/spree_i18n/tree/main/config/locales).
+</Info>
+
+## Related Documentation
+
+- [Markets](/developer/core-concepts/markets) — Locale and currency configuration per geographic region
+- [Slugs](/developer/core-concepts/slugs) — Localized slugs and URL identifiers
+- [Stores](/developer/core-concepts/stores) — Multi-store setup
+- [Products](/developer/core-concepts/products) — Product translations
diff --git a/docs/developer/core-concepts/users.mdx b/docs/developer/core-concepts/users.mdx
index 6dd7eb5ef2..d6beb8f2ad 100644
--- a/docs/developer/core-concepts/users.mdx
+++ b/docs/developer/core-concepts/users.mdx
@@ -1,373 +1,311 @@
---
title: Users
+description: Customers and admin users — authentication, accounts, and permissions
---
## Overview
-In your Spree application you will usually have 2 types of users:
+Spree has two separate user types:
-* **Customers** - users who browse and purchase products
-* **Admins** - users who manage the store via the Admin Panel
+- **Customers** — users who browse your store, manage their account, and purchase products via the Store API
+- **Admins** — users who manage the store via the Admin Panel
-Spree uses two separate user classes to distinguish between them:
-
-| Class | Description | Default |
-|-------|-------------|---------|
-| `Spree.user_class` | Customers who browse and purchase products | `Spree::User` |
-| `Spree.admin_user_class` | Administrators who manage the store via Admin Panel | `Spree::AdminUser` |
-
-<Warning>
-Always use `Spree.user_class` and `Spree.admin_user_class` instead of referencing the classes directly. This ensures compatibility with custom user models.
-</Warning>
+| User type | Class | Default |
+|-----------|-------|---------|
+| Customers | `Spree.user_class` | `Spree::User` |
+| Admins | `Spree.admin_user_class` | `Spree::AdminUser` |
<Info>
-You can use your own User classes. More on this in the [Customize Authentication guide](/developer/customization/authentication).
+You can use your own user classes. See the [Customize Authentication guide](/developer/customization/authentication) for details.
</Info>
## Customers
-Customers are users who browse your store and purchase products. They are managed via `Spree.user_class`.
+Customers interact with your store through the Store API. They can register, log in, manage their profile, and view order history.
```mermaid
erDiagram
- spree_users ||--o{ spree_orders : "places"
- spree_users ||--o{ spree_addresses : "has many"
- spree_users ||--o{ spree_credit_cards : "has many"
- spree_users ||--o{ spree_payment_sources : "has many"
- spree_users ||--o{ spree_store_credits : "has many"
- spree_users ||--o{ spree_gift_cards : "has many"
- spree_users ||--o{ spree_wishlists : "has many"
- spree_users ||--o| spree_addresses : "default ship address"
- spree_users ||--o| spree_addresses : "default bill address"
- spree_credit_cards ||--|| spree_payment_methods : "belongs to"
- spree_payment_sources ||--|| spree_payment_methods : "belongs to"
-
- spree_users {
- bigint id PK
+ Customer ||--o{ Order : "places"
+ Customer ||--o{ Address : "has many"
+ Customer ||--o{ Wishlist : "has many"
+ Customer ||--o{ StoreCredit : "has many"
+ Customer ||--o{ PaymentSource : "has many"
+
+ Customer {
+ string id
string email
- bigint ship_address_id FK
- bigint bill_address_id FK
- datetime created_at
+ string first_name
+ string last_name
}
- spree_orders {
- bigint id PK
- bigint user_id FK
+ Order {
string number
string state
- decimal total
}
- spree_addresses {
- bigint id PK
+ Address {
string firstname
string lastname
string address1
string city
- string zipcode
}
- spree_credit_cards {
- bigint id PK
- bigint user_id FK
- bigint payment_method_id FK
- string cc_type
- string last_digits
+ Wishlist {
string name
+ boolean is_default
}
+```
- spree_payment_sources {
- bigint id PK
- bigint user_id FK
- bigint payment_method_id FK
- string type
- string name
- }
+### Registration
- spree_store_credits {
- bigint id PK
- bigint user_id FK
- decimal amount
- string currency
- }
+<CodeGroup>
- spree_gift_cards {
- bigint id PK
- bigint user_id FK
- string code
- decimal balance
- string currency
- }
-
- spree_wishlists {
- bigint id PK
- bigint user_id FK
- string name
- boolean is_default
- }
+```typescript SDK
+const { token, user } = await client.store.auth.register({
+ email: '[email protected]',
+ password: 'password123',
+ password_confirmation: 'password123',
+ first_name: 'John',
+ last_name: 'Doe',
+})
+// token => JWT token for subsequent authenticated requests
+// user => { id: "usr_xxx", email: "[email protected]", first_name: "John", ... }
+```
- spree_payment_methods {
- bigint id PK
- string type
- string name
- }
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/store/auth/register' \
+ -H 'Authorization: Bearer spree_pk_xxx' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "email": "[email protected]",
+ "password": "password123",
+ "password_confirmation": "password123",
+ "first_name": "John",
+ "last_name": "Doe"
+ }'
```
-Customers can have:
+</CodeGroup>
-* **[Addresses](/developer/core-concepts/addresses)** - both billing and shipping
-* **[Orders](/developer/core-concepts/orders)** - a list of products that the customer has purchased
-* **Credit Cards** - saved credit cards for checkout
-* **Payment Sources** - saved non-credit card payment methods (PayPal, Klarna, etc.)
-* **Store Credits** - assigned by the store owners, to be used to purchase products
-* **Gift Cards** - gift cards owned by or assigned to the customer
-* **Wishlists** - a list of products that the customer has marked as a wishlist
+### Login
-### Customer Attributes
+<CodeGroup>
-| Attribute | Description | Example Value |
-|-------------------|-----------------------------------------------------------------------------|---------------------|
-| `email` | The email address of the customer | `[email protected]` |
-| `ship_address_id` | References the default shipping address | `2` |
-| `bill_address_id` | References the default billing address | `3` |
+```typescript SDK
+const { token, user } = await client.store.auth.login({
+ email: '[email protected]',
+ password: 'password123',
+})
+// Use the token for authenticated requests
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/store/auth/login' \
+ -H 'Authorization: Bearer spree_pk_xxx' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "email": "[email protected]",
+ "password": "password123"
+ }'
+```
-There will be more attributes provided by [Devise](https://github.com/plataformatec/devise) gem, but these are the most important ones.
+</CodeGroup>
-### Customer Methods
+The response includes a JWT `token` and a `user` object. Pass the token in subsequent requests via the `Authorization: Bearer <token>` header.
-`Spree.user_class` includes several [ActiveRecord concerns](https://api.rubyonrails.org/v7.1.3.2/classes/ActiveSupport/Concern.html) which provide additional methods:
+### Token Refresh
-```ruby
-# Find a customer
-customer = Spree.user_class.find_by(email: "[email protected]")
+Refresh an expiring token to keep the session alive:
-# Get customer orders
-customer.orders
-```
+<CodeGroup>
-```ruby Returns the last incomplete order for the given store.
-customer.last_incomplete_spree_order(store)
+```typescript SDK
+const { token } = await client.store.auth.refresh({
+ token: existingToken,
+})
```
-```ruby Returns the total amount available store credits for the customer in the given store.
-customer.available_store_credits(store)
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/store/auth/refresh' \
+ -H 'Authorization: Bearer <jwt_token>'
```
-```ruby Returns the default Wishlist for the given Store.
-customer.default_wishlist_for_store(store)
+</CodeGroup>
+
+### Customer Profile
+
+<CodeGroup>
+
+```typescript SDK
+// Get current customer
+const customer = await client.store.customer.get()
+// {
+// id: "usr_xxx",
+// email: "[email protected]",
+// first_name: "John",
+// last_name: "Doe",
+// default_shipping_address: { ... },
+// default_billing_address: { ... },
+// addresses: [{ ... }, { ... }],
+// }
+
+// Update profile
+const updated = await client.store.customer.update({
+ first_name: 'Jonathan',
+ accepts_email_marketing: true,
+})
```
-```ruby Returns a list of all active payment sources (credit cards, PayPal, Klarna, etc.) that can be used on checkout.
-customer.payment_sources
+```bash cURL
+# Get current customer
+curl 'https://api.mystore.com/api/v3/store/customer' \
+ -H 'Authorization: Bearer <jwt_token>'
+
+# Update profile
+curl -X PATCH 'https://api.mystore.com/api/v3/store/customer' \
+ -H 'Authorization: Bearer <jwt_token>' \
+ -H 'Content-Type: application/json' \
+ -d '{ "first_name": "Jonathan", "accepts_email_marketing": true }'
```
-## Admins
+</CodeGroup>
+
+### Customer Resources
+
+Authenticated customers have access to these resources:
-Admins are users who manage the store via the Admin Panel. They are managed via `Spree.admin_user_class`.
+| Resource | Description |
+|----------|-------------|
+| [**Addresses**](/developer/core-concepts/addresses#customer-address-book) | Billing and shipping addresses with default selection |
+| [**Orders**](/developer/core-concepts/orders#order-history) | Past order history |
+| **Credit Cards** | Saved credit cards for checkout |
+| **Payment Sources** | Other saved payment methods (PayPal, Klarna, etc.) |
+| **Store Credits** | Balance assigned by the store, usable at checkout |
+| **Gift Cards** | Gift cards owned by or assigned to the customer |
+| **Wishlists** | Saved product lists |
+
+### Guest Checkout
+
+Customers don't need to register to purchase. Guest checkout uses an order token (`X-Spree-Order-Token`) to identify the cart. See [Orders — Cart](/developer/core-concepts/orders#cart) for details.
+
+## Admin Users
+
+Admin users manage the store via the Admin Panel. They have roles that control what they can access.
```mermaid
erDiagram
- spree_admin_users ||--o{ spree_role_users : "has many"
- spree_role_users }o--|| spree_roles : "belongs to"
- spree_role_users }o--|| spree_stores : "resource"
- spree_admin_users ||--o{ spree_invitations : "inviter"
- spree_admin_users ||--o{ spree_invitations : "invitee"
-
- spree_admin_users {
- bigint id PK
+ AdminUser ||--o{ RoleUser : "has many"
+ RoleUser }o--|| Role : "belongs to"
+ RoleUser }o--|| Store : "scoped to"
+ AdminUser ||--o{ Invitation : "invites"
+
+ AdminUser {
+ string id
string email
- datetime created_at
}
- spree_role_users {
- bigint id PK
- bigint user_id FK
- bigint role_id FK
+ RoleUser {
+ string role_id
string resource_type
- bigint resource_id
- }
-
- spree_roles {
- bigint id PK
- string name
+ string resource_id
}
- spree_stores {
- bigint id PK
+ Role {
string name
}
- spree_invitations {
- bigint id PK
+ Invitation {
string email
- string token
string status
+ string token
datetime expires_at
}
```
-### Admin Roles
+### Roles
-Admin users can have different roles attached which control their permissions in the Admin Panel.
+Admin users can have different roles that control their permissions:
| Role | Description |
|------|-------------|
| `admin` | Full access to all Admin Panel features |
<Info>
-You can create custom roles with specific permissions. See the [Customize Permissions guide](/developer/customization/permissions) for more details.
+You can create custom roles with specific permissions. See the [Customize Permissions guide](/developer/customization/permissions) for details.
</Info>
-### Managing Admin Access
+### Creating Admin Users
+
+Use the Spree CLI to create admin users:
-Resources that include the `Spree::UserManagement` concern (such as `Spree::Store`) provide methods to manage admin access:
+```bash
+spree user create
+```
-```ruby
-store = Spree::Store.default
-admin = Spree.admin_user_class.find_by(email: "[email protected]")
-role = Spree::Role.find_by(name: 'admin')
+The CLI will prompt you for the email and password. You can also pass them directly:
-# Add an admin to the store with a specific role
-store.add_user(admin, role)
+```bash
+spree user create --email [email protected] --password secret123
+```
-# Add an admin with the default role
-store.add_user(admin)
+The created user gets the `admin` role on the default store.
-# Remove an admin's access to the store
-store.remove_user(admin)
+### Inviting Admin Users
-# Check admin permissions
-admin.has_spree_role?('admin')
-```
+You can invite new admins through the Admin Panel or programmatically.
-### Admin User Invitation Flow
+**Via Admin Panel:**
-Spree uses a custom `Spree::Invitation` model to handle admin user invitations. This provides a secure, token-based invitation system with built-in expiration and role assignment.
+1. Navigate to **Settings → Users**
+2. Click **Invite User**
+3. Enter the email address and select a role
+4. Click **Send Invitation**
+
+The invitee receives an email with an invitation link. If they already have an account, they log in to accept. Otherwise, they create an account first.
```mermaid
flowchart TB
- A[Admin creates invitation] --> B[Spree::Invitation created]
- B --> C[Token generated automatically]
- C --> D["Event 'invitation.created' published"]
- D --> E[Invitation email sent]
- E --> F[Invitee clicks invitation link]
- F --> G{Invitee exists?}
- G -->|Yes| H[Redirect to login]
- G -->|No| I[Redirect to registration]
- H --> J[Invitee logs in]
- I --> K[Invitee creates account]
- J --> L[Accept invitation]
- K --> L
- L --> M[RoleUser created]
- M --> N["Event 'invitation.accepted' published"]
- N --> O[Admin can access resource]
+ A[Admin creates invitation] --> B[Invitation email sent]
+ B --> C[Invitee clicks link]
+ C --> D{Has account?}
+ D -->|Yes| E[Log in]
+ D -->|No| F[Create account]
+ E --> G[Accept invitation]
+ F --> G
+ G --> H[Role assigned to store]
```
-#### Invitation Model
-
-The `Spree::Invitation` model tracks:
+#### Invitation Details
| Attribute | Description |
|-----------|-------------|
-| `email` | Email address of the invitee |
+| `email` | Invitee's email address |
| `token` | Secure token for the invitation link |
| `status` | `pending` or `accepted` |
-| `expires_at` | When the invitation expires (default: 2 weeks) |
-| `resource` | The resource being granted access to (e.g., Store) |
+| `expires_at` | Expiration date (default: 2 weeks) |
+| `resource` | The store being granted access to |
| `role` | The role to assign upon acceptance |
-| `inviter` | The admin who created the invitation |
-| `invitee` | The user who accepts the invitation |
-
-#### Inviting an Admin via Admin Panel
-
-1. Navigate to **Settings → Users** in the Admin Panel
-2. Click **Invite User**
-3. Enter the new admin's email address
-4. Select the appropriate role
-5. Click **Send Invitation**
-
-The invitee will receive an email with an invitation link.
-
-#### Inviting an Admin via Code
-
-```ruby
-# Create an invitation
-invitation = Spree::Invitation.create!(
- email: "[email protected]",
- inviter: current_admin_user,
- resource: Spree::Store.default,
- role: Spree::Role.find_by(name: 'admin')
-)
-
-# The 'invitation.created' event triggers the email automatically
-# To skip the email:
-invitation = Spree::Invitation.create!(
- email: "[email protected]",
- inviter: current_admin_user,
- resource: Spree::Store.default,
- role: Spree::Role.find_by(name: 'admin'),
- skip_email: true
-)
-```
-
-#### Resending an Invitation
-
-```ruby
-invitation = Spree::Invitation.pending.find_by(email: "[email protected]")
-invitation.resend!
-```
-
-#### Accepting an Invitation
-
-When an invitee accepts, the invitation transitions to `accepted` and a `Spree::RoleUser` record is created linking the user to the resource with the specified role.
-
-```ruby
-invitation = Spree::Invitation.pending.find_by(token: params[:token])
-invitation.invitee = current_admin_user
-invitation.accept!
-```
-
-#### Invitation Expiration
-
-By default, invitations expire after 2 weeks. You can customize this per invitation:
-
-```ruby
-invitation = Spree::Invitation.create!(
- email: "[email protected]",
- inviter: current_admin_user,
- resource: Spree::Store.default,
- role: Spree::Role.find_by(name: 'admin'),
- expires_at: 1.month.from_now
-)
-```
#### Invitation Events
-The invitation system publishes events that you can subscribe to:
+The invitation system publishes [events](/developer/core-concepts/events) you can subscribe to:
| Event | Description |
|-------|-------------|
| `invitation.created` | Invitation was created (triggers email) |
-| `invitation.accepted` | Invitation was accepted |
-| `invitation.resent` | Invitation was resent |
+| `invitation.accepted` | Invitation was accepted and role assigned |
+| `invitation.resent` | Invitation was resent to the invitee |
## Permissions
-Spree uses [CanCanCan](https://github.com/CanCanCommunity/cancancan) library to handle authorization for both customers and admins.
-
-More on permissions can be found in the [Customize Permissions guide](/developer/customization/permissions).
+Spree uses [CanCanCan](https://github.com/CanCanCommunity/cancancan) for authorization. Permissions apply to both customers (Store API access) and admins (Admin Panel access).
-## Current User
-
-In Spree controllers or any controller inheriting from `Spree::BaseController`, you can access the current user with `spree_current_user` method:
-
-```ruby
-spree_current_user
-```
+See the [Customize Permissions guide](/developer/customization/permissions) for details on creating custom roles and permission sets.
## Related Documentation
-- [Addresses](/developer/core-concepts/addresses) - User address management
-- [Orders](/developer/core-concepts/orders) - User order history
-- [Authentication](/developer/customization/authentication) - Custom authentication
-- [Permissions](/developer/customization/permissions) - User permissions and authorization
+- [Addresses](/developer/core-concepts/addresses) — Customer address management
+- [Orders](/developer/core-concepts/orders) — Order history and checkout
+- [Authentication](/developer/customization/authentication) — Custom authentication setup
+- [Permissions](/developer/customization/permissions) — Roles and authorization
+- [Events](/developer/core-concepts/events) — Subscribe to user and invitation events
diff --git a/docs/developer/core-concepts/webhooks.mdx b/docs/developer/core-concepts/webhooks.mdx
index 92963e6b23..14e2d15cb1 100644
--- a/docs/developer/core-concepts/webhooks.mdx
+++ b/docs/developer/core-concepts/webhooks.mdx
@@ -113,19 +113,24 @@ endpoint.subscriptions = ['*'] # All events (explicit)
## Webhook Payload
-Each webhook delivery sends a JSON payload with the following structure:
+Each webhook delivery sends a JSON payload with the following structure. The `data` object uses the same [Store API V3 serializers](/api-reference/introduction) as the REST API, so webhook payloads and API responses share the same schema:
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "order.completed",
- "created_at": "2024-01-15T10:30:00Z",
+ "created_at": "2025-01-15T10:30:00Z",
"data": {
- "id": 123,
+ "id": "or_m3Rp9wXz",
"number": "R123456789",
"state": "complete",
"total": "99.99",
- "item_count": 3
+ "display_total": "$99.99",
+ "item_count": 3,
+ "currency": "USD",
+ "line_items": [ ... ],
+ "shipments": [ ... ],
+ "payments": [ ... ]
},
"metadata": {
"spree_version": "5.1.0"
@@ -138,9 +143,11 @@ Each webhook delivery sends a JSON payload with the following structure:
| `id` | Unique UUID for this event |
| `name` | Event name (e.g., `order.completed`) |
| `created_at` | ISO8601 timestamp when event occurred |
-| `data` | Serialized resource data |
+| `data` | Serialized resource data (V3 API format with [prefixed IDs](/api-reference/introduction)) |
| `metadata` | Additional context including Spree version |
+For complete payload schemas for each event type, see [Webhook Events & Payloads](/api-reference/webhooks-events).
+
## HTTP Request Details
### Headers
diff --git a/docs/developer/create-spree-app/quickstart.mdx b/docs/developer/create-spree-app/quickstart.mdx
new file mode 100644
index 0000000000..abf2c60f56
--- /dev/null
+++ b/docs/developer/create-spree-app/quickstart.mdx
@@ -0,0 +1,207 @@
+---
+title: "create-spree-app"
+sidebarTitle: Overview
+description: "Scaffold a new Spree Commerce project with a single command. Backend runs via Docker using pre-built images."
+---
+
+## Quick Start
+
+```bash
+npx create-spree-app@latest my-store
+```
+
+The CLI walks you through an interactive setup:
+
+1. Choose **Full-stack** (Backend + Next.js Storefront) or **Backend only**
+2. Optionally load **sample data** (products, categories, images)
+3. Optionally **start Docker services** immediately
+
+Once complete, your store is running at [http://localhost:3000](http://localhost:3000).
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) 20 or later
+- [Docker](https://docs.docker.com/get-docker/) (for running the Spree backend and PostgreSQL)
+
+## Setup Modes
+
+### Full-stack (default)
+
+Sets up both the Spree backend (Docker) and a [Next.js storefront](/developer/storefront/nextjs/quickstart) with the [Spree SDK](/developer/sdk/quickstart) pre-configured.
+
+```bash
+npx create-spree-app@latest my-store
+```
+
+The storefront is downloaded from the [Spree Storefront](https://github.com/spree/storefront) template and placed in `apps/storefront/`. The CLI automatically:
+
+- Installs storefront dependencies
+- Fetches a Store API key from the running backend
+- Writes the API key to the storefront's `.env.local`
+
+### Backend only
+
+Skips the storefront — just the Spree backend and PostgreSQL via Docker. Ideal when you're building a custom frontend or only need the API.
+
+```bash
+npx create-spree-app@latest my-store --backend-only
+```
+
+## CLI Flags
+
+All prompts can be skipped with flags for non-interactive (CI/CD) usage:
+
+```bash
+npx create-spree-app@latest my-store --backend-only --no-sample-data --no-start
+```
+
+| Flag | Description |
+|------|-------------|
+| `--backend-only` | Skip storefront setup |
+| `--no-sample-data` | Skip loading sample products and categories |
+| `--no-start` | Don't start Docker services after scaffolding |
+| `--port <number>` | Port for the Spree backend (default: `3000`) |
+| `--use-npm` | Use npm as package manager |
+| `--use-yarn` | Use yarn as package manager |
+| `--use-pnpm` | Use pnpm as package manager |
+
+<Tip>
+ The package manager is auto-detected from how you run the command. If you use `pnpm dlx create-spree-app`, pnpm will be used automatically.
+</Tip>
+
+<Tip>
+ If the default port is already in use, the CLI will automatically find a free port and let you know.
+</Tip>
+
+## Generated Project Structure
+
+<CodeGroup>
+```text Full-stack
+my-store/
+├── docker-compose.yml # Spree backend + PostgreSQL
+├── .env # Backend environment variables
+├── .gitignore
+├── package.json # Convenience scripts
+├── README.md
+└── apps/
+ └── storefront/ # Next.js storefront
+ ├── .env.local # API URL + API key
+ └── ...
+```
+
+```text Backend only
+my-store/
+├── docker-compose.yml # Spree backend + PostgreSQL
+├── .env # Backend environment variables
+├── .gitignore
+├── package.json # Convenience scripts
+└── README.md
+```
+</CodeGroup>
+
+### What's in docker-compose.yml
+
+- **Spree** — runs the `ghcr.io/spree/spree:latest` image on the configured port (default `3000`)
+- **PostgreSQL 17** — database with persistent volume
+- Health checks on both services
+
+### Spree CLI Commands
+
+The project includes [@spree/cli](https://www.npmjs.com/package/@spree/cli) for managing your Spree backend:
+
+| Command | Description |
+|---------|-------------|
+| `spree start` | Start backend services and stream logs |
+| `spree stop` | Stop backend services |
+| `spree down` | Stop and remove backend services |
+| `spree update` | Pull latest Spree image and restart (runs migrations automatically) |
+| `spree logs` | View backend logs |
+| `spree logs:worker` | View background jobs logs |
+| `spree console` | Rails console |
+| `spree seed` | Re-seed the database |
+| `spree load-sample-data` | Load sample products, categories, and images |
+
+## After Setup
+
+### Admin Dashboard
+
+Open [http://localhost:3000/admin](http://localhost:3000/admin) and log in with:
+
+| | |
+|---|---|
+| **Email** | `[email protected]` |
+| **Password** | `spree123` |
+
+### Store API
+
+The REST API is available at [http://localhost:3000/api/v3/store](http://localhost:3000/api/v3/store). See the [API Reference](/api-reference) for details.
+
+### Storefront (full-stack mode)
+
+If you chose full-stack mode, start the storefront in a separate terminal:
+
+```bash
+cd my-store/apps/storefront
+npm run dev
+```
+
+Open [http://localhost:3001](http://localhost:3001) to see your store.
+
+## Manual Start
+
+If you used `--no-start`, start services manually:
+
+```bash
+cd my-store
+spree start
+```
+
+Wait for Spree to be healthy, then optionally load sample data:
+
+```bash
+spree load-sample-data
+```
+
+
+## Spree CLI
+
+You can also use the [Spree CLI](/developer/cli) directly for additional commands:
+
+```bash
+spree user create # Create an admin user
+spree api-key create # Create an API key
+spree api-key list # List API keys
+```
+
+## Updating Spree
+
+To update to the latest Spree version:
+
+```bash
+spree update
+```
+
+This pulls the latest Docker image and recreates the containers. The entrypoint automatically runs database migrations.
+
+To pin a specific version, edit `SPREE_VERSION_TAG` in `.env`:
+
+```
+SPREE_VERSION_TAG=5.4
+```
+
+## Next Steps
+
+<CardGroup cols={2}>
+ <Card title="Next.js Storefront" icon="react" href="/developer/storefront/nextjs/quickstart">
+ Customize and extend the Storefront
+ </Card>
+ <Card title="Spree SDK" icon="code" href="/developer/sdk/quickstart">
+ TypeScript SDK for the Store and Admin APIs
+ </Card>
+ <Card title="API Reference" icon="book" href="/api-reference">
+ Explore the REST API endpoints
+ </Card>
+ <Card title="Core Concepts" icon="brain" href="/developer/core-concepts/architecture">
+ Learn about Spree's architecture
+ </Card>
+</CardGroup>
diff --git a/docs/developer/deployment/assets.mdx b/docs/developer/deployment/assets.mdx
index 6aa864c8a1..201f28b2a8 100644
--- a/docs/developer/deployment/assets.mdx
+++ b/docs/developer/deployment/assets.mdx
@@ -2,44 +2,24 @@
title: Assets
---
-Spree uses [Active Storage](https://guides.rubyonrails.org/active_storage_overview.html) to handle file uploads (eg. product images). By default, Active Storage uses local disk storage for attachments. This isn't suitable for production environments.
+By default, files are stored on the local filesystem. For production, use a cloud storage service.
-For production environments, we recommend using a cloud storage service such as [AWS S3](https://aws.amazon.com/s3/) or [Cloudflare R2](https://www.cloudflare.com/r2/).
+Spree auto-detects the storage provider based on which environment variables are set — no code changes needed. See [Environment Variables](/developer/deployment/environment_variables#file-storage-s3--cloudflare-r2) for the full list.
## AWS S3
-To use Amazon S3 as your storage service, you need to configure the storage in the `config/storage.yml` file.
+Set the following environment variables:
-```yaml
-amazon:
- service: S3
- access_key_id: <%= ENV.fetch("AWS_ACCESS_KEY_ID", "") %>
- secret_access_key: <%= ENV.fetch("AWS_SECRET_ACCESS_KEY", "") %>
- region: <%= ENV.fetch("AWS_REGION", "") %>
- bucket: <%= ENV.fetch("AWS_BUCKET", "spree-#{Rails.env}") %>
-```
-
-You will also need to add the `aws-sdk-s3` gem to your Gemfile.
-
-```ruby
-gem "aws-sdk-s3", require: false
-```
-
-And run `bundle install`.
-
-Now you need to switch the storage service in your `config/environments/production.rb` file.
-
-```ruby
-config.active_storage.service = :amazon
-```
-
-Now you will need to grab the credentials from your AWS S3 bucket and set them as environment variables used in the `config/storage.yml` file on your hosting provider.
-
-To test them locally you can put them in the `.env` file.
+| Variable | Default | Description |
+| --- | --- | --- |
+| `AWS_ACCESS_KEY_ID` | — | AWS access key |
+| `AWS_SECRET_ACCESS_KEY` | — | AWS secret key |
+| `AWS_REGION` | — | AWS region (e.g., `us-east-1`) |
+| `AWS_BUCKET` | `spree-production` | S3 bucket name |
### CORS Configuration
-Spree Admin Dashboard uses direct uploads to handle file uploads. For this to work properly, you need to configure CORS on your S3 bucket.
+The Admin Dashboard uses direct uploads. Configure CORS on your S3 bucket to allow this:
1. Go to your S3 bucket in AWS Console
2. Click on "Permissions" tab
@@ -58,58 +38,25 @@ Spree Admin Dashboard uses direct uploads to handle file uploads. For this to wo
```
<Info>
-`myspreestore.com` should be replaced with your domain name which you access your Spree Admin Dashboard.
+Replace `myspreestore.com` with the domain you use to access your Spree Admin Dashboard.
</Info>
## Cloudflare R2
-Cloudflare R2 is an S3-compatible, zero egress-fee, object storage with a built-in CDN. We strongly recommend using it as your storage service.
-
-To use Cloudflare R2 as your storage service, you need to configure the storage in the `config/storage.yml` file.
-
-```yaml
-cloudflare:
- service: S3
- endpoint: <%= ENV.fetch("CLOUDFLARE_ENDPOINT", "") %>
- access_key_id: <%= ENV.fetch("CLOUDFLARE_ACCESS_KEY_ID", "") %>
- secret_access_key: <%= ENV.fetch("CLOUDFLARE_SECRET_ACCESS_KEY", "") %>
- region: auto
- bucket: <%= ENV.fetch("CLOUDFLARE_BUCKET", "spree-#{Rails.env}") %>
- request_checksum_calculation: "when_required"
- response_checksum_validation: "when_required"
-```
-
-You will also need to add the `aws-sdk-s3` gem to your Gemfile.
-
-```ruby
-gem "aws-sdk-s3", require: false
-```
+Cloudflare R2 is S3-compatible object storage with zero egress fees and a built-in CDN.
-<Info>
-aws-sdk-s3 version 1.178.0 introduced a modification to the default checksum behavior from the client that is currently incompatible with R2 APIs.
+Set the following environment variables:
-To mitigate, users can use 1.177.0 or add the following to their s3 client instantiation:
-
-```yaml
-request_checksum_calculation: "when_required"
-response_checksum_validation: "when_required"
-```
-</Info>
-
-And run `bundle install`.
-
-Now you need to switch the storage service in your `config/environments/production.rb` file.
-
-```ruby
-config.active_storage.service = :cloudflare
-```
-
-Now you will need to grab the credentials from your Cloudflare R2 bucket and set them as environment variables used in the `config/storage.yml` file on your hosting provider.
-To test them locally you can put them in the `.env` file.
+| Variable | Default | Description |
+| --- | --- | --- |
+| `CLOUDFLARE_ENDPOINT` | — | R2 endpoint URL |
+| `CLOUDFLARE_ACCESS_KEY_ID` | — | R2 access key |
+| `CLOUDFLARE_SECRET_ACCESS_KEY` | — | R2 secret key |
+| `CLOUDFLARE_BUCKET` | `spree-production` | R2 bucket name |
### CORS Configuration
-Spree Admin Dashboard uses direct uploads to handle file uploads. For this to work properly, you need to configure CORS on your R2 bucket.
+Configure CORS on your R2 bucket for direct uploads:
1. Go to your R2 bucket in Cloudflare Console
2. Click on "Settings" tab
@@ -140,5 +87,5 @@ Spree Admin Dashboard uses direct uploads to handle file uploads. For this to wo
```
<Info>
-`myspreestore.com` should be replaced with your domain name which you access your Spree Admin Dashboard.
-</Info>
\ No newline at end of file
+Replace `myspreestore.com` with the domain you use to access your Spree Admin Dashboard.
+</Info>
diff --git a/docs/developer/deployment/aws.mdx b/docs/developer/deployment/aws.mdx
index d632a6fa00..ab3e5c08fd 100644
--- a/docs/developer/deployment/aws.mdx
+++ b/docs/developer/deployment/aws.mdx
@@ -15,20 +15,18 @@ To fully run your Spree application on AWS, you will need the following services
|---------|-------------|
| [AWS ECS Fargate](https://aws.amazon.com/fargate/) | Amazon Elastic Container Service (ECS) is a fully managed container orchestration service that allows you to run and scale containerized applications without managing the underlying infrastructure. |
| [AWS RDS](https://aws.amazon.com/rds/) | Amazon Relational Database Service makes it easy to set up, operate, and scale a relational database in the cloud. Spree works great with multiple databases: [Amazon Aurora both MySQL and PostgreSQL variants](https://aws.amazon.com/rds/aurora/), [RDS PostgreSQL](https://aws.amazon.com/rds/postgresql/), [RDS MySQL](https://aws.amazon.com/rds/mysql/) and [RDS MariaDB](https://aws.amazon.com/rds/mariadb/) |
-| [AWS ElastiCache](https://aws.amazon.com/elasticache/redis/?nc=sn&loc=2&dn=1) | You will need 2 instances of Valkey or Redis: one for the [Active Job background queue](https://guides.rubyonrails.org/active_job_basics.html) and one for the [Spree cache](/developer/deployment/caching). |
+| [AWS ElastiCache](https://aws.amazon.com/elasticache/redis/?nc=sn&loc=2&dn=1) | Valkey or Redis instance for background jobs (Sidekiq), [caching](/developer/deployment/caching), and Action Cable. |
| [AWS S3](https://aws.amazon.com/s3/) | Object storage service to store and read your uploaded files such as Product images, etc. [More information](/developer/deployment/assets#aws-s3). |
| [AWS CloudFront](https://aws.amazon.com/cloudfront/) | Fast content delivery network CDN to speed up your asset images/stylesheets/javascript delivery. This will greatly enhance your application responsiveness. |
| [AWS Route 53](https://aws.amazon.com/route53/) | Domain name system (DNS) service to manage your domain names and DNS records. |
| [AWS Certificate Manager](https://aws.amazon.com/certificate-manager/) | AWS Certificate Manager is a service that provides you with SSL/TLS certificates that you can use to secure your application. Spree in production works only with HTTPS. |
| [AWS ECR](https://aws.amazon.com/ecr/) | Amazon Elastic Container Registry is a fully managed Docker container registry that makes it easy to store, manage, and deploy Docker container images. |
-## Docker builds
+## Docker Image
-To deploy your Spree application on AWS, you will need to build a Docker image and send it to AWS ECR so that AWS ECS Fargate can pull it and run it.
+You can use the [official Docker image](/developer/deployment/docker) (`ghcr.io/spree/spree`) directly, or build your own from your Rails application's Dockerfile.
-[Spree Starter Dockerfile](https://github.com/spree/spree_starter/blob/main/Dockerfile) is a good starting point for your Docker build.
-
-You can deploy it to AWS ECR straitgh from GitHub via GitHub Actions, eg:
+To build and deploy a custom image to AWS ECR via GitHub Actions:
```yaml
name: Deploy to AWS Fargate
@@ -282,7 +280,6 @@ You will need to create two ECS task definitions: one for the web service and on
### Worker service
```json
-@ -0,0 +1,52 @@
{
"family": "spree-worker",
"networkMode": "awsvpc",
diff --git a/docs/developer/deployment/caching.mdx b/docs/developer/deployment/caching.mdx
index f3819c3b0e..f24ad54678 100644
--- a/docs/developer/deployment/caching.mdx
+++ b/docs/developer/deployment/caching.mdx
@@ -1,79 +1,27 @@
---
title: Caching
-description: >-
- This guide will cover all sorts of topics related to Spree application
- performance
+description: Configure caching for your Spree application
---
-Caching is a great way to improve the performance of your Spree application. In all modern web applications, usually the most time consuming operations are database queries and rendering templates. Caching allows you to store the results of these operations in memory and serve them from there.
+Caching improves performance by storing the results of expensive database queries and template renders in memory.
-We recommend using a distributed cache storage engine such as Memcached, Valkey or Redis. Spree Starter uses Redis by default.
+## Setting up Redis as Cache Store
-## Setting up Redis (or Valkey) as a cache storage engine
-
-<Info>
-If you're using Spree Starter, you don't need to do anything as it's already pre-configured for you.
-</Info>
-
-Firstly add `redis` gem to your project
+Spree comes pre-configured to use Redis for caching in production. Just set the `REDIS_URL` environment variable — no gem installation or code changes needed.
```bash
-bundle add redis
-```
-
-Now, you will need to change the `config/environments/production.rb` from:
-
-```ruby
-# config.cache_store = :mem_cache_store
+REDIS_URL=redis://localhost:6379/0
```
-to:
+When `REDIS_URL` is set, Spree automatically uses it for caching. When not set, it falls back to an in-memory cache store.
-```ruby
-if ENV['REDIS_CACHE_URL'].present?
- cache_servers = ENV['REDIS_CACHE_URL'].split(',') # if multiple instances are provided
- config.cache_store = :redis_cache_store, {
- url: cache_servers,
- connect_timeout: 30, # Defaults to 1 second
- read_timeout: 0.2, # Defaults to 1 second
- write_timeout: 0.2, # Defaults to 1 second
- reconnect_attempts: 2, # Defaults to 1
- }
-end
-```
-
-For more advanced configuration options, please refer to the [Spree Starter repository](https://github.com/spree/spree_starter/blob/main/config/environments/production.rb#L72).
-
-## Testing locally
+## Testing Locally
-To enable caching in the development environment please type in your project directory:
+To enable caching in the development environment:
```bash
-bin/rails dev cache
-```
-
-You will need to restart your webserver after this.
-
-## API cache
-
-<Info>
-Changing Spree API cache is only required for applications heavily using the API. The default configuration is already optimized for the most common use cases.
-</Info>
-
-Additionally Spree API has a built-in caching mechanism. It's enabled by default and you don't need to do anything to enable it. You can however tweak it to your needs.
-
-The default cache TTL is 1 hour. You can change it by setting `Spree::Api::Config[:api_v2_serializers_cache_ttl]` in `config/initializers/spree.rb`, eg.
-
-```ruby
-Spree::Api::Config[:api_v2_serializers_cache_ttl] = 3600 # 1 hour
-```
-
-This is the setting for caching individual objects (serializers), eg. Products, Orders, etc.
-
-We also have a setting for caching collections of objects (serializers), eg. Product listings. It's `Spree::Api::Config[:api_v2_collection_cache_ttl]`.
-
-```ruby
-Spree::Api::Config[:api_v2_collection_cache_ttl] = 3600 # 1 hour
+cd server
+bin/rails dev:cache
```
-After modifying the settings, you will need to restart your webserver.
+You will need to restart your web server after this.
diff --git a/docs/developer/deployment/database.mdx b/docs/developer/deployment/database.mdx
index 73e9e6ee14..2a666f2ee3 100644
--- a/docs/developer/deployment/database.mdx
+++ b/docs/developer/deployment/database.mdx
@@ -3,8 +3,6 @@ title: Database Configuration
description: Learn how to configure Spree to work with PostgreSQL, MySQL, or SQLite.
---
-Spree works with all major relational databases supported by Ruby on Rails. You can choose the database that best fits your needs.
-
## Supported Databases
| Database | Development | Production | Notes |
diff --git a/docs/developer/deployment/docker.mdx b/docs/developer/deployment/docker.mdx
index f99b8cbd20..637e6cdf79 100644
--- a/docs/developer/deployment/docker.mdx
+++ b/docs/developer/deployment/docker.mdx
@@ -1,34 +1,132 @@
---
title: Docker
-description: Learn how to build a Docker image of your Spree application.
+description: Run the official Spree Docker image or build your own.
---
-Spree (when using Spree Starter template) comes with a Dockerfile that can be used to build a Docker image of your application.
+## Official Docker Image
-You can find the Dockerfile in the [Dockerfile](https://github.com/spree/spree_starter/blob/main/Dockerfile) file in the root of the project or in the Spree Starter repository.
+Spree publishes multi-arch Docker images (`linux/amd64` and `linux/arm64`) to the GitHub Container Registry on every release.
-This Dockerfile is pre-configured to run Spree with a PostgreSQL database by default. You can also use MySQL or SQLite by changing the `DATABASE_URL` environment variable. [Learn more about database configuration](/developer/deployment/database).
+```bash
+docker pull ghcr.io/spree/spree:latest
+```
-You can later use that image to run your application in a containerized environment eg. AWS ECS, AWS Fargate, Azure Container Instances, etc.
+### Available Tags
-## Building the Docker image
+| Tag | Description |
+|-----|-------------|
+| `latest` | Latest stable release |
+| `5.1.3` | Specific version |
+| `5.1` | Latest patch for a minor version |
-```bash
-docker build -t spree .
+Browse all tags on the [GitHub Packages page](https://github.com/spree/spree/pkgs/container/spree).
+
+### Running the Image
+
+The image runs a Puma web server on port 3000. You also need a worker container for background jobs (Sidekiq):
+
+```yaml docker-compose.yml
+services:
+ postgres:
+ image: postgres:17-alpine
+ environment:
+ POSTGRES_HOST_AUTH_METHOD: trust
+ volumes:
+ - postgres_data:/var/lib/postgresql/data
+ healthcheck:
+ test: pg_isready -U postgres
+ interval: 5s
+ timeout: 5s
+ retries: 5
+
+ redis:
+ image: redis:7-alpine
+ volumes:
+ - redis_data:/data
+ healthcheck:
+ test: redis-cli ping
+ interval: 5s
+ timeout: 5s
+ retries: 5
+
+ web:
+ image: ghcr.io/spree/spree:latest
+ depends_on:
+ postgres:
+ condition: service_healthy
+ redis:
+ condition: service_healthy
+ environment:
+ DATABASE_URL: postgres://postgres@postgres:5432/spree_production
+ REDIS_URL: redis://redis:6379/0
+ SECRET_KEY_BASE: change-me-to-a-real-secret
+ RAILS_FORCE_SSL: "false"
+ RAILS_ASSUME_SSL: "false"
+ ports:
+ - "3000:3000"
+ healthcheck:
+ test: curl -f http://localhost:3000/up || exit 1
+ interval: 10s
+ timeout: 5s
+ retries: 10
+ start_period: 30s
+
+ worker:
+ image: ghcr.io/spree/spree:latest
+ depends_on:
+ web:
+ condition: service_healthy
+ environment:
+ DATABASE_URL: postgres://postgres@postgres:5432/spree_production
+ REDIS_URL: redis://redis:6379/0
+ SECRET_KEY_BASE: change-me-to-a-real-secret
+ command: bundle exec sidekiq
+
+volumes:
+ postgres_data:
+ redis_data:
```
-## Running the Docker container
+Start everything:
```bash
-docker run -p 3000:3000 -e SECRET_KEY_BASE=... -e DATABASE_URL=... -e REDIS_URL=... spree
+docker compose up -d
```
-You will need to supply the following environment variables to run the container:
+The database is automatically created and migrated on first boot. The app is available at [http://localhost:3000](http://localhost:3000).
+
+<Tip>
+Use [create-spree-app](/developer/create-spree-app/quickstart) for a fully scaffolded Docker setup with `.env` files, health checks, and optional Next.js storefront — all configured automatically.
+</Tip>
+
+### Required Environment Variables
| Variable | Description | Example |
| --- | --- | --- |
-| `DATABASE_URL` | Database connection URL. Spree supports PostgreSQL, MySQL, and SQLite | `postgres://user:pass@localhost:5432/spree` |
-| `REDIS_URL` | Redis/Valkey URL, used for background jobs processing,this could be your AWS ElastiCache instance or any other Redis/Valkey instance | `redis://localhost:6379/0` |
-| `SECRET_KEY_BASE` | You can generate this by running `bin/rails secret` | `2fad5c0b79d25e4765d3018d8c740f8c3a665f0e5c...` |
+| `DATABASE_URL` | PostgreSQL connection URL | `postgres://user:pass@host:5432/spree` |
+| `REDIS_URL` | Redis URL for jobs, caching, and Action Cable | `redis://redis:6379/0` |
+| `SECRET_KEY_BASE` | Secret key for session encryption | Generate with `bin/rails secret` |
+
+See [Environment Variables](/developer/deployment/environment_variables) for the full list.
+
+## Building Your Own Image
+
+If you have your own Rails application with Spree installed, build a Docker image from your app's Dockerfile:
+
+```bash
+docker build -t my-spree .
+```
+
+Then use your custom image in place of `ghcr.io/spree/spree`:
+
+```bash
+docker run -p 3000:3000 \
+ -e DATABASE_URL=postgres://user:pass@host:5432/spree \
+ -e REDIS_URL=redis://localhost:6379/0 \
+ -e SECRET_KEY_BASE=your-secret \
+ my-spree
+```
-This is the bare minimum you need to run Spree Starter. [Learn more about environment variables](/developer/deployment/environment_variables).
+<Tip>
+When creating a new Rails app with Spree via `rails new -m`, a production-ready Dockerfile is generated automatically by Rails.
+</Tip>
diff --git a/docs/developer/deployment/emails.mdx b/docs/developer/deployment/emails.mdx
index 11d96dd956..2cfd67c1d0 100644
--- a/docs/developer/deployment/emails.mdx
+++ b/docs/developer/deployment/emails.mdx
@@ -4,35 +4,76 @@ sidebarTitle: Emails
description: Learn how to send transactional emails from your Spree application.
---
-Spree uses [ActionMailer](https://guides.rubyonrails.org/action_mailer_basics.html) to send transactional emails (eg. order confirmation, password reset, etc.) under the hood. You can use any SMTP server to send emails from your application. For production use we recommend using a service like [SendGrid](https://sendgrid.com/).
+Spree sends transactional emails such as order confirmation, password reset, shipping notifications, etc. You can use any SMTP provider — Resend, Postmark, Mailgun, SendGrid, Amazon SES, or your own SMTP server.
-## Configuring SendGrid
+## Configuration
-Spree Starter comes with SendGrid pre-configured out of the box and you will need to set the following environment variables:
+Set the following environment variables to enable email delivery:
-* `SENDGRID_API_KEY` - Your SendGrid API key. Can be found in the [SendGrid dashboard](https://app.sendgrid.com/settings/api_keys).
-* `SENDGRID_DOMAIN` - The domain you want to use for sending emails that was verified in SendGrid, eg. `mystore.com`.
+| Variable | Default | Description |
+| --- | --- | --- |
+| `SMTP_HOST` | — | SMTP server address (e.g., `smtp.sendgrid.net`, `smtp.resend.com`) |
+| `SMTP_PORT` | `587` | SMTP server port |
+| `SMTP_USERNAME` | — | SMTP auth username |
+| `SMTP_PASSWORD` | — | SMTP auth password |
+| `SMTP_FROM_ADDRESS` | — | Default "from" email address (e.g., `[email protected]`) |
+| `RAILS_HOST` | `example.com` | Host used in email URLs |
-If you're not using Spree Starter you will need to add these code in your `config/environments/production.rb` file:
+When `SMTP_HOST` is not set, emails are printed to the Rails log instead of being sent.
-```ruby
- if ENV['SENDGRID_API_KEY'].present?
- ActionMailer::Base.smtp_settings = {
- user_name: 'apikey', # This is the string literal 'apikey', NOT the ID of your API key
- password: ENV['SENDGRID_API_KEY'], # This is the secret sendgrid API key which was issued during API key creation
- domain: ENV.fetch('SENDGRID_DOMAIN', Rails.application.routes.default_url_options[:host]),
- address: 'smtp.sendgrid.net',
- port: 587,
- authentication: :plain,
- enable_starttls_auto: true
- }
- end
-```
+### Provider Examples
+
+<Tabs>
+ <Tab title="SendGrid">
+ ```bash
+ SMTP_HOST=smtp.sendgrid.net
+ SMTP_USERNAME=apikey
+ SMTP_PASSWORD=SG.your-sendgrid-api-key
+ ```
+
+ <Warning>
+ Remember to verify the email address in SendGrid you intend to use for sending, otherwise emails will be rejected.
+ [Read more about sender verification](https://www.twilio.com/docs/sendgrid/ui/sending-email/sender-verification).
+ </Warning>
+ </Tab>
+ <Tab title="Resend">
+ ```bash
+ SMTP_HOST=smtp.resend.com
+ SMTP_USERNAME=resend
+ SMTP_PASSWORD=re_your-resend-api-key
+ ```
+ </Tab>
+ <Tab title="Postmark">
+ ```bash
+ SMTP_HOST=smtp.postmarkapp.com
+ SMTP_USERNAME=your-postmark-server-token
+ SMTP_PASSWORD=your-postmark-server-token
+ ```
+ </Tab>
+ <Tab title="Amazon SES">
+ ```bash
+ SMTP_HOST=email-smtp.us-east-1.amazonaws.com
+ SMTP_USERNAME=your-ses-access-key-id
+ SMTP_PASSWORD=your-ses-secret-access-key
+ ```
+ </Tab>
+</Tabs>
-<Warning>
-Remember to verify the email address in SendGrid, you intend to use for sending emails, otherwise emails will be rejected.
+## Local Development
+
+In local development, emails are printed to the Rails log by default. To preview emails with a web UI, run [Mailpit](https://mailpit.axllent.org):
+
+```bash
+docker run -d --name mailpit -p 8025:8025 -p 1025:1025 axllent/mailpit
+SMTP_HOST=localhost bin/dev
+```
-[Read more about SendGrid sender verification](https://www.twilio.com/docs/sendgrid/ui/sending-email/sender-verification)
-</Warning>
+Open [http://localhost:8025](http://localhost:8025) to see all outgoing emails.
-That's it! You can now send emails from your application.
\ No newline at end of file
+<Tip>
+If you're using `docker compose up` for development, Mailpit is included automatically and all emails are caught at [http://localhost:8025](http://localhost:8025).
+</Tip>
diff --git a/docs/developer/deployment/environment_variables.mdx b/docs/developer/deployment/environment_variables.mdx
index 30b7d3a47d..e127f60ce8 100644
--- a/docs/developer/deployment/environment_variables.mdx
+++ b/docs/developer/deployment/environment_variables.mdx
@@ -2,44 +2,89 @@
title: Environment Variables
---
-[Spree Starter](https://github.com/spree/spree_starter) uses several environment variables to configure the application.
+Spree uses environment variables for all deployment configuration. No secrets or credentials are stored in the codebase.
-## Required environment variables
+## Required
-This variables are required to run Spree Starter.
+These variables are required to run Spree in production.
| Variable | Description | Example |
| --- | --- | --- |
-| `DATABASE_URL` | Database connection URL. Spree supports PostgreSQL, MySQL, and SQLite | `postgres://user:pass@localhost:5432/spree` |
-| `REDIS_URL` | Redis/Valkey URL, used for background jobs processing,this could be your AWS ElastiCache instance or any other Redis/Valkey instance | `redis://localhost:6379/0` |
-| `SECRET_KEY_BASE` | You can generate this by running `bin/rails secret` | `2fad5c0b79d25e4765d3018d8c740f8c3a665f0e5c...` |
+| `DATABASE_URL` | PostgreSQL connection URL | `postgres://user:pass@localhost:5432/spree` |
+| `REDIS_URL` | Redis URL for background jobs (Sidekiq), caching, and Action Cable | `redis://localhost:6379/0` |
+| `SECRET_KEY_BASE` | Secret key for session encryption. Generate with `bin/rails secret` | `2fad5c0b79d25e4765d3018d8c740f8c3a665f0e5c...` |
-### Database URL examples
+## Email (SMTP)
-Spree supports PostgreSQL, MySQL, and SQLite. Set the `DATABASE_URL` according to your database:
+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.
-| Database | Example |
-|----------|---------|
-| PostgreSQL | `postgres://user:pass@localhost:5432/spree` |
-| MySQL | `mysql2://user:pass@localhost:3306/spree` |
-| SQLite | `sqlite3:db/production.sqlite3` |
+| Variable | Default | Description |
+| --- | --- | --- |
+| `SMTP_HOST` | — | SMTP server address (e.g., `smtp.sendgrid.net`) |
+| `SMTP_PORT` | `587` | SMTP server port |
+| `SMTP_USERNAME` | — | SMTP auth username |
+| `SMTP_PASSWORD` | — | SMTP auth password |
+| `SMTP_FROM_ADDRESS` | — | Default "from" email address |
+| `RAILS_HOST` | `example.com` | Host used in email URLs |
+
+## Web Server
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `PORT` | `3000` | Web server port |
+| `RAILS_MAX_THREADS` | `3` | Puma threads per worker |
+| `WEB_CONCURRENCY` | `1` | Number of Puma workers. Set to `auto` for one per CPU core |
+
+## Application
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `RAILS_ENV` | `production` | Rails environment |
+| `RAILS_LOG_LEVEL` | `info` | Log level (`debug`, `info`, `warn`, `error`) |
+
+## File Storage (S3 / Cloudflare R2)
+
+By default, uploaded files (product images, assets) are stored on the local filesystem. Set the appropriate credentials to use cloud storage instead. Spree auto-detects the provider based on which credentials are present.
+
+### Amazon S3
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `AWS_ACCESS_KEY_ID` | — | AWS access key |
+| `AWS_SECRET_ACCESS_KEY` | — | AWS secret key |
+| `AWS_REGION` | — | AWS region (e.g., `us-east-1`) |
+| `AWS_BUCKET` | `spree-production` | S3 bucket name |
+
+### Cloudflare R2
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `CLOUDFLARE_ENDPOINT` | — | R2 endpoint URL |
+| `CLOUDFLARE_ACCESS_KEY_ID` | — | R2 access key |
+| `CLOUDFLARE_SECRET_ACCESS_KEY` | — | R2 secret key |
+| `CLOUDFLARE_BUCKET` | `spree-production` | R2 bucket name |
+
+## Error Tracking (Sentry)
-[Learn more about database configuration](/developer/deployment/database).
+| Variable | Default | Description |
+| --- | --- | --- |
+| `SENTRY_DSN` | — | [Sentry](https://sentry.io/) DSN. When set, errors are reported to Sentry |
-## Optional environment variables
+## SSL
-There are also some other environment variables that you can set to customize your Spree application.
+By default, Spree assumes it runs behind an SSL-terminating reverse proxy. Set these to `false` if running without SSL (e.g., local development or behind a proxy that doesn't do SSL termination).
-| Variable | Description | Default value | Example |
-| --- | --- | --- | --- |
-| `DEVISE_SESSION_TIMEOUT` | Session timeout (in days) | `14` | `30` |
-| `GOOGLE_PLACES_API_KEY` | [Google Places API key](https://developers.google.com/places/web-service/get-api-key) (optional, used on checkout for address autocomplete) | | `ABCD1234567890` |
-| `PORT` | Web server port | `3000` | `4000` |
-| `RAILS_ENV` | Rails environment (production, development, test) | `production` | `staging` |
-| `RAILS_LOG_LEVEL` | Log level, you can switch it to `debug` to see more detailed logs | `info` | `debug` |
-| `RAILS_MAX_THREADS` | Web server (Puma) threads | `3` | `5` |
-| `REDIS_CACHE_URL` | Redis/Valkey URL, used for caching, this could be your AWS ElastiCache instance or any other Redis/Valkey instance (optional, if not provided will use file based cache) | | `redis://localhost:6379/1` |
-| `SCREENSHOT_API_TOKEN` | [Screenshot API token](https://screenshotapi.net/) (optional, used for screenshot generation) | | `1234132512341234` |
-| `SENDGRID_API_KEY` | [SendGrid API key](https://docs.sendgrid.com/api-reference/api-keys) (optional, if not provided will not send transactional emails) | | `SG.1234567890` |
-| `SENDGRID_DOMAIN` | The domain you want to use for sending emails that was verified in SendGrid | | `mystore.com` |
-| `SENTRY_DSN` | Sentry DSN (optional, if not provided will not send errors to [Sentry](https://sentry.io/)) | | `https://sentry.io/...` |
+| Variable | Default | Description |
+| --- | --- | --- |
+| `RAILS_ASSUME_SSL` | `true` | Assume requests arrive via SSL (sets `X-Forwarded-Proto`) |
+| `RAILS_FORCE_SSL` | `true` | Redirect HTTP to HTTPS and use secure cookies |
+
+## Local Development
+
+These variables are used when running the `server/` app locally (not via `DATABASE_URL`):
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `DATABASE_HOST` | `localhost` | PostgreSQL host |
+| `DATABASE_PORT` | `5432` | PostgreSQL port |
+| `DATABASE_USERNAME` | `postgres` | PostgreSQL user |
diff --git a/docs/developer/getting-started/quickstart.mdx b/docs/developer/getting-started/quickstart.mdx
index 38a3c171c1..bf89eace91 100644
--- a/docs/developer/getting-started/quickstart.mdx
+++ b/docs/developer/getting-started/quickstart.mdx
@@ -4,41 +4,29 @@ sidebarTitle: Installation
description: "Follow the instructions below to learn how to build and deploy your Spree application."
---
-<Info>
- Spree works with **PostgreSQL**, **MySQL**, and **SQLite** databases. The installer defaults to SQLite for quick setup. You can switch to PostgreSQL or MySQL at any time later. [Learn more about database configuration](/developer/deployment/database).
-</Info>
-
## Installation options
<Tabs>
- <Tab title="Spree Installer">
- Use the guided installer to set up your Spree application with all the required dependencies (system libraries, Ruby language) on your system.
+ <Tab title="create-spree-app">
+ The quickest way to get started. Scaffolds a full Spree project with Next.js Storefront (optional).
- Copy and paste the following command to your terminal:
+ **Requirements:** [Node.js](https://nodejs.org/) 20+ and [Docker](https://docs.docker.com/get-docker/) running.
```bash
- bash -c "$(curl -fsSL https://spreecommerce.org/install)"
+ npx create-spree-app@latest my-store
```
- This will fire up the guided installer that will ask you a few questions (eg. application name, load sample data, etc.) and then set up your Spree application.
+ The CLI walks you through an interactive setup:
- <Info>
- **System Requirements**
-
- MacOS:
- * MacOS 14.0+
- * XCode command line tools installed
-
- Windows:
- * Windows Subsystem for Linux is required, you can install it via `wsl --install`
- </Info>
+ 1. Choose **Full-stack** (Backend + Next.js Storefront) or **Backend only**
+ 2. Optionally load **sample data** (products, categories, images)
- <Info>
- If you have any issues with the installer, please create an issue on [GitHub](https://github.com/spree/spree/issues/new). Thank you!
- </Info>
+ Once complete, your store should be running at [http://localhost:3000/admin](http://localhost:3000/admin). The port can be different if `3000` is already used on your system.
+
+ See the full [create-spree-app documentation](/developer/create-spree-app/quickstart) for all CLI flags and options.
</Tab>
<Tab title="Manual Installation">
- If you prefer to install Spree manually, you're free to do so.
+ For developers who prefer full control over the setup, or want to add Spree to an existing Rails application.
1. Install [Ruby](https://www.ruby-lang.org/en/documentation/installation/)
2. Install [vips](https://www.libvips.org/install.html) for image processing
@@ -46,7 +34,7 @@ description: "Follow the instructions below to learn how to build and deploy you
```bash
gem install rails
```
- 4. Run the following command to create a new Spree application:
+ 4. Create a new Spree application:
```bash
rails new my_store -m https://raw.githubusercontent.com/spree/spree/main/spree/template.rb
```
@@ -55,11 +43,11 @@ description: "Follow the instructions below to learn how to build and deploy you
rails new my_store -d postgresql -m https://raw.githubusercontent.com/spree/spree/main/spree/template.rb
rails new my_store -d mysql -m https://raw.githubusercontent.com/spree/spree/main/spree/template.rb
```
- 5. Navigate to the application directory
+ 5. Navigate to the application directory:
```bash
cd my_store
```
- 6. Run the following command to start the development server:
+ 6. Start the development server:
```bash
bin/dev
```
@@ -67,24 +55,21 @@ description: "Follow the instructions below to learn how to build and deploy you
```bash
bin/rails spree_sample:load
```
+
+ <Info>
+ Spree works with **PostgreSQL**, **MySQL**, and **SQLite** databases. The Rails template defaults to SQLite for quick setup. You can switch to PostgreSQL or MySQL at any time. [Learn more about database configuration](/developer/deployment/database).
+ </Info>
</Tab>
</Tabs>
## Accessing Admin Panel
-Use your browser window to navigate to [http://localhost:3000/admin](http://localhost:3000/admin). You can log in with the credentials you've chosen during installation, the defaults are:
-
-login:
-
-```
-```
-
-password:
+Navigate to [http://localhost:3000/admin](http://localhost:3000/admin) and log in with the default credentials:
-```
-spree123
-```
+| | |
+|---|---|
+| **Email** | `[email protected]` |
+| **Password** | `spree123` |
Upon successful authentication, you should see the admin screen:
diff --git a/docs/developer/how-to/custom-payment-method.mdx b/docs/developer/how-to/custom-payment-method.mdx
new file mode 100644
index 0000000000..d79069c7ca
--- /dev/null
+++ b/docs/developer/how-to/custom-payment-method.mdx
@@ -0,0 +1,364 @@
+---
+title: Build a Custom Payment Method
+description: Step-by-step guide to creating a custom payment gateway integration with Payment Sessions, 3D Secure, and PCI compliance.
+---
+
+## Overview
+
+This guide walks you through building a custom payment method integration for Spree. By the end, you'll have a fully functional payment gateway that:
+
+- Appears as a payment option during checkout
+- Uses Payment Sessions for PCI-compliant payment collection
+- Supports 3D Secure and alternative payment methods
+- Handles webhooks for reliable payment confirmation
+- Optionally supports saving payment methods for future use (Payment Setup Sessions)
+
+Before starting, make sure you understand [how payments work in Spree](/developer/core-concepts/payments).
+
+## Step 1: Create the Payment Method Model
+
+Create a new model inheriting from `Spree::PaymentMethod`. This is the central class that defines how your gateway processes payments.
+
+```ruby app/models/my_gateway.rb
+class MyGateway < Spree::PaymentMethod
+ preference :api_key, :string
+ preference :publishable_key, :string
+ preference :webhook_secret, :string
+
+ def payment_icon_name
+ 'my-gateway'
+ end
+end
+```
+
+## Step 2: Register the Payment Method
+
+Add your gateway to the list of available payment methods so it appears in the admin panel:
+
+```ruby config/initializers/spree.rb
+Rails.application.config.after_initialize do
+ Spree.payment_methods << MyGateway
+end
+```
+
+After restarting your server, you can select "MyGateway" when creating a new payment method in the admin panel under **Settings > Payments**.
+
+## Step 3: Add Payment Session Support
+
+Payment Sessions are the modern, PCI-compliant way to handle payments. Your gateway creates a session with the provider, the frontend collects payment details using the provider's SDK, and Spree records the result.
+
+### Define the STI Subclass
+
+Create a Payment Session subclass for your gateway. This uses Single Table Inheritance (STI) on the `spree_payment_sessions` table:
+
+```ruby app/models/spree/payment_sessions/my_gateway.rb
+module Spree
+ module PaymentSessions
+ class MyGateway < Spree::PaymentSession
+ # Add gateway-specific helper methods here
+
+ def client_secret
+ external_data['client_secret']
+ end
+ end
+ end
+end
+```
+
+### Implement Session Methods on the Gateway
+
+Override the key methods on your `PaymentMethod` subclass:
+
+```ruby app/models/my_gateway.rb
+class MyGateway < Spree::PaymentMethod
+ preference :api_key, :string
+ preference :publishable_key, :string
+ preference :webhook_secret, :string
+
+ # Tell Spree this gateway uses Payment Sessions
+ def session_required?
+ true
+ end
+
+ # Return the STI subclass
+ def payment_session_class
+ Spree::PaymentSessions::MyGateway
+ end
+
+ # No source required upfront — it's created when the session completes
+ def source_required?
+ false
+ end
+
+ # Create a session with your payment provider
+ def create_payment_session(order:, amount: nil, external_data: {})
+ total = amount || order.total_minus_store_credits
+
+ # Call your provider's API to create a payment session
+ provider_session = MyProvider::Client.new(preferred_api_key).create_session(
+ amount: (total * 100).to_i, # amount in cents
+ currency: order.currency,
+ metadata: { order_number: order.number }
+ )
+
+ payment_sessions.create!(
+ order: order,
+ amount: total,
+ currency: order.currency,
+ external_id: provider_session.id,
+ external_data: {
+ client_secret: provider_session.client_secret
+ },
+ customer: order.user
+ )
+ end
+
+ # Update an existing session (e.g., when order total changes)
+ def update_payment_session(payment_session:, amount: nil, external_data: {})
+ if amount.present?
+ MyProvider::Client.new(preferred_api_key).update_session(
+ payment_session.external_id,
+ amount: (amount * 100).to_i
+ )
+ payment_session.update!(amount: amount)
+ end
+
+ payment_session
+ end
+
+ # Complete the session after the customer pays on the frontend
+ def complete_payment_session(payment_session:, params: {})
+ # Verify the payment with your provider
+ result = MyProvider::Client.new(preferred_api_key).retrieve_session(
+ payment_session.external_id
+ )
+
+ if result.status == 'succeeded'
+ payment_session.process!
+
+ # Create the Spree::Payment record
+ payment = payment_session.order.payments.create!(
+ amount: payment_session.amount,
+ payment_method: self,
+ response_code: payment_session.external_id,
+ state: 'checkout'
+ )
+
+ # Transition the payment to completed
+ payment.started_processing!
+ payment.complete!
+
+ payment_session.complete!
+ else
+ payment_session.fail!
+ end
+
+ payment_session
+ end
+
+ def payment_icon_name
+ 'my-gateway'
+ end
+end
+```
+
+### How the Frontend Uses It
+
+The frontend creates a session, then uses the provider's SDK to collect payment:
+
+```typescript
+// 1. Get available payment methods
+const methods = await client.store.orders.paymentMethods.list(cart.id, options)
+
+// 2. Find your gateway (check session_required flag)
+const myGateway = methods.find(m => m.session_required)
+
+// 3. Create a payment session
+const session = await client.store.orders.paymentSessions.create(cart.id, {
+ payment_method_id: myGateway.id,
+}, options)
+
+// 4. Use the client_secret with your provider's frontend SDK
+const result = await MyProviderSDK.confirmPayment(session.external_data.client_secret)
+
+// 5. Complete the session
+const completed = await client.store.orders.paymentSessions.complete(
+ cart.id, session.id,
+ { session_result: result.id },
+ options
+)
+```
+
+## Step 4: Handle Webhooks (Recommended)
+
+Webhooks ensure payments are captured even if the customer closes their browser before the frontend can call `complete`. This is critical for production reliability.
+
+```ruby app/controllers/my_gateway/webhooks_controller.rb
+module MyGateway
+ class WebhooksController < ApplicationController
+ skip_before_action :verify_authenticity_token
+
+ def create
+ payload = request.body.read
+ signature = request.headers['X-Signature']
+
+ # Verify webhook authenticity
+ unless MyProvider::Webhook.verify(payload, signature, gateway.preferred_webhook_secret)
+ head :unauthorized
+ return
+ end
+
+ event = JSON.parse(payload)
+
+ case event['type']
+ when 'payment.succeeded'
+ handle_payment_succeeded(event['data'])
+ when 'payment.failed'
+ handle_payment_failed(event['data'])
+ end
+
+ head :ok
+ end
+
+ private
+
+ def handle_payment_succeeded(data)
+ payment_session = Spree::PaymentSession.find_by(external_id: data['session_id'])
+ return unless payment_session
+ return if payment_session.completed?
+
+ gateway.complete_payment_session(payment_session: payment_session)
+ end
+
+ def handle_payment_failed(data)
+ payment_session = Spree::PaymentSession.find_by(external_id: data['session_id'])
+ return unless payment_session
+
+ payment_session.fail! unless payment_session.failed?
+ end
+
+ def gateway
+ @gateway ||= MyGateway.active.first
+ end
+ end
+end
+```
+
+Add the webhook route:
+
+```ruby config/routes.rb
+post '/my-gateway/webhooks', to: 'my_gateway/webhooks#create'
+```
+
+## Step 5: Control Payment Method Visibility (Optional)
+
+Override visibility methods to control where and when your payment method appears:
+
+```ruby app/models/my_gateway.rb
+class MyGateway < Spree::PaymentMethod
+ # Only show for stores that support specific currencies
+ def available_for_store?(store)
+ store.supported_currencies.include?('EUR')
+ end
+
+ # Only show for orders above a certain amount
+ def available_for_order?(order)
+ order.total > 10 && order.currency == 'EUR'
+ end
+end
+```
+
+## Step 6: Add Payment Setup Session Support (Optional)
+
+If your provider supports saving payment methods for future use (like Stripe's SetupIntent), you can add Payment Setup Session support:
+
+```ruby app/models/my_gateway.rb
+class MyGateway < Spree::PaymentMethod
+ # ... existing code ...
+
+ def setup_session_supported?
+ true
+ end
+
+ def payment_setup_session_class
+ Spree::PaymentSetupSessions::MyGateway
+ end
+
+ def create_payment_setup_session(customer:, external_data: {})
+ provider_setup = MyProvider::Client.new(preferred_api_key).create_setup_session(
+ customer_id: find_or_create_provider_customer(customer)
+ )
+
+ payment_setup_sessions.create!(
+ customer: customer,
+ external_id: provider_setup.id,
+ external_client_secret: provider_setup.client_secret
+ )
+ end
+
+ def complete_payment_setup_session(setup_session:, params: {})
+ result = MyProvider::Client.new(preferred_api_key).retrieve_setup_session(
+ setup_session.external_id
+ )
+
+ if result.status == 'succeeded'
+ # Create a saved payment source
+ credit_card = Spree::CreditCard.create!(
+ payment_method: self,
+ user: setup_session.customer,
+ gateway_payment_profile_id: result.payment_method_id,
+ cc_type: result.card_brand,
+ last_digits: result.card_last4,
+ month: result.card_exp_month,
+ year: result.card_exp_year,
+ name: result.cardholder_name
+ )
+
+ setup_session.update!(
+ payment_source: credit_card
+ )
+ setup_session.complete!
+ else
+ setup_session.fail!
+ end
+
+ setup_session
+ end
+end
+```
+
+And the STI subclass:
+
+```ruby app/models/spree/payment_setup_sessions/my_gateway.rb
+module Spree
+ module PaymentSetupSessions
+ class MyGateway < Spree::PaymentSetupSession
+ end
+ end
+end
+```
+
+## Gateway Options Reference
+
+For every gateway action (authorize, purchase, capture, void, credit), Spree passes a hash of gateway options:
+
+| Option | Description |
+|--------------------|-----------------------------------------------------------------------------------------------|
+| `email` and `customer` | The email address related to the order |
+| `ip` | The last IP address for the order |
+| `order_id` | The Order's `number` attribute, plus the `identifier` for each payment |
+| `shipping` | The total shipping cost for the order, in cents |
+| `tax` | The total tax cost for the order, in cents |
+| `subtotal` | The item total for the order, in cents |
+| `currency` | The 3-character currency code for the order |
+| `discount` | The promotional discount applied to the order |
+| `billing_address` | A hash containing billing address information |
+| `shipping_address` | A hash containing shipping address information |
+
+## Related Documentation
+
+- [Payments](/developer/core-concepts/payments) - Payment architecture and core concepts
+- [Checkout Customization](/developer/customization/checkout) - Customizing the checkout flow
+- [Events](/developer/core-concepts/events) - Subscribe to payment events
+- [Stripe Integration](/integrations/payments/stripe) - Reference implementation using Stripe
+- [Adyen Integration](/integrations/payments/adyen) - Reference implementation using Adyen
diff --git a/docs/developer/how-to/custom-promotion.mdx b/docs/developer/how-to/custom-promotion.mdx
new file mode 100644
index 0000000000..81f059e2f8
--- /dev/null
+++ b/docs/developer/how-to/custom-promotion.mdx
@@ -0,0 +1,373 @@
+---
+title: Build Custom Promotion Rules & Actions
+description: Step-by-step guide to creating custom promotion rules and actions for business-specific eligibility logic and discount behaviors.
+---
+
+## Overview
+
+Spree's promotion system is built around two extension points: **Rules** (eligibility conditions) and **Actions** (what happens when a promotion applies). While Spree ships with a comprehensive set of [built-in rules and actions](/developer/core-concepts/promotions#rules), you can create custom ones for business-specific logic.
+
+This guide covers:
+- Creating a custom promotion rule with admin UI
+- Creating a custom promotion action with a calculator
+- Understanding the `eligible?`, `actionable?`, and `perform` contracts
+
+Before starting, make sure you understand [how promotions work in Spree](/developer/core-concepts/promotions).
+
+## Custom Promotion Rules
+
+Rules determine whether a promotion is eligible for a given order. Each rule implements `eligible?` which returns `true` or `false`.
+
+### Step 1: Create the Rule Class
+
+Create a new class inheriting from `Spree::PromotionRule`:
+
+```ruby app/models/spree/promotion/rules/minimum_quantity.rb
+module Spree
+ class Promotion
+ module Rules
+ class MinimumQuantity < Spree::PromotionRule
+ preference :quantity, :integer, default: 5
+
+ def applicable?(promotable)
+ promotable.is_a?(Spree::Order)
+ end
+
+ def eligible?(order, options = {})
+ total_quantity = order.line_items.sum(&:quantity)
+
+ if total_quantity >= preferred_quantity
+ true
+ else
+ eligibility_errors.add(
+ :base,
+ "Order must contain at least #{preferred_quantity} items"
+ )
+ false
+ end
+ end
+ end
+ end
+ end
+end
+```
+
+#### Key Methods to Implement
+
+| Method | Required | Description |
+|--------|----------|-------------|
+| `applicable?(promotable)` | Yes | Returns `true` if this rule type can evaluate the promotable (usually `promotable.is_a?(Spree::Order)`) |
+| `eligible?(promotable, options = {})` | Yes | Returns `true` if the promotable meets this rule's conditions. Add messages to `eligibility_errors` to explain why not. |
+| `actionable?(line_item)` | No | Returns `true` if a specific line item should receive the promotion's action. Defaults to `true`. Override this for rules that target specific items (like product or category rules). |
+
+The `options` hash passed to `eligible?` can include `:user`, `:email`, and other context from the checkout flow.
+
+#### Using Preferences
+
+Rules use Spree's preference system for configuration. Each preference creates getter/setter methods automatically:
+
+```ruby
+preference :amount, :decimal, default: 100.00
+preference :operator, :string, default: 'gte'
+preference :category_ids, :array, default: []
+
+# These create:
+# preferred_amount / preferred_amount=
+# preferred_operator / preferred_operator=
+# preferred_category_ids / preferred_category_ids=
+```
+
+Available types: `:string`, `:integer`, `:decimal`, `:boolean`, `:array`.
+
+### Step 2: Register the Rule
+
+Add your rule to the promotion configuration so it appears in the admin panel:
+
+```ruby config/initializers/spree.rb
+Rails.application.config.after_initialize do
+ Spree.promotions.rules << Spree::Promotion::Rules::MinimumQuantity
+end
+```
+
+### Step 3: Create the Admin Partial
+
+Create a form partial so admins can configure the rule's preferences. The partial name must match the rule class name in underscore format:
+
+```erb app/views/spree/admin/promotions/rules/_minimum_quantity.html.erb
+<div class="row mb-3">
+ <%= f.spree_number_field :preferred_quantity, label: Spree.t(:minimum_quantity) %>
+</div>
+```
+
+### Step 4: Add Translations
+
+```yaml config/locales/en.yml
+en:
+ spree:
+ minimum_quantity: Minimum Quantity
+ promotion_rule_types:
+ minimum_quantity:
+ name: Minimum Quantity
+ description: Order must contain at least X items
+```
+
+### Step 5: Restart and Test
+
+After restarting your application, the new rule will be available in **Admin > Promotions** when adding rules to a promotion.
+
+### Example: Rule with `actionable?`
+
+When your rule targets specific line items (not the whole order), implement `actionable?` so that actions like `CreateItemAdjustments` only discount matching items:
+
+```ruby app/models/spree/promotion/rules/brand.rb
+module Spree
+ class Promotion
+ module Rules
+ class Brand < Spree::PromotionRule
+ preference :brand_names, :array, default: []
+
+ def applicable?(promotable)
+ promotable.is_a?(Spree::Order)
+ end
+
+ def eligible?(order, options = {})
+ order.line_items.any? { |li| matches_brand?(li) }
+ end
+
+ # Only discount line items from matching brands
+ def actionable?(line_item)
+ matches_brand?(line_item)
+ end
+
+ private
+
+ def matches_brand?(line_item)
+ brand = line_item.product.get_metafield('details.brand')&.value
+ preferred_brand_names.include?(brand)
+ end
+ end
+ end
+ end
+end
+```
+
+## Custom Promotion Actions
+
+Actions define what happens when a promotion is applied. Most actions create [adjustments](/developer/core-concepts/adjustments) on orders or line items.
+
+### Step 1: Create the Action Class
+
+#### Discount Action (with Calculator)
+
+For actions that create monetary adjustments, include `Spree::CalculatedAdjustments` and `Spree::AdjustmentSource`:
+
+```ruby app/models/spree/promotion/actions/tiered_discount.rb
+module Spree
+ class Promotion
+ module Actions
+ class TieredDiscount < Spree::PromotionAction
+ include Spree::CalculatedAdjustments
+ include Spree::AdjustmentSource
+
+ before_validation -> { self.calculator ||= Calculator::FlatRate.new }
+
+ def perform(options = {})
+ order = options[:order]
+ return false unless order.present?
+
+ create_unique_adjustment(order, order)
+ end
+
+ def compute_amount(order)
+ # Tiered discount: $10 off orders over $50, $25 off orders over $100
+ discount = case order.item_total
+ when 100..Float::INFINITY then 25
+ when 50..99.99 then 10
+ else 0
+ end
+
+ # Must return negative amount for discounts
+ # Cap at order total to prevent negative orders
+ [discount, order.item_total].min * -1
+ end
+ end
+ end
+ end
+end
+```
+
+#### Non-Discount Action
+
+For actions that don't create adjustments (e.g., awarding points, sending notifications):
+
+```ruby app/models/spree/promotion/actions/add_loyalty_points.rb
+module Spree
+ class Promotion
+ module Actions
+ class AddLoyaltyPoints < Spree::PromotionAction
+ preference :points, :integer, default: 100
+
+ def perform(options = {})
+ order = options[:order]
+ return false unless order.user.present?
+
+ order.user.add_loyalty_points(preferred_points, source: promotion)
+ true
+ end
+ end
+ end
+ end
+end
+```
+
+#### Key Methods to Implement
+
+| Method | Required | Description |
+|--------|----------|-------------|
+| `perform(options = {})` | Yes | Called when the promotion is activated. `options` includes `:order` and `:promotion`. Return `true` if the action was applied. |
+| `compute_amount(adjustable)` | For discount actions | Return the adjustment amount (negative for discounts). Cap at the adjustable's total to prevent negative amounts. |
+| `revert(options = {})` | No | Called when a promotion is deactivated. Use to undo side effects (e.g., remove added line items). |
+
+#### Available Helper Methods
+
+When you include `Spree::AdjustmentSource`, you get:
+
+```ruby
+# Create a single adjustment (e.g., on the order)
+create_unique_adjustment(order, adjustable)
+
+# Create adjustments on multiple items (e.g., all line items)
+create_unique_adjustments(order, order.line_items)
+
+# With a filter block (e.g., only actionable line items)
+create_unique_adjustments(order, order.line_items) do |line_item|
+ promotion.line_item_actionable?(order, line_item)
+end
+```
+
+When you include `Spree::CalculatedAdjustments`, you get:
+
+```ruby
+# Delegate to the calculator
+compute(adjustable) # calls calculator.compute(adjustable)
+
+# Set calculator by class name
+self.calculator_type = 'Spree::Calculator::FlatRate'
+
+# List available calculators for this action type
+self.class.calculators
+```
+
+### Step 2: Register the Action
+
+```ruby config/initializers/spree.rb
+Rails.application.config.after_initialize do
+ Spree.promotions.actions << Spree::Promotion::Actions::TieredDiscount
+end
+```
+
+### Step 3: Add Translations
+
+```yaml config/locales/en.yml
+en:
+ spree:
+ promotion_action_types:
+ tiered_discount:
+ name: Tiered Discount
+ description: Different discount amounts based on order total tiers
+```
+
+### Step 4: Restart and Test
+
+After restarting, the new action will be available in **Admin > Promotions** when adding actions to a promotion.
+
+## How Rules and Actions Work Together
+
+Understanding how Spree evaluates promotions helps you build better custom rules and actions:
+
+```mermaid
+flowchart TD
+ A[Order Updated] --> B[PromotionHandler::Cart]
+ B --> C{For each promotion}
+ C --> D{Check dates & usage}
+ D -->|expired/exceeded| E[Deactivate]
+ D -->|valid| F{Evaluate rules}
+ F -->|match_policy: all| G[ALL rules must pass]
+ F -->|match_policy: any| H[ANY rule must pass]
+ G -->|eligible| I[Run actions]
+ H -->|eligible| I
+ G -->|ineligible| E
+ H -->|ineligible| E
+ I --> J[action.perform for each action]
+ J --> K[Create adjustments]
+ K --> L[Best promotion wins]
+```
+
+**Key points:**
+- `match_policy: 'all'` means every rule must return `eligible? == true`
+- `match_policy: 'any'` means at least one rule must return `eligible? == true`
+- For item-level actions (`CreateItemAdjustments`), `actionable?(line_item)` on each rule filters which line items get the discount
+- When multiple promotions compete, Spree picks the best one (largest discount) and marks others as ineligible
+
+## Testing Custom Rules and Actions
+
+```ruby spec/models/spree/promotion/rules/minimum_quantity_spec.rb
+require 'spec_helper'
+
+RSpec.describe Spree::Promotion::Rules::MinimumQuantity do
+ let(:rule) { described_class.new(preferred_quantity: 3) }
+ let(:order) { create(:order_with_line_items, line_items_count: 1) }
+
+ describe '#eligible?' do
+ context 'when order has enough items' do
+ before { order.line_items.first.update(quantity: 3) }
+
+ it { expect(rule.eligible?(order)).to be true }
+ end
+
+ context 'when order does not have enough items' do
+ it { expect(rule.eligible?(order)).to be false }
+
+ it 'sets eligibility error' do
+ rule.eligible?(order)
+ expect(rule.eligibility_errors.full_messages).to include(
+ /at least 3 items/
+ )
+ end
+ end
+ end
+end
+```
+
+```ruby spec/models/spree/promotion/actions/tiered_discount_spec.rb
+require 'spec_helper'
+
+RSpec.describe Spree::Promotion::Actions::TieredDiscount do
+ let(:promotion) { create(:promotion) }
+ let(:action) { described_class.create!(promotion: promotion) }
+
+ describe '#compute_amount' do
+ it 'returns -10 for orders over $50' do
+ order = build(:order, item_total: 75)
+ expect(action.compute_amount(order)).to eq(-10)
+ end
+
+ it 'returns -25 for orders over $100' do
+ order = build(:order, item_total: 150)
+ expect(action.compute_amount(order)).to eq(-25)
+ end
+
+ it 'returns 0 for orders under $50' do
+ order = build(:order, item_total: 30)
+ expect(action.compute_amount(order)).to eq(0)
+ end
+ end
+end
+```
+
+## Related Documentation
+
+- [Promotions](/developer/core-concepts/promotions) - Promotion architecture and built-in rules/actions
+- [Calculators](/developer/core-concepts/calculators) - Available calculator types for promotion actions
+- [Adjustments](/developer/core-concepts/adjustments) - How adjustments work on orders and line items
+- [Events](/developer/core-concepts/events) - Subscribe to promotion events
diff --git a/docs/developer/how-to/custom-report.mdx b/docs/developer/how-to/custom-report.mdx
new file mode 100644
index 0000000000..2c31270d43
--- /dev/null
+++ b/docs/developer/how-to/custom-report.mdx
@@ -0,0 +1,387 @@
+---
+title: Build a Custom Report
+description: Step-by-step guide to creating custom reports with data queries, line item formatters, and CSV export.
+---
+
+## Overview
+
+Spree's reporting system is designed for extension. Each report is a pair of classes — a **Report** that defines the data query and a **ReportLineItem** that formats each row — registered in `Spree.reports` so it appears in the admin UI.
+
+This guide walks you through building a custom report from scratch, including advanced patterns for SQL aggregations and multi-vendor support.
+
+Before starting, make sure you understand [how the reporting system works](/developer/core-concepts/reports).
+
+## Creating a Custom Report
+
+### Step 1: Create the Report Class
+
+Create a new report class inheriting from `Spree::Report`. The key method to implement is `line_items_scope`, which returns an `ActiveRecord::Relation` defining the records in your report:
+
+```ruby app/models/spree/reports/customer_orders.rb
+module Spree
+ module Reports
+ class CustomerOrders < Spree::Report
+ # Define the scope of records to include in the report
+ def line_items_scope
+ store.orders.complete.where(
+ completed_at: date_from..date_to,
+ currency: currency
+ ).includes(:user, :bill_address)
+ end
+ end
+ end
+end
+```
+
+The `line_items_scope` method has access to:
+
+| Helper | Description |
+|--------|-------------|
+| `store` | The current store |
+| `date_from` | Report start date |
+| `date_to` | Report end date |
+| `currency` | Report currency |
+| `vendor` | Vendor (if multi-vendor is enabled) |
+
+### Step 2: Create the Line Item Class
+
+Create a corresponding line item class that transforms each record into report columns. The class name must match the report class name (e.g., `Reports::CustomerOrders` → `ReportLineItems::CustomerOrders`):
+
+```ruby app/models/spree/report_line_items/customer_orders.rb
+module Spree
+ module ReportLineItems
+ class CustomerOrders < Spree::ReportLineItem
+ # Define attributes that will become columns
+ attribute :order_number, :string
+ attribute :completed_at, :string
+ attribute :customer_email, :string
+ attribute :customer_name, :string
+ attribute :item_count, :integer
+ attribute :total, :string
+
+ # Map record fields to report columns
+ def order_number
+ record.number
+ end
+
+ def completed_at
+ record.completed_at.strftime('%Y-%m-%d %H:%M')
+ end
+
+ def customer_email
+ record.email
+ end
+
+ def customer_name
+ record.bill_address&.full_name
+ end
+
+ def item_count
+ record.line_items.sum(:quantity)
+ end
+
+ def total
+ Spree::Money.new(record.total, currency: currency)
+ end
+ end
+ end
+end
+```
+
+**Important notes:**
+- Use `attribute` to define columns with their types — these become CSV headers
+- Each attribute needs a corresponding method that extracts/formats data from `record`
+- `record` is a single item from `line_items_scope`
+- Use `Spree::Money` for currency formatting
+- `currency` and `store` are delegated from the report
+
+#### Available Base Class Methods
+
+`Spree::ReportLineItem` provides:
+
+```ruby
+# Returns column headers for display
+self.headers
+# => [{ name: :order_number, label: "Order Number" }, ...]
+
+# Returns column names for CSV header row
+self.csv_headers
+# => ["order_number", "completed_at", "customer_email", ...]
+
+# Converts line item to CSV row array
+to_csv
+# => ["R123456", "2025-01-15 14:30", "[email protected]", ...]
+```
+
+### Step 3: Register the Report
+
+Add your report to the registry in an initializer:
+
+```ruby config/initializers/spree.rb
+Rails.application.config.after_initialize do
+ Spree.reports << Spree::Reports::CustomerOrders
+end
+```
+
+### Step 4: Add Translations
+
+Add the report name and column header translations:
+
+```yaml config/locales/en.yml
+en:
+ spree:
+ report_names:
+ customer_orders: Customer Orders
+ order_number: Order Number
+ completed_at: Completed At
+ customer_email: Customer Email
+ customer_name: Customer Name
+ item_count: Item Count
+ total: Total
+```
+
+After restarting your application, the new report will be available in **Admin > Reports**.
+
+## Advanced Patterns
+
+### Complex Queries with Aggregations
+
+For reports that aggregate data across records, use SQL directly in `line_items_scope`:
+
+```ruby app/models/spree/reports/revenue_by_category.rb
+module Spree
+ module Reports
+ class RevenueByCategory < Spree::Report
+ def line_items_scope
+ line_items_sql = Spree::LineItem
+ .joins(:order)
+ .where(
+ spree_orders: {
+ completed_at: date_from..date_to,
+ currency: currency
+ }
+ )
+ .select(
+ "spree_line_items.variant_id",
+ "SUM(spree_line_items.quantity) as quantity",
+ "SUM(spree_line_items.pre_tax_amount) as revenue"
+ )
+ .group(:variant_id)
+ .to_sql
+
+ store.taxons
+ .where(depth: 1) # Top-level categories
+ .joins("LEFT JOIN spree_products_taxons ON spree_products_taxons.taxon_id = spree_taxons.id")
+ .joins("LEFT JOIN spree_variants ON spree_variants.product_id = spree_products_taxons.product_id")
+ .joins("LEFT JOIN (#{line_items_sql}) AS line_items ON line_items.variant_id = spree_variants.id")
+ .select(
+ "spree_taxons.*",
+ "COALESCE(SUM(line_items.quantity), 0) AS total_quantity",
+ "COALESCE(SUM(line_items.revenue), 0.0) AS total_revenue"
+ )
+ .group("spree_taxons.id")
+ end
+ end
+ end
+end
+```
+
+When using aggregated queries, the `record` in your line item class will have virtual attributes (like `total_quantity`, `total_revenue`) available as methods.
+
+### Custom Summary Section
+
+Override `summary` to provide aggregate metrics alongside the line items:
+
+```ruby app/models/spree/reports/customer_orders.rb
+module Spree
+ module Reports
+ class CustomerOrders < Spree::Report
+ def summary
+ {
+ total_orders: line_items_scope.count,
+ total_revenue: line_items_scope.sum(:total),
+ average_order_value: line_items_scope.average(:total)
+ }
+ end
+ end
+ end
+end
+```
+
+### Multi-Vendor Support
+
+If you're using Spree Multi-Vendor, filter by vendor when one is selected:
+
+```ruby app/models/spree/reports/vendor_sales.rb
+module Spree
+ module Reports
+ class VendorSales < Spree::Report
+ def line_items_scope
+ scope = store.line_items.where(
+ order: Spree::Order.complete.where(
+ completed_at: date_from..date_to,
+ currency: currency
+ )
+ )
+
+ # Filter by vendor if one is selected
+ scope = scope.where(vendor_id: vendor.id) if defined?(vendor) && vendor.present?
+
+ scope
+ end
+ end
+ end
+end
+```
+
+## Testing Custom Reports
+
+### Testing the Report Class
+
+Test that your report's `line_items_scope` returns the correct records:
+
+```ruby spec/models/spree/reports/customer_orders_spec.rb
+require 'rails_helper'
+
+RSpec.describe Spree::Reports::CustomerOrders, type: :model do
+ let(:store) { create(:store) }
+ let(:user) { create(:admin_user) }
+
+ subject(:report) do
+ described_class.new(
+ store: store,
+ user: user,
+ currency: 'USD',
+ date_from: 1.month.ago,
+ date_to: Time.current
+ )
+ end
+
+ describe '#line_items_scope' do
+ let!(:completed_order) do
+ create(:completed_order_with_totals, store: store, currency: 'USD', completed_at: 1.week.ago)
+ end
+
+ let!(:incomplete_order) do
+ create(:order, store: store, currency: 'USD', state: 'cart')
+ end
+
+ let!(:other_currency_order) do
+ create(:completed_order_with_totals, store: store, currency: 'EUR', completed_at: 1.week.ago)
+ end
+
+ let!(:old_order) do
+ create(:completed_order_with_totals, store: store, currency: 'USD', completed_at: 2.months.ago)
+ end
+
+ it 'returns only completed orders within the date range and currency' do
+ scope = report.line_items_scope
+
+ expect(scope).to include(completed_order)
+ expect(scope).not_to include(incomplete_order)
+ expect(scope).not_to include(other_currency_order)
+ expect(scope).not_to include(old_order)
+ end
+ end
+
+ describe '#line_items' do
+ let!(:order) do
+ create(:completed_order_with_totals, store: store, currency: 'USD', completed_at: 1.week.ago)
+ end
+
+ it 'returns ReportLineItem objects' do
+ items = report.line_items
+ expect(items).to all(be_a(Spree::ReportLineItems::CustomerOrders))
+ end
+
+ it 'respects the limit option' do
+ create(:completed_order_with_totals, store: store, currency: 'USD', completed_at: 2.days.ago)
+ items = report.line_items(limit: 1)
+ expect(items.length).to eq(1)
+ end
+ end
+end
+```
+
+### Testing the ReportLineItem Class
+
+Test that your line item correctly formats each record:
+
+```ruby spec/models/spree/report_line_items/customer_orders_spec.rb
+require 'rails_helper'
+
+RSpec.describe Spree::ReportLineItems::CustomerOrders, type: :model do
+ let(:store) { create(:store) }
+ let(:user) { create(:admin_user) }
+ let(:bill_address) { create(:address) }
+ let(:order) do
+ create(:completed_order_with_totals,
+ store: store,
+ currency: 'USD',
+ completed_at: 1.week.ago,
+ bill_address: bill_address)
+ end
+
+ let(:report) do
+ Spree::Reports::CustomerOrders.new(
+ store: store,
+ user: user,
+ currency: 'USD',
+ date_from: 1.month.ago,
+ date_to: Time.current
+ )
+ end
+
+ subject(:line_item) { described_class.new(record: order, report: report) }
+
+ describe '#order_number' do
+ it 'returns the order number' do
+ expect(line_item.order_number).to eq(order.number)
+ end
+ end
+
+ describe '#customer_name' do
+ it 'returns the billing address full name' do
+ expect(line_item.customer_name).to eq(bill_address.full_name)
+ end
+
+ context 'when no billing address' do
+ let(:bill_address) { nil }
+
+ it 'returns nil' do
+ order.update_column(:bill_address_id, nil)
+ order.reload
+ expect(line_item.customer_name).to be_nil
+ end
+ end
+ end
+
+ describe '#total' do
+ it 'returns a Spree::Money formatted total' do
+ result = line_item.total
+ expect(result).to be_a(Spree::Money)
+ expect(result.money.to_f).to eq(order.total.to_f)
+ end
+ end
+
+ describe '#to_csv' do
+ it 'returns an array of values for CSV row' do
+ csv_row = line_item.to_csv
+ expect(csv_row.length).to eq(6)
+ expect(csv_row[0]).to eq(order.number)
+ end
+ end
+end
+```
+
+### Key Testing Patterns
+
+1. **Test scope filtering** — verify `line_items_scope` returns only records matching date range, currency, and store
+2. **Test attribute formatting** — verify each attribute method returns correctly formatted data
+3. **Test CSV output** — check `headers`, `csv_headers`, and `to_csv` return expected values
+4. **Test edge cases** — handle nil values gracefully (e.g., missing addresses)
+
+## Related Documentation
+
+- [Reports](/developer/core-concepts/reports) - Report architecture and built-in reports
+- [Events](/developer/core-concepts/events) - How report generation uses the events system
diff --git a/docs/developer/sdk/admin/quickstart.mdx b/docs/developer/sdk/admin/quickstart.mdx
new file mode 100644
index 0000000000..eae8e9e636
--- /dev/null
+++ b/docs/developer/sdk/admin/quickstart.mdx
@@ -0,0 +1,24 @@
+---
+title: Admin API
+description: Manage your store programmatically with the Spree Admin SDK
+---
+
+<Info>
+ The Admin API SDK is coming soon. The `client.admin` namespace is ready and will provide full access to administrative endpoints for managing products, orders, customers, and store settings.
+</Info>
+
+## Preview
+
+```typescript
+import { createSpreeClient } from '@spree/sdk';
+
+const client = createSpreeClient({
+ baseUrl: 'https://api.mystore.com',
+ secretKey: 'spree_sk_xxx', // Admin API requires a secret key
+});
+
+// Admin endpoints will be available under client.admin.*
+// client.admin.products.list()
+// client.admin.orders.list()
+// client.admin.customers.list()
+```
diff --git a/docs/developer/sdk/authentication.mdx b/docs/developer/sdk/authentication.mdx
new file mode 100644
index 0000000000..68a7008273
--- /dev/null
+++ b/docs/developer/sdk/authentication.mdx
@@ -0,0 +1,62 @@
+---
+title: Authentication
+description: Authentication modes and guest checkout with the Spree SDK
+---
+
+import SdkClientSetup from '/snippets/store-api/sdk-client-setup.mdx'
+import AuthJwtExample from '/snippets/store-api/auth-jwt-example.mdx'
+import AuthGuestCart from '/snippets/store-api/auth-guest-cart.mdx'
+
+The SDK supports multiple authentication modes depending on your use case. For a full overview of the API authentication methods, see the [Store API Authentication](/api-reference/store-api/authentication) reference.
+
+## Publishable Key Only (Guest/Public Access)
+
+Use a publishable API key for public endpoints like browsing products:
+
+<SdkClientSetup />
+
+```typescript
+// Public endpoints work without user authentication
+const products = await client.store.products.list()
+```
+
+## Publishable Key + JWT (Authenticated Customer)
+
+For authenticated customer actions like viewing orders or managing addresses:
+
+<AuthJwtExample />
+
+```typescript
+// Refresh token when needed
+const newTokens = await client.store.auth.refresh({ token })
+```
+
+## Register New Customer
+
+```typescript
+const { token, user } = await client.store.auth.register({
+ email: '[email protected]',
+ password: 'password123',
+ password_confirmation: 'password123',
+ first_name: 'John',
+ last_name: 'Doe',
+})
+```
+
+## Guest Checkout
+
+For guest checkout, use the `token` (or `order_token`) returned when creating a cart:
+
+<AuthGuestCart />
+
+```typescript
+const options = { orderToken: cart.token }
+
+// Update order with email
+await client.store.orders.update(cart.id, {
+ email: '[email protected]',
+}, options)
+
+// Complete checkout
+await client.store.orders.complete(cart.id, options)
+```
diff --git a/docs/developer/sdk/configuration.mdx b/docs/developer/sdk/configuration.mdx
new file mode 100644
index 0000000000..cee5db380a
--- /dev/null
+++ b/docs/developer/sdk/configuration.mdx
@@ -0,0 +1,128 @@
+---
+title: Configuration
+description: Localization, error handling, TypeScript types, and custom fetch
+---
+
+import LocalizationExample from '/snippets/store-api/localization-example.mdx'
+
+## Localization & Currency
+
+Pass locale and currency headers with any request. For full details, see the [Localization](/api-reference/store-api/localization) reference.
+
+<LocalizationExample />
+
+```typescript
+// Works with all endpoints
+const taxon = await client.store.taxons.get('categories/clothing', {
+ expand: ['ancestors'],
+}, {
+ locale: 'de',
+ currency: 'EUR',
+})
+```
+
+## Error Handling
+
+```typescript
+import { SpreeError } from '@spree/sdk';
+
+try {
+ await client.store.products.get('non-existent');
+} catch (error) {
+ if (error instanceof SpreeError) {
+ console.log(error.code); // 'record_not_found'
+ console.log(error.message); // 'Product not found'
+ console.log(error.status); // 404
+ console.log(error.details); // Validation errors (if any)
+ }
+}
+```
+
+## Custom Fetch
+
+You can provide a custom fetch implementation:
+
+```typescript
+import { createSpreeClient } from '@spree/sdk';
+
+const client = createSpreeClient({
+ baseUrl: 'https://api.mystore.com',
+ publishableKey: 'spree_pk_xxx',
+ fetch: customFetchImplementation,
+});
+```
+
+## TypeScript Support
+
+The SDK includes full TypeScript support with generated types from the API serializers:
+
+```typescript
+import type {
+ StoreProduct,
+ StoreOrder,
+ StoreVariant,
+ StoreTaxon,
+ StoreTaxonomy,
+ StoreLineItem,
+ StoreAddress,
+ StoreCustomer,
+ PaginatedResponse,
+} from '@spree/sdk';
+
+// All responses are fully typed
+const products: PaginatedResponse<StoreProduct> = await client.store.products.list();
+const taxon: StoreTaxon = await client.store.taxons.get('clothing');
+```
+
+## Available Types
+
+### Core Types
+- `StoreProduct` - Product data
+- `StoreVariant` - Variant data
+- `StoreOrder` - Order/cart data
+- `StoreLineItem` - Line item in cart
+- `StoreTaxonomy` - Category group
+- `StoreTaxon` - Individual category
+- `StoreCountry` - Country with states
+- `StoreState` - State/province
+- `StoreAddress` - Customer address
+- `StoreCustomer` - Customer profile
+- `StoreStore` - Store configuration
+
+### Commerce Types
+- `StorePayment` - Payment record
+- `StorePaymentMethod` - Payment method
+- `StorePaymentSession` - Provider-agnostic payment session
+- `StoreShipment` - Shipment record
+- `StoreShippingRate` - Shipping rate option
+- `StoreShippingMethod` - Shipping method
+- `StoreCreditCard` - Saved credit card
+- `StoreGiftCard` - Gift card
+
+### Product Types
+- `StoreImage` - Product image
+- `StorePrice` - Price data
+- `StoreOptionType` - Option type (e.g., Size, Color)
+- `StoreOptionValue` - Option value (e.g., Small, Red)
+- `StoreDigitalLink` - Digital download link
+
+### Wishlist Types
+- `StoreWishlist` - Wishlist
+- `StoreWishedItem` - Wishlist item
+
+### Client Types
+- `SpreeClient` - Main client class
+- `StoreClient` - Store API client
+- `AdminClient` - Admin API client
+- `SpreeClientConfig` - Client configuration
+- `RequestOptions` - Per-request options
+- `RetryConfig` - Retry behavior configuration
+
+### Utility Types
+- `PaginatedResponse<T>` - Paginated API response
+- `AuthTokens` - JWT tokens from login
+- `AddressParams` - Address input parameters
+- `CreatePaymentSessionParams` - Payment session creation parameters
+- `UpdatePaymentSessionParams` - Payment session update parameters
+- `CompletePaymentSessionParams` - Payment session completion parameters
+- `ProductFiltersResponse` - Product filters response
diff --git a/docs/developer/sdk/quickstart.mdx b/docs/developer/sdk/quickstart.mdx
new file mode 100644
index 0000000000..dcccafc134
--- /dev/null
+++ b/docs/developer/sdk/quickstart.mdx
@@ -0,0 +1,92 @@
+---
+title: Quickstart
+description: Install and start using the Spree SDK in your project
+---
+
+## Installation
+
+```bash
+npm install @spree/sdk
+# or
+yarn add @spree/sdk
+# or
+pnpm add @spree/sdk
+```
+
+## Quick Start
+
+```typescript
+import { createSpreeClient } from '@spree/sdk';
+
+// Initialize the client
+const client = createSpreeClient({
+ baseUrl: 'https://api.mystore.com',
+ publishableKey: 'spree_pk_xxx', // Store API
+ secretKey: 'spree_sk_xxx', // Admin API (optional)
+});
+
+// Browse products (Store API)
+const products = await client.store.products.list({
+ limit: 10,
+ expand: ['variants', 'images'],
+});
+
+// Get a single product
+const product = await client.store.products.get('spree-tote');
+
+// Authentication
+const { token, user } = await client.store.auth.login({
+ email: '[email protected]',
+ password: 'password123',
+});
+
+// Create a cart and add items
+const cart = await client.store.cart.create();
+await client.store.orders.lineItems.create(cart.id, {
+ variant_id: 'var_abc123',
+ quantity: 2,
+}, { orderToken: cart.token });
+
+// Checkout flow
+await client.store.orders.next(cart.id, { orderToken: cart.token });
+await client.store.orders.complete(cart.id, { orderToken: cart.token });
+```
+
+## Client Architecture
+
+The SDK exposes two API namespaces:
+
+```typescript
+client.store // Store API — customer-facing (products, cart, checkout, account)
+client.admin // Admin API — administrative (coming soon)
+```
+
+All Store API endpoints live under `client.store.*`. The Admin API namespace is ready for future endpoints.
+
+## Nested Resources
+
+The SDK uses a resource builder pattern for nested resources:
+
+| Parent Resource | Nested Resource | Available Methods |
+|-----------------|-----------------|-------------------|
+| `store.orders` | `lineItems` | `create`, `update`, `delete` |
+| `store.orders` | `payments` | `list`, `get` |
+| `store.orders` | `paymentMethods` | `list` |
+| `store.orders` | `paymentSessions` | `create`, `get`, `update`, `complete` |
+| `store.orders` | `shipments` | `list`, `update` |
+| `store.orders` | `couponCodes` | `apply`, `remove` |
+| `store.customer` | `addresses` | `list`, `get`, `create`, `update`, `delete`, `markAsDefault` |
+| `store.customer` | `creditCards` | `list`, `get`, `delete` |
+| `store.customer` | `giftCards` | `list`, `get` |
+| `store.taxons` | `products` | `list` |
+| `store.wishlists` | `items` | `create`, `update`, `delete` |
+
+```typescript
+// Nested resources follow the pattern: client.store.parent.nested.method(parentId, ...)
+await client.store.orders.lineItems.create(orderId, params, options);
+await client.store.orders.payments.list(orderId, options);
+await client.store.orders.shipments.update(orderId, shipmentId, params, options);
+await client.store.customer.addresses.list({}, options);
+await client.store.taxons.products.list(taxonId, params, options);
+await client.store.wishlists.items.create(wishlistId, params, options);
+```
diff --git a/docs/developer/sdk/store/account.mdx b/docs/developer/sdk/store/account.mdx
new file mode 100644
index 0000000000..9dc8963823
--- /dev/null
+++ b/docs/developer/sdk/store/account.mdx
@@ -0,0 +1,67 @@
+---
+title: Customer Account
+description: Manage customer profiles, addresses, and credit cards with the Spree SDK
+---
+
+## Customer Profile
+
+```typescript
+const options = { token: jwtToken };
+
+// Get profile
+const profile = await client.store.customer.get(options);
+
+// Update profile
+await client.store.customer.update({
+ first_name: 'John',
+ last_name: 'Doe',
+}, options);
+```
+
+## Addresses
+
+```typescript
+const options = { token: jwtToken };
+
+// List addresses
+const { data: addresses } = await client.store.customer.addresses.list({}, options);
+
+// Get address by ID
+const address = await client.store.customer.addresses.get('addr_xxx', options);
+
+// Create address
+await client.store.customer.addresses.create({
+ firstname: 'John',
+ lastname: 'Doe',
+ address1: '123 Main St',
+ city: 'New York',
+ zipcode: '10001',
+ country_iso: 'US',
+ state_abbr: 'NY',
+}, options);
+
+// Update address
+await client.store.customer.addresses.update('addr_xxx', { city: 'Brooklyn' }, options);
+
+// Delete address
+await client.store.customer.addresses.delete('addr_xxx', options);
+
+// Mark as default billing or shipping address
+await client.store.customer.addresses.markAsDefault('addr_xxx', 'billing', options);
+await client.store.customer.addresses.markAsDefault('addr_xxx', 'shipping', options);
+```
+
+## Credit Cards
+
+```typescript
+const options = { token: jwtToken };
+
+// List saved credit cards
+const { data: cards } = await client.store.customer.creditCards.list({}, options);
+
+// Get credit card by ID
+const card = await client.store.customer.creditCards.get('cc_xxx', options);
+
+// Delete credit card
+await client.store.customer.creditCards.delete('cc_xxx', options);
+```
diff --git a/docs/developer/sdk/store/cart-checkout.mdx b/docs/developer/sdk/store/cart-checkout.mdx
new file mode 100644
index 0000000000..447174e85d
--- /dev/null
+++ b/docs/developer/sdk/store/cart-checkout.mdx
@@ -0,0 +1,114 @@
+---
+title: Cart & Checkout
+description: Manage carts, line items, coupons, and checkout flow with the Spree SDK
+---
+
+## Cart
+
+```typescript
+// Create a new cart
+const cart = await client.store.cart.create();
+
+// Get current cart
+const cart = await client.store.cart.get({ orderToken: 'xxx' });
+
+// Associate guest cart with authenticated user
+// (after user logs in, merge their guest cart with their account)
+await client.store.cart.associate({
+ token: jwtToken, // User's JWT token
+ orderToken: cart.token, // Guest cart token
+});
+```
+
+## Orders & Checkout
+
+### List Orders
+
+```typescript
+// List orders for authenticated customer
+const orders = await client.store.orders.list({}, { token });
+```
+
+### Get an Order
+
+```typescript
+const order = await client.store.orders.get('R123456789', {
+ expand: ['line_items', 'shipments'],
+}, { orderToken: cart.token });
+```
+
+### Update an Order
+
+```typescript
+await client.store.orders.update(cart.id, {
+ email: '[email protected]',
+ ship_address: {
+ firstname: 'John',
+ lastname: 'Doe',
+ address1: '123 Main St',
+ city: 'New York',
+ zipcode: '10001',
+ phone: '+1 555 123 4567',
+ country_iso: 'US',
+ state_abbr: 'NY',
+ },
+ bill_address_id: 'addr_xxx', // Or use existing address by ID
+}, { orderToken: cart.token });
+```
+
+### Checkout Flow
+
+```typescript
+const options = { orderToken: cart.token };
+
+await client.store.orders.next(cart.id, options); // Move to next step
+await client.store.orders.advance(cart.id, options); // Advance through all steps
+await client.store.orders.complete(cart.id, options); // Complete the order
+```
+
+## Line Items
+
+```typescript
+const options = { orderToken: cart.token };
+
+// Add item
+await client.store.orders.lineItems.create(cart.id, {
+ variant_id: 'var_123',
+ quantity: 2,
+}, options);
+
+// Update item quantity
+await client.store.orders.lineItems.update(cart.id, lineItemId, {
+ quantity: 3,
+}, options);
+
+// Remove item
+await client.store.orders.lineItems.delete(cart.id, lineItemId, options);
+```
+
+## Coupon Codes
+
+```typescript
+const options = { orderToken: cart.token };
+
+// Apply a coupon code
+await client.store.orders.couponCodes.apply(cart.id, 'SAVE20', options);
+
+// Remove a coupon code
+await client.store.orders.couponCodes.remove(cart.id, 'promo_xxx', options);
+```
+
+## Store Credits
+
+```typescript
+const options = { orderToken: cart.token };
+
+// Apply store credit to order (applies maximum available by default)
+await client.store.orders.addStoreCredit(cart.id, undefined, options);
+
+// Apply specific amount of store credit
+await client.store.orders.addStoreCredit(cart.id, 25.00, options);
+
+// Remove store credit from order
+await client.store.orders.removeStoreCredit(cart.id, options);
+```
diff --git a/docs/developer/sdk/store/markets.mdx b/docs/developer/sdk/store/markets.mdx
new file mode 100644
index 0000000000..1cdad67742
--- /dev/null
+++ b/docs/developer/sdk/store/markets.mdx
@@ -0,0 +1,163 @@
+---
+title: Markets
+description: Fetch markets, resolve by country, and list market countries with the Spree SDK
+---
+
+## List Markets
+
+Returns all markets for the current store with their countries, currency, locales, and tax configuration.
+
+<CodeGroup>
+
+```typescript SDK
+const { data: markets } = await client.store.markets.list()
+
+markets.forEach(market => {
+ market.id // "mkt_UkLWZg9DAJ"
+ market.name // "North America"
+ market.currency // "USD"
+ market.default_locale // "en"
+ market.tax_inclusive // false
+ market.default // true
+ market.supported_locales // ["en", "es"]
+ market.countries // [{ iso: "US", name: "United States of America", ... }]
+})
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/markets' \
+ -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+</CodeGroup>
+
+**Response:**
+
+```json
+{
+ "data": [
+ {
+ "id": "mkt_UkLWZg9DAJ",
+ "name": "North America",
+ "currency": "USD",
+ "default_locale": "en",
+ "tax_inclusive": false,
+ "default": true,
+ "supported_locales": ["en", "es"],
+ "countries": [
+ { "iso": "US", "iso3": "USA", "name": "United States of America", "states_required": true, "zipcode_required": true }
+ ]
+ },
+ {
+ "id": "mkt_gbHJdmfrXB",
+ "name": "Europe",
+ "currency": "EUR",
+ "default_locale": "de",
+ "tax_inclusive": true,
+ "default": false,
+ "supported_locales": ["de", "en", "fr"],
+ "countries": [
+ { "iso": "DE", "iso3": "DEU", "name": "Germany", "states_required": false, "zipcode_required": true },
+ { "iso": "FR", "iso3": "FRA", "name": "France", "states_required": false, "zipcode_required": true }
+ ]
+ }
+ ]
+}
+```
+
+## Get a Market
+
+<CodeGroup>
+
+```typescript SDK
+const market = await client.store.markets.get('mkt_gbHJdmfrXB')
+
+market.name // "Europe"
+market.currency // "EUR"
+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'
+```
+
+</CodeGroup>
+
+## Resolve Market by Country
+
+Determine which market applies for a given country ISO code. Useful for auto-selecting the correct currency and locale when a customer's location is known.
+
+<CodeGroup>
+
+```typescript SDK
+const market = await client.store.markets.resolve('DE')
+
+market.id // "mkt_gbHJdmfrXB"
+market.name // "Europe"
+market.currency // "EUR"
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/markets/resolve?country=DE' \
+ -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+</CodeGroup>
+
+<Info>
+If no market matches the given country, a `404` error is returned.
+</Info>
+
+## List Countries in a Market
+
+Returns countries belonging to a specific market. Use this for address form country dropdowns during checkout.
+
+<CodeGroup>
+
+```typescript SDK
+const { data: countries } = await client.store.markets.countries.list('mkt_gbHJdmfrXB')
+
+countries.forEach(country => {
+ country.iso // "DE"
+ country.name // "Germany"
+ country.states_required // false
+ country.zipcode_required // true
+})
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/markets/mkt_gbHJdmfrXB/countries' \
+ -H 'Authorization: Bearer spree_pk_xxx'
+```
+
+</CodeGroup>
+
+## Get a Country in a Market
+
+Returns a single country by ISO code within a market. Use `expand: ['states']` for address forms that need state/province dropdowns.
+
+<CodeGroup>
+
+```typescript SDK
+const country = await client.store.markets.countries.get('mkt_gbHJdmfrXB', 'US', {
+ expand: ['states'],
+})
+
+country.iso // "US"
+country.name // "United States of America"
+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'
+```
+
+</CodeGroup>
+
+## Related Documentation
+
+- [Markets](/developer/core-concepts/markets) — Market concepts, zones, and configuration
+- [Localization](/api-reference/store-api/localization) — Locale and currency headers
+- [Geography](/developer/sdk/store/products#geography) — Global country endpoints
diff --git a/docs/developer/sdk/store/payments.mdx b/docs/developer/sdk/store/payments.mdx
new file mode 100644
index 0000000000..8967a2ae40
--- /dev/null
+++ b/docs/developer/sdk/store/payments.mdx
@@ -0,0 +1,71 @@
+---
+title: Payments & Shipping
+description: Handle payments, payment sessions, and shipping with the Spree SDK
+---
+
+## Payments
+
+```typescript
+const options = { orderToken: cart.token };
+
+// Get available payment methods for an order
+const methods = await client.store.orders.paymentMethods.list(cart.id, options);
+
+// List payments on an order
+const payments = await client.store.orders.payments.list(cart.id, options);
+
+// Get a specific payment
+const payment = await client.store.orders.payments.get(cart.id, paymentId, options);
+```
+
+## Payment Sessions
+
+Payment sessions provide a unified, provider-agnostic interface for payment processing. They work with any payment gateway (Stripe, Adyen, PayPal, etc.) through a single API.
+
+```typescript
+const options = { orderToken: cart.token };
+
+// Create a payment session (initializes a session with the payment gateway)
+const session = await client.store.orders.paymentSessions.create(cart.id, {
+ payment_method_id: 'pm_xxx',
+ amount: '99.99', // Optional, defaults to order total
+ external_data: { // Optional, provider-specific data
+ return_url: 'https://mystore.com/checkout/complete',
+ },
+}, options);
+
+// The session contains provider-specific data (e.g., Stripe client_secret)
+console.log(session.external_data.client_secret);
+
+// Get a payment session
+const existing = await client.store.orders.paymentSessions.get(
+ cart.id, session.id, options
+);
+
+// Update a payment session (e.g., after order total changes)
+await client.store.orders.paymentSessions.update(cart.id, session.id, {
+ amount: '149.99',
+}, options);
+
+// Complete the payment session (after customer confirms payment on the frontend)
+const completed = await client.store.orders.paymentSessions.complete(
+ cart.id, session.id,
+ { session_result: 'success' },
+ options
+);
+console.log(completed.status); // 'completed'
+```
+
+## Shipments
+
+```typescript
+const options = { orderToken: cart.token };
+
+// List shipments for an order
+const shipments = await client.store.orders.shipments.list(cart.id, options);
+
+// Select a shipping rate
+await client.store.orders.shipments.update(cart.id, shipmentId, {
+ selected_shipping_rate_id: 'rate_xxx',
+}, options);
+```
diff --git a/docs/developer/sdk/store/products.mdx b/docs/developer/sdk/store/products.mdx
new file mode 100644
index 0000000000..6452418639
--- /dev/null
+++ b/docs/developer/sdk/store/products.mdx
@@ -0,0 +1,140 @@
+---
+title: Products & Categories
+description: Browse products, categories, and taxonomies with the Spree SDK
+---
+
+## Products
+
+### List Products
+
+```typescript
+const products = await client.store.products.list({
+ page: 1,
+ limit: 25,
+ expand: ['variants', 'images', 'taxons'],
+});
+```
+
+### Filtering Products
+
+Use flat param keys — the SDK wraps them in `q[...]` automatically:
+
+```typescript
+const products = await client.store.products.list({
+ name_cont: 'shirt', // Name contains
+ price_gte: 20, // Min price
+ price_lte: 100, // Max price
+ with_option_value_ids: ['optval_abc', 'optval_def'], // By option values
+ in_stock: true, // In stock only
+ multi_search: 'blue shirt', // Full-text search
+});
+```
+
+### Sorting Products
+
+Pass `sort` with one of the supported values:
+
+```typescript
+const products = await client.store.products.list({
+ sort: 'price asc', // price asc, price desc, best_selling,
+ // name asc, name desc, available_on desc, available_on asc
+});
+```
+
+### Get a Product
+
+Fetch a single product by slug or prefix ID:
+
+```typescript
+const product = await client.store.products.get('spree-tote', {
+ expand: ['variants', 'images'],
+});
+```
+
+### Product Filters
+
+Get available filters (price range, availability, options, taxons) and sort options for building filter UIs:
+
+```typescript
+const filters = await client.store.products.filters({
+ taxon_id: 'txn_abc123', // Optional: scope filters to a taxon
+});
+
+// Response:
+// {
+// filters: [
+// { id: 'price', type: 'price_range', min: 9.99, max: 199.99, currency: 'USD' },
+// { id: 'availability', type: 'availability', options: [{ id: 'in_stock', count: 42 }, ...] },
+// { id: 'opttype_abc', type: 'option', name: 'color', presentation: 'Color', options: [...] },
+// { id: 'taxons', type: 'taxon', options: [{ id: 'txn_abc', name: 'Shirts', permalink: '...', count: 12 }] },
+// ],
+// sort_options: [{ id: 'manual' }, { id: 'price asc' }, { id: 'best_selling' }, ...],
+// default_sort: 'manual',
+// total_count: 85,
+// }
+```
+
+## Categories (Taxonomies & Taxons)
+
+### List Taxonomies
+
+```typescript
+const taxonomies = await client.store.taxonomies.list({
+ expand: ['taxons'],
+});
+```
+
+### Get a Taxonomy
+
+```typescript
+const categories = await client.store.taxonomies.get('tax_123', {
+ expand: ['root', 'taxons'],
+});
+```
+
+### List Taxons
+
+```typescript
+const taxons = await client.store.taxons.list({
+ depth_eq: 1, // Top-level categories only
+ taxonomy_id_eq: '123', // Filter by taxonomy
+});
+```
+
+### Get a Taxon
+
+Fetch by ID or permalink:
+
+```typescript
+const taxon = await client.store.taxons.get('categories/clothing', {
+ expand: ['ancestors', 'children'], // For breadcrumbs and subcategories
+});
+```
+
+### List Products in a Category
+
+```typescript
+const categoryProducts = await client.store.taxons.products.list('categories/clothing', {
+ page: 1,
+ limit: 12,
+ expand: ['images', 'default_variant'],
+});
+```
+
+## Store
+
+```typescript
+// Get current store information
+const store = await client.store.store.get();
+```
+
+## Geography
+
+```typescript
+// List countries available for checkout
+const { data: countries } = await client.store.countries.list();
+
+// Get country by ISO code (includes states)
+const usa = await client.store.countries.get('US');
+console.log(usa.states); // Array of states
+```
diff --git a/docs/developer/sdk/store/wishlists.mdx b/docs/developer/sdk/store/wishlists.mdx
new file mode 100644
index 0000000000..e6042378a7
--- /dev/null
+++ b/docs/developer/sdk/store/wishlists.mdx
@@ -0,0 +1,52 @@
+---
+title: Wishlists
+description: Manage wishlists and wished items with the Spree SDK
+---
+
+## Wishlists
+
+```typescript
+const options = { token: jwtToken };
+
+// List wishlists
+const { data: wishlists } = await client.store.wishlists.list({}, options);
+
+// Get wishlist by ID
+const wishlist = await client.store.wishlists.get('wl_xxx', {
+ expand: ['wished_items'],
+}, options);
+
+// Create wishlist
+const newWishlist = await client.store.wishlists.create({
+ name: 'Birthday Ideas',
+ is_private: true,
+}, options);
+
+// Update wishlist
+await client.store.wishlists.update('wl_xxx', {
+ name: 'Updated Name',
+}, options);
+
+// Delete wishlist
+await client.store.wishlists.delete('wl_xxx', options);
+```
+
+## Wishlist Items
+
+```typescript
+const options = { token: jwtToken };
+
+// Add item to wishlist
+await client.store.wishlists.items.create('wl_xxx', {
+ variant_id: 'var_123',
+ quantity: 1,
+}, options);
+
+// Update item quantity
+await client.store.wishlists.items.update('wl_xxx', 'wi_xxx', {
+ quantity: 2,
+}, options);
+
+// Remove item from wishlist
+await client.store.wishlists.items.delete('wl_xxx', 'wi_xxx', options);
+```
diff --git a/docs/developer/security/pci_compliance.mdx b/docs/developer/security/pci_compliance.mdx
index c168f37d50..269431f1f6 100644
--- a/docs/developer/security/pci_compliance.mdx
+++ b/docs/developer/security/pci_compliance.mdx
@@ -2,14 +2,14 @@
title: "PCI Compliance"
---
-All store owners wishing to process credit card transactions should be familiar with [PCI Compliance](http://en.wikipedia.org/wiki/Pci_compliance). [Spree Stripe](https://github.com/spree/spree_stripe) and [Spree Braintree vzero](https://github.com/spree-contrib/spree_braintree_vzero) are PCI-compliant.
+All store owners wishing to process credit card transactions should be familiar with [PCI Compliance](http://en.wikipedia.org/wiki/Pci_compliance). All officially supported payment gateways — [Spree Stripe](https://github.com/spree/spree_stripe), [Spree Adyen](https://github.com/spree/spree_adyen), and [Spree PayPal Checkout](https://github.com/spree/spree_paypal_checkout) — are fully PCI-compliant.
## Using payment tokens
-We do not transmit or store Credit Card numbers. Instead we're using payment processor tokens supplied by their SDKs to authorize and charge customer cards.
+We do not transmit or store Credit Card numbers. Instead we're using payment processor tokens supplied by their SDKs to authorize and charge customer cards. Sensitive payment data is collected directly by the gateway's frontend SDK (e.g., Stripe.js, Adyen Drop-in) and never touches your server.
## 3-D Secure and Strong Customer Authentication support
[Spree Stripe integration](https://github.com/spree/spree_stripe) supports [Strong Customer Authentication (SCA)](https://stripe.com/en-pl/guides/strong-customer-authentication) out of the box. We also use Stripe JavaScript SDK to render all payment forms.
-[Spree Braintree vzero](https://github.com/spree-contrib/spree_braintree_vzero) extension supports [3D Secure 2.0](https://developers.braintreepayments.com/guides/3d-secure/overview).
+[Spree Adyen integration](https://github.com/spree/spree_adyen) supports 3D Secure 2.0 through the Adyen Drop-in component.
diff --git a/docs/developer/storefront/nextjs/architecture.mdx b/docs/developer/storefront/nextjs/architecture.mdx
new file mode 100644
index 0000000000..d1665b915c
--- /dev/null
+++ b/docs/developer/storefront/nextjs/architecture.mdx
@@ -0,0 +1,150 @@
+---
+title: Architecture
+description: Server-first architecture, project structure, and auth flow
+---
+
+## Server-First Pattern
+
+The storefront follows a **server-first architecture** where all API calls are made server-side. The Spree API key is never exposed to the browser.
+
+```
+Browser → Server Action → @spree/next → Spree API
+ (with httpOnly cookies)
+```
+
+- **Server Actions** (`src/lib/data/`) — thin wrappers around `@spree/next` data functions
+- **httpOnly Cookies** — auth tokens, cart tokens, and locale are stored securely
+- **No Client-Side API Calls** — the Spree API key stays on the server
+- **Auto-Localization** — locale and country are read from cookies automatically by `@spree/next`
+
+## Project Structure
+
+```
+src/
+├── app/
+│ └── [country]/[locale]/ # Localized routes
+│ ├── (storefront)/ # Main storefront layout
+│ │ ├── page.tsx # Homepage
+│ │ ├── account/ # Customer account
+│ │ │ ├── addresses/ # Address management
+│ │ │ ├── credit-cards/ # Saved payment methods
+│ │ │ ├── gift-cards/ # Gift cards
+│ │ │ ├── orders/ # Order history
+│ │ │ │ └── [id]/ # Order details
+│ │ │ ├── profile/ # Profile settings
+│ │ │ └── register/ # Registration
+│ │ ├── cart/ # Shopping cart
+│ │ ├── products/ # Product listing
+│ │ │ └── [slug]/ # Product details
+│ │ ├── t/[...permalink]/ # Taxon/category pages
+│ │ └── taxonomies/ # Category overview
+│ └── (checkout)/ # Checkout layout (no header/footer)
+│ ├── checkout/[id]/ # Checkout flow
+│ └── order-placed/[id]/ # Order confirmation
+├── components/
+│ ├── cart/ # CartDrawer
+│ ├── checkout/ # AddressStep, DeliveryStep, PaymentStep, etc.
+│ ├── layout/ # Header, Footer, CountrySwitcher
+│ ├── navigation/ # Breadcrumbs
+│ ├── products/ # ProductCard, ProductGrid, Filters, MediaGallery, VariantPicker
+│ └── search/ # SearchBar
+├── contexts/
+│ ├── AuthContext.tsx # Auth state
+│ ├── CartContext.tsx # Client-side cart state sync
+│ ├── CheckoutContext.tsx # Checkout flow state
+│ └── StoreContext.tsx # Store/locale/currency state
+├── hooks/
+│ ├── useCarouselProducts.ts # Product carousel data
+│ └── useProductListing.ts # Product listing with filters
+└── lib/
+ ├── analytics/ # GTM integration
+ ├── constants.ts # App constants
+ ├── data/ # Server Actions
+ │ ├── addresses.ts # Address CRUD
+ │ ├── cart.ts # Cart operations
+ │ ├── checkout.ts # Checkout flow
+ │ ├── cookies.ts # Auth check helper
+ │ ├── countries.ts # Countries/regions
+ │ ├── credit-cards.ts # Payment methods
+ │ ├── customer.ts # Auth & profile
+ │ ├── gift-cards.ts # Gift cards
+ │ ├── orders.ts # Order history
+ │ ├── payment.ts # Payment processing
+ │ ├── products.ts # Product queries
+ │ ├── store.ts # Store configuration
+ │ ├── taxonomies.ts # Categories/taxons
+ │ └── utils.ts # Shared helpers (actionResult, withFallback)
+ └── utils/ # Client utilities
+ ├── address.ts # Address formatting
+ ├── cookies.ts # Cookie helpers
+ ├── credit-card.ts # Card formatting
+ ├── path.ts # URL path helpers
+ └── product-query.ts # Product filter query builder
+```
+
+## Authentication Flow
+
+1. User submits login form
+2. Server action calls `@spree/next` which authenticates with the Spree API
+3. JWT token is stored in an httpOnly cookie by `@spree/next`
+4. Subsequent requests include the token automatically
+5. Token is never accessible to client-side JavaScript
+
+```typescript
+// src/lib/data/customer.ts
+import { login as _login, getCustomer as _getCustomer } from '@spree/next'
+
+export async function login(email: string, password: string) {
+ return _login(email, password) // token stored in httpOnly cookie automatically
+}
+
+export async function getCustomer() {
+ return _getCustomer() // reads token from cookie automatically
+}
+```
+
+## Multi-Region Support
+
+The storefront supports multiple countries and currencies via URL segments:
+
+```
+/us/en/products # US store, English
+/de/de/products # German store, German
+/uk/en/products # UK store, English
+```
+
+A middleware (`src/proxy.ts`) uses `createSpreeMiddleware` from `@spree/next` to detect the visitor's country and locale, then redirects to the correct URL prefix. The `CountrySwitcher` component lets users change regions manually.
+
+## Server Actions
+
+All data fetching is done through server actions in `src/lib/data/`. These are thin wrappers around `@spree/next` functions — locale and currency are resolved automatically from cookies:
+
+```typescript
+// Products
+import { getProducts, getProduct, getProductFilters } from '@/lib/data/products'
+
+const products = await getProducts({ limit: 12 })
+const product = await getProduct('product-slug')
+const filters = await getProductFilters()
+
+// Cart
+import { getCart, addToCart, updateCartItem, removeCartItem } from '@/lib/data/cart'
+
+const cart = await getCart()
+await addToCart('var_xxx', 1)
+await updateCartItem('li_xxx', 2)
+await removeCartItem('li_xxx')
+
+// Authentication
+import { login, register, logout, getCustomer } from '@/lib/data/customer'
+
+await login('[email protected]', 'password')
+const customer = await getCustomer()
+await logout()
+
+// Addresses
+import { getAddresses, createAddress, updateAddress, deleteAddress } from '@/lib/data/addresses'
+
+const addresses = await getAddresses()
+await createAddress({ firstname: 'John', ... })
+```
diff --git a/docs/developer/storefront/nextjs/customization.mdx b/docs/developer/storefront/nextjs/customization.mdx
new file mode 100644
index 0000000000..78204b20f9
--- /dev/null
+++ b/docs/developer/storefront/nextjs/customization.mdx
@@ -0,0 +1,141 @@
+---
+title: Customization
+description: Fork, customize, and extend the Spree Next.js Storefront
+---
+
+## Forking the Starter
+
+The recommended approach is to fork the repository so you can customize freely while pulling upstream updates.
+
+### 1. Fork on GitHub
+
+Go to [github.com/spree/storefront](https://github.com/spree/storefront) and click **Fork**.
+
+### 2. Clone Your Fork
+
+```bash
+git clone https://github.com/YOUR_USERNAME/storefront.git
+cd storefront
+npm install
+```
+
+### 3. Add Upstream Remote
+
+```bash
+git remote add upstream https://github.com/spree/storefront.git
+```
+
+### 4. Pull Upstream Updates
+
+When the official starter gets updates, pull them into your fork:
+
+```bash
+git fetch upstream
+git merge upstream/main
+```
+
+Resolve any conflicts in your customized files, then commit.
+
+## Styling
+
+The storefront uses Tailwind CSS 4, which replaces the traditional `tailwind.config.ts` with CSS-native configuration via the `@theme` directive in `src/app/globals.css`.
+
+### Theme Customization
+
+Edit the `@theme inline` block in `src/app/globals.css` to change colors, fonts, and other design tokens:
+
+```css
+@import "tailwindcss";
+
+:root {
+ --background: #fcfaf7;
+ --foreground: #171717;
+}
+
+@theme inline {
+ --color-background: var(--background);
+ --color-foreground: var(--foreground);
+ --font-sans: var(--font-geist);
+
+ /* Replace with your brand colors */
+ --color-primary-50: #eff6ff;
+ --color-primary-100: #dbeafe;
+ --color-primary-200: #bfdbfe;
+ --color-primary-300: #93c5fd;
+ --color-primary-400: #60a5fa;
+ --color-primary-500: #0077ff;
+ --color-primary-600: #0066dd;
+ --color-primary-700: #0055bb;
+ --color-primary-800: #004499;
+ --color-primary-900: #003377;
+ --color-primary-950: #001d4d;
+}
+```
+
+Variables defined in `@theme inline` become Tailwind utilities automatically — for example, `--color-primary-500` maps to `bg-primary-500`, `text-primary-500`, etc.
+
+## Components
+
+All components live in `src/components/` and can be customized or replaced:
+
+```
+src/components/
+├── cart/ # CartDrawer
+├── checkout/ # AddressStep, DeliveryStep, PaymentStep, StripePaymentForm, etc.
+├── layout/ # Header, Footer, CountrySwitcher
+├── navigation/ # Breadcrumbs
+├── products/ # ProductCard, ProductGrid, ProductCarousel, Filters, MediaGallery, VariantPicker
+└── search/ # SearchBar
+```
+
+Components use standard React patterns — modify them directly or replace them entirely with your own implementations.
+
+## Data Layer
+
+To customize API behavior, modify the server actions in `src/lib/data/`. Each file handles a specific domain:
+
+| File | Purpose |
+|------|---------|
+| `products.ts` | Product listing and detail queries |
+| `cart.ts` | Cart operations (add, update, remove) |
+| `checkout.ts` | Checkout flow (addresses, shipping, completion) |
+| `customer.ts` | Authentication and profile management |
+| `addresses.ts` | Address CRUD |
+| `orders.ts` | Order history |
+| `payment.ts` | Payment sessions and processing |
+| `taxonomies.ts` | Categories and taxons |
+| `countries.ts` | Country and region data |
+| `cookies.ts` | Auth check helper |
+| `store.ts` | Store configuration |
+| `credit-cards.ts` | Saved payment methods |
+| `gift-cards.ts` | Gift card management |
+| `utils.ts` | Shared helpers (error handling, fallbacks) |
+
+These server actions wrap the `@spree/next` package functions. You can add custom logic, caching strategies, or additional transformations as needed.
+
+## Adding New Pages
+
+Follow the existing App Router pattern with localized routes. Place pages under the `(storefront)` route group to inherit the shared header/footer layout:
+
+```
+src/app/[country]/[locale]/(storefront)/your-new-page/page.tsx
+```
+
+```typescript
+import { listProducts } from '@spree/next';
+
+export default async function YourNewPage() {
+ const products = await listProducts({ limit: 6 });
+
+ return (
+ <div>
+ <h1>Your New Page</h1>
+ {/* Your content */}
+ </div>
+ );
+}
+```
+
+## Building a Custom Storefront
+
+If you prefer to build from scratch instead of forking the starter, you can use the `@spree/next` and `@spree/sdk` packages directly in any Next.js application. See the [@spree/next Package](/developer/storefront/nextjs/spree-next-package) documentation for the complete API reference.
diff --git a/docs/developer/storefront/nextjs/deployment.mdx b/docs/developer/storefront/nextjs/deployment.mdx
new file mode 100644
index 0000000000..6985d73482
--- /dev/null
+++ b/docs/developer/storefront/nextjs/deployment.mdx
@@ -0,0 +1,184 @@
+---
+title: Deployment
+description: Deploy the Spree Next.js Storefront to Vercel, Docker, or any Node.js host
+---
+
+## Environment Variables
+
+Set these variables in your hosting platform's dashboard or `.env` file.
+
+### Required
+
+| Variable | Description |
+|----------|-------------|
+| `SPREE_API_URL` | Your Spree API endpoint (e.g., `https://api.mystore.com`) |
+| `SPREE_PUBLISHABLE_KEY` | Publishable API key from your Spree admin |
+
+<Note>
+ These are server-side only variables — no `NEXT_PUBLIC_` prefix needed since all API calls happen in Server Actions.
+</Note>
+
+### Optional
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `GTM_ID` | Google Tag Manager container ID | _(disabled)_ |
+| `SENTRY_DSN` | Sentry DSN for error tracking | _(disabled)_ |
+| `SENTRY_ORG` | Sentry organization slug | _(none)_ |
+| `SENTRY_PROJECT` | Sentry project slug | _(none)_ |
+| `SENTRY_AUTH_TOKEN` | Sentry auth token (for source maps in CI) | _(none)_ |
+
+## Production Build
+
+```bash
+npm run build
+npm start
+```
+
+The build output is a standalone Next.js application. The `npm start` command starts the production server.
+
+## Vercel
+
+Vercel is the recommended deployment platform for Next.js applications.
+
+### One-Click Deploy
+
+1. Push your code to GitHub
+2. Go to [vercel.com/new](https://vercel.com/new) and import your repository
+3. Add environment variables (`SPREE_API_URL`, `SPREE_PUBLISHABLE_KEY`)
+4. Click **Deploy**
+
+Vercel automatically detects the Next.js framework and configures the build settings.
+
+### Vercel CLI
+
+```bash
+npm i -g vercel
+vercel
+```
+
+### Preview Deployments
+
+Every pull request gets a unique preview URL, making it easy to test storefront changes before merging. Add your Spree API environment variables to the Vercel project settings so previews connect to your staging API.
+
+## Docker
+
+Create a `Dockerfile` in your project root:
+
+```dockerfile
+FROM node:20-alpine AS base
+
+FROM base AS deps
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --production=false
+
+FROM base AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build
+
+FROM base AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 nextjs
+
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+
+USER nextjs
+EXPOSE 3000
+ENV PORT=3000
+ENV HOSTNAME="0.0.0.0"
+
+CMD ["node", "server.js"]
+```
+
+<Note>
+ Enable standalone output in your `next.config.ts` for Docker deployments:
+
+ ```typescript
+ const nextConfig = {
+ output: 'standalone',
+ }
+ ```
+</Note>
+
+Build and run:
+
+```bash
+docker build -t spree-storefront .
+docker run -p 3000:3000 \
+ -e SPREE_API_URL=https://api.mystore.com \
+ -e SPREE_PUBLISHABLE_KEY=your_key \
+ spree-storefront
+```
+
+## Self-Hosted Node.js
+
+For any platform that supports Node.js (Render, Railway, Fly.io, AWS, etc.):
+
+1. Install dependencies and build:
+
+```bash
+npm ci
+npm run build
+```
+
+2. Start the production server:
+
+```bash
+npm start
+```
+
+The server listens on port `3000` by default. Set the `PORT` environment variable to change it.
+
+## CI/CD
+
+### GitHub Actions
+
+```yaml
+name: Deploy Storefront
+on:
+ push:
+ branches: [main]
+
+jobs:
+ deploy:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - uses: actions/setup-node@v4
+ with:
+ node-version: 20
+ cache: npm
+
+ - run: npm ci
+ - run: npm run build
+
+ # Add your deployment step here
+ # Example for Vercel:
+ # - uses: amondnet/vercel-action@v25
+ # with:
+ # vercel-token: ${{ secrets.VERCEL_TOKEN }}
+ # vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
+ # vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
+ # vercel-args: --prod
+```
+
+## Performance Checklist
+
+Before going to production, verify:
+
+- **API URL** points to your production Spree instance (not `localhost`)
+- **HTTPS** is enabled on both the storefront and the Spree API
+- **CORS** is configured on your Spree API to allow requests from your storefront domain
+- **Sentry** is configured for error monitoring (`SENTRY_DSN`)
+- **GTM/GA4** is set up for analytics (`GTM_ID`)
+- **Cookie security** — the storefront uses `secure: true` for cookies in production (`NODE_ENV=production`)
+- **Caching** — Next.js cache tags are used for efficient revalidation; review your caching strategy for high-traffic stores
diff --git a/docs/developer/storefront/nextjs/quickstart.mdx b/docs/developer/storefront/nextjs/quickstart.mdx
new file mode 100644
index 0000000000..61a68e0a8e
--- /dev/null
+++ b/docs/developer/storefront/nextjs/quickstart.mdx
@@ -0,0 +1,94 @@
+---
+title: Quickstart
+description: Get started with the Spree Next.js Storefront
+---
+
+The [Spree Storefront](https://github.com/spree/storefront) is a production-ready, headless e-commerce storefront built with Next.js 16, React 19, and the Spree Commerce API v3.
+
+## Tech Stack
+
+- **Next.js 16** - App Router, Server Actions, Turbopack
+- **React 19** - Server Components
+- **Tailwind CSS 4** - Utility-first styling
+- **TypeScript 5** - Full type safety
+- **[@spree/sdk](https://github.com/spree/spree/tree/main/packages/sdk)** - Official Spree Commerce SDK
+- **[@spree/next](https://github.com/spree/spree/tree/main/packages/next)** - Server actions, caching, and cookie-based auth
+- **Sentry** - Error tracking and performance monitoring
+
+## Features
+
+- **Server-First Architecture** - All API calls happen server-side, API keys never exposed to the browser
+- **Secure Authentication** - JWT tokens stored in httpOnly cookies
+- **Product Catalog** - Browse, search, and filter with faceted navigation
+- **Shopping Cart** - Server-side state management
+- **Multi-Step Checkout** - Guest and signed-in users, multi-shipments, coupon codes, gift cards, store credit
+- **Stripe Payments** - Credit Cards, Apple Pay, Google Pay, Klarna, Affirm, SEPA and more via [Spree Stripe](https://github.com/spree/spree_stripe)
+- **Google Tag Manager** and **GA4 Ecommerce** event tracking
+- **Customer Account** - Profile, order history, address book, gift cards, saved payment methods
+- **Multi-Region** - Country and currency switching via URL segments
+- **Responsive Design** - Mobile-first Tailwind CSS
+
+## Prerequisites
+
+- Node.js 20+
+- A running Spree Commerce 5.4+ instance
+
+## Installation
+
+### Option 1: Fork the Repository (Recommended)
+
+Fork the repository on GitHub, then clone your fork:
+
+```bash
+git clone https://github.com/YOUR_USERNAME/storefront.git
+cd storefront
+npm install
+```
+
+This gives you a full copy you can customize freely while still being able to pull upstream updates.
+
+### Option 2: Clone Directly
+
+```bash
+git clone https://github.com/spree/storefront.git
+cd storefront
+npm install
+```
+
+## Configuration
+
+Copy the environment file:
+
+```bash
+cp .env.local.example .env.local
+```
+
+Update `.env.local` with your Spree API credentials:
+
+```env
+SPREE_API_URL=http://localhost:3000
+SPREE_PUBLISHABLE_KEY=your_publishable_api_key_here
+```
+
+<Note>
+ These are server-side only variables — no `NEXT_PUBLIC_` prefix needed since all API calls happen in Server Actions.
+</Note>
+
+See [Deployment](/developer/storefront/nextjs/deployment) for all optional environment variables (Sentry, GTM, etc.).
+
+## Development
+
+```bash
+npm run dev
+```
+
+Open [http://localhost:3001](http://localhost:3001) in your browser.
+
+## Production Build
+
+```bash
+npm run build
+npm start
+```
+
+See the [Deployment](/developer/storefront/nextjs/deployment) guide for Vercel, Docker, and other hosting options.
diff --git a/docs/developer/storefront/nextjs/spree-next-package.mdx b/docs/developer/storefront/nextjs/spree-next-package.mdx
new file mode 100644
index 0000000000..4efd91b17d
--- /dev/null
+++ b/docs/developer/storefront/nextjs/spree-next-package.mdx
@@ -0,0 +1,322 @@
+---
+title: "@spree/next Package"
+description: Next.js integration library — server actions, caching, and cookie-based auth
+---
+
+The `@spree/next` package provides a complete Next.js integration for Spree Commerce with server actions, automatic cookie management, and full TypeScript support.
+
+## Installation
+
+```bash
+npm install @spree/next @spree/sdk
+```
+
+## Configuration
+
+### Auto-initialization
+
+Set environment variables and the client initializes automatically:
+
+```env
+SPREE_API_URL=https://api.mystore.com
+SPREE_PUBLISHABLE_KEY=spree_pk_xxx
+```
+
+### Explicit initialization
+
+```typescript
+// lib/storefront.ts
+import { initSpreeNext } from '@spree/next';
+
+initSpreeNext({
+ baseUrl: process.env.SPREE_API_URL!,
+ publishableKey: process.env.SPREE_PUBLISHABLE_KEY!,
+ cartCookieName: '_spree_cart_token', // default
+ accessTokenCookieName: '_spree_jwt', // default
+ defaultLocale: 'en',
+ defaultCurrency: 'USD',
+ defaultCountry: 'US',
+});
+```
+
+## Data Functions
+
+Plain async functions for reading data in Server Components. Wrap with `"use cache"` in your app for caching.
+
+### Products
+
+```typescript
+import { listProducts, getProduct, getProductFilters } from '@spree/next';
+
+const products = await listProducts({ limit: 25 });
+const product = await getProduct('spree-tote', { expand: ['variants', 'images'] });
+const filters = await getProductFilters({ taxon_id_eq: 'txn_123' });
+```
+
+### Categories
+
+```typescript
+import { listTaxons, getTaxon, listTaxonProducts } from '@spree/next';
+import { listTaxonomies, getTaxonomy } from '@spree/next';
+
+const taxons = await listTaxons({ depth_eq: 1 });
+const taxon = await getTaxon('categories/clothing');
+const products = await listTaxonProducts('categories/clothing', { limit: 12 });
+
+const taxonomies = await listTaxonomies({ expand: ['taxons'] });
+const taxonomy = await getTaxonomy('tax_123');
+```
+
+### Store & Geography
+
+```typescript
+import { getStore, listCountries, getCountry, listCurrencies, listLocales } from '@spree/next';
+
+const store = await getStore();
+const countries = await listCountries();
+const usa = await getCountry('US');
+const currencies = await listCurrencies();
+const locales = await listLocales();
+```
+
+### Using in Server Components
+
+```typescript
+import { listProducts, listTaxons } from '@spree/next';
+
+export default async function ProductsPage() {
+ const products = await listProducts({ limit: 12 });
+ const categories = await listTaxons({ depth_eq: 1 });
+
+ return (
+ <div>
+ {products.data.map((product) => (
+ <div key={product.id}>{product.name}</div>
+ ))}
+ </div>
+ );
+}
+```
+
+## Server Actions
+
+Server actions handle mutations and auth-dependent reads. They automatically manage cookies for cart tokens and JWT authentication.
+
+### Cart
+
+```typescript
+import { getCart, getOrCreateCart, addItem, updateItem, removeItem, clearCart, associateCart } from '@spree/next';
+
+const cart = await getCart(); // null if no cart
+const cart = await getOrCreateCart(); // creates if needed
+await addItem(variantId, quantity);
+await updateItem(lineItemId, { quantity: 2 });
+await removeItem(lineItemId);
+await clearCart();
+await associateCart(); // link guest cart to logged-in user
+```
+
+### Checkout
+
+All checkout functions take `orderId` as the first argument:
+
+```typescript
+import {
+ getCheckout,
+ updateAddresses,
+ advance,
+ next,
+ getShipments,
+ selectShippingRate,
+ applyCoupon,
+ removeCoupon,
+ complete,
+} from '@spree/next';
+
+const checkout = await getCheckout(orderId);
+await updateAddresses(orderId, { ship_address: { ... }, bill_address: { ... } });
+await advance(orderId);
+await next(orderId);
+const shipments = await getShipments(orderId);
+await selectShippingRate(orderId, shipmentId, shippingRateId);
+await applyCoupon(orderId, 'SAVE20');
+await removeCoupon(orderId, promotionId);
+await complete(orderId);
+```
+
+### Authentication
+
+```typescript
+import { login, register, logout, getCustomer, updateCustomer } from '@spree/next';
+
+await login(email, password);
+await register(email, password, passwordConfirmation);
+await logout();
+const customer = await getCustomer(); // null if not logged in
+await updateCustomer({ first_name: 'John' });
+```
+
+### Addresses
+
+```typescript
+import { listAddresses, getAddress, createAddress, updateAddress, deleteAddress } from '@spree/next';
+
+const addresses = await listAddresses();
+const address = await getAddress(addressId);
+await createAddress({ firstname: 'John', address1: '123 Main St', ... });
+await updateAddress(addressId, { city: 'Brooklyn' });
+await deleteAddress(addressId);
+```
+
+### Orders
+
+```typescript
+import { listOrders, getOrder } from '@spree/next';
+
+const orders = await listOrders();
+const order = await getOrder(orderId);
+```
+
+### Payment Sessions
+
+```typescript
+import {
+ createPaymentSession,
+ getPaymentSession,
+ updatePaymentSession,
+ completePaymentSession,
+} from '@spree/next';
+
+const session = await createPaymentSession(orderId, { payment_method_id: 'pm_123' });
+
+// Access provider data (e.g., Stripe client secret)
+const clientSecret = session.external_data.client_secret;
+
+const current = await getPaymentSession(orderId, sessionId);
+await updatePaymentSession(orderId, sessionId, { amount: '50.00' });
+await completePaymentSession(orderId, sessionId, { session_result: 'success' });
+```
+
+### Payment Setup Sessions
+
+For saving payment methods outside of checkout (e.g., "Add a credit card" in account settings):
+
+```typescript
+import {
+ createPaymentSetupSession,
+ getPaymentSetupSession,
+ completePaymentSetupSession,
+} from '@spree/next';
+
+const session = await createPaymentSetupSession({ payment_method_id: 'pm_123' });
+const current = await getPaymentSetupSession(sessionId);
+await completePaymentSetupSession(sessionId, { session_result: 'success' });
+```
+
+### Credit Cards & Gift Cards
+
+```typescript
+import { listCreditCards, deleteCreditCard } from '@spree/next';
+import { listGiftCards, getGiftCard } from '@spree/next';
+
+const cards = await listCreditCards();
+await deleteCreditCard(cardId);
+
+const giftCards = await listGiftCards();
+const giftCard = await getGiftCard(giftCardId);
+```
+
+## Using Server Actions in Forms
+
+```typescript
+import { addItem, getCart } from '@spree/next';
+
+export default async function CartPage() {
+ const cart = await getCart();
+
+ async function handleAddItem(formData: FormData) {
+ 'use server';
+ await addItem(formData.get('variantId') as string, 1);
+ }
+
+ return <form action={handleAddItem}>...</form>;
+}
+```
+
+## Localization
+
+### Automatic (recommended)
+
+Data functions automatically read locale and country from cookies. Use the included middleware to set cookies based on the URL:
+
+```typescript
+// middleware.ts
+import { createSpreeMiddleware } from '@spree/next/middleware';
+
+export default createSpreeMiddleware({
+ defaultCountry: 'us',
+ defaultLocale: 'en',
+});
+
+export const config = {
+ matcher: ['/((?!_next/static|_next/image|favicon.ico|.*\\..*$).*)'],
+};
+```
+
+Then data functions work without any locale arguments:
+
+```typescript
+// Locale/country auto-read from cookies — no options needed
+const products = await listProducts({ limit: 10 });
+const taxon = await getTaxon('categories/clothing');
+```
+
+Use the `setLocale` server action in country/language switchers:
+
+```typescript
+import { setLocale } from '@spree/next';
+
+await setLocale({ country: 'de', locale: 'de' });
+```
+
+### Manual override
+
+You can still pass locale options explicitly — they override the auto-detected values:
+
+```typescript
+const products = await listProducts({ limit: 10 }, { locale: 'fr', country: 'FR' });
+const taxon = await getTaxon('categories/clothing', {}, { locale: 'de', country: 'DE' });
+```
+
+## TypeScript
+
+All types are re-exported from `@spree/sdk`:
+
+```typescript
+import type {
+ StoreProduct,
+ StoreOrder,
+ StoreLineItem,
+ StoreVariant,
+ StoreTaxon,
+ StoreTaxonomy,
+ StoreCountry,
+ StoreCurrency,
+ StoreLocale,
+ StoreStore,
+ StoreAddress,
+ StoreCustomer,
+ StoreCreditCard,
+ StoreGiftCard,
+ StoreShipment,
+ StoreShippingRate,
+ StorePayment,
+ StorePaymentMethod,
+ StorePaymentSession,
+ StorePaymentSetupSession,
+ PaginatedResponse,
+ ProductFiltersResponse,
+ AddressParams,
+ SpreeError,
+} from '@spree/next';
+```
diff --git a/docs/developer/storefront/storefront.mdx b/docs/developer/storefront/storefront.mdx
index 6eb2096cf8..40fc53de7a 100644
--- a/docs/developer/storefront/storefront.mdx
+++ b/docs/developer/storefront/storefront.mdx
@@ -1,13 +1,43 @@
---
-title: "Storefront Overview"
+title: "Rails Storefront Overview"
sidebarTitle: "Overview"
---
-Spree 5 ships with a new mobile-first storefront that is fully customizable & themeable.
+Rails Storefront is a mobile-first storefront that is fully customizable & themeable.
-## Architecture
+### Tech Stack
-Spree Storefront consists of:
+- [Ruby on Rails](https://rubyonrails.org/)
+- [Tailwind CSS v4](https://tailwindcss.com/) — Responsive, mobile-first design
+- [Turbo / Hotwire](https://turbo.hotwired.dev/) — Fast, SPA-like navigation
+- [StimulusJS](https://stimulus.hotwired.dev/) — JavaScript controllers for interactivity
+- [Importmaps](https://github.com/rails/importmap-rails) - NodeJS not required
+
+### Installation
+
+You can install it by running
+
+ ```bash
+ bundle add spree_storefront
+ ```
+
+Then run the install generator:
+
+ ```bash
+ bin/rails g spree:storefront:install
+ ```
+
+This will set up the storefront views, Tailwind CSS configuration, and page builder migrations.
+
+You will also need to create your first theme:
+
+ ```bash
+ Spree::Store.default.send(:create_default_theme)
+ ```
+
+### Architecture
+
+Rails Storefront consists of:
<CardGroup>
<Card title="Themes" href="/developer/storefront/themes">
@@ -27,11 +57,10 @@ Spree Storefront consists of:
</Card>
</CardGroup>
-## Page Builder
+### Page Builder
-The new storefront comes with a visual Page Builder that allows non-developers to build pages using a drag-and-drop interface, as a part of Spree Admin Dashboard (provided via `spree_admin` gem). This allows your team to create new pages and sections, modify existing ones, and add new blocks to the pages in a no-code way.
+The storefront comes with a visual Page Builder that allows non-developers to build pages using a drag-and-drop interface. This allows your team to create new pages and sections, modify existing ones, and add new blocks to the pages in a no-code way.
![](https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1738166777/docs/Storefront/Theme%20Editor/7.1.1.1.2_Theme_Editor_-_Click_On_Default_Theme_qy0urp.png)
You can learn more about the Page Builder in the [User Documentation](/user/storefront/theme-editor).
-
diff --git a/docs/developer/tutorial/introduction.mdx b/docs/developer/tutorial/introduction.mdx
index e8e090f69e..9551c19c63 100644
--- a/docs/developer/tutorial/introduction.mdx
+++ b/docs/developer/tutorial/introduction.mdx
@@ -4,13 +4,13 @@ sidebarTitle: Introduction
description: Learn how to build a custom feature from scratch, covering models, Admin dashboard, API and Storefront.
---
-This tutorial walks you through creating a complete Spree feature from scratch, covering models, Admin dashboard, API and Storefront.
+This tutorial walks you through creating a complete Spree feature from scratch, covering models, Admin dashboard and API.
You will also learn how to extend core Spree features to connect them with your new feature.
By the end, you'll understand how to add new manageable features to the Spree platform.
## Overview
-Spree is built on top of [Ruby on Rails framework](https://rubyonrails.org) and follows Model-View-Controller (MVC) architecture. To fully implement a new feature, you will typically create the following components:
+To fully implement a new feature, you will typically create the following components:
* Database model
* Admin Dashboard controllers and views
@@ -35,9 +35,6 @@ Spree is built on top of [Ruby on Rails framework](https://rubyonrails.org) and
<Card title="5. Extending Core Models" icon="plug" href="/developer/tutorial/extending-models">
Connect Brands to Products using associations
</Card>
- <Card title="6. Storefront" icon="store" href="/developer/tutorial/storefront">
- Create customer-facing brand pages
- </Card>
<Card title="7. Testing" icon="flask-vial" href="/developer/tutorial/testing">
Write automated tests for your feature
</Card>
@@ -45,4 +42,4 @@ Spree is built on top of [Ruby on Rails framework](https://rubyonrails.org) and
## Example: Building a Brands Feature
-In this guide we will create a complete "Brands" feature that allows admins to manage [Product](/developer/core-concepts/products) brands.
\ No newline at end of file
+In this guide we will create a complete "Brands" feature that allows admins to manage [Product](/developer/core-concepts/products) brands.
diff --git a/docs/developer/upgrades/4.5-to-4.6.mdx b/docs/developer/upgrades/4.5-to-4.6.mdx
index 2fa196ee8d..1d1c737471 100644
--- a/docs/developer/upgrades/4.5-to-4.6.mdx
+++ b/docs/developer/upgrades/4.5-to-4.6.mdx
@@ -30,7 +30,7 @@ If your application used the spree_globalize extension, you can remove it from y
We've configured Mobility to use [a strategy that uses a separate table to store translations](https://dejimata.com/2017/3/3/translating-with-mobility#strategy-2), just like how spree_globalize did. This means, you won't need to make any changes to the database structure or migrate data.
-During the upgrade process, you may need to review your custom queries that rely on translations, as there are minor differences in how Mobility handles them. Spree 4.6 includes a few [built-in concerns](/developer/core-concepts/i18n#resource-translations-implementation) to make it easier to work with translatable models.
+During the upgrade process, you may need to review your custom queries that rely on translations, as there are minor differences in how Mobility handles them. Spree 4.6 includes a few [built-in concerns](/developer/core-concepts/translations#resource-translations-implementation) to make it easier to work with translatable models.
Run the following command to remove spree_globalize from your Gemfile:
@@ -74,7 +74,7 @@ bin/rails g spree:frontend:install
### Update migrations for translation tables with additional columns
-If you want to translate more fields in [translated resources](/developer/core-concepts/i18n#resource-translations), you have to alter copied migrations or add new ones.
+If you want to translate more fields in [translated resources](/developer/core-concepts/translations#resource-translations), you have to alter copied migrations or add new ones.
We're using the [Spree::TranslationMigrations](https://github.com/spree/spree/blob/main/core/lib/spree/translation_migrations.rb) to help with migrating data.
### Add or update the behavior of the translated model
@@ -86,7 +86,7 @@ If you overwrote Spree models in your application, you have to define this block
- `Spree::TranslatableResource` - required for all translated models
- `Spree::TranslatableResourceSlug` - required for translated models with slugs/permalinks
-[Read more](/developer/core-concepts/i18n#resource-translations-implementation) how Spree handles resource translations.
+[Read more](/developer/core-concepts/translations#resource-translations-implementation) how Spree handles resource translations.
### Generating slugs with `friendly_id`
@@ -98,7 +98,7 @@ Currently, it's not possible to translate encrypted data. If you're already encr
### Full text search with pg_search scopes
-If you use the [pg_search](https://github.com/Casecommons/pg_search) for the full text search in [translated resources](/developer/core-concepts/i18n#resource-translations), you need to move your scopes to the translated model, eg. from the `Spree::Product` to the `Spree::Product::Translation`.
+If you use the [pg_search](https://github.com/Casecommons/pg_search) for the full text search in [translated resources](/developer/core-concepts/translations#resource-translations), you need to move your scopes to the translated model, eg. from the `Spree::Product` to the `Spree::Product::Translation`.
If you still want to have the original scope, you need to rewrite it, from:
diff --git a/docs/docs.json b/docs/docs.json
index af3f6fec90..149079180a 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -1,21 +1,26 @@
{
"$schema": "https://mintlify.com/docs.json",
"name": "Spree Commerce documentation",
- "theme": "almond",
+ "theme": "sequoia",
"colors": {
"primary": "#0A2242",
"light": "#D7DFE9",
"dark": "#0A2242"
},
+ "fonts": {
+ "body": {
+ "family": "Inter"
+ },
+ "heading": {
+ "family": "Inter"
+ }
+ },
"styling": {
"eyebrows": "breadcrumbs",
"codeblocks": {
"theme": "night-owl"
}
},
- "interaction": {
- "drilldown": true
- },
"favicon": "/favicon.png",
"seo": {
"metatags": {
@@ -44,27 +49,36 @@
"source": "/developer/customization/webhooks",
"destination": "/developer/core-concepts/webhooks"
},
+ {
+ "source": "/developer/core-concepts/i18n",
+ "destination": "/developer/core-concepts/translations"
+ },
{
"source": "/developer/customization/promotions",
- "destination": "/developer/core-concepts/promotions"
+ "destination": "/developer/how-to/custom-promotion"
+ },
+ {
+ "source": "/developer/core-concepts/users",
+ "destination": "/developer/core-concepts/customers"
},
{
"source": "/developer/extending-spree/promotions",
- "destination": "/developer/core-concepts/promotions"
+ "destination": "/developer/how-to/custom-promotion"
}
],
"contextual": {
"options": ["copy", "view", "chatgpt", "claude", "mcp", "cursor", "vscode"]
},
"navigation": {
- "versions": [
+ "pages": ["index"],
+ "tabs": [
{
- "version": "v5",
- "default": true,
- "pages": ["index"],
- "tabs": [
+ "tab": "Guides",
+ "menu": [
{
- "tab": "Developer Docs",
+ "item": "Getting Started",
+ "icon": "rocket",
+ "description": "Quickstart guide and core concepts",
"groups": [
{
"group": "Getting started",
@@ -72,49 +86,136 @@
"pages": ["developer/getting-started/quickstart"]
},
{
- "group": "Tutorial",
- "icon": "graduation-cap",
+ "group": "Platform",
+ "icon": "settings",
"pages": [
- "developer/tutorial/introduction",
- "developer/tutorial/model",
- "developer/tutorial/admin",
- "developer/tutorial/rich-text",
- "developer/tutorial/file-uploads",
- "developer/tutorial/extending-models",
- "developer/tutorial/storefront",
- "developer/tutorial/testing"
+ "developer/core-concepts/architecture",
+ "developer/core-concepts/stores",
+ "developer/core-concepts/markets",
+ "developer/core-concepts/customers",
+ "developer/core-concepts/staff-roles"
]
},
{
- "group": "Core Concepts",
- "icon": "brain",
+ "group": "Catalog",
+ "icon": "package",
"pages": [
- "developer/core-concepts/architecture",
- "developer/core-concepts/stores",
- "developer/core-concepts/markets",
- "developer/core-concepts/orders",
- "developer/core-concepts/users",
"developer/core-concepts/products",
"developer/core-concepts/pricing",
"developer/core-concepts/inventory",
+ "developer/core-concepts/images-assets",
+ "developer/core-concepts/search-filtering"
+ ]
+ },
+ {
+ "group": "Cart & Checkout",
+ "icon": "shopping-cart",
+ "pages": [
+ "developer/core-concepts/orders",
"developer/core-concepts/payments",
- "developer/core-concepts/store-credits-gift-cards",
"developer/core-concepts/taxes",
"developer/core-concepts/promotions",
+ "developer/core-concepts/store-credits-gift-cards"
+ ]
+ },
+ {
+ "group": "Fulfillment",
+ "icon": "truck",
+ "pages": [
"developer/core-concepts/shipments",
- "developer/core-concepts/calculators",
- "developer/core-concepts/adjustments",
"developer/core-concepts/addresses",
- "developer/core-concepts/metafields",
+ "developer/core-concepts/adjustments",
+ "developer/core-concepts/calculators"
+ ]
+ },
+ {
+ "group": "Extensibility",
+ "icon": "plug",
+ "pages": [
"developer/core-concepts/events",
"developer/core-concepts/webhooks",
- "developer/core-concepts/i18n",
- "developer/core-concepts/search-filtering",
+ "developer/core-concepts/translations",
"developer/core-concepts/slugs",
- "developer/core-concepts/images-assets",
+ "developer/core-concepts/metafields",
"developer/core-concepts/reports",
"developer/core-concepts/imports-exports"
]
+ }
+ ]
+ },
+ {
+ "item": "Building a Storefront",
+ "icon": "store",
+ "description": "Next.js, custom frontend, or Rails engine",
+ "groups": [
+ {
+ "group": "Next.js Storefront",
+ "pages": [
+ "developer/storefront/nextjs/quickstart",
+ "developer/storefront/nextjs/architecture",
+ "developer/storefront/nextjs/spree-next-package",
+ "developer/storefront/nextjs/customization",
+ "developer/storefront/nextjs/deployment"
+ ]
+ },
+ {
+ "group": "Custom Frontend",
+ "pages": ["developer/storefront/custom/quickstart"]
+ }
+ ]
+ },
+ {
+ "item": "Use Cases",
+ "icon": "book-open",
+ "description": "Multi-store, multi-tenant, and marketplace setups",
+ "groups": [
+ {
+ "group": "Multi-Store",
+ "pages": [
+ "developer/multi-store/quickstart",
+ "developer/multi-store/setup"
+ ]
+ },
+ {
+ "group": "Multi-Tenant",
+ "pages": [
+ "developer/multi-tenant/quickstart",
+ "developer/multi-tenant/installation",
+ "developer/multi-tenant/core-concepts",
+ "developer/multi-tenant/configuration"
+ ]
+ },
+ {
+ "group": "Multi-Vendor",
+ "pages": [
+ "developer/multi-vendor/quickstart",
+ "developer/multi-vendor/installation"
+ ]
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "tab": "Framework",
+ "menu": [
+ {
+ "item": "Extending",
+ "icon": "puzzle",
+ "description": "Customize admin, models, and business logic",
+ "groups": [
+ {
+ "group": "Tutorial",
+ "icon": "graduation-cap",
+ "pages": [
+ "developer/tutorial/introduction",
+ "developer/tutorial/model",
+ "developer/tutorial/admin",
+ "developer/tutorial/rich-text",
+ "developer/tutorial/file-uploads",
+ "developer/tutorial/extending-models",
+ "developer/tutorial/testing"
+ ]
},
{
"group": "Admin Dashboard",
@@ -132,21 +233,6 @@
"developer/admin/custom-css"
]
},
- {
- "group": "Storefront",
- "icon": "store",
- "pages": [
- "developer/storefront/storefront",
- "developer/storefront/themes",
- "developer/storefront/pages",
- "developer/storefront/sections",
- "developer/storefront/blocks",
- "developer/storefront/links",
- "developer/storefront/helper-methods",
- "developer/storefront/custom-javascript",
- "developer/storefront/custom-css"
- ]
- },
{
"group": "Customization Reference",
"icon": "wrench",
@@ -164,49 +250,48 @@
"developer/customization/api",
"developer/customization/extensions"
]
+ }
+ ]
+ },
+ {
+ "item": "How-to Guides",
+ "icon": "book-open",
+ "description": "Step-by-step guides for common tasks",
+ "groups": [
+ {
+ "group": "Payments",
+ "icon": "credit-card",
+ "pages": ["developer/how-to/custom-payment-method"]
},
{
- "group": "Use Cases",
- "icon": "book-open",
- "pages": [
- {
- "group": "Multi-Store",
- "pages": [
- "developer/multi-store/quickstart",
- "developer/multi-store/setup"
- ]
- },
- {
- "group": "Multi-Tenant",
- "pages": [
- "developer/multi-tenant/quickstart",
- "developer/multi-tenant/installation",
- "developer/multi-tenant/core-concepts",
- "developer/multi-tenant/configuration"
- ]
- },
- {
- "group": "Multi-Vendor",
- "pages": [
- "developer/multi-vendor/quickstart",
- "developer/multi-vendor/installation"
- ]
- }
- ]
+ "group": "Promotions",
+ "icon": "tag",
+ "pages": ["developer/how-to/custom-promotion"]
},
+ {
+ "group": "Reports",
+ "icon": "chart-bar",
+ "pages": ["developer/how-to/custom-report"]
+ }
+ ]
+ },
+ {
+ "item": "Operations",
+ "icon": "server",
+ "description": "Deploy, upgrade, and maintain your store",
+ "groups": [
{
"group": "Deployment",
"icon": "server",
"pages": [
- "developer/deployment/database",
- "developer/deployment/render",
- "developer/deployment/aws",
"developer/deployment/docker",
"developer/deployment/environment_variables",
- "developer/deployment/emails",
+ "developer/deployment/caching",
"developer/deployment/assets",
"developer/deployment/cdn",
- "developer/deployment/caching"
+ "developer/deployment/emails",
+ "developer/deployment/database",
+ "developer/deployment/aws"
]
},
{
@@ -265,17 +350,119 @@
]
}
]
+ }
+ ]
+ },
+ {
+ "tab": "SDK & Tools",
+ "menu": [
+ {
+ "item": "SDK",
+ "icon": "code",
+ "description": "JavaScript/TypeScript SDK for Spree API",
+ "groups": [
+ {
+ "group": "Getting Started",
+ "pages": [
+ "developer/sdk/quickstart",
+ "developer/sdk/authentication",
+ "developer/sdk/configuration"
+ ]
+ },
+ {
+ "group": "Store API",
+ "pages": [
+ "developer/sdk/store/products",
+ "developer/sdk/store/cart-checkout",
+ "developer/sdk/store/payments",
+ "developer/sdk/store/markets",
+ "developer/sdk/store/account",
+ "developer/sdk/store/wishlists"
+ ]
+ },
+ {
+ "group": "Admin API",
+ "pages": ["developer/sdk/admin/quickstart"]
+ }
+ ]
+ },
+ {
+ "item": "CLI",
+ "icon": "square-terminal",
+ "description": "Command-line interface for Spree",
+ "groups": [
+ {
+ "group": "CLI",
+ "pages": ["developer/cli/quickstart"]
+ }
+ ]
+ },
+ {
+ "item": "create-spree-app",
+ "icon": "rocket",
+ "description": "Scaffold a new Spree project",
+ "groups": [
+ {
+ "group": "create-spree-app",
+ "pages": ["developer/create-spree-app/quickstart"]
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "tab": "API Reference",
+ "menu": [
+ {
+ "item": "Store API",
+ "icon": "store",
+ "description": "REST API for storefronts and custom integrations",
+ "groups": [
+ {
+ "group": "API basics",
+ "pages": [
+ "api-reference/store-api/introduction",
+ "api-reference/store-api/authentication",
+ "api-reference/store-api/errors",
+ "api-reference/store-api/rate-limitting",
+ "api-reference/store-api/querying",
+ "api-reference/store-api/relations",
+ "api-reference/store-api/metadata",
+ "api-reference/store-api/localization"
+ ]
+ },
+ {
+ "group": "Endpoints",
+ "openapi": {
+ "source": "api-reference/store.yaml",
+ "directory": "api-reference/store-api"
+ }
+ }
+ ]
+ },
+ {
+ "item": "Webhooks",
+ "icon": "webhook",
+ "description": "Event payloads and delivery reference",
+ "groups": [
+ {
+ "group": "Webhooks",
+ "pages": ["api-reference/webhooks-events"]
+ }
+ ]
},
{
- "tab": "Ecommerce API",
+ "item": "Legacy API v2",
+ "icon": "clock",
+ "description": "Previous-generation Storefront and Platform APIs",
"groups": [
{
"group": "API basics",
"pages": [
- "api-reference/introduction",
- "api-reference/pagination",
- "api-reference/filtering-and-sorting",
- "api-reference/fetching-multiple-resources"
+ "api-reference/v2/introduction",
+ "api-reference/v2/pagination",
+ "api-reference/v2/filtering-and-sorting",
+ "api-reference/v2/fetching-multiple-resources"
]
},
{
@@ -288,1713 +475,273 @@
},
{
"group": "Storefront API",
- "pages": [
- "api-reference/storefront/authentication",
- {
- "group": "Account",
- "pages": [
- "api-reference/storefront/account/retrieve-an-account",
- "api-reference/storefront/account/create-an-account",
- "api-reference/storefront/account/update-an-account"
- ]
- },
- {
- "group": "Account / Address",
- "pages": [
- "api-reference/storefront/account-address/list-all-addresses",
- "api-reference/storefront/account-address/create-an-address",
- "api-reference/storefront/account-address/remove-an-address",
- "api-reference/storefront/account-address/update-an-address"
- ]
- },
- {
- "group": "Account / Credit Cards",
- "pages": [
- "api-reference/storefront/account-credit-cards/list-all-credit-cards",
- "api-reference/storefront/account-credit-cards/remove-a-credit-card",
- "api-reference/storefront/account-credit-cards/retrieve-the-default-credit-card"
- ]
- },
- {
- "group": "Account / Orders",
- "pages": [
- "api-reference/storefront/account-orders/list-all-orders",
- "api-reference/storefront/account-orders/retrieve-an-order"
- ]
- },
- {
- "group": "Order Status",
- "pages": [
- "api-reference/storefront/order-status/retrieve-an-order-status"
- ]
- },
- {
- "group": "Cart",
- "pages": [
- "api-reference/storefront/cart/retrieve-a-cart",
- "api-reference/storefront/cart/create-a-cart",
- "api-reference/storefront/cart/delete-a-cart"
- ]
- },
- {
- "group": "Cart / Line Items",
- "pages": [
- "api-reference/storefront/cart-line-items/add-an-item-to-cart",
- "api-reference/storefront/cart-line-items/set-line-item-quantity",
- "api-reference/storefront/cart-line-items/remove-a-line-item"
- ]
- },
- {
- "group": "Cart / Coupons & Gift Cards",
- "pages": [
- "api-reference/storefront/cart-coupons/apply-a-coupon-code",
- "api-reference/storefront/cart-coupons/remove-a-coupon",
- "api-reference/storefront/cart-coupons/remove-all-coupons"
- ]
- },
- {
- "group": "Cart / Other",
- "pages": [
- "api-reference/storefront/cart-other/empty-the-cart",
- "api-reference/storefront/cart-other/list-estimated-shipping-rates",
- "api-reference/storefront/cart-other/associate-a-cart-with-a-user",
- "api-reference/storefront/cart-other/change-cart-currency"
- ]
- },
- {
- "group": "Checkout",
- "pages": [
- "api-reference/storefront/checkout/update-checkout",
- "api-reference/storefront/checkout/validate-order-payment"
- ]
- },
- {
- "group": "Checkout / State",
- "pages": [
- "api-reference/storefront/checkout-state/next-checkout-step",
- "api-reference/storefront/checkout-state/advance-checkout",
- "api-reference/storefront/checkout-state/complete-checkout"
- ]
- },
- {
- "group": "Checkout / Shipments",
- "pages": [
- "api-reference/storefront/checkout-shipments/selects-shipping-method-for-shipments",
- "api-reference/storefront/checkout-shipments/list-shipping-rates"
- ]
- },
- {
- "group": "Checkout / Payments",
- "pages": [
- "api-reference/storefront/checkout-payments/create-new-payment",
- "api-reference/storefront/checkout-payments/list-payment-methods"
- ]
- },
- {
- "group": "Checkout / Store Credit",
- "pages": [
- "api-reference/storefront/checkout-store-credit/add-store-credit",
- "api-reference/storefront/checkout-store-credit/remove-store-credit"
- ]
- },
- {
- "group": "Stripe",
- "pages": [
- "api-reference/storefront/stripe/return-a-stripe-payment-intent",
- "api-reference/storefront/stripe/create-a-stripe-payment-intent",
- "api-reference/storefront/stripe/updates-stripe-payment-intent",
- "api-reference/storefront/stripe/mark-the-payment-intent-as-confirmed-and-move-the-order-to-the-complete-state",
- "api-reference/storefront/stripe/create-a-stripe-setup-intent"
- ]
- },
- {
- "group": "Adyen",
- "pages": [
- "api-reference/storefront/adyen/create-an-adyen-payment-session",
- "api-reference/storefront/adyen/complete-an-adyen-payment-session",
- "api-reference/storefront/adyen/get-adyen-payment-session"
- ]
- },
- {
- "group": "Products",
- "pages": [
- "api-reference/storefront/products/list-all-products",
- "api-reference/storefront/products/retrieve-a-product"
- ]
- },
- {
- "group": "Vendors",
- "pages": [
- "api-reference/storefront/vendors/list-all-vendors",
- "api-reference/storefront/vendors/retrieve-a-vendor"
- ]
- },
- {
- "group": "Stores",
- "pages": [
- "api-reference/storefront/stores/return-the-current-store"
- ]
- },
- {
- "group": "Policies",
- "pages": [
- "api-reference/storefront/policies/list-all-store-policies",
- "api-reference/storefront/policies/retrieve-a-policy"
- ]
- },
- {
- "group": "Posts",
- "pages": [
- "api-reference/storefront/posts/list-all-posts",
- "api-reference/storefront/posts/retrieve-a-post"
- ]
- },
- {
- "group": "Post Categories",
- "pages": [
- "api-reference/storefront/post-categories/list-all-post-categories",
- "api-reference/storefront/post-categories/retrieve-a-post-category"
- ]
- },
- {
- "group": "Taxons",
- "pages": [
- "api-reference/storefront/taxons/list-all-taxons",
- "api-reference/storefront/taxons/retrieve-a-taxon"
- ]
- },
- {
- "group": "Countries",
- "pages": [
- "api-reference/storefront/countries/list-all-countries",
- "api-reference/storefront/countries/retrieve-a-country",
- "api-reference/storefront/countries/get-default-country"
- ]
- },
- {
- "group": "Wishlists",
- "pages": [
- "api-reference/storefront/wishlists/list-all-wishlists",
- "api-reference/storefront/wishlists/create-a-wishlist",
- "api-reference/storefront/wishlists/retrieve-a-wishlist",
- "api-reference/storefront/wishlists/delete-a-wishlist",
- "api-reference/storefront/wishlists/update-a-wishlist",
- "api-reference/storefront/wishlists/retrieve-the-default-wishlist"
- ]
- },
- {
- "group": "Wishlists / Wished Items",
- "pages": [
- "api-reference/storefront/wishlists-wished-items/add-item-to-wishlist",
- "api-reference/storefront/wishlists-wished-items/add-items-to-wishlist",
- "api-reference/storefront/wishlists-wished-items/set-wished-item-quantity",
- "api-reference/storefront/wishlists-wished-items/delete-item-from-wishlist",
- "api-reference/storefront/wishlists-wished-items/delete-items-from-wishlist"
- ]
- },
- {
- "group": "Digital Downloads",
- "pages": [
- "api-reference/storefront/digital-downloads/download-a-digital-asset"
- ]
- }
- ]
+ "pages": ["api-reference/storefront/authentication"],
+ "openapi": {
+ "source": "api-reference/storefront.yaml",
+ "directory": "api-reference/storefront"
+ }
},
{
"group": "Platform API",
- "pages": [
- "api-reference/platform/authentication",
- {
- "group": "Addresses",
- "pages": [
- "api-reference/platform/addresses/return-a-list-of-addresses",
- "api-reference/platform/addresses/create-an-address",
- "api-reference/platform/addresses/return-an-address",
- "api-reference/platform/addresses/delete-an-address",
- "api-reference/platform/addresses/update-an-address"
- ]
- },
- {
- "group": "Adjustments",
- "pages": [
- "api-reference/platform/adjustments/return-a-list-of-adjustments",
- "api-reference/platform/adjustments/create-an-adjustment",
- "api-reference/platform/adjustments/return-an-adjustment",
- "api-reference/platform/adjustments/delete-an-adjustment",
- "api-reference/platform/adjustments/update-an-adjustment"
- ]
- },
- {
- "group": "Classifications",
- "pages": [
- "api-reference/platform/classifications/return-a-list-of-classifications",
- "api-reference/platform/classifications/create-a-classification",
- "api-reference/platform/classifications/return-a-classification",
- "api-reference/platform/classifications/delete-a-classification",
- "api-reference/platform/classifications/update-a-classification"
- ]
- },
- {
- "group": "Countries",
- "pages": [
- "api-reference/platform/countries/returns-a-list-of-countries",
- "api-reference/platform/countries/returns-a-country"
- ]
- },
- {
- "group": "Data Feeds",
- "pages": [
- "api-reference/platform/data-feeds/return-a-list-of-data-feeds",
- "api-reference/platform/data-feeds/create-a-data-feed",
- "api-reference/platform/data-feeds/return-a-data-feed",
- "api-reference/platform/data-feeds/delete-a-data-feed",
- "api-reference/platform/data-feeds/update-a-data-feed"
- ]
- },
- {
- "group": "Digital Links",
- "pages": [
- "api-reference/platform/digital-links/return-a-list-of-digital-links",
- "api-reference/platform/digital-links/create-a-digital-link",
- "api-reference/platform/digital-links/return-a-digital-link",
- "api-reference/platform/digital-links/delete-a-digital-link",
- "api-reference/platform/digital-links/update-a-digital-link",
- "api-reference/platform/digital-links/reset-a-digital-link"
- ]
- },
- {
- "group": "Digital Assets",
- "pages": [
- "api-reference/platform/digital-assets/return-a-list-of-digital-assets",
- "api-reference/platform/digital-assets/create-a-digital-asset",
- "api-reference/platform/digital-assets/return-a-digital-asset",
- "api-reference/platform/digital-assets/delete-a-digital-asset",
- "api-reference/platform/digital-assets/update-a-digital-asset"
- ]
- },
- {
- "group": "Line Items",
- "pages": [
- "api-reference/platform/line-items/return-a-list-of-line-items",
- "api-reference/platform/line-items/create-a-line-item",
- "api-reference/platform/line-items/return-a-line-item",
- "api-reference/platform/line-items/delete-a-line-item",
- "api-reference/platform/line-items/update-a-line-item"
- ]
- },
- {
- "group": "Option Types",
- "pages": [
- "api-reference/platform/option-types/return-a-list-of-option-types",
- "api-reference/platform/option-types/create-an-option-type",
- "api-reference/platform/option-types/return-an-option-type",
- "api-reference/platform/option-types/delete-an-option-type",
- "api-reference/platform/option-types/update-an-option-type"
- ]
- },
- {
- "group": "Option Values",
- "pages": [
- "api-reference/platform/option-values/return-a-list-of-option-values",
- "api-reference/platform/option-values/create-an-option-value",
- "api-reference/platform/option-values/return-an-option-value",
- "api-reference/platform/option-values/delete-an-option-value",
- "api-reference/platform/option-values/update-an-option-value"
- ]
- },
- {
- "group": "Orders",
- "pages": [
- "api-reference/platform/orders/return-a-list-of-orders",
- "api-reference/platform/orders/creates-an-order",
- "api-reference/platform/orders/return-an-order",
- "api-reference/platform/orders/delete-an-order",
- "api-reference/platform/orders/update-an-order",
- "api-reference/platform/orders/advances-an-order",
- "api-reference/platform/orders/next-an-order",
- "api-reference/platform/orders/completes-an-order",
- "api-reference/platform/orders/empties-an-order",
- "api-reference/platform/orders/approves-an-order",
- "api-reference/platform/orders/cancels-an-order",
- "api-reference/platform/orders/use-store-credit-for-an-order",
- "api-reference/platform/orders/apply-coupon-code-for-an-order"
- ]
- },
- {
- "group": "Payment Methods",
- "pages": [
- "api-reference/platform/payment-methods/return-a-list-of-payment-methods",
- "api-reference/platform/payment-methods/create-a-payment-method",
- "api-reference/platform/payment-methods/return-a-payment-method",
- "api-reference/platform/payment-methods/delete-a-payment-method",
- "api-reference/platform/payment-methods/update-a-payment-method"
- ]
- },
- {
- "group": "Payments",
- "pages": [
- "api-reference/platform/payments/return-a-list-of-payments",
- "api-reference/platform/payments/return-a-payment",
- "api-reference/platform/payments/delete-a-payment"
- ]
- },
- {
- "group": "Products",
- "pages": [
- "api-reference/platform/products/return-a-list-of-products",
- "api-reference/platform/products/create-a-product",
- "api-reference/platform/products/return-a-product",
- "api-reference/platform/products/delete-a-product",
- "api-reference/platform/products/update-a-product"
- ]
- },
- {
- "group": "Promotion Actions",
- "pages": [
- "api-reference/platform/promotion-actions/return-a-list-of-promotion-actions",
- "api-reference/platform/promotion-actions/create-a-promotion-action",
- "api-reference/platform/promotion-actions/return-a-promotion-action",
- "api-reference/platform/promotion-actions/delete-a-promotion-action",
- "api-reference/platform/promotion-actions/update-a-promotion-action"
- ]
- },
- {
- "group": "Promotion Categories",
- "pages": [
- "api-reference/platform/promotion-categories/return-a-list-of-promotion-categories",
- "api-reference/platform/promotion-categories/create-a-promotion-category",
- "api-reference/platform/promotion-categories/return-a-promotion-category",
- "api-reference/platform/promotion-categories/delete-a-promotion-category",
- "api-reference/platform/promotion-categories/update-a-promotion-category"
- ]
- },
- {
- "group": "Promotion Rules",
- "pages": [
- "api-reference/platform/promotion-rules/return-a-list-of-promotion-rules",
- "api-reference/platform/promotion-rules/create-a-promotion-rule",
- "api-reference/platform/promotion-rules/return-a-promotion-rule",
- "api-reference/platform/promotion-rules/delete-a-promotion-rule",
- "api-reference/platform/promotion-rules/update-a-promotion-rule"
- ]
- },
- {
- "group": "Promotions",
- "pages": [
- "api-reference/platform/promotions/return-a-list-of-promotions",
- "api-reference/platform/promotions/create-a-promotion",
- "api-reference/platform/promotions/return-a-promotion",
- "api-reference/platform/promotions/delete-a-promotion",
- "api-reference/platform/promotions/update-a-promotion"
- ]
- },
- {
- "group": "Roles",
- "pages": [
- "api-reference/platform/roles/return-a-list-of-roles",
- "api-reference/platform/roles/create-a-role",
- "api-reference/platform/roles/return-a-role",
- "api-reference/platform/roles/delete-a-role",
- "api-reference/platform/roles/update-a-role"
- ]
- },
- {
- "group": "Shipments",
- "pages": [
- "api-reference/platform/shipments/return-a-list-of-shipments",
- "api-reference/platform/shipments/create-a-shipment",
- "api-reference/platform/shipments/return-a-shipment",
- "api-reference/platform/shipments/delete-a-shipment",
- "api-reference/platform/shipments/update-a-shipment",
- "api-reference/platform/shipments/adds-item-variant-to-an-existing-shipment",
- "api-reference/platform/shipments/removes-item-variant-from-shipment",
- "api-reference/platform/shipments/mark-shipment-as-ready-to-be-shipped",
- "api-reference/platform/shipments/mark-shipment-as-shipped",
- "api-reference/platform/shipments/cancels-the-shipment",
- "api-reference/platform/shipments/resumes-the-shipment",
- "api-reference/platform/shipments/moves-shipment-back-to-pending-state"
- ]
- },
- {
- "group": "Shipping Categories",
- "pages": [
- "api-reference/platform/shipping-categories/return-a-list-of-shipping-categories",
- "api-reference/platform/shipping-categories/create-a-shipping-category",
- "api-reference/platform/shipping-categories/return-a-shipping-category",
- "api-reference/platform/shipping-categories/delete-a-shipping-category",
- "api-reference/platform/shipping-categories/update-a-shipping-category"
- ]
- },
- {
- "group": "Shipping Methods",
- "pages": [
- "api-reference/platform/shipping-methods/return-a-list-of-shipping-methods",
- "api-reference/platform/shipping-methods/create-a-shipping-method",
- "api-reference/platform/shipping-methods/return-a-shipping-method",
- "api-reference/platform/shipping-methods/delete-a-shipping-method",
- "api-reference/platform/shipping-methods/update-a-shipping-method"
- ]
- },
- {
- "group": "States",
- "pages": [
- "api-reference/platform/states/returns-a-list-of-states",
- "api-reference/platform/states/returns-a-state"
- ]
- },
- {
- "group": "Stock Items",
- "pages": [
- "api-reference/platform/stock-items/return-a-list-of-stock-items",
- "api-reference/platform/stock-items/create-a-stock-item",
- "api-reference/platform/stock-items/return-a-stock-item",
- "api-reference/platform/stock-items/delete-a-stock-item",
- "api-reference/platform/stock-items/update-a-stock-item"
- ]
- },
- {
- "group": "Stock Locations",
- "pages": [
- "api-reference/platform/stock-locations/return-a-list-of-stock-locations",
- "api-reference/platform/stock-locations/create-a-stock-location",
- "api-reference/platform/stock-locations/return-a-stock-location",
- "api-reference/platform/stock-locations/delete-a-stock-location",
- "api-reference/platform/stock-locations/update-a-stock-location"
- ]
- },
- {
- "group": "Store Credit Categories",
- "pages": [
- "api-reference/platform/store-credit-categories/return-a-list-of-store-credit-categories",
- "api-reference/platform/store-credit-categories/create-a-store-credit-category",
- "api-reference/platform/store-credit-categories/return-a-store-credit-category",
- "api-reference/platform/store-credit-categories/delete-a-store-credit-category",
- "api-reference/platform/store-credit-categories/update-a-store-credit-category"
- ]
- },
- {
- "group": "Store Credit Types",
- "pages": [
- "api-reference/platform/store-credit-types/return-a-list-of-store-credit-types",
- "api-reference/platform/store-credit-types/create-a-store-credit-type",
- "api-reference/platform/store-credit-types/return-a-store-credit-type",
- "api-reference/platform/store-credit-types/delete-a-store-credit-type",
- "api-reference/platform/store-credit-types/update-a-store-credit-type"
- ]
- },
- {
- "group": "Store Credits",
- "pages": [
- "api-reference/platform/store-credits/return-a-list-of-store-credits",
- "api-reference/platform/store-credits/create-a-store-credit",
- "api-reference/platform/store-credits/return-a-store-credit",
- "api-reference/platform/store-credits/delete-a-store-credit",
- "api-reference/platform/store-credits/update-a-store-credit"
- ]
- },
- {
- "group": "Tax Categories",
- "pages": [
- "api-reference/platform/tax-categories/return-a-list-of-tax-categories",
- "api-reference/platform/tax-categories/create-a-tax-category",
- "api-reference/platform/tax-categories/return-a-tax-category",
- "api-reference/platform/tax-categories/delete-a-tax-category",
- "api-reference/platform/tax-categories/update-a-tax-category"
- ]
- },
- {
- "group": "Tax Rates",
- "pages": [
- "api-reference/platform/tax-rates/return-a-list-of-tax-rates",
- "api-reference/platform/tax-rates/create-a-tax-rate",
- "api-reference/platform/tax-rates/return-a-tax-rate",
- "api-reference/platform/tax-rates/delete-a-tax-rate",
- "api-reference/platform/tax-rates/update-a-tax-rate"
- ]
- },
- {
- "group": "Taxonomies",
- "pages": [
- "api-reference/platform/taxonomies/return-a-list-of-taxonomies",
- "api-reference/platform/taxonomies/create-a-taxonomy",
- "api-reference/platform/taxonomies/return-a-taxonomy",
- "api-reference/platform/taxonomies/delete-a-taxonomy",
- "api-reference/platform/taxonomies/update-a-taxonomy"
- ]
- },
- {
- "group": "Taxons",
- "pages": [
- "api-reference/platform/taxons/return-a-list-of-taxons",
- "api-reference/platform/taxons/create-a-taxon",
- "api-reference/platform/taxons/return-a-taxon",
- "api-reference/platform/taxons/delete-a-taxon",
- "api-reference/platform/taxons/update-a-taxon",
- "api-reference/platform/taxons/reposition-a-taxon"
- ]
- },
- {
- "group": "Users",
- "pages": [
- "api-reference/platform/users/return-a-list-of-users",
- "api-reference/platform/users/create-a-user",
- "api-reference/platform/users/return-a-user",
- "api-reference/platform/users/delete-a-user",
- "api-reference/platform/users/update-a-user"
- ]
- },
- {
- "group": "Variants",
- "pages": [
- "api-reference/platform/variants/return-a-list-of-variants",
- "api-reference/platform/variants/return-a-variant",
- "api-reference/platform/variants/delete-a-variant"
- ]
- },
- {
- "group": "Vendors",
- "pages": [
- "api-reference/platform/vendors/return-a-list-of-vendors",
- "api-reference/platform/vendors/create-a-vendor",
- "api-reference/platform/vendors/return-a-vendor",
- "api-reference/platform/vendors/delete-a-vendor",
- "api-reference/platform/vendors/update-a-vendor",
- "api-reference/platform/vendors/invites-vendor-to-the-platform",
- "api-reference/platform/vendors/start-onboarding-process",
- "api-reference/platform/vendors/completes-onboarding-process",
- "api-reference/platform/vendors/approves-vendor",
- "api-reference/platform/vendors/rejects-vendor",
- "api-reference/platform/vendors/suspends-vendor"
- ]
- },
- {
- "group": "Webhook Events",
- "pages": [
- "api-reference/platform/webhook-events/return-a-list-of-webhook-events"
- ]
- },
- {
- "group": "Webhook Subscribers",
- "pages": [
- "api-reference/platform/webhook-subscribers/return-a-list-of-webhook-subscribers",
- "api-reference/platform/webhook-subscribers/create-a-webhook-subscriber",
- "api-reference/platform/webhook-subscribers/return-a-webhook-subscriber",
- "api-reference/platform/webhook-subscribers/delete-a-webhook-subscriber",
- "api-reference/platform/webhook-subscribers/update-a-webhook-subscriber"
- ]
- },
- {
- "group": "Wished Items",
- "pages": [
- "api-reference/platform/wished-items/return-a-list-of-wished-items",
- "api-reference/platform/wished-items/create-a-wished-item",
- "api-reference/platform/wished-items/return-a-wished-item",
- "api-reference/platform/wished-items/delete-a-wished-item",
- "api-reference/platform/wished-items/update-a-wished-item"
- ]
- },
- {
- "group": "Wishlists",
- "pages": [
- "api-reference/platform/wishlists/return-a-list-of-wishlists",
- "api-reference/platform/wishlists/create-a-wishlist",
- "api-reference/platform/wishlists/return-a-wishlist",
- "api-reference/platform/wishlists/delete-a-wishlist",
- "api-reference/platform/wishlists/update-a-wishlist"
- ]
- },
- {
- "group": "Zones",
- "pages": [
- "api-reference/platform/zones/return-a-list-of-zones",
- "api-reference/platform/zones/create-a-zone",
- "api-reference/platform/zones/return-a-zone",
- "api-reference/platform/zones/delete-a-zone",
- "api-reference/platform/zones/update-a-zone"
- ]
- }
- ]
- }
- ]
- },
- {
- "tab": "Integrations",
- "groups": [
- {
- "group": "Integrations",
- "pages": ["integrations/integrations"]
- },
- {
- "group": "Payments",
- "pages": [
- "integrations/payments/stripe",
- "integrations/payments/adyen",
- "integrations/payments/paypal",
- "integrations/payments/razorpay"
- ]
- },
- {
- "group": "Analytics",
- "pages": [
- "integrations/analytics/google-analytics",
- "integrations/analytics/google-tag-manager"
- ]
- },
- {
- "group": "Marketing",
- "pages": ["integrations/marketing/klaviyo"]
- },
- {
- "group": "SSO, MFA & Social Login",
- "pages": [
- "integrations/sso-mfa-social-login/admin-dashboard",
- "integrations/sso-mfa-social-login/storefront"
- ]
- }
- ]
- },
- {
- "tab": "User Docs",
- "groups": [
- {
- "group": "Introduction",
- "pages": [
- "user/what-is-spree-commerce",
- "user/using-spree",
- "user/user-quickstart-guide"
- ]
- },
- {
- "group": "Migration",
- "pages": ["user/migration/migrate-from-shopify"]
- },
- {
- "group": "Products",
- "pages": [
- {
- "group": "Create & Edit Products",
- "pages": [
- "user/products/creating-products",
- "user/products/deleting-products",
- "user/products/editing-products",
- "user/products/editing-multi-variant-products",
- "user/products/cloning-products"
- ]
- },
- {
- "group": "Manage Products",
- "pages": [
- "user/manage-products/search-products",
- "user/manage-products/bulk-product-operations",
- "user/manage-products/price-lists",
- "user/manage-products/export-products",
- "user/manage-products/import-products",
- "user/manage-products/product-import-file-template",
- "user/manage-products/stock-levels",
- "user/manage-products/stock-transfers",
- "user/manage-products/product-taxonomies",
- "user/manage-products/product-options",
- "user/manage-products/product-metafields"
- ]
- }
- ]
- },
- {
- "group": "Orders",
- "pages": [
- "user/orders/order-states",
- "user/orders/processing-orders",
- "user/orders/creating-orders",
- "user/orders/editing-orders",
- "user/orders/order-adjustments",
- "user/orders/exporting-orders",
- "user/orders/cancelling-orders",
- "user/orders/refunding-orders",
- "user/orders/searching-orders"
- ]
- },
- {
- "group": "Returns",
- "pages": [
- "user/settings/returns-configuration",
- "user/returns/returns-processing"
- ]
- },
- {
- "group": "Customers",
- "pages": [
- "user/customers/create-customer",
- "user/customers/customer-profile",
- "user/customers/edit-customer",
- "user/customers/issue-gift-card",
- "user/customers/assign-store-credits",
- "user/customers/searching-customers",
- "user/customers/exporting-customers",
- "user/customers/customer-groups"
- ]
- },
- {
- "group": "Promotions",
- "pages": [
- "user/promotions/create-a-promotion",
- "user/promotions/promotion-rules",
- "user/promotions/promotion-actions",
- "user/promotions/gift-cards"
- ]
- },
- {
- "group": "Vendors",
- "pages": [
- "user/vendors/invite-vendor",
- "user/vendors/vendor-onboarding"
- ]
- },
- {
- "group": "Storefront",
- "pages": [
- {
- "group": "Storefront Themes",
- "pages": [
- "user/storefront/theme-editor",
- "user/storefront/create-new-theme",
- "user/storefront/delete-theme",
- "user/storefront/product-details-page",
- "user/storefront/product-listing-page"
- ]
- },
- {
- "group": "Storefront Pages",
- "pages": [
- "user/storefront/create-page",
- "user/storefront/edit-page",
- "user/storefront/delete-page"
- ]
- },
- "user/storefront/storefront-settings",
- "user/storefront/create-new-store"
- ]
- },
- {
- "group": "Posts",
- "pages": [
- "user/storefront/create-post",
- "user/storefront/edit-post",
- "user/storefront/search-posts",
- "user/storefront/delete-post"
- ]
- },
- {
- "group": "Settings",
- "pages": [
- "user/settings/store-details",
- "user/settings/users",
- "user/settings/emails",
- "user/settings/policies",
- "user/settings/checkout",
- "user/settings/domains",
- "user/settings/locations",
- "user/settings/metafields",
- "user/settings/payments",
- "user/settings/zones",
- "user/settings/shipping-methods",
- "user/settings/tax"
- ]
- },
- {
- "group": "Security",
- "pages": ["user/security"]
- }
- ]
- },
- {
- "tab": "Use Cases",
- "groups": [
- {
- "group": "Overview",
- "pages": ["use-case/overview"]
- },
- {
- "group": "B2B Commerce",
- "pages": [
- "use-case/b2b/b2b-commerce-model",
- "use-case/b2b/b2b-capabilities",
- "use-case/b2b/b2b-admin-capabilities",
- "use-case/b2b/b2b-buyer-capabilities"
- ]
- },
- {
- "group": "Digital Products",
- "pages": [
- "use-case/digital-products/model",
- "use-case/digital-products/capabilities",
- "use-case/digital-products/admin-capabilities"
- ]
- },
- {
- "group": "ChatGPT Integration",
- "pages": [
- "use-case/chatgpt-integration/chatgpt-shopping",
- "use-case/chatgpt-integration/chatgpt-instant-checkout",
- "use-case/chatgpt-integration/chatgpt-buyer-experience"
- ]
- },
- {
- "group": "Multi-Store Platform",
- "pages": [
- "use-case/multi-store/model",
- "use-case/multi-store/capabilities",
- "use-case/multi-store/admin-capabilities"
- ]
- },
- {
- "group": "Multi-Tenant Platform",
- "pages": [
- "use-case/multi-tenant/multi-tenant-model",
- "use-case/multi-tenant/multi-tenant-capabilities",
- "use-case/multi-tenant/super-admin-capabilities",
- "use-case/multi-tenant/tenant-capabilities",
- "use-case/multi-tenant/franchises-and-reseller-networks",
- "use-case/multi-tenant/multi-brand-enterprise-model",
- "use-case/multi-tenant/white-label-saas"
- ]
- },
- {
- "group": "Multi-Vendor Marketplace",
- "pages": [
- "use-case/marketplace/model",
- "use-case/marketplace/capabilities",
- "use-case/marketplace/admin-dashboard",
- "use-case/marketplace/vendor-dashboard",
- "use-case/marketplace/customer-ux"
- ]
- }
- ]
- }
- ]
- },
- {
- "version": "v4",
- "tabs": [
- {
- "tab": "Developer Docs",
- "groups": [
- {
- "group": "Getting started",
- "pages": ["developer/getting-started/quickstart"]
- },
- {
- "group": "Core Concepts",
- "pages": [
- "developer/core-concepts/architecture",
- "developer/core-concepts/stores",
- "developer/core-concepts/markets",
- "developer/core-concepts/orders",
- "developer/core-concepts/users",
- "developer/core-concepts/products",
- "developer/core-concepts/inventory",
- "developer/core-concepts/payments",
- "developer/core-concepts/store-credits-gift-cards",
- "developer/core-concepts/taxes",
- "developer/core-concepts/promotions",
- "developer/core-concepts/shipments",
- "developer/core-concepts/addresses",
- "developer/core-concepts/i18n"
- ]
- },
- {
- "group": "Customization Reference",
- "pages": [
- "developer/customization/quickstart",
- "developer/customization/v4/authentication",
- "developer/customization/v4/images",
- "developer/customization/v4/checkout",
- "developer/customization/v4/admin-panel",
- "developer/customization/v4/storefront",
- "developer/customization/v4/deface",
- "developer/customization/permissions",
- "developer/customization/dependencies",
- "developer/customization/decorators",
- "developer/customization/routes"
- ]
- },
- {
- "group": "Deployment",
- "pages": [
- "developer/deployment/render",
- "developer/deployment/docker",
- "developer/deployment/assets",
- "developer/deployment/cdn",
- "developer/deployment/caching"
- ]
- },
- {
- "group": "Upgrading",
- "pages": [
- "developer/upgrades/quickstart",
- {
- "group": "Upgrade Guides",
- "pages": [
- "developer/upgrades/4.8-to-4.9",
- "developer/upgrades/4.x-to-4.8",
- "developer/upgrades/4.6-to-4.7",
- "developer/upgrades/4.5-to-4.6",
- "developer/upgrades/4.4-to-4.5",
- "developer/upgrades/4.3-to-4.4",
- "developer/upgrades/4.2-to-4.3",
- "developer/upgrades/4.1-to-4.2",
- "developer/upgrades/4.0-to-4.1",
- "developer/upgrades/3.7-to-4.0",
- "developer/upgrades/3.6-to-3.7",
- "developer/upgrades/3.5-to-3.6",
- "developer/upgrades/3.4-to-3.5",
- "developer/upgrades/3.3-to-3.4",
- "developer/upgrades/3.2-to-3.3",
- "developer/upgrades/3.1-to-3.2",
- "developer/upgrades/3.0-to-3.1",
- "developer/upgrades/2.3-to-2.4",
- "developer/upgrades/2.2-to-2.3",
- "developer/upgrades/2.1-to-2.2",
- "developer/upgrades/2.0-to-2.1"
- ]
- }
- ]
- },
- {
- "group": "Contributing",
- "pages": [
- "developer/contributing/quickstart",
- "developer/contributing/developing-spree",
- "developer/contributing/creating-an-extension"
- ]
- },
- {
- "group": "Security",
- "pages": [
- "developer/security/security_policy",
- "developer/security/pci_compliance"
- ]
- },
- {
- "group": "Advanced",
- "pages": ["developer/advanced/adding_spree_to_rails_app"]
- }
- ]
- },
- {
- "tab": "Ecommerce API",
- "groups": [
- {
- "group": "API basics",
- "pages": [
- "api-reference/introduction",
- "api-reference/pagination",
- "api-reference/filtering-and-sorting",
- "api-reference/fetching-multiple-resources"
- ]
- },
- {
- "group": "Storefront API",
- "pages": [
- "api-reference/storefront/authentication",
- {
- "group": "Account",
- "pages": [
- "api-reference/storefront/account/retrieve-an-account",
- "api-reference/storefront/account/create-an-account",
- "api-reference/storefront/account/update-an-account"
- ]
- },
- {
- "group": "Account / Address",
- "pages": [
- "api-reference/storefront/account-address/list-all-addresses",
- "api-reference/storefront/account-address/create-an-address",
- "api-reference/storefront/account-address/remove-an-address",
- "api-reference/storefront/account-address/update-an-address"
- ]
- },
- {
- "group": "Account / Credit Cards",
- "pages": [
- "api-reference/storefront/account-credit-cards/list-all-credit-cards",
- "api-reference/storefront/account-credit-cards/remove-a-credit-card",
- "api-reference/storefront/account-credit-cards/retrieve-the-default-credit-card"
- ]
- },
- {
- "group": "Account / Orders",
- "pages": [
- "api-reference/storefront/account-orders/list-all-orders",
- "api-reference/storefront/account-orders/retrieve-an-order"
- ]
- },
- {
- "group": "Order Status",
- "pages": [
- "api-reference/storefront/order-status/retrieve-an-order-status"
- ]
- },
- {
- "group": "Cart",
- "pages": [
- "api-reference/storefront/cart/retrieve-a-cart",
- "api-reference/storefront/cart/create-a-cart",
- "api-reference/storefront/cart/delete-a-cart"
- ]
- },
- {
- "group": "Cart / Line Items",
- "pages": [
- "api-reference/storefront/cart-line-items/add-an-item-to-cart",
- "api-reference/storefront/cart-line-items/set-line-item-quantity",
- "api-reference/storefront/cart-line-items/remove-a-line-item"
- ]
- },
- {
- "group": "Cart / Other",
- "pages": [
- "api-reference/storefront/cart-other/empty-the-cart",
- "api-reference/storefront/cart-other/list-estimated-shipping-rates",
- "api-reference/storefront/cart-other/associate-a-cart-with-a-user",
- "api-reference/storefront/cart-other/change-cart-currency"
- ]
- },
- {
- "group": "Cart / Coupons",
- "pages": [
- "api-reference/storefront/cart-coupons/apply-a-coupon-code",
- "api-reference/storefront/cart-coupons/remove-a-coupon",
- "api-reference/storefront/cart-coupons/remove-all-coupons"
- ]
- },
- {
- "group": "Checkout",
- "pages": [
- "api-reference/storefront/checkout/update-checkout",
- "api-reference/storefront/checkout/validate-order-payment"
- ]
- },
- {
- "group": "Checkout / State",
- "pages": [
- "api-reference/storefront/checkout-state/next-checkout-step",
- "api-reference/storefront/checkout-state/advance-checkout",
- "api-reference/storefront/checkout-state/complete-checkout"
- ]
- },
- {
- "group": "Checkout / Shipments",
- "pages": [
- "api-reference/storefront/checkout-shipments/selects-shipping-method-for-shipments",
- "api-reference/storefront/checkout-shipments/list-shipping-rates"
- ]
- },
- {
- "group": "Checkout / Payments",
- "pages": [
- "api-reference/storefront/checkout-payments/create-new-payment",
- "api-reference/storefront/checkout-payments/list-payment-methods"
- ]
- },
- {
- "group": "Checkout / Store Credit",
- "pages": [
- "api-reference/storefront/checkout-store-credit/add-store-credit",
- "api-reference/storefront/checkout-store-credit/remove-store-credit"
- ]
- },
- {
- "group": "Products",
- "pages": [
- "api-reference/storefront/products/list-all-products",
- "api-reference/storefront/products/retrieve-a-product"
- ]
- },
- {
- "group": "Vendors",
- "pages": [
- "api-reference/storefront/vendors/list-all-vendors",
- "api-reference/storefront/vendors/retrieve-a-vendor"
- ]
- },
- {
- "group": "Stores",
- "pages": [
- "api-reference/storefront/stores/return-the-current-store"
- ]
- },
- {
- "group": "Taxons",
- "pages": [
- "api-reference/storefront/taxons/list-all-taxons",
- "api-reference/storefront/taxons/retrieve-a-taxon"
- ]
- },
- {
- "group": "Countries",
- "pages": [
- "api-reference/storefront/countries/list-all-countries",
- "api-reference/storefront/countries/retrieve-a-country",
- "api-reference/storefront/countries/get-default-country"
- ]
- },
- {
- "group": "Wishlists",
- "pages": [
- "api-reference/storefront/wishlists/list-all-wishlists",
- "api-reference/storefront/wishlists/create-a-wishlist",
- "api-reference/storefront/wishlists/retrieve-a-wishlist",
- "api-reference/storefront/wishlists/delete-a-wishlist",
- "api-reference/storefront/wishlists/update-a-wishlist",
- "api-reference/storefront/wishlists/retrieve-the-default-wishlist"
- ]
- },
- {
- "group": "Wishlists / Wished Items",
- "pages": [
- "api-reference/storefront/wishlists-wished-items/add-item-to-wishlist",
- "api-reference/storefront/wishlists-wished-items/add-items-to-wishlist",
- "api-reference/storefront/wishlists-wished-items/set-wished-item-quantity",
- "api-reference/storefront/wishlists-wished-items/delete-item-from-wishlist",
- "api-reference/storefront/wishlists-wished-items/delete-items-from-wishlist"
- ]
- },
- {
- "group": "Digital Downloads",
- "pages": [
- "api-reference/storefront/digital-downloads/download-a-digital-asset"
- ]
- }
- ]
- },
- {
- "group": "Platform API",
- "pages": [
- "api-reference/platform/authentication",
- {
- "group": "Addresses",
- "pages": [
- "api-reference/platform/addresses/return-a-list-of-addresses",
- "api-reference/platform/addresses/create-an-address",
- "api-reference/platform/addresses/return-an-address",
- "api-reference/platform/addresses/delete-an-address",
- "api-reference/platform/addresses/update-an-address"
- ]
- },
- {
- "group": "Adjustments",
- "pages": [
- "api-reference/platform/adjustments/return-a-list-of-adjustments",
- "api-reference/platform/adjustments/create-an-adjustment",
- "api-reference/platform/adjustments/return-an-adjustment",
- "api-reference/platform/adjustments/delete-an-adjustment",
- "api-reference/platform/adjustments/update-an-adjustment"
- ]
- },
- {
- "group": "Classifications",
- "pages": [
- "api-reference/platform/classifications/return-a-list-of-classifications",
- "api-reference/platform/classifications/create-a-classification",
- "api-reference/platform/classifications/return-a-classification",
- "api-reference/platform/classifications/delete-a-classification",
- "api-reference/platform/classifications/update-a-classification"
- ]
- },
- {
- "group": "Countries",
- "pages": [
- "api-reference/platform/countries/returns-a-list-of-countries",
- "api-reference/platform/countries/returns-a-country"
- ]
- },
- {
- "group": "Data Feeds",
- "pages": [
- "api-reference/platform/data-feeds/return-a-list-of-data-feeds",
- "api-reference/platform/data-feeds/create-a-data-feed",
- "api-reference/platform/data-feeds/return-a-data-feed",
- "api-reference/platform/data-feeds/delete-a-data-feed",
- "api-reference/platform/data-feeds/update-a-data-feed"
- ]
- },
- {
- "group": "Digital Links",
- "pages": [
- "api-reference/platform/digital-links/return-a-list-of-digital-links",
- "api-reference/platform/digital-links/create-a-digital-link",
- "api-reference/platform/digital-links/return-a-digital-link",
- "api-reference/platform/digital-links/delete-a-digital-link",
- "api-reference/platform/digital-links/update-a-digital-link",
- "api-reference/platform/digital-links/reset-a-digital-link"
- ]
- },
- {
- "group": "Digital Assets",
- "pages": [
- "api-reference/platform/digital-assets/return-a-list-of-digital-assets",
- "api-reference/platform/digital-assets/create-a-digital-asset",
- "api-reference/platform/digital-assets/return-a-digital-asset",
- "api-reference/platform/digital-assets/delete-a-digital-asset",
- "api-reference/platform/digital-assets/update-a-digital-asset"
- ]
- },
- {
- "group": "Line Items",
- "pages": [
- "api-reference/platform/line-items/return-a-list-of-line-items",
- "api-reference/platform/line-items/create-a-line-item",
- "api-reference/platform/line-items/return-a-line-item",
- "api-reference/platform/line-items/delete-a-line-item",
- "api-reference/platform/line-items/update-a-line-item"
- ]
- },
- {
- "group": "Option Types",
- "pages": [
- "api-reference/platform/option-types/return-a-list-of-option-types",
- "api-reference/platform/option-types/create-an-option-type",
- "api-reference/platform/option-types/return-an-option-type",
- "api-reference/platform/option-types/delete-an-option-type",
- "api-reference/platform/option-types/update-an-option-type"
- ]
- },
- {
- "group": "Option Values",
- "pages": [
- "api-reference/platform/option-values/return-a-list-of-option-values",
- "api-reference/platform/option-values/create-an-option-value",
- "api-reference/platform/option-values/return-an-option-value",
- "api-reference/platform/option-values/delete-an-option-value",
- "api-reference/platform/option-values/update-an-option-value"
- ]
- },
- {
- "group": "Orders",
- "pages": [
- "api-reference/platform/orders/return-a-list-of-orders",
- "api-reference/platform/orders/creates-an-order",
- "api-reference/platform/orders/return-an-order",
- "api-reference/platform/orders/delete-an-order",
- "api-reference/platform/orders/update-an-order",
- "api-reference/platform/orders/advances-an-order",
- "api-reference/platform/orders/next-an-order",
- "api-reference/platform/orders/completes-an-order",
- "api-reference/platform/orders/empties-an-order",
- "api-reference/platform/orders/approves-an-order",
- "api-reference/platform/orders/cancels-an-order",
- "api-reference/platform/orders/use-store-credit-for-an-order",
- "api-reference/platform/orders/apply-coupon-code-for-an-order"
- ]
- },
- {
- "group": "Payment Methods",
- "pages": [
- "api-reference/platform/payment-methods/return-a-list-of-payment-methods",
- "api-reference/platform/payment-methods/create-a-payment-method",
- "api-reference/platform/payment-methods/return-a-payment-method",
- "api-reference/platform/payment-methods/delete-a-payment-method",
- "api-reference/platform/payment-methods/update-a-payment-method"
- ]
- },
- {
- "group": "Payments",
- "pages": [
- "api-reference/platform/payments/return-a-list-of-payments",
- "api-reference/platform/payments/return-a-payment",
- "api-reference/platform/payments/delete-a-payment"
- ]
- },
- {
- "group": "Products",
- "pages": [
- "api-reference/platform/products/return-a-list-of-products",
- "api-reference/platform/products/create-a-product",
- "api-reference/platform/products/return-a-product",
- "api-reference/platform/products/delete-a-product",
- "api-reference/platform/products/update-a-product"
- ]
- },
- {
- "group": "Promotion Actions",
- "pages": [
- "api-reference/platform/promotion-actions/return-a-list-of-promotion-actions",
- "api-reference/platform/promotion-actions/create-a-promotion-action",
- "api-reference/platform/promotion-actions/return-a-promotion-action",
- "api-reference/platform/promotion-actions/delete-a-promotion-action",
- "api-reference/platform/promotion-actions/update-a-promotion-action"
- ]
- },
- {
- "group": "Promotion Categories",
- "pages": [
- "api-reference/platform/promotion-categories/return-a-list-of-promotion-categories",
- "api-reference/platform/promotion-categories/create-a-promotion-category",
- "api-reference/platform/promotion-categories/return-a-promotion-category",
- "api-reference/platform/promotion-categories/delete-a-promotion-category",
- "api-reference/platform/promotion-categories/update-a-promotion-category"
- ]
- },
- {
- "group": "Promotion Rules",
- "pages": [
- "api-reference/platform/promotion-rules/return-a-list-of-promotion-rules",
- "api-reference/platform/promotion-rules/create-a-promotion-rule",
- "api-reference/platform/promotion-rules/return-a-promotion-rule",
- "api-reference/platform/promotion-rules/delete-a-promotion-rule",
- "api-reference/platform/promotion-rules/update-a-promotion-rule"
- ]
- },
- {
- "group": "Promotions",
- "pages": [
- "api-reference/platform/promotions/return-a-list-of-promotions",
- "api-reference/platform/promotions/create-a-promotion",
- "api-reference/platform/promotions/return-a-promotion",
- "api-reference/platform/promotions/delete-a-promotion",
- "api-reference/platform/promotions/update-a-promotion"
- ]
- },
- {
- "group": "Roles",
- "pages": [
- "api-reference/platform/roles/return-a-list-of-roles",
- "api-reference/platform/roles/create-a-role",
- "api-reference/platform/roles/return-a-role",
- "api-reference/platform/roles/delete-a-role",
- "api-reference/platform/roles/update-a-role"
- ]
- },
- {
- "group": "Shipments",
- "pages": [
- "api-reference/platform/shipments/return-a-list-of-shipments",
- "api-reference/platform/shipments/create-a-shipment",
- "api-reference/platform/shipments/return-a-shipment",
- "api-reference/platform/shipments/delete-a-shipment",
- "api-reference/platform/shipments/update-a-shipment",
- "api-reference/platform/shipments/adds-item-variant-to-an-existing-shipment",
- "api-reference/platform/shipments/removes-item-variant-from-shipment",
- "api-reference/platform/shipments/mark-shipment-as-ready-to-be-shipped",
- "api-reference/platform/shipments/mark-shipment-as-shipped",
- "api-reference/platform/shipments/cancels-the-shipment",
- "api-reference/platform/shipments/resumes-the-shipment",
- "api-reference/platform/shipments/moves-shipment-back-to-pending-state"
- ]
- },
- {
- "group": "Shipping Categories",
- "pages": [
- "api-reference/platform/shipping-categories/return-a-list-of-shipping-categories",
- "api-reference/platform/shipping-categories/create-a-shipping-category",
- "api-reference/platform/shipping-categories/return-a-shipping-category",
- "api-reference/platform/shipping-categories/delete-a-shipping-category",
- "api-reference/platform/shipping-categories/update-a-shipping-category"
- ]
- },
- {
- "group": "Shipping Methods",
- "pages": [
- "api-reference/platform/shipping-methods/return-a-list-of-shipping-methods",
- "api-reference/platform/shipping-methods/create-a-shipping-method",
- "api-reference/platform/shipping-methods/return-a-shipping-method",
- "api-reference/platform/shipping-methods/delete-a-shipping-method",
- "api-reference/platform/shipping-methods/update-a-shipping-method"
- ]
- },
- {
- "group": "States",
- "pages": [
- "api-reference/platform/states/returns-a-list-of-states",
- "api-reference/platform/states/returns-a-state"
- ]
- },
- {
- "group": "Stock Items",
- "pages": [
- "api-reference/platform/stock-items/return-a-list-of-stock-items",
- "api-reference/platform/stock-items/create-a-stock-item",
- "api-reference/platform/stock-items/return-a-stock-item",
- "api-reference/platform/stock-items/delete-a-stock-item",
- "api-reference/platform/stock-items/update-a-stock-item"
- ]
- },
- {
- "group": "Stock Locations",
- "pages": [
- "api-reference/platform/stock-locations/return-a-list-of-stock-locations",
- "api-reference/platform/stock-locations/create-a-stock-location",
- "api-reference/platform/stock-locations/return-a-stock-location",
- "api-reference/platform/stock-locations/delete-a-stock-location",
- "api-reference/platform/stock-locations/update-a-stock-location"
- ]
- },
- {
- "group": "Store Credit Categories",
- "pages": [
- "api-reference/platform/store-credit-categories/return-a-list-of-store-credit-categories",
- "api-reference/platform/store-credit-categories/create-a-store-credit-category",
- "api-reference/platform/store-credit-categories/return-a-store-credit-category",
- "api-reference/platform/store-credit-categories/delete-a-store-credit-category",
- "api-reference/platform/store-credit-categories/update-a-store-credit-category"
- ]
- },
- {
- "group": "Store Credit Types",
- "pages": [
- "api-reference/platform/store-credit-types/return-a-list-of-store-credit-types",
- "api-reference/platform/store-credit-types/create-a-store-credit-type",
- "api-reference/platform/store-credit-types/return-a-store-credit-type",
- "api-reference/platform/store-credit-types/delete-a-store-credit-type",
- "api-reference/platform/store-credit-types/update-a-store-credit-type"
- ]
- },
- {
- "group": "Store Credits",
- "pages": [
- "api-reference/platform/store-credits/return-a-list-of-store-credits",
- "api-reference/platform/store-credits/create-a-store-credit",
- "api-reference/platform/store-credits/return-a-store-credit",
- "api-reference/platform/store-credits/delete-a-store-credit",
- "api-reference/platform/store-credits/update-a-store-credit"
- ]
- },
- {
- "group": "Tax Categories",
- "pages": [
- "api-reference/platform/tax-categories/return-a-list-of-tax-categories",
- "api-reference/platform/tax-categories/create-a-tax-category",
- "api-reference/platform/tax-categories/return-a-tax-category",
- "api-reference/platform/tax-categories/delete-a-tax-category",
- "api-reference/platform/tax-categories/update-a-tax-category"
- ]
- },
- {
- "group": "Tax Rates",
- "pages": [
- "api-reference/platform/tax-rates/return-a-list-of-tax-rates",
- "api-reference/platform/tax-rates/create-a-tax-rate",
- "api-reference/platform/tax-rates/return-a-tax-rate",
- "api-reference/platform/tax-rates/delete-a-tax-rate",
- "api-reference/platform/tax-rates/update-a-tax-rate"
- ]
- },
- {
- "group": "Taxonomies",
- "pages": [
- "api-reference/platform/taxonomies/return-a-list-of-taxonomies",
- "api-reference/platform/taxonomies/create-a-taxonomy",
- "api-reference/platform/taxonomies/return-a-taxonomy",
- "api-reference/platform/taxonomies/delete-a-taxonomy",
- "api-reference/platform/taxonomies/update-a-taxonomy"
- ]
- },
- {
- "group": "Taxons",
- "pages": [
- "api-reference/platform/taxons/return-a-list-of-taxons",
- "api-reference/platform/taxons/create-a-taxon",
- "api-reference/platform/taxons/return-a-taxon",
- "api-reference/platform/taxons/delete-a-taxon",
- "api-reference/platform/taxons/update-a-taxon",
- "api-reference/platform/taxons/reposition-a-taxon"
- ]
- },
- {
- "group": "Users",
- "pages": [
- "api-reference/platform/users/return-a-list-of-users",
- "api-reference/platform/users/create-a-user",
- "api-reference/platform/users/return-a-user",
- "api-reference/platform/users/delete-a-user",
- "api-reference/platform/users/update-a-user"
- ]
- },
- {
- "group": "Variants",
- "pages": [
- "api-reference/platform/variants/return-a-list-of-variants",
- "api-reference/platform/variants/return-a-variant",
- "api-reference/platform/variants/delete-a-variant"
- ]
- },
- {
- "group": "Vendors",
- "pages": [
- "api-reference/platform/vendors/return-a-list-of-vendors",
- "api-reference/platform/vendors/create-a-vendor",
- "api-reference/platform/vendors/return-a-vendor",
- "api-reference/platform/vendors/delete-a-vendor",
- "api-reference/platform/vendors/update-a-vendor",
- "api-reference/platform/vendors/invites-vendor-to-the-platform",
- "api-reference/platform/vendors/start-onboarding-process",
- "api-reference/platform/vendors/completes-onboarding-process",
- "api-reference/platform/vendors/approves-vendor",
- "api-reference/platform/vendors/rejects-vendor",
- "api-reference/platform/vendors/suspends-vendor"
- ]
- },
- {
- "group": "Webhook Events",
- "pages": [
- "api-reference/platform/webhook-events/return-a-list-of-webhook-events"
- ]
- },
- {
- "group": "Webhook Subscribers",
- "pages": [
- "api-reference/platform/webhook-subscribers/return-a-list-of-webhook-subscribers",
- "api-reference/platform/webhook-subscribers/create-a-webhook-subscriber",
- "api-reference/platform/webhook-subscribers/return-a-webhook-subscriber",
- "api-reference/platform/webhook-subscribers/delete-a-webhook-subscriber",
- "api-reference/platform/webhook-subscribers/update-a-webhook-subscriber"
- ]
- },
- {
- "group": "Wished Items",
- "pages": [
- "api-reference/platform/wished-items/return-a-list-of-wished-items",
- "api-reference/platform/wished-items/create-a-wished-item",
- "api-reference/platform/wished-items/return-a-wished-item",
- "api-reference/platform/wished-items/delete-a-wished-item",
- "api-reference/platform/wished-items/update-a-wished-item"
- ]
- },
- {
- "group": "Wishlists",
- "pages": [
- "api-reference/platform/wishlists/return-a-list-of-wishlists",
- "api-reference/platform/wishlists/create-a-wishlist",
- "api-reference/platform/wishlists/return-a-wishlist",
- "api-reference/platform/wishlists/delete-a-wishlist",
- "api-reference/platform/wishlists/update-a-wishlist"
- ]
- },
- {
- "group": "Zones",
- "pages": [
- "api-reference/platform/zones/return-a-list-of-zones",
- "api-reference/platform/zones/create-a-zone",
- "api-reference/platform/zones/return-a-zone",
- "api-reference/platform/zones/delete-a-zone",
- "api-reference/platform/zones/update-a-zone"
- ]
- }
- ]
+ "pages": ["api-reference/platform/authentication"],
+ "openapi": {
+ "source": "api-reference/platform.yaml",
+ "directory": "api-reference/platform"
+ }
}
]
+ }
+ ]
+ },
+ {
+ "tab": "Integrations",
+ "groups": [
+ {
+ "group": "Integrations",
+ "pages": ["integrations/integrations"]
},
{
- "tab": "User Docs",
- "groups": [
- {
- "group": "Introduction",
- "pages": [
- "user/what-is-spree-commerce",
- "user/using-spree",
- "user/user-quickstart-guide"
- ]
- },
- {
- "group": "Products",
- "pages": [
- {
- "group": "Create & Edit Products",
- "pages": [
- "user/products/creating-products",
- "user/products/deleting-products",
- "user/products/editing-products",
- "user/products/editing-multi-variant-products",
- "user/products/cloning-products"
- ]
- },
- {
- "group": "Manage Products",
- "pages": [
- "user/manage-products/search-products",
- "user/manage-products/bulk-product-operations",
- "user/manage-products/export-products",
- "user/manage-products/stock-levels",
- "user/manage-products/stock-transfers",
- "user/manage-products/product-taxonomies",
- "user/manage-products/product-options",
- "user/manage-products/product-properties"
- ]
- }
- ]
- },
+ "group": "Payments",
+ "pages": [
+ "integrations/payments/stripe",
+ "integrations/payments/adyen",
+ "integrations/payments/paypal",
+ "integrations/payments/razorpay"
+ ]
+ },
+ {
+ "group": "Analytics",
+ "pages": [
+ "integrations/analytics/google-analytics",
+ "integrations/analytics/google-tag-manager"
+ ]
+ },
+ {
+ "group": "Marketing",
+ "pages": ["integrations/marketing/klaviyo"]
+ },
+ {
+ "group": "SSO, MFA & Social Login",
+ "pages": [
+ "integrations/sso-mfa-social-login/admin-dashboard",
+ "integrations/sso-mfa-social-login/storefront"
+ ]
+ }
+ ]
+ },
+ {
+ "tab": "User Guide",
+ "groups": [
+ {
+ "group": "Introduction",
+ "pages": [
+ "user/what-is-spree-commerce",
+ "user/using-spree",
+ "user/user-quickstart-guide"
+ ]
+ },
+ {
+ "group": "Migration",
+ "pages": ["user/migration/migrate-from-shopify"]
+ },
+ {
+ "group": "Products",
+ "pages": [
{
- "group": "Orders",
+ "group": "Create & Edit Products",
"pages": [
- "user/orders/order-states",
- "user/orders/processing-orders",
- "user/orders/creating-orders",
- "user/orders/editing-orders",
- "user/orders/exporting-orders",
- "user/orders/cancelling-orders",
- "user/orders/refunding-orders",
- "user/orders/searching-orders"
+ "user/products/creating-products",
+ "user/products/deleting-products",
+ "user/products/editing-products",
+ "user/products/editing-multi-variant-products",
+ "user/products/cloning-products"
]
},
{
- "group": "Customers",
+ "group": "Manage Products",
"pages": [
- "user/customers/create-customer",
- "user/customers/customer-profile",
- "user/customers/edit-customer",
- "user/customers/issue-gift-card",
- "user/customers/assign-store-credits",
- "user/customers/searching-customers",
- "user/customers/exporting-customers"
+ "user/manage-products/search-products",
+ "user/manage-products/bulk-product-operations",
+ "user/manage-products/price-lists",
+ "user/manage-products/export-products",
+ "user/manage-products/import-products",
+ "user/manage-products/product-import-file-template",
+ "user/manage-products/stock-levels",
+ "user/manage-products/stock-transfers",
+ "user/manage-products/product-taxonomies",
+ "user/manage-products/product-options",
+ "user/manage-products/product-metafields"
]
- },
+ }
+ ]
+ },
+ {
+ "group": "Orders",
+ "pages": [
+ "user/orders/order-states",
+ "user/orders/processing-orders",
+ "user/orders/creating-orders",
+ "user/orders/editing-orders",
+ "user/orders/order-adjustments",
+ "user/orders/exporting-orders",
+ "user/orders/cancelling-orders",
+ "user/orders/refunding-orders",
+ "user/orders/searching-orders"
+ ]
+ },
+ {
+ "group": "Returns",
+ "pages": [
+ "user/settings/returns-configuration",
+ "user/returns/returns-processing"
+ ]
+ },
+ {
+ "group": "Customers",
+ "pages": [
+ "user/customers/create-customer",
+ "user/customers/customer-profile",
+ "user/customers/edit-customer",
+ "user/customers/issue-gift-card",
+ "user/customers/assign-store-credits",
+ "user/customers/searching-customers",
+ "user/customers/exporting-customers",
+ "user/customers/customer-groups"
+ ]
+ },
+ {
+ "group": "Promotions",
+ "pages": [
+ "user/promotions/create-a-promotion",
+ "user/promotions/promotion-rules",
+ "user/promotions/promotion-actions",
+ "user/promotions/gift-cards"
+ ]
+ },
+ {
+ "group": "Vendors",
+ "pages": [
+ "user/vendors/invite-vendor",
+ "user/vendors/vendor-onboarding"
+ ]
+ },
+ {
+ "group": "Storefront",
+ "pages": [
{
- "group": "Vendors",
+ "group": "Storefront Themes",
"pages": [
- "user/vendors/invite-vendor",
- "user/vendors/vendor-onboarding"
+ "user/storefront/theme-editor",
+ "user/storefront/create-new-theme",
+ "user/storefront/delete-theme",
+ "user/storefront/product-details-page",
+ "user/storefront/product-listing-page"
]
},
{
- "group": "Storefront",
+ "group": "Storefront Pages",
"pages": [
- {
- "group": "Storefront Themes",
- "pages": [
- "user/storefront/theme-editor",
- "user/storefront/create-new-theme",
- "user/storefront/delete-theme"
- ]
- },
- {
- "group": "Storefront Pages",
- "pages": [
- "user/storefront/create-page",
- "user/storefront/edit-page",
- "user/storefront/delete-page"
- ]
- },
- {
- "group": "Storefront Posts",
- "pages": [
- "user/storefront/create-post",
- "user/storefront/edit-post",
- "user/storefront/search-posts",
- "user/storefront/delete-post",
- "user/storefront/import-posts"
- ]
- },
- "user/storefront/storefront-settings",
- "user/storefront/create-new-store"
+ "user/storefront/create-page",
+ "user/storefront/edit-page",
+ "user/storefront/delete-page"
]
},
- {
- "group": "Settings",
- "pages": [
- "user/settings/locations",
- "user/settings/shipping-methods"
- ]
- }
+ "user/storefront/storefront-settings",
+ "user/storefront/create-new-store"
+ ]
+ },
+ {
+ "group": "Posts",
+ "pages": [
+ "user/storefront/create-post",
+ "user/storefront/edit-post",
+ "user/storefront/search-posts",
+ "user/storefront/delete-post"
+ ]
+ },
+ {
+ "group": "Settings",
+ "pages": [
+ "user/settings/store-details",
+ "user/settings/users",
+ "user/settings/emails",
+ "user/settings/policies",
+ "user/settings/checkout",
+ "user/settings/domains",
+ "user/settings/locations",
+ "user/settings/metafields",
+ "user/settings/payments",
+ "user/settings/zones",
+ "user/settings/shipping-methods",
+ "user/settings/tax"
+ ]
+ },
+ {
+ "group": "Security",
+ "pages": ["user/security"]
+ }
+ ]
+ },
+ {
+ "tab": "Solutions",
+ "groups": [
+ {
+ "group": "Overview",
+ "pages": ["use-case/overview"]
+ },
+ {
+ "group": "B2B Commerce",
+ "pages": [
+ "use-case/b2b/b2b-commerce-model",
+ "use-case/b2b/b2b-capabilities",
+ "use-case/b2b/b2b-admin-capabilities",
+ "use-case/b2b/b2b-buyer-capabilities"
+ ]
+ },
+ {
+ "group": "Digital Products",
+ "pages": [
+ "use-case/digital-products/model",
+ "use-case/digital-products/capabilities",
+ "use-case/digital-products/admin-capabilities"
+ ]
+ },
+ {
+ "group": "ChatGPT Integration",
+ "pages": [
+ "use-case/chatgpt-integration/chatgpt-shopping",
+ "use-case/chatgpt-integration/chatgpt-instant-checkout",
+ "use-case/chatgpt-integration/chatgpt-buyer-experience"
+ ]
+ },
+ {
+ "group": "Multi-Store Platform",
+ "pages": [
+ "use-case/multi-store/model",
+ "use-case/multi-store/capabilities",
+ "use-case/multi-store/admin-capabilities"
+ ]
+ },
+ {
+ "group": "Multi-Tenant Platform",
+ "pages": [
+ "use-case/multi-tenant/multi-tenant-model",
+ "use-case/multi-tenant/multi-tenant-capabilities",
+ "use-case/multi-tenant/super-admin-capabilities",
+ "use-case/multi-tenant/tenant-capabilities",
+ "use-case/multi-tenant/franchises-and-reseller-networks",
+ "use-case/multi-tenant/multi-brand-enterprise-model",
+ "use-case/multi-tenant/white-label-saas"
+ ]
+ },
+ {
+ "group": "Multi-Vendor Marketplace",
+ "pages": [
+ "use-case/marketplace/model",
+ "use-case/marketplace/capabilities",
+ "use-case/marketplace/admin-dashboard",
+ "use-case/marketplace/vendor-dashboard",
+ "use-case/marketplace/customer-ux"
]
}
]
@@ -2007,14 +754,40 @@
},
"api": {
"examples": {
- "languages": ["curl", "javascript", "ruby", "python", "php", "java", "c#"]
+ "languages": ["javascript", "curl"]
},
- "openapi": ["api-reference/storefront.yaml", "api-reference/platform.yaml"],
+ "openapi": [
+ "api-reference/store.yaml",
+ "api-reference/storefront.yaml",
+ "api-reference/platform.yaml"
+ ],
"mdx": {
- "server": ["http://localhost:3000", "https://demo.spreecommerce.org"]
+ "server": ["http://localhost:3000"]
}
},
"navbar": {
+ "links": [
+ {
+ "label": "15.2k",
+ "href": "https://github.com/spree/spree",
+ "icon": {
+ "library": "lucide",
+ "name": "github"
+ }
+ },
+ {
+ "label": "v5.3.4",
+ "href": "https://github.com/spree/spree/releases/tag/v5.3.4"
+ },
+ {
+ "label": "Join Slack",
+ "href": "https://slack.spreecommerce.org",
+ "icon": {
+ "library": "lucide",
+ "name": "slack"
+ }
+ }
+ ],
"primary": {
"type": "button",
"label": "Support",
diff --git a/docs/index.mdx b/docs/index.mdx
index 2052314c94..5e3ba4d77d 100644
--- a/docs/index.mdx
+++ b/docs/index.mdx
@@ -4,58 +4,393 @@ description: "The open-source commerce engine that adapts to your stack, your bu
mode: "custom"
---
-export const HeroCard = ({ filename, title, description, href }) => {
+{/* ── Icon components (Lucide SVG paths) ── */}
+
+export const Icon = ({ children, className = "" }) => (
+ <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"
+ fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"
+ className={className}>
+ {children}
+ </svg>
+);
+
+{/* ── Quick Start card ── */}
+
+export const QuickStartCard = ({ icon, title, description, href, tag }) => (
+ <a href={href}
+ className="group relative flex flex-col gap-3 rounded-xl border border-gray-200 dark:border-zinc-800 p-5 hover:border-gray-300 dark:hover:border-zinc-700 hover:shadow-sm transition-all no-underline">
+ <div className="flex items-center gap-3">
+ <div className="flex items-center justify-center w-10 h-10 rounded-lg bg-gray-100 dark:bg-zinc-800 text-gray-600 dark:text-zinc-400 group-hover:bg-blue-50 group-hover:text-blue-600 dark:group-hover:bg-blue-950 dark:group-hover:text-blue-400 transition-colors">
+ {icon}
+ </div>
+ <div className="flex items-center gap-2">
+ <h3 className="text-base font-semibold text-gray-900 dark:text-zinc-50 m-0">{title}</h3>
+ {tag && <span className="text-xs font-medium px-2 py-0.5 rounded-full bg-emerald-100 text-emerald-700 dark:bg-emerald-900 dark:text-emerald-300">{tag}</span>}
+ </div>
+ </div>
+ <p className="text-sm text-gray-500 dark:text-zinc-400 m-0 leading-relaxed">{description}</p>
+ </a>
+);
+
+{/* ── Concept grid item ── */}
+
+export const ConceptItem = ({ icon, title, href }) => (
+ <a href={href}
+ className="group flex items-center gap-3 rounded-lg border border-gray-100 dark:border-zinc-800/50 px-3.5 py-3 hover:border-gray-200 dark:hover:border-zinc-700 hover:bg-gray-50 dark:hover:bg-zinc-800/50 transition-all no-underline">
+ <div className="flex items-center justify-center w-8 h-8 rounded-md bg-gray-100 dark:bg-zinc-800 text-gray-500 dark:text-zinc-400 group-hover:text-blue-600 dark:group-hover:text-blue-400 transition-colors shrink-0">
+ {icon}
+ </div>
+ <span className="text-sm font-medium text-gray-700 dark:text-zinc-300 group-hover:text-gray-900 dark:group-hover:text-zinc-100 transition-colors">{title}</span>
+ </a>
+);
+
+{/* ── Use case card ── */}
+
+export const UseCaseCard = ({ icon, title, description, href }) => (
+ <a href={href}
+ className="group flex flex-col gap-2 rounded-xl border border-gray-200 dark:border-zinc-800 p-5 hover:border-gray-300 dark:hover:border-zinc-700 hover:shadow-sm transition-all no-underline">
+ <div className="flex items-center justify-center w-9 h-9 rounded-lg bg-gray-100 dark:bg-zinc-800 text-gray-500 dark:text-zinc-400 group-hover:text-blue-600 dark:group-hover:text-blue-400 transition-colors">
+ {icon}
+ </div>
+ <h4 className="text-sm font-semibold text-gray-900 dark:text-zinc-50 m-0">{title}</h4>
+ <p className="text-xs text-gray-500 dark:text-zinc-400 m-0 leading-relaxed">{description}</p>
+ </a>
+);
+
+{/* ── Integration logo ── */}
+
+export const IntegrationItem = ({ icon, name, href }) => (
+ <a href={href}
+ className="group flex flex-col items-center gap-2 rounded-lg p-3 hover:bg-gray-50 dark:hover:bg-zinc-800/50 transition-colors no-underline">
+ <div className="flex items-center justify-center w-10 h-10 rounded-lg border border-gray-200 dark:border-zinc-700 bg-white dark:bg-zinc-800 text-gray-500 dark:text-zinc-400 group-hover:border-gray-300 dark:group-hover:border-zinc-600 transition-colors">
+ {icon}
+ </div>
+ <span className="text-xs font-medium text-gray-600 dark:text-zinc-400">{name}</span>
+ </a>
+);
+
+{/* ── Section heading ── */}
+
+export const SectionHeading = ({ title, description }) => (
+ <div className="mb-6">
+ <h2 className="text-xl font-semibold text-gray-900 dark:text-zinc-50 m-0">{title}</h2>
+ {description && <p className="text-sm text-gray-500 dark:text-zinc-400 mt-1 m-0">{description}</p>}
+ </div>
+);
+
+{/* ── Resource link ── */}
+
+export const ResourceLink = ({ icon, title, description, href }) => (
+ <a href={href}
+ className="group flex items-start gap-3 rounded-lg p-3 hover:bg-gray-50 dark:hover:bg-zinc-800/50 transition-colors no-underline">
+ <div className="flex items-center justify-center w-8 h-8 rounded-md text-gray-400 dark:text-zinc-500 group-hover:text-blue-600 dark:group-hover:text-blue-400 transition-colors shrink-0 mt-0.5">
+ {icon}
+ </div>
+ <div>
+ <div className="text-sm font-medium text-gray-700 dark:text-zinc-300 group-hover:text-gray-900 dark:group-hover:text-zinc-100 transition-colors">{title}</div>
+ <div className="text-xs text-gray-400 dark:text-zinc-500 mt-0.5">{description}</div>
+ </div>
+ </a>
+);
+
+{/* ── Small icons (16×16) ── */}
+
+export const SmallIcon = ({ children, className = "" }) => (
+ <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24"
+ fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"
+ className={className}>
+ {children}
+ </svg>
+);
+
+{/* ── Copy-to-clipboard install command ── */}
+
+export const CopyCommand = ({ command }) => {
+ const [copied, setCopied] = useState(false);
+ const handleCopy = () => {
+ navigator.clipboard.writeText(command);
+ setCopied(true);
+ setTimeout(() => setCopied(false), 2000);
+ };
return (
- <a className="group cursor-pointer pb-8" href={href}>
- <img
- src={`https://spreecommerce.org/docs/images/hero/${filename}.png`}
- className="block dark:hidden pointer-events-none group-hover:scale-105 transition-all duration-100"
- />
- <img
- src={`https://spreecommerce.org/docs/images/hero/${filename}.png`}
- className="pointer-events-none group-hover:scale-105 transition-all duration-100 hidden dark:block"
- />
- <h3 className="mt-5 text-gray-900 dark:text-zinc-50 font-medium">
- {title}
- </h3>
- <span className="mt-1.5">{description}</span>
- </a>
+ <button onClick={handleCopy}
+ className="group/copy inline-flex items-center gap-3 rounded-lg bg-gray-950 dark:bg-zinc-800 pl-5 pr-3 py-3 font-mono text-sm text-gray-100 border-0 cursor-pointer hover:bg-gray-900 dark:hover:bg-zinc-700 transition-colors">
+ <span className="text-gray-500 select-none">$</span>
+ <span>{command}</span>
+ <span className="ml-2 flex items-center justify-center w-8 h-8 rounded-md text-gray-400 hover:text-gray-200 transition-colors"
+ title="Copy to clipboard">
+ {copied ? (
+ <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#4ade80" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M20 6 9 17l-5-5" /></svg>
+ ) : (
+ <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><rect width="14" height="14" x="8" y="8" rx="2" ry="2" /><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" /></svg>
+ )}
+ </span>
+ </button>
);
};
-<div className="relative">
- <div className="relative z-10 px-4 py-16 max-w-3xl mx-auto">
- <h1 className="block text-4xl font-medium text-center text-gray-900 dark:text-zinc-50 tracking-tight">
+{/* ════════════════════════════════════════════════════════════════════════
+ PAGE CONTENT
+ ════════════════════════════════════════════════════════════════════════ */}
+
+<div className="relative max-w-5xl mx-auto px-4 py-16">
+
+ {/* ── HERO ── */}
+ <div className="text-center mb-16">
+ <h1 className="text-4xl sm:text-5xl font-bold text-gray-900 dark:text-zinc-50 tracking-tight m-0">
Spree Documentation
</h1>
-
- <div className="max-w-xl mx-auto px-4 mt-4 text-lg text-center text-gray-500 dark:text-zinc-500">
- The open-source commerce engine that adapts to your stack, your business model, and your scale
+ <p className="max-w-2xl mx-auto mt-4 text-lg text-gray-500 dark:text-zinc-400">
+ The open-source commerce engine that adapts to your stack, your business model, and your scale.
+ </p>
+ <div className="mt-6 flex flex-col items-center gap-2">
+ <CopyCommand command="npx create-spree-app@latest my-store" />
+ <a href="/developer/getting-started/quickstart" className="text-xs text-gray-400 dark:text-zinc-500 hover:text-gray-600 dark:hover:text-zinc-300 no-underline transition-colors">
+ More installation options →
+ </a>
</div>
+ </div>
- <div className="px-6 lg:px-0 mt-12 grid sm:grid-cols-2 gap-x-6 gap-y-4">
- <HeroCard filename="dev" title="Developer Docs" description="Setup your Spree Commerce in minutes and start developing" href="/developer/getting-started" />
-
- <HeroCard
- filename="api"
- title="API Reference"
- description="Explore the Spree API reference"
+ {/* ── SECTION 1: QUICK START PATHS ── */}
+ <div className="mb-16">
+ <SectionHeading title="Get Started" description="Choose the path that matches how you work" />
+ <div className="grid sm:grid-cols-2 gap-4">
+ <QuickStartCard
+ href="/developer/storefront/nextjs/quickstart"
+ tag="Popular"
+ icon={<Icon><rect width="18" height="18" x="3" y="3" rx="2" /><path d="m10 8 4 4-4 4" /></Icon>}
+ title="Build a Storefront"
+ description="Start with Next.js and our TypeScript SDK. Build a custom frontend connected to Spree's API."
+ />
+ <QuickStartCard
+ href="/developer/tutorial/introduction"
+ icon={<Icon><path d="M12 3H5a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7" /><path d="M18.375 2.625a1 1 0 0 1 3 3l-9.013 9.014a2 2 0 0 1-.853.505l-2.873.84a.5.5 0 0 1-.62-.62l.84-2.873a2 2 0 0 1 .506-.852z" /></Icon>}
+ title="Extend the Framework"
+ description="Customize models, admin UI, and business logic. Full access to the platform internals."
+ />
+ <QuickStartCard
href="/api-reference"
+ icon={<Icon><path d="M21 12V7H5a2 2 0 0 1 0-4h14v4" /><path d="M3 5v14a2 2 0 0 0 2 2h16v-5" /><path d="M18 12a2 2 0 0 0 0 4h4v-4z" /></Icon>}
+ title="Explore the API"
+ description="REST API with OpenAPI spec, filtering, pagination, and TypeScript types."
/>
-
- <HeroCard
- filename="user"
- title="User Documentation"
- description="Learn how to use Spree Commerce as a store owner or operator"
- href="/user"
+ <QuickStartCard
+ href="/developer/core-concepts/architecture"
+ icon={<Icon><circle cx="12" cy="12" r="10" /><path d="M12 2a14.5 14.5 0 0 0 0 20 14.5 14.5 0 0 0 0-20" /><path d="M2 12h20" /></Icon>}
+ title="Evaluate Spree"
+ description="Architecture overview, use cases, and platform capabilities. Ideal for technical decision makers."
/>
+ </div>
+ </div>
+
+ {/* ── SECTION 2: COMMERCE BUILDING BLOCKS ── */}
+ <div className="mb-16">
+ <SectionHeading title="Commerce Building Blocks" description="Explore core commerce concepts that power your store" />
+
+ <div className="space-y-6">
+
+ {/* Catalog */}
+ <div>
+ <div className="text-xs font-semibold uppercase tracking-wider text-gray-400 dark:text-zinc-500 mb-2 px-1">Catalog</div>
+ <div className="grid grid-cols-2 sm:grid-cols-4 gap-2">
+ <ConceptItem href="/developer/core-concepts/products"
+ icon={<SmallIcon><path d="m7.5 4.27 9 5.15" /><path d="M21 8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16Z" /><path d="m3.3 7 8.7 5 8.7-5" /><path d="M12 22V12" /></SmallIcon>}
+ title="Products" />
+ <ConceptItem href="/developer/core-concepts/pricing"
+ icon={<SmallIcon><line x1="12" x2="12" y1="2" y2="22" /><path d="M17 5H9.5a3.5 3.5 0 0 0 0 7h5a3.5 3.5 0 0 1 0 7H6" /></SmallIcon>}
+ title="Pricing" />
+ <ConceptItem href="/developer/core-concepts/inventory"
+ icon={<SmallIcon><path d="M16 16h6" /><path d="M19 13v6" /><path d="M21 10V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l2-1.14" /><path d="m7.5 4.27 9 5.15" /><path d="M3.3 7 12 12l8.7-5" /><path d="M12 22V12" /></SmallIcon>}
+ title="Inventory" />
+ <ConceptItem href="/developer/core-concepts/images-assets"
+ icon={<SmallIcon><rect width="18" height="18" x="3" y="3" rx="2" ry="2" /><circle cx="9" cy="9" r="2" /><path d="m21 15-3.086-3.086a2 2 0 0 0-2.828 0L6 21" /></SmallIcon>}
+ title="Images & Assets" />
+ </div>
+ </div>
+
+ {/* Cart & Checkout */}
+ <div>
+ <div className="text-xs font-semibold uppercase tracking-wider text-gray-400 dark:text-zinc-500 mb-2 px-1">Cart & Checkout</div>
+ <div className="grid grid-cols-2 sm:grid-cols-4 gap-2">
+ <ConceptItem href="/developer/core-concepts/orders"
+ icon={<SmallIcon><path d="M6 2 3 6v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2V6l-3-4Z" /><path d="M3 6h18" /><path d="M16 10a4 4 0 0 1-8 0" /></SmallIcon>}
+ title="Orders" />
+ <ConceptItem href="/developer/core-concepts/payments"
+ icon={<SmallIcon><rect width="20" height="14" x="2" y="5" rx="2" /><line x1="2" x2="22" y1="10" y2="10" /></SmallIcon>}
+ title="Payments" />
+ <ConceptItem href="/developer/core-concepts/taxes"
+ icon={<SmallIcon><path d="M2 9a3 3 0 0 1 0 6v2a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-2a3 3 0 0 1 0-6V7a2 2 0 0 0-2-2H4a2 2 0 0 0-2 2Z" /><path d="m9.5 14.5 5-5" /></SmallIcon>}
+ title="Taxes" />
+ <ConceptItem href="/developer/core-concepts/promotions"
+ icon={<SmallIcon><path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z" /><path d="M12 9v4" /><path d="M12 17h.01" /></SmallIcon>}
+ title="Promotions" />
+ </div>
+ </div>
+
+ {/* Fulfillment */}
+ <div>
+ <div className="text-xs font-semibold uppercase tracking-wider text-gray-400 dark:text-zinc-500 mb-2 px-1">Fulfillment</div>
+ <div className="grid grid-cols-2 sm:grid-cols-4 gap-2">
+ <ConceptItem href="/developer/core-concepts/shipments"
+ icon={<SmallIcon><path d="M14 18V6a2 2 0 0 0-2-2H4a2 2 0 0 0-2 2v11a1 1 0 0 0 1 1h2" /><path d="M15 18H9" /><path d="M19 18h2a1 1 0 0 0 1-1v-3.65a1 1 0 0 0-.22-.624l-3.48-4.35A1 1 0 0 0 17.52 8H14" /><circle cx="17" cy="18" r="2" /><circle cx="7" cy="18" r="2" /></SmallIcon>}
+ title="Shipments" />
+ <ConceptItem href="/developer/core-concepts/addresses"
+ icon={<SmallIcon><path d="M20 10c0 4.993-5.539 10.193-7.399 11.799a1 1 0 0 1-1.202 0C9.539 20.193 4 14.993 4 10a8 8 0 0 1 16 0" /><circle cx="12" cy="10" r="3" /></SmallIcon>}
+ title="Addresses" />
+ <ConceptItem href="/developer/core-concepts/calculators"
+ icon={<SmallIcon><rect width="16" height="20" x="4" y="2" rx="2" /><line x1="8" x2="16" y1="6" y2="6" /><line x1="16" x2="16" y1="14" y2="18" /><path d="M16 10h.01" /><path d="M12 10h.01" /><path d="M8 10h.01" /><path d="M12 14h.01" /><path d="M8 14h.01" /><path d="M12 18h.01" /><path d="M8 18h.01" /></SmallIcon>}
+ title="Calculators" />
+ <ConceptItem href="/developer/core-concepts/adjustments"
+ icon={<SmallIcon><path d="M12 20h9" /><path d="M16.376 3.622a1 1 0 0 1 3.002 3.002L7.368 18.635a2 2 0 0 1-.855.506l-2.872.838a.5.5 0 0 1-.62-.62l.838-2.872a2 2 0 0 1 .506-.854z" /></SmallIcon>}
+ title="Adjustments" />
+ </div>
+ </div>
+
+ {/* Platform */}
+ <div>
+ <div className="text-xs font-semibold uppercase tracking-wider text-gray-400 dark:text-zinc-500 mb-2 px-1">Platform</div>
+ <div className="grid grid-cols-2 sm:grid-cols-4 gap-2">
+ <ConceptItem href="/developer/core-concepts/stores"
+ icon={<SmallIcon><path d="m2 7 4.41-4.41A2 2 0 0 1 7.83 2h8.34a2 2 0 0 1 1.42.59L22 7" /><path d="M4 12v8a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-8" /><path d="M15 22v-4a2 2 0 0 0-2-2h-2a2 2 0 0 0-2 2v4" /><rect width="20" height="5" x="2" y="7" /></SmallIcon>}
+ title="Stores" />
+ <ConceptItem href="/developer/core-concepts/markets"
+ icon={<SmallIcon><circle cx="12" cy="12" r="10" /><path d="M12 2a14.5 14.5 0 0 0 0 20 14.5 14.5 0 0 0 0-20" /><path d="M2 12h20" /></SmallIcon>}
+ title="Markets" />
+ <ConceptItem href="/developer/core-concepts/customers"
+ icon={<SmallIcon><path d="M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2" /><circle cx="9" cy="7" r="4" /><path d="M22 21v-2a4 4 0 0 0-3-3.87" /><path d="M16 3.13a4 4 0 0 1 0 7.75" /></SmallIcon>}
+ title="Customers" />
+ <ConceptItem href="/developer/core-concepts/search-filtering"
+ icon={<SmallIcon><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></SmallIcon>}
+ title="Search & Filtering" />
+ </div>
+ </div>
+
+ {/* Extensibility */}
+ <div>
+ <div className="text-xs font-semibold uppercase tracking-wider text-gray-400 dark:text-zinc-500 mb-2 px-1">Extensibility</div>
+ <div className="grid grid-cols-2 sm:grid-cols-4 gap-2">
+ <ConceptItem href="/developer/core-concepts/events"
+ icon={<SmallIcon><path d="m13 2-2 2.5h3L12 7" /><path d="M10 14v-3" /><path d="M14 14v-3" /><path d="M11 19c-1.7 0-3-1.3-3-3v-2h8v2c0 1.7-1.3 3-3 3Z" /><path d="M12 22v-3" /></SmallIcon>}
+ title="Events" />
+ <ConceptItem href="/developer/core-concepts/webhooks"
+ icon={<SmallIcon><path d="M18 16.98h-5.99c-1.1 0-1.95.94-2.48 1.9A4 4 0 0 1 2 17c.01-.7.2-1.4.57-2" /><path d="m6 17 3.13-5.78c.53-.97.1-2.18-.5-3.1a4 4 0 1 1 6.89-4.06" /><path d="m12 6 3.13 5.73C15.66 12.7 16.9 13 18 13a4 4 0 0 1 .8 7.92" /></SmallIcon>}
+ title="Webhooks" />
+ <ConceptItem href="/developer/core-concepts/translations"
+ icon={<SmallIcon><path d="m5 8 6 6" /><path d="m4 14 6-6 2-3" /><path d="M2 5h12" /><path d="M7 2h1" /><path d="m22 22-5-10-5 10" /><path d="M14 18h6" /></SmallIcon>}
+ title="Translations" />
+ <ConceptItem href="/developer/core-concepts/metafields"
+ icon={<SmallIcon><path d="M12 3H5a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7" /><path d="M18.375 2.625a1 1 0 0 1 3 3l-9.013 9.014a2 2 0 0 1-.853.505l-2.873.84a.5.5 0 0 1-.62-.62l.84-2.873a2 2 0 0 1 .506-.852z" /></SmallIcon>}
+ title="Metafields" />
+ </div>
+ </div>
+
+ </div>
+ </div>
+
+ {/* ── SECTION 3: USE CASES ── */}
+ <div className="mb-16">
+ <SectionHeading title="Solutions & Use Cases" description="See how teams use Spree for different commerce models" />
+ <div className="grid sm:grid-cols-2 lg:grid-cols-3 gap-4">
+ <UseCaseCard href="/use-case/multi-store/model"
+ icon={<SmallIcon><path d="m2 7 4.41-4.41A2 2 0 0 1 7.83 2h8.34a2 2 0 0 1 1.42.59L22 7" /><path d="M4 12v8a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-8" /><path d="M15 22v-4a2 2 0 0 0-2-2h-2a2 2 0 0 0-2 2v4" /><rect width="20" height="5" x="2" y="7" /></SmallIcon>}
+ title="Multi-Store"
+ description="Run multiple storefronts from one backend with shared catalog, inventory, and orders." />
+ <UseCaseCard href="/use-case/marketplace/model"
+ icon={<SmallIcon><path d="M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2" /><circle cx="9" cy="7" r="4" /><path d="M22 21v-2a4 4 0 0 0-3-3.87" /><path d="M16 3.13a4 4 0 0 1 0 7.75" /></SmallIcon>}
+ title="Marketplace"
+ description="Multi-vendor marketplace with vendor dashboards, split payments, and per-vendor fulfillment." />
+ <UseCaseCard href="/use-case/b2b/b2b-commerce-model"
+ icon={<SmallIcon><path d="M6 22V4a2 2 0 0 1 2-2h8a2 2 0 0 1 2 2v18Z" /><path d="M6 12H4a2 2 0 0 0-2 2v6a2 2 0 0 0 2 2h2" /><path d="M18 9h2a2 2 0 0 1 2 2v9a2 2 0 0 1-2 2h-2" /><path d="M10 6h4" /><path d="M10 10h4" /><path d="M10 14h4" /><path d="M10 18h4" /></SmallIcon>}
+ title="B2B Commerce"
+ description="Wholesale pricing, company accounts, purchase orders, and buyer-specific catalogs." />
+ <UseCaseCard href="/use-case/multi-tenant/multi-tenant-model"
+ icon={<SmallIcon><rect width="7" height="7" x="14" y="3" rx="1" /><path d="M10 21V8a1 1 0 0 0-1-1H4a1 1 0 0 0-1 1v12a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-5a1 1 0 0 0-1-1H3" /></SmallIcon>}
+ title="Multi-Tenant"
+ description="White-label SaaS, franchise networks, and multi-brand enterprise from a single deployment." />
+ <UseCaseCard href="/use-case/digital-products/model"
+ icon={<SmallIcon><path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z" /><path d="M14 2v4a2 2 0 0 0 2 2h4" /><path d="M10 18v-1" /><path d="M14 18v-1" /><path d="M10 12v-1" /><path d="M14 12v-1" /></SmallIcon>}
+ title="Digital Products"
+ description="Downloadable goods, licenses, and digital subscriptions with fulfillment automation." />
+ <UseCaseCard href="/use-case/chatgpt-integration/chatgpt-shopping"
+ icon={<SmallIcon><path d="M12 8V4H8" /><rect width="16" height="12" x="4" y="8" rx="2" /><path d="M2 14h2" /><path d="M20 14h2" /><path d="M15 13v2" /><path d="M9 13v2" /></SmallIcon>}
+ title="ChatGPT Shopping"
+ description="AI-powered shopping experience with instant checkout via ChatGPT integration." />
+ </div>
+ </div>
+
+ {/* ── SECTION 4: SDK & INTEGRATIONS ── */}
+ <div className="mb-16">
+ <div className="grid sm:grid-cols-2 gap-8">
+
+ {/* SDK & Tools */}
+ <div>
+ <SectionHeading title="SDK & Tools" description="TypeScript-first developer experience" />
+ <div className="space-y-2">
+ <ResourceLink href="/developer/sdk/quickstart"
+ icon={<SmallIcon><polyline points="16 18 22 12 16 6" /><polyline points="8 6 2 12 8 18" /></SmallIcon>}
+ title="@spree/sdk"
+ description="TypeScript SDK for Store and Admin APIs" />
+ <ResourceLink href="/developer/create-spree-app/quickstart"
+ icon={<SmallIcon><path d="M5 12h14" /><path d="M12 5v14" /></SmallIcon>}
+ title="create-spree-app"
+ description="Scaffold a new Spree project in seconds" />
+ <ResourceLink href="/developer/cli/quickstart"
+ icon={<SmallIcon><polyline points="4 17 10 11 4 5" /><line x1="12" x2="20" y1="19" y2="19" /></SmallIcon>}
+ title="Spree CLI"
+ description="Command-line tools for development" />
+ <ResourceLink href="/api-reference"
+ icon={<SmallIcon><path d="M21 12V7H5a2 2 0 0 1 0-4h14v4" /><path d="M3 5v14a2 2 0 0 0 2 2h16v-5" /><path d="M18 12a2 2 0 0 0 0 4h4v-4z" /></SmallIcon>}
+ title="API Reference"
+ description="OpenAPI spec with interactive explorer" />
+ </div>
+ </div>
+
+ {/* Integrations */}
+ <div>
+ <SectionHeading title="Integrations" description="Pre-built connectors for popular services" />
+ <div className="grid grid-cols-4 gap-1">
+ <IntegrationItem href="/integrations/payments/stripe" name="Stripe"
+ icon={<SmallIcon><rect width="20" height="14" x="2" y="5" rx="2" /><line x1="2" x2="22" y1="10" y2="10" /></SmallIcon>} />
+ <IntegrationItem href="/integrations/payments/paypal" name="PayPal"
+ icon={<SmallIcon><circle cx="12" cy="12" r="10" /><line x1="12" x2="12" y1="8" y2="16" /><line x1="8" x2="16" y1="12" y2="12" /></SmallIcon>} />
+ <IntegrationItem href="/integrations/payments/adyen" name="Adyen"
+ icon={<SmallIcon><path d="M21 12V7H5a2 2 0 0 1 0-4h14v4" /><path d="M3 5v14a2 2 0 0 0 2 2h16v-5" /><path d="M18 12a2 2 0 0 0 0 4h4v-4z" /></SmallIcon>} />
+ <IntegrationItem href="/integrations/payments/razorpay" name="Razorpay"
+ icon={<SmallIcon><path d="m13 2-2 2.5h3L12 7" /><path d="M12 22V7" /></SmallIcon>} />
+ <IntegrationItem href="/integrations/analytics/google-analytics" name="GA4"
+ icon={<SmallIcon><path d="M3 3v16a2 2 0 0 0 2 2h16" /><path d="m19 9-5 5-4-4-3 3" /></SmallIcon>} />
+ <IntegrationItem href="/integrations/analytics/google-tag-manager" name="GTM"
+ icon={<SmallIcon><path d="M9.568 3H5.25A2.25 2.25 0 0 0 3 5.25v4.318c0 .597.237 1.17.659 1.591l9.581 9.581c.699.699 1.78.872 2.607.33a18.095 18.095 0 0 0 5.223-5.223c.542-.827.369-1.908-.33-2.607L11.16 3.66A2.25 2.25 0 0 0 9.568 3Z" /><path d="M6 6h.01" /></SmallIcon>} />
+ <IntegrationItem href="/integrations/marketing/klaviyo" name="Klaviyo"
+ icon={<SmallIcon><rect width="20" height="16" x="2" y="4" rx="2" /><path d="m22 7-8.97 5.7a1.94 1.94 0 0 1-2.06 0L2 7" /></SmallIcon>} />
+ <IntegrationItem href="/integrations" name="All"
+ icon={<SmallIcon><path d="M5 12h14" /><path d="M12 5v14" /></SmallIcon>} />
+ </div>
+ </div>
- <HeroCard
- filename="integrations"
- title="Integrations"
- description="Integrate Spree with your favorite tools and services"
- href="/integrations"
- />
</div>
</div>
+
+ {/* ── SECTION 5: MORE RESOURCES ── */}
+ <div className="border-t border-gray-200 dark:border-zinc-800 pt-10">
+ <div className="grid grid-cols-2 sm:grid-cols-4 gap-4">
+ <a href="/user" className="group text-center p-4 rounded-lg hover:bg-gray-50 dark:hover:bg-zinc-800/50 transition-colors no-underline">
+ <div className="text-sm font-medium text-gray-700 dark:text-zinc-300 group-hover:text-gray-900 dark:group-hover:text-zinc-100">Admin Guide</div>
+ <div className="text-xs text-gray-400 dark:text-zinc-500 mt-1">For store operators</div>
+ </a>
+ <a href="/developer/deployment/database" className="group text-center p-4 rounded-lg hover:bg-gray-50 dark:hover:bg-zinc-800/50 transition-colors no-underline">
+ <div className="text-sm font-medium text-gray-700 dark:text-zinc-300 group-hover:text-gray-900 dark:group-hover:text-zinc-100">Deployment</div>
+ <div className="text-xs text-gray-400 dark:text-zinc-500 mt-1">Docker, AWS, Render</div>
+ </a>
+ <a href="/developer/upgrades/quickstart" className="group text-center p-4 rounded-lg hover:bg-gray-50 dark:hover:bg-zinc-800/50 transition-colors no-underline">
+ <div className="text-sm font-medium text-gray-700 dark:text-zinc-300 group-hover:text-gray-900 dark:group-hover:text-zinc-100">Upgrade Guides</div>
+ <div className="text-xs text-gray-400 dark:text-zinc-500 mt-1">Version migration paths</div>
+ </a>
+ <a href="/developer/contributing/quickstart" className="group text-center p-4 rounded-lg hover:bg-gray-50 dark:hover:bg-zinc-800/50 transition-colors no-underline">
+ <div className="text-sm font-medium text-gray-700 dark:text-zinc-300 group-hover:text-gray-900 dark:group-hover:text-zinc-100">Contributing</div>
+ <div className="text-xs text-gray-400 dark:text-zinc-500 mt-1">Help build Spree</div>
+ </a>
+ </div>
+ </div>
+
</div>
diff --git a/docs/snippets/store-api/auth-guest-cart.mdx b/docs/snippets/store-api/auth-guest-cart.mdx
new file mode 100644
index 0000000000..27caf05737
--- /dev/null
+++ b/docs/snippets/store-api/auth-guest-cart.mdx
@@ -0,0 +1,13 @@
+```typescript
+// Create a cart (guest)
+const cart = await client.store.cart.create()
+
+// Use orderToken for all cart operations
+const options = { orderToken: cart.token }
+
+// Add items
+await client.store.orders.lineItems.create(cart.id, {
+ variant_id: 'variant_abc123',
+ quantity: 1,
+}, options)
+```
diff --git a/docs/snippets/store-api/auth-jwt-example.mdx b/docs/snippets/store-api/auth-jwt-example.mdx
new file mode 100644
index 0000000000..4030c9ee44
--- /dev/null
+++ b/docs/snippets/store-api/auth-jwt-example.mdx
@@ -0,0 +1,10 @@
+```typescript
+// Login to get a JWT token
+const { token, user } = await client.store.auth.login({
+ email: '[email protected]',
+ password: 'password123',
+})
+
+// Use the token for authenticated requests
+const orders = await client.store.orders.list({}, { token })
+```
diff --git a/docs/snippets/store-api/localization-example.mdx b/docs/snippets/store-api/localization-example.mdx
new file mode 100644
index 0000000000..8068f2f647
--- /dev/null
+++ b/docs/snippets/store-api/localization-example.mdx
@@ -0,0 +1,8 @@
+```typescript
+// Set locale and currency per request
+const products = await client.store.products.list({}, {
+ locale: 'fr',
+ currency: 'EUR',
+ country: 'FR',
+})
+```
diff --git a/docs/snippets/store-api/sdk-client-setup.mdx b/docs/snippets/store-api/sdk-client-setup.mdx
new file mode 100644
index 0000000000..46a8e07c5c
--- /dev/null
+++ b/docs/snippets/store-api/sdk-client-setup.mdx
@@ -0,0 +1,8 @@
+```typescript
+import { createSpreeClient } from '@spree/sdk'
+
+const client = createSpreeClient({
+ baseUrl: 'http://localhost:3000',
+ publishableKey: 'spree_pk_xxx',
+})
+```
diff --git a/docs/style.css b/docs/style.css
new file mode 100644
index 0000000000..684aa28efb
--- /dev/null
+++ b/docs/style.css
@@ -0,0 +1,3 @@
+.nav-logo {
+ height: 32px;
+}
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
index 6b3a42a0d0..6a542b3681 100644
--- a/packages/sdk/README.md
+++ b/packages/sdk/README.md
@@ -364,14 +364,37 @@ const completed = await client.store.orders.paymentSessions.complete(
console.log(completed.status); // 'completed'
```
+### Markets
+
+```typescript
+// List all markets
+const { data: markets } = await client.store.markets.list();
+// [{ id: "mkt_xxx", name: "North America", currency: "USD", default_locale: "en", ... }]
+
+// Get a single market
+const market = await client.store.markets.get('mkt_xxx');
+
+// Resolve which market applies for a country
+const market = await client.store.markets.resolve('DE');
+// => { id: "mkt_xxx", name: "Europe", currency: "EUR", default_locale: "de", ... }
+
+// List countries in a market
+const { data: countries } = await client.store.markets.countries.list('mkt_xxx');
+
+// Get a country in a market (with states for address forms)
+const country = await client.store.markets.countries.get('mkt_xxx', 'DE', {
+ expand: ['states'],
+});
+```
+
### Geography
```typescript
// List countries available for checkout
const { data: countries } = await client.store.countries.list();
-// Get country by ISO code (includes states)
-const usa = await client.store.countries.get('US');
+// Get country by ISO code (with states)
+const usa = await client.store.countries.get('US', { expand: ['states'] });
console.log(usa.states); // Array of states
```
@@ -501,6 +524,7 @@ The SDK uses a resource builder pattern for nested resources:
| `store.customer` | `addresses` | `list`, `get`, `create`, `update`, `delete`, `markAsDefault` |
| `store.customer` | `creditCards` | `list`, `get`, `delete` |
| `store.customer` | `giftCards` | `list`, `get` |
+| `store.markets` | `countries` | `list`, `get` |
| `store.taxons` | `products` | `list` |
| `store.wishlists` | `items` | `create`, `update`, `delete` |
@@ -511,6 +535,7 @@ await client.store.orders.lineItems.create(orderId, params, options);
await client.store.orders.payments.list(orderId, options);
await client.store.orders.shipments.update(orderId, shipmentId, params, options);
await client.store.customer.addresses.list({}, options);
+await client.store.markets.countries.list(marketId);
await client.store.taxons.products.list(taxonId, params, options);
await client.store.wishlists.items.create(wishlistId, params, options);
```
@@ -608,6 +633,7 @@ The SDK exports all Store API types:
- `StoreState` - State/province
- `StoreAddress` - Customer address
- `StoreCustomer` - Customer profile
+- `StoreMarket` - Market configuration (currency, locales, countries)
- `StoreStore` - Store configuration
### Commerce Types