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.

Added 'Markets' user documentation (#13767)

jaburghes620ce68d28ba
diff --git a/docs/images/user/settings/markets/1-markets-overview.png b/docs/images/user/settings/markets/1-markets-overview.png
new file mode 100644
index 0000000000..8e0e91c541
Binary files /dev/null and b/docs/images/user/settings/markets/1-markets-overview.png differ
diff --git a/docs/images/user/settings/markets/2-new-market.png b/docs/images/user/settings/markets/2-new-market.png
new file mode 100644
index 0000000000..37c4899c16
Binary files /dev/null and b/docs/images/user/settings/markets/2-new-market.png differ
diff --git a/docs/images/user/settings/markets/3-edit-market.png b/docs/images/user/settings/markets/3-edit-market.png
new file mode 100644
index 0000000000..5bfba1c20a
Binary files /dev/null and b/docs/images/user/settings/markets/3-edit-market.png differ
diff --git a/docs/images/user/settings/store-details/1-name-and-logo.png b/docs/images/user/settings/store-details/1-name-and-logo.png
new file mode 100644
index 0000000000..2673d705ad
Binary files /dev/null and b/docs/images/user/settings/store-details/1-name-and-logo.png differ
diff --git a/docs/images/user/settings/store-details/1.StoreDetails.png b/docs/images/user/settings/store-details/1.StoreDetails.png
deleted file mode 100644
index af8b2b99cc..0000000000
Binary files a/docs/images/user/settings/store-details/1.StoreDetails.png and /dev/null differ
diff --git a/docs/images/user/settings/store-details/2-standards-and-formats.png b/docs/images/user/settings/store-details/2-standards-and-formats.png
new file mode 100644
index 0000000000..7a60b44e5b
Binary files /dev/null and b/docs/images/user/settings/store-details/2-standards-and-formats.png differ
diff --git a/docs/images/user/settings/store-details/2.NameandLogo.png b/docs/images/user/settings/store-details/2.NameandLogo.png
deleted file mode 100644
index 399cc77a81..0000000000
Binary files a/docs/images/user/settings/store-details/2.NameandLogo.png and /dev/null differ
diff --git a/docs/images/user/settings/store-details/3-phone-and-address.png b/docs/images/user/settings/store-details/3-phone-and-address.png
new file mode 100644
index 0000000000..ea49065182
Binary files /dev/null and b/docs/images/user/settings/store-details/3-phone-and-address.png differ
diff --git a/docs/images/user/settings/store-details/3.CurrenciesandCountries.png b/docs/images/user/settings/store-details/3.CurrenciesandCountries.png
deleted file mode 100644
index ad3bc45f8b..0000000000
Binary files a/docs/images/user/settings/store-details/3.CurrenciesandCountries.png and /dev/null differ
diff --git a/docs/images/user/settings/store-details/4-digital-assets.png b/docs/images/user/settings/store-details/4-digital-assets.png
new file mode 100644
index 0000000000..83ab78b148
Binary files /dev/null and b/docs/images/user/settings/store-details/4-digital-assets.png differ
diff --git a/docs/images/user/settings/store-details/4.Languageandcurrencyselector.png b/docs/images/user/settings/store-details/4.Languageandcurrencyselector.png
deleted file mode 100644
index 455f63cdf4..0000000000
Binary files a/docs/images/user/settings/store-details/4.Languageandcurrencyselector.png and /dev/null differ
diff --git a/docs/images/user/settings/store-details/5.StandardsandFormats.png b/docs/images/user/settings/store-details/5.StandardsandFormats.png
deleted file mode 100644
index bb20dc74e1..0000000000
Binary files a/docs/images/user/settings/store-details/5.StandardsandFormats.png and /dev/null differ
diff --git a/docs/images/user/settings/store-details/6.DigitalAssets.png b/docs/images/user/settings/store-details/6.DigitalAssets.png
deleted file mode 100644
index d6c607f00b..0000000000
Binary files a/docs/images/user/settings/store-details/6.DigitalAssets.png and /dev/null differ
diff --git a/docs/images/user/settings/store-details/7.JWTAuthentication.png b/docs/images/user/settings/store-details/7.JWTAuthentication.png
deleted file mode 100644
index ed3e2ddcb6..0000000000
Binary files a/docs/images/user/settings/store-details/7.JWTAuthentication.png and /dev/null differ
diff --git a/docs/images/user/settings/store-details/8.VendorCommissionRates.png b/docs/images/user/settings/store-details/8.VendorCommissionRates.png
deleted file mode 100644
index ca3c1672ed..0000000000
Binary files a/docs/images/user/settings/store-details/8.VendorCommissionRates.png and /dev/null differ
diff --git a/docs/images/user/settings/store-details/9.VendorPayouts.png b/docs/images/user/settings/store-details/9.VendorPayouts.png
deleted file mode 100644
index 67cd52468e..0000000000
Binary files a/docs/images/user/settings/store-details/9.VendorPayouts.png and /dev/null differ
diff --git a/docs/images/user/settings/store-details/placeholder b/docs/images/user/settings/store-details/placeholder
new file mode 100644
index 0000000000..8b13789179
--- /dev/null
+++ b/docs/images/user/settings/store-details/placeholder
@@ -0,0 +1 @@
+
diff --git a/docs/user/manage-products/price-lists.mdx b/docs/user/manage-products/price-lists.mdx
index fcf73bfd18..49700cde60 100644
--- a/docs/user/manage-products/price-lists.mdx
+++ b/docs/user/manage-products/price-lists.mdx
@@ -42,6 +42,7 @@ Available Rule Types:
- **User** - Apply pricing only for specific users.
- **Customer Group** - Apply pricing to a specific customer group.
+- **Market** - Apply pricing to customers shopping in a specific market.
- **Volume** - Apply pricing when order quantity falls within a min–max range.
- **Zone** - Apply pricing to customers in a specific tax/shipping zone.
diff --git a/docs/user/settings/markets.mdx b/docs/user/settings/markets.mdx
new file mode 100644
index 0000000000..fea1a3e21f
--- /dev/null
+++ b/docs/user/settings/markets.mdx
@@ -0,0 +1,69 @@
+---
+title: "Markets"
+description: "Learn how to create and manage markets in Spree Commerce."
+---
+
+Markets allow you to define distinct shopping experiences for different regions or customer
+segments — each with its own currency, language, and tax settings. When multiple markets are
+configured, customers can switch between them on the storefront to see prices and content in
+their preferred currency and language.
+
+Markets can also be used as a rule condition in Price Lists, making it easy to apply
+region-specific pricing without duplicating products.
+
+<Note>Markets are not directly linked to Zones, but the two features work well together for multi-regional stores. Use Zones to control where you ship and how tax is applied by region, and Markets to manage the currency and language experience your customers see on the storefront.</Note>
+
+To manage markets, navigate to **Settings → Markets** in the admin dashboard.
+
+![The Markets overview page showing all configured markets](/docs/images/user/settings/markets/1-markets-overview.png)
+
+## Markets Overview
+
+The Markets table displays all configured markets with the following details:
+
+- **Name** — the internal label for the market (e.g., "United States", "Europe")
+- **Currency** — the currency customers in this market will see at checkout
+- **Default Locale** — the primary language for this market
+- **Default** — indicates which market is set as the default for new visitors
+
+## Create a Market
+
+To create a new market, click **New Market** in the top-right corner.
+
+![The market creation form in Spree Commerce](/docs/images/user/settings/markets/2-new-market.png)
+
+Fill in the following fields:
+
+- **Name** — an internal label to identify this market (e.g., "United Kingdom", "DACH Region")
+- **Default Country** — the primary country for this market, used to determine default shipping
+ and tax behaviour
+- **Currency** — the currency displayed to customers in this market at checkout
+- **Default Locale** — the primary language shown to customers in this market
+- **Supported Locales** — additional languages customers can switch to within this market
+- **Tax Inclusive** — check this if prices should be displayed with tax already included
+ (common in VAT-inclusive markets such as the EU)
+- **Default** — check this to make this the default market for visitors who haven't selected one
+
+Once you've filled in the details, click **Create** to save the new market.
+
+## Edit a Market
+
+To edit a market, click on its row in the Markets table to open the edit form.
+
+![Editing a market in Spree Commerce](/docs/images/user/settings/markets/3-edit-market.png)
+
+The edit form contains the same fields as the creation form. Update the relevant fields and
+click **Update** to save your changes.
+
+## Delete a Market
+
+To delete a market, click on its row to open the edit form, then click **Delete** at the
+bottom of the page.
+
+<Warning>Deleting a market cannot be undone. Before deleting, check that no active Price List rules or storefront configurations reference this market.</Warning>
+
+## Related
+
+- [<u>Zones</u>](https://spreecommerce.org/docs/user/settings/zones)
+- [<u>Tax</u>](https://spreecommerce.org/docs/user/settings/tax)
+- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists)
diff --git a/docs/user/settings/store-details.mdx b/docs/user/settings/store-details.mdx
index d52d605e37..ec3af61149 100644
--- a/docs/user/settings/store-details.mdx
+++ b/docs/user/settings/store-details.mdx
@@ -1,98 +1,66 @@
---
title: "Store Details"
-description: "In this Spree user doc, you'll learn how to configure important store settings."
+description: "Learn how to configure your store's core settings in Spree Commerce."
---
-The Store Details section allows you to configure key settings that determine how your store is presented to customers and how it operates behind the scenes. 
+The Store Details section is where you define your store's identity and core operational
+preferences — from its name and logo to timezones, units of measurement, and how digital
+downloads are handled.
-From your store’s name and logo to currency, locale, time zone, and units of measurement, this section is where you define your store’s identity and core operational preferences.
-
-To configure these settings, navigate to the **Settings → Store Details**.
-
-<img src="/images/user/settings/store-details/1.StoreDetails.png" />
+To configure these settings, navigate to **Settings → Store Details** in the admin dashboard.
## Name & Logo
-<img src="/images/user/settings/store-details/2.NameandLogo.png" />
+![Name and Logo settings in Spree Commerce](/docs/images/user/settings/store-details/1-name-and-logo.png)
-- **Name**: This is the public-facing name of your store. It will appear in headers, footers, and other storefront areas.
-- **Logo**: Upload a store logo (recommended size: 240x240 px). This image is used only in the admin dashboard. To add a storefront logo, see [Storefront Themes → Theme Editor](https://spreecommerce.org/docs/user/storefront/theme-editor#page-header).
+- **Name** — the public-facing name of your store, displayed in headers, footers, and other
+ storefront areas.
+- **Logo** — upload a store logo (recommended size: 240x240 px). This image is used only in
+ the admin dashboard.
## Currencies & Countries
-<img src="/images/user/settings/store-details/3.CurrenciesandCountries.png" />
-
-If you're running a multi-region store (or operate in a country with multiple languages or currencies) this section lets you configure how prices and languages are displayed to your customers, and allows you to limit the regions you ship to:
-
-- **Default currency**: Choose the primary currency used for your store’s pricing and transactions.
-- **Supported currencies**: Select additional currencies, if applicable.
-- **Default country**: Set the primary country where your business is based.
-- **Shipping zones**: Manage zones to define where products can be shipped.
-- **Default locale**: Set the primary language for your storefront.
-- **Default locales**: Define additional locales.
-
-<Note>Currencies and languages are selected from predefined lists, whereas Shipping Zones can be configured in the Zones tabs of the Settings menu.</Note>
-
-If you enable multiple locales or currencies, the storefront will automatically display a language and currency selector to your customers.
+<Note>Currency, locale, and regional settings are now managed in **Settings → Markets**. See [<u>Markets</u>](https://spreecommerce.org/docs/user/settings/markets) for full details.</Note>
-<img src="/images/user/settings/store-details/4.Languageandcurrencyselector.png" />
+## Standards & Formats
-## Standards and Formats
+![Standards and Formats settings in Spree Commerce](/docs/images/user/settings/store-details/2-standards-and-formats.png)
-<img src="/images/user/settings/store-details/5.StandardsandFormats.png" />
+Here you can set the timezone, unit system, and weight units to match your region and business
+preferences:
-Here you can set the timezone, unit system, and weight units to match your region and business preferences:
-
-- **Timezone**: Set your store’s timezone for accurate timestamps and order data.
-- **Unit system**: Choose between imperial and metric. This affects how weights and measures are displayed across your storefront. Options include:
+- **Timezone** — set your store's timezone for accurate timestamps and order data.
+- **Unit system** — choose between imperial and metric. This affects how weights and measures
+ are displayed across your storefront:
- Imperial system
- Metric system
-- **Weight unit**: Choose the default unit for product weights. Option include:
- - Pound (lb) - imperial system
- - Ounce (oz) - imperial system
- - Kilogram (kg) - metric system
- - Gram (g) - metric system
-
-## Digital Assets
+- **Weight unit** — choose the default unit for product weights:
+ - Pound (lb) — imperial system
+ - Ounce (oz) — imperial system
+ - Kilogram (kg) — metric system
+ - Gram (g) — metric system
-<img src="/images/user/settings/store-details/6.DigitalAssets.png" />
-
-Here you can control how digital products (e.g., downloads) are handled after purchase:
+## Phone & Address
-- **Limit digital links download days**: Set how long download links remain active (in days).
-- **Limit digital links download count**: Restrict the number of download attempts per purchase.
+![Phone and Address settings in Spree Commerce](/docs/images/user/settings/store-details/3-phone-and-address.png)
-## Enterprise-only Features
+Enter your store's contact details here:
-<Warning>The following features are only available in Spree Enterprise Edition.</Warning>
+- **Phone** — your store's contact phone number.
+- **Address** — your business address.
-### JWT Authentication
-
-<img src="/images/user/settings/store-details/7.JWTAuthentication.png" />
-
-JWT (JSON Web Token) authentication allows secure, stateless communication between your store and external services or frontends. It’s commonly used when integrating with custom storefronts, mobile apps, or third-party platforms, ensuring users can be authenticated without relying on server-side sessions.
-
-If your store uses JWT for authentication, specify the JWKS endpoint here. Ensure the URL includes a valid protocol (e.g., https://).
-
-### Vendor Commission Rate
-
-<img src="/images/user/settings/store-details/8.VendorCommissionRates.png" />
-
-Set a default commission percentage that your platform takes from vendor sales. This ensures consistent and automated revenue sharing across your marketplace.
-
-Different commission rates can be set per vendor when inviting them to join your marketplace. See the support article on Invite a Vendor for more details.
-
-### Vendor Payouts
+## Digital Assets
-<img src="/images/user/settings/store-details/9.VendorPayouts.png" />
+![Digital Assets settings in Spree Commerce](/docs/images/user/settings/store-details/4-digital-assets.png)
-Here you can configure how and when vendors receive their earnings. Depending on your setup, this may involve automatic payouts via Stripe Connect or manual disbursements. The payout schedule can be:
+Here you can control how digital products (e.g., downloads) are handled after purchase:
-- Daily
-- Weekly
-- Bi-weekly
-- Monthly
+- **Limit digital links download days** — set how long download links remain active after
+ purchase (in days).
+- **Limit digital links download count** — restrict the number of times a download link can
+ be used per purchase.
-## Save Changes
+## Saving Changes
-After making any updates, click Update at the bottom of the page to save your store settings, otherwise any changes you’ve made will not be saved.
+After making any updates, click **Update** at the bottom of the page to save your store
+settings, otherwise any changes you've made will not be saved.