Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Added AI Agents user guides and rewrote Price Lists and Translations (#14953)
jaburghesfe9f22baa0ca
diff --git a/docs/docs.json b/docs/docs.jsonindex 1ce8076f14..38def057a6 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -1367,6 +1367,15 @@"user/reports/reports"]},+ {+ "group": "AI Agents",+ "icon": "bot",+ "pages": [+ "user/ai-agents/ai-agents",+ "user/ai-agents/connect-claude",+ "user/ai-agents/connect-chatgpt"+ ]+ },{"group": "Settings","icon": "settings",@@ -3006,6 +3015,15 @@"user/reports/reports"]},+ {+ "group": "AI Agents",+ "icon": "bot",+ "pages": [+ "user/ai-agents/ai-agents",+ "user/ai-agents/connect-claude",+ "user/ai-agents/connect-chatgpt"+ ]+ },{"group": "Settings","pages": [diff --git a/docs/images/user/ai-agents/ai-agents/1-ai-agents.png b/docs/images/user/ai-agents/ai-agents/1-ai-agents.pngnew file mode 100644index 0000000000..98b4422b01Binary files /dev/null and b/docs/images/user/ai-agents/ai-agents/1-ai-agents.png differdiff --git a/docs/images/user/ai-agents/ai-agents/2-connect-agent.png b/docs/images/user/ai-agents/ai-agents/2-connect-agent.pngnew file mode 100644index 0000000000..932a16f5a5Binary files /dev/null and b/docs/images/user/ai-agents/ai-agents/2-connect-agent.png differdiff --git a/docs/images/user/ai-agents/ai-agents/3-agent-ready.png b/docs/images/user/ai-agents/ai-agents/3-agent-ready.pngnew file mode 100644index 0000000000..8928abb9eeBinary files /dev/null and b/docs/images/user/ai-agents/ai-agents/3-agent-ready.png differdiff --git a/docs/images/user/ai-agents/ai-agents/4-consent.png b/docs/images/user/ai-agents/ai-agents/4-consent.pngnew file mode 100644index 0000000000..ee381e8000Binary files /dev/null and b/docs/images/user/ai-agents/ai-agents/4-consent.png differdiff --git a/docs/images/user/ai-agents/connect-chatgpt/1-connect-agent.png b/docs/images/user/ai-agents/connect-chatgpt/1-connect-agent.pngnew file mode 100644index 0000000000..b8d669850aBinary files /dev/null and b/docs/images/user/ai-agents/connect-chatgpt/1-connect-agent.png differdiff --git a/docs/images/user/ai-agents/connect-chatgpt/2-agent-credentials.png b/docs/images/user/ai-agents/connect-chatgpt/2-agent-credentials.pngnew file mode 100644index 0000000000..f5055d6ef2Binary files /dev/null and b/docs/images/user/ai-agents/connect-chatgpt/2-agent-credentials.png differdiff --git a/docs/images/user/ai-agents/connect-chatgpt/3-chatgpt-new-mcp.png b/docs/images/user/ai-agents/connect-chatgpt/3-chatgpt-new-mcp.pngnew file mode 100644index 0000000000..525d8e2d28Binary files /dev/null and b/docs/images/user/ai-agents/connect-chatgpt/3-chatgpt-new-mcp.png differdiff --git a/docs/images/user/ai-agents/connect-chatgpt/4-chatgpt-oauth.png b/docs/images/user/ai-agents/connect-chatgpt/4-chatgpt-oauth.pngnew file mode 100644index 0000000000..38cb57eab4Binary files /dev/null and b/docs/images/user/ai-agents/connect-chatgpt/4-chatgpt-oauth.png differdiff --git a/docs/images/user/ai-agents/connect-chatgpt/5-oauth-client-edit.png b/docs/images/user/ai-agents/connect-chatgpt/5-oauth-client-edit.pngnew file mode 100644index 0000000000..19f845b577Binary files /dev/null and b/docs/images/user/ai-agents/connect-chatgpt/5-oauth-client-edit.png differdiff --git a/docs/images/user/ai-agents/connect-chatgpt/6-approve.png b/docs/images/user/ai-agents/connect-chatgpt/6-approve.pngnew file mode 100644index 0000000000..a9edfe3950Binary files /dev/null and b/docs/images/user/ai-agents/connect-chatgpt/6-approve.png differdiff --git a/docs/images/user/ai-agents/connect-chatgpt/7-chatgpt-in-chat.png b/docs/images/user/ai-agents/connect-chatgpt/7-chatgpt-in-chat.pngnew file mode 100644index 0000000000..bb5441e970Binary files /dev/null and b/docs/images/user/ai-agents/connect-chatgpt/7-chatgpt-in-chat.png differdiff --git a/docs/images/user/ai-agents/connect-claude/1-connect-agent.png b/docs/images/user/ai-agents/connect-claude/1-connect-agent.pngnew file mode 100644index 0000000000..c63fd9e430Binary files /dev/null and b/docs/images/user/ai-agents/connect-claude/1-connect-agent.png differdiff --git a/docs/images/user/ai-agents/connect-claude/2-agent-credentials.png b/docs/images/user/ai-agents/connect-claude/2-agent-credentials.pngnew file mode 100644index 0000000000..e5325c5a32Binary files /dev/null and b/docs/images/user/ai-agents/connect-claude/2-agent-credentials.png differdiff --git a/docs/images/user/ai-agents/connect-claude/3-claude-add-connector.png b/docs/images/user/ai-agents/connect-claude/3-claude-add-connector.pngnew file mode 100644index 0000000000..2f0c7b0a4dBinary files /dev/null and b/docs/images/user/ai-agents/connect-claude/3-claude-add-connector.png differdiff --git a/docs/images/user/ai-agents/connect-claude/4-claude-client-id.png b/docs/images/user/ai-agents/connect-claude/4-claude-client-id.pngnew file mode 100644index 0000000000..89762d5409Binary files /dev/null and b/docs/images/user/ai-agents/connect-claude/4-claude-client-id.png differdiff --git a/docs/images/user/ai-agents/connect-claude/5-approve.png b/docs/images/user/ai-agents/connect-claude/5-approve.pngnew file mode 100644index 0000000000..8e2549d8cbBinary files /dev/null and b/docs/images/user/ai-agents/connect-claude/5-approve.png differdiff --git a/docs/images/user/ai-agents/connect-claude/6-claude-in-chat.png b/docs/images/user/ai-agents/connect-claude/6-claude-in-chat.pngnew file mode 100644index 0000000000..ee313fee90Binary files /dev/null and b/docs/images/user/ai-agents/connect-claude/6-claude-in-chat.png differdiff --git a/docs/images/user/pricing/price-lists/1-price-lists.png b/docs/images/user/pricing/price-lists/1-price-lists.pngnew file mode 100644index 0000000000..754464319fBinary files /dev/null and b/docs/images/user/pricing/price-lists/1-price-lists.png differdiff --git a/docs/images/user/pricing/price-lists/2-price-list-page.png b/docs/images/user/pricing/price-lists/2-price-list-page.pngnew file mode 100644index 0000000000..0ae7b75f4eBinary files /dev/null and b/docs/images/user/pricing/price-lists/2-price-list-page.png differdiff --git a/docs/images/user/pricing/price-lists/3-add-products.png b/docs/images/user/pricing/price-lists/3-add-products.pngnew file mode 100644index 0000000000..2cd5df1874Binary files /dev/null and b/docs/images/user/pricing/price-lists/3-add-products.png differdiff --git a/docs/images/user/pricing/price-lists/4-product-states.png b/docs/images/user/pricing/price-lists/4-product-states.pngnew file mode 100644index 0000000000..2d105b7dbeBinary files /dev/null and b/docs/images/user/pricing/price-lists/4-product-states.png differdiff --git a/docs/images/user/pricing/price-lists/5-edit-prices.png b/docs/images/user/pricing/price-lists/5-edit-prices.pngnew file mode 100644index 0000000000..2eb376b398Binary files /dev/null and b/docs/images/user/pricing/price-lists/5-edit-prices.png differdiff --git a/docs/images/user/translations/translations/1-translations-screen.png b/docs/images/user/translations/translations/1-translations-screen.pngnew file mode 100644index 0000000000..21549a4ddaBinary files /dev/null and b/docs/images/user/translations/translations/1-translations-screen.png differdiff --git a/docs/images/user/translations/translations/2-manage-translations-card.png b/docs/images/user/translations/translations/2-manage-translations-card.pngnew file mode 100644index 0000000000..b9925ab7dfBinary files /dev/null and b/docs/images/user/translations/translations/2-manage-translations-card.png differdiff --git a/docs/images/user/translations/translations/3-translation-panel.png b/docs/images/user/translations/translations/3-translation-panel.pngnew file mode 100644index 0000000000..fbb4a70f98Binary files /dev/null and b/docs/images/user/translations/translations/3-translation-panel.png differdiff --git a/docs/user/ai-agents/ai-agents.mdx b/docs/user/ai-agents/ai-agents.mdxnew file mode 100644index 0000000000..11991a7901--- /dev/null+++ b/docs/user/ai-agents/ai-agents.mdx@@ -0,0 +1,106 @@+---+title: "AI Agents"+description: "Learn how to connect Claude, ChatGPT and other AI assistants to your store, and control what they are allowed to do, in Spree Commerce."+---++An AI agent is an assistant such as Claude or ChatGPT that you connect to your store so it can work in it on your behalf. Once connected, it can answer questions about your orders, search your catalog, run a report or make a change, by calling your store directly rather than by being told what your store contains.++A connection belongs to one person rather than to the store. It carries that person's own permissions, never more, and only the permissions they approved when they connected it. Two members of staff connecting the same agent get two separate connections, each held to what that person can do.++Agents are worth connecting when your team already asks the same questions of the dashboard every day, or when a job takes more clicks than it deserves. Asking an assistant which products are out of stock, or to cancel an order and tell the customer, is faster than finding the screens for it.++To manage AI agents, navigate to **Settings → AI Agents** in the admin dashboard.++<Note>Connecting an agent needs permission to manage connected applications. A staff member without it sees **You do not have permission to connect an agent to this store** instead of the connection screen.</Note>++## Reviewing Connected Agents++++The screen lists one card per agent that has been connected to the store. Each card shows:++- **Access** - What the agent is allowed to do.+- **Status** - Whether anyone is currently connected through it.+- **People connected** - How many members of staff have connected it, and who they are.++An agent with nobody connected through it is a registration that is no longer in use. Before anyone has connected anything, the screen reads **No agents have been connected yet**.++## How to Connect an Agent++Connecting takes two parts. First the agent is registered in Spree, which produces the two values the agent needs. Then those values are entered in the agent itself, which sends you back to Spree to sign in and approve what it may do.++### Registering the Agent in Spree++++1. Click **Connect an agent**.+2. Choose the assistant you are connecting. **Claude** covers claude.ai, Claude Desktop and Claude Code. **ChatGPT** covers ChatGPT and Codex. **Something else** covers any other assistant that speaks MCP.+3. Click **Continue**.++++The panel then shows two values, each with a button that copies it:++- **Your store's MCP address** - Where the agent sends its requests. It is your store's own address followed by `/api/v3/admin/mcp`.+- **Client ID** - What identifies this agent to your store. Some assistants ask for it and some do not.++<Note>Choosing **Something else** asks for a name and the agent's redirect URI, which is where the agent expects to be sent back to after you sign in. It comes from that agent's own documentation. For Claude and ChatGPT this is filled in for you, so there is nothing to look up.</Note>++<Note>Registering the same assistant twice reconnects the one already registered rather than creating a second. One Claude registration covers claude.ai, Claude Desktop and Claude Code together, and everyone on your team connects through it.</Note>++<Note>Registering an agent creates an entry under **Settings → OAuth clients**, which holds its Client ID and the address the assistant is sent back to. For Claude and ChatGPT that entry is filled in for you, and the only reason to open it is to look the Client ID up again or to remove the agent outright.</Note>++### Connecting It to the Assistant++What happens next depends on the assistant, because each keeps its connector settings in a different place and asks for the two values in a different order.++- [<u>Connect Claude</u>](/user/ai-agents/connect-claude) - claude.ai and Claude Desktop, on a personal plan or a Team or Enterprise plan+- [<u>Connect ChatGPT</u>](/user/ai-agents/connect-chatgpt) - ChatGPT, which also needs a callback URL copied back into your store++For anything else, paste **Your store's MCP address** into wherever that assistant keeps its MCP or connector settings, supplying the **Client ID** if it asks for one. It will send you to your store to sign in and approve.++## What an Agent Is Allowed to Do++++Signing in brings up an approval screen listing the permissions the agent has asked for. Tick the ones you want it to have and click **Allow access**. Approving fewer than it asked for is allowed, and the agent simply works without the rest.++Three limits apply to every connection, whoever makes it.++**An agent never gets more permissions than the person connecting it.** The approval screen offers only the permissions you hold yourself. Anything the agent asked for that your role does not include is listed as withheld and cannot be approved. Someone on a merchandiser role connecting the same agent as an owner is offered a much shorter list.++**Some permissions are never offered to an agent at all.** Managing connected applications, API keys, integrations, webhooks and staff are all withheld from every connection, including an owner's. An agent therefore cannot connect another agent, create a key that outlives its own connection, or change who works at your store.++**A connection is personal.** Each member of staff connects for themselves and approves their own permissions, even when everyone is using the same connector. What one person approved has no effect on anyone else.++<Note>An agent is never shown the jobs it was not approved for, so a connection approved for products alone sees a short list of product jobs rather than everything the store can do.</Note>++## How to Revoke Access++Access can be taken back from one person, or from everybody at once. The two are done on different screens.++### Revoking Access from a User++1. Navigate to **Settings → AI Agents** and find the agent's card.+2. Find the person whose access you are removing.+3. Click **Revoke access** and confirm.++That person loses access immediately and everyone else stays connected. The agent's registration is kept, so they can connect again later and approve a fresh set of permissions.++<Note>Approving more permissions for an agent you have already connected is done by revoking your own access and connecting again, because the approval screen appears only when a connection is made.</Note>++### Removing an Agent Entirely++Deleting the agent's registration disconnects everybody at once and leaves nothing for anyone to reconnect to.++1. Navigate to **Settings → OAuth clients** and find the agent.+2. Open its actions and choose **Delete**.+3. Confirm.++<Warning>Deleting a registration stops the agent working for every member of staff immediately, not only for you, and takes every connection made through it with it. Reconnecting afterwards means registering the agent again, which produces a new Client ID that everyone has to enter.</Warning>++## Further Reading++- [<u>Staff</u>](/user/settings/staff) - The people who can connect an agent+- [<u>Roles</u>](/user/settings/roles) - The permissions a role carries, which bound what an agent can be given+- [<u>API Keys</u>](/user/settings/api-keys) - Standing credentials for integrations, which work differently from an agentdiff --git a/docs/user/ai-agents/connect-chatgpt.mdx b/docs/user/ai-agents/connect-chatgpt.mdxnew file mode 100644index 0000000000..8c6e4687e7--- /dev/null+++ b/docs/user/ai-agents/connect-chatgpt.mdx@@ -0,0 +1,86 @@+---+title: "Connect ChatGPT"+description: "Learn how to connect ChatGPT to your store so it can work in it on your behalf, in Spree Commerce."+---++ChatGPT connects to your store as a custom MCP server. Once connected, it can answer questions about your orders, search your catalog and make changes, bounded by the permissions you approve.++Asking ChatGPT to look up records, produce reports or complete multi-step jobs can save a lot of time spent clicking around in the dashboard. Checking what a customer ordered, listing everything out of stock in one category, or reading last month's sales figures each mean opening a screen, applying a filter and reading the result off it. ChatGPT can answer all three from a single question. It can also carry out the work rather than only report on it, so cancelling an order and refunding the customer takes one request instead of several screens.++The steps below are in the order that avoids going back and forth.++## Step 1: Register ChatGPT in Your Store++++1. Navigate to **Settings → AI Agents** and click **Connect an agent**.+2. Choose **ChatGPT** and click **Continue**.+3. Keep the panel open. It shows **Your store's MCP address** and a **Client ID**, each with a button that copies it.++++See [<u>AI Agents</u>](/user/ai-agents/ai-agents) for what the registration does and who is allowed to make one.++## Step 2: Set ChatGPT Up++++1. In ChatGPT, open **Plugins → Add → Add custom MCP server**.+2. Give it a name and a description your team will recognize, such as your store's name.+3. Paste **Your store's MCP address** as the MCP URL.+4. Set **Authentication** to **OAuth**.+5. Open the advanced OAuth settings and paste the **Client ID**.++++The advanced settings also show a **callback URL**, which is where ChatGPT expects to be sent back to after you sign in. Copy it. The next step registers it in your store.++<Note>Leave the registration URL empty. It is for assistants that register themselves automatically, which Spree does not offer, and pasting the Client ID is what takes its place.</Note>++<Warning>**Do not finish creating it yet**. The consent boxes have to be ticked before the button that creates it becomes available, and creating it before the callback URL is registered produces an error when you try to connect.</Warning>++## Step 3: Register the Callback URL in Your Store++++Registering ChatGPT in step 1 created a client under **Settings → OAuth clients**. That is where its callback URL is kept, so the one ChatGPT generated goes there.++1. In the Spree dashboard, navigate to **Settings → OAuth clients**.+2. Find the **ChatGPT** client, open its actions and choose **Edit**.+3. Enter every address the client may be sent back to, separated by spaces: the ones already registered, followed by the one you copied from ChatGPT. Save.++The **Callback URL** field holds a list rather than a single address. Keep whatever is already registered and add yours to it, rather than replacing it, so that anything already relying on those addresses carries on working.++<Note>Read the addresses already registered from the **Callback URL** column on the OAuth clients list, where each is shown in full, and type the complete list into the field.</Note>++<Warning>Attempting to connect before this step is done results in an error.</Warning>++## Step 4: Connect and Approve++++Finish creating the MCP server in ChatGPT. Before it connects, ChatGPT shows a notice covering what it may share with the store and how that data may be used, and asks you to confirm. Click **Connect**, and ChatGPT sends you to your store to sign in.++An approval screen then lists the permissions ChatGPT has asked for. Tick the ones you want it to have and click **Allow access**. The plugin is in place as soon as the approval goes through, so there is nothing further to install.++ChatGPT asks for every permission your store offers, which is what the standard expects of a client that has not been told to ask for less. The approval screen is where the connection is narrowed, so approving a short list is normal rather than a sign that something is wrong.++A connection never carries more than the person who made it. Anything your own role does not include is shown as withheld and cannot be approved, so two people connecting the same server can end up with very different access. See [<u>AI Agents</u>](/user/ai-agents/ai-agents) for what is never offered to an agent at all.++## How to Use It++++A connected plugin is not used until it is selected for the chat it is needed in. In a new chat, open the **+** menu and select the store's plugin.++Then ask it something straightforward to confirm the connection works, such as listing your last five orders.++A job that changes data declares itself as a change, and ChatGPT may ask you to confirm before running one. Whether it asks depends on the permissions the plugin holds and on what is being done, so a change can also go through without a prompt. Reading is always answered without one.++<Note>ChatGPT is only shown the jobs it was approved for, so a connection approved for products alone offers a short list of product jobs rather than everything the store can do.</Note>++## Further Reading++- [<u>AI Agents</u>](/user/ai-agents/ai-agents) - Reviewing connections, permissions and revoking access+- [<u>Connect Claude</u>](/user/ai-agents/connect-claude) - The same thing for Claude+- [<u>Roles</u>](/user/settings/roles) - The permissions a role carries, which bound what ChatGPT can be givendiff --git a/docs/user/ai-agents/connect-claude.mdx b/docs/user/ai-agents/connect-claude.mdxnew file mode 100644index 0000000000..53e31254f5--- /dev/null+++ b/docs/user/ai-agents/connect-claude.mdx@@ -0,0 +1,90 @@+---+title: "Connect Claude"+description: "Learn how to connect Claude to your store so it can work in it on your behalf, in Spree Commerce."+---++Claude connects to your store as a custom connector. Once connected, it can answer questions about your orders, search your catalog and make changes, bounded by the permissions you approve.++Asking Claude a question is usually quicker than finding a record on a screen. A question that would mean filtering a list, opening several records and adding the figures up comes back as one answer, and a job that takes a few steps in the dashboard can be asked for in a sentence. Finding which products are out of stock before you reorder, pulling last month's sales for one category, or cancelling an order and refunding the customer are each a single request.++One registration in Spree covers claude.ai, Claude Desktop and Claude Code together, so there is nothing to repeat for each of them. How the connector is added on Claude's side depends on the plan: on a personal plan each person adds it to their own account, and on a Team or Enterprise plan an owner adds it once for the whole organization and everyone connects to that.++This page covers claude.ai and Claude Desktop. Claude Code is a command-line tool and is covered in the developer documentation.++## Before You Start++Register Claude in your store first, which produces the two values its connector needs.++++1. Navigate to **Settings → AI Agents** and click **Connect an agent**.+2. Choose **Claude** and click **Continue**.+3. Keep the panel open. It shows **Your store's MCP address** and a **Client ID**, each with a button that copies it.++++See [<u>AI Agents</u>](/user/ai-agents/ai-agents) for what the registration does and who is allowed to make one.++## How to Connect on a Free, Pro or Max Plan++On a personal plan the connector belongs to your own Claude account.++++1. In Claude, open **Connectors**, reached from either **Settings** or **Customize**, and choose to add a custom connector.+2. Enter a name your team will recognize, such as your store's name, paste **Your store's MCP address**, and click **Continue**. Claude checks that it can reach the address before going on.+3. On the next screen, leave **Authentication** set to **Sign in now** and **OAuth client** set to **Use your own OAuth client**. Claude works both out from your store, so they are normally chosen for you already.+4. Paste the **Client ID** and continue.+5. The connector is added at this point but not yet connected to anything. Click **Connect**.+6. Claude opens your browser and asks you to confirm that you started this yourself. Continue, and your store's sign-in appears.++++<Note>**Register automatically** is offered as an OAuth client option but does not work here. Spree registers clients in advance rather than letting them register themselves, which is why there is a Client ID to paste.</Note>++<Note>A free Claude account allows one custom connector, so a store connected there uses the single slot available.</Note>++## How to Connect on a Team or Enterprise Plan++On a Team or Enterprise plan the connector is added once for the organization, and each person then connects to it with their own store login. Adding it is done by an Owner or Primary Owner.++**The owner adds the connector**++1. Go to **claude.ai/admin-settings/connectors** and click **Add → Custom → Web**.+2. Enter a name your team will recognize and paste **Your store's MCP address**. Click **Continue**.+3. Under **Authentication**, choose **Sign in now**.+4. Under **OAuth client**, choose **Use your own OAuth client** and paste the **Client ID**. Leave the client secret empty.+5. Click **Add**.++The connector now appears for everyone in the organization. Nobody has access to the store yet, because each person still has to connect for themselves.++**Each person connects for themselves**++1. In Claude, open **Customize → Connectors**, find the store's connector and click **Connect**.+2. Sign in to your store and approve what the agent may do.++## Approving What Claude May Do++++Signing in brings up an approval screen listing the permissions Claude has asked for. Tick the ones you want it to have and click **Allow access**.++Claude asks for every permission your store offers, which is what the standard expects of a client that has not been told to ask for less. The approval screen is where the connection is narrowed, so approving a short list is normal rather than a sign that something is wrong.++A connection never carries more than the person who made it. Anything your own role does not include is shown as withheld and cannot be approved, so two people connecting the same connector can end up with very different access. See [<u>AI Agents</u>](/user/ai-agents/ai-agents) for what is never offered to an agent at all.++## How to Use It++++In a new chat, click **+ → Connectors** and switch the store on. Then ask it something straightforward to confirm the connection works, such as listing your last five orders.++A job that changes data declares itself as a change, and Claude asks you to confirm before running one unless the connector has been set to allow that job automatically. Reading is always answered without a prompt.++<Note>Claude is only shown the jobs it was approved for, so a connection approved for products alone offers a short list of product jobs rather than everything the store can do.</Note>++## Further Reading++- [<u>AI Agents</u>](/user/ai-agents/ai-agents) - Reviewing connections, permissions and revoking access+- [<u>Connect ChatGPT</u>](/user/ai-agents/connect-chatgpt) - The same thing for ChatGPT+- [<u>Roles</u>](/user/settings/roles) - The permissions a role carries, which bound what Claude can be givendiff --git a/docs/user/pricing/price-lists.mdx b/docs/user/pricing/price-lists.mdxindex b7bfe4caec..05eca6f722 100644--- a/docs/user/pricing/price-lists.mdx+++ b/docs/user/pricing/price-lists.mdx@@ -1,121 +1,140 @@---title: "Price Lists"-description: "Learn how to set up volume pricing, user-specific pricing, and more in Spree Commerce."+description: "Learn how to set alternative prices for a market, a sales channel or larger quantities in Spree Commerce."----import { Since } from '/snippets/since.mdx';+A price list is a second set of prices sitting alongside your normal shop prices. It holds the products it covers, what each one costs in each currency, and the rules deciding who gets it. A shopper matching those rules pays the list's price, and everybody else pays your normal price.-<Since version="5.3" />+Price lists suit prices that follow a situation rather than a customer: what a market pays, what a sales channel charges, or what a case of twenty-four costs compared with a single unit. The rules do the matching, so a shopper does not have to be identified or signed in for a list to reach them, unless the sales channel itself requires an account before anyone can browse.-Price lists are a powerful tool for managing customer-specific pricing strategies - essential for industries like B2B, wholesale, and marketplaces. They let you offer different prices to different customer segments based on conditions like location, quantity, or account status, without needing to duplicate product records or use heavy customizations.+A price list is not a catalog. A catalog is an agreement with named buyers, assigned to a company or a customer group, and it can hide products as well as price them. A price list points at a circumstance instead, reaches anybody in it, and only ever changes prices. Reach for a price list when the price depends on where the order comes from or how much is being bought, and for a catalog when it depends on who is buying. See [<u>Catalogs</u>](/user/catalogs/catalogs).-With Spree’s native support for price lists, you can create and manage custom pricing logic directly in the admin dashboard - no development required.+To manage price lists, navigate to **Products → Price Lists** in the admin dashboard.-## Create a Price List+<Note>A catalog keeps its prices on the catalog itself, so they will never appear under price lists. The two are managed separately even though both end up as prices a buyer pays.</Note>-To get started, navigate to **Products → Price Lists** in the admin dashboard.+## Reviewing Price Lists-+-Here, you’ll see an overview of all active and inactive price lists. Click **New Price List** in the top right corner to open the price list creation form.+The list shows one row per price list, with its description under its name.-+| Column | What it means |+|---|---|+| **Name** | What the list is called, with its description underneath. |+| **Status** | **Draft** while it is being set up, **Active** once it applies, **Scheduled** when it is waiting for its start date, or **Inactive** once it has been switched off. |+| **Products** | How many products the list covers. |+| **Prices** | How many price slots the list holds across every currency, including slots still waiting for an amount. |-Fill in the following fields:+The **Status** filter narrows the list to any of the four states, and **Add filter** narrows it by start date, end date, or when a list was created or last updated.-- **Name** - Internal name for the price list (displayed in the admin).-- **Description (optional)** - Notes or context for other admins.-- **Start Date** and **End Date** - Defines when the price list should be active.- - If not set, the price list will take effect immediately and it will never expire+<Note>A slot is counted for every variant of every product in every currency as soon as the product is added, so a new list with three products can show a large **Prices** figure before a single amount has been typed.</Note>-Once you’ve completed the above, click **Create** to proceed.+## How to Create a Price List-## Configure a Price List+Click **New price list** to open a form with four sections.-+- **Name** - What your team calls the list, such as the region or arrangement it covers. Shoppers never see it, and it is the only required field.+- **Description** - A note for your team on who the list is for.+- **Rules** - Who the list applies to. A list with no rules applies to every shopper.+- **Starts** and **Ends** - The dates it runs between. Leaving both empty means it applies from the moment it is activated, with no end date.-Once created, you’ll be redirected to the price list edit form, where you can define rules for when the price list should apply, add products to be included in the price list, and set the modified prices of those products.+Click **Create**, and the list opens on its own page as a **Draft**, ready for its products.-### Add Rules+## How to Choose Who a List Applies To-+-You can add multiple rules with Match Any or Match All logic.+The **Rules** card holds the conditions a shopper has to meet. With more than one rule, **All rules must match** and **Any rule may match** decide how they combine. Each kind of rule can be used once per list, so one already in use is not offered again.-Available Rule Types:+- **Market** - One or more of your markets. Leaving the box empty applies the rule in every market. A market rule reaches every shopper there, signed in or not. See [<u>Markets</u>](/user/settings/markets).+- **Channel** - Ties the list to a sales channel, so the same product can cost one thing in your online store and another somewhere else. See [<u>Sales Channels</u>](/user/settings/sales-channels).+- **Volume pricing** - A **Minimum quantity**, and a **Maximum quantity** where there is a ceiling. Leaving the maximum empty means no upper limit.-- **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.+The pencil beside a rule edits it and the bin removes it, with the removal taking effect when the price list is saved.-<Note>-Pricing for a particular customer group or company is no longer a price list rule. Create a [Catalog](/user/catalogs/catalogs) and assign it to the group or company instead — it carries its own price list, and can also restrict what they see and set order minimums. Price lists that already use a **Customer Group** or **User** rule keep working; those rules are simply not offered for new lists.-</Note>+<Note>Customer group and individual customer rules are not offered on price lists. To give a customer group or a company its own prices, assign them to a catalog instead.</Note>-To add a rule, simply click **Add Rule**, select a rule type, and configure its criteria.+## How to Add Products to a Price List-### Add Products+-+1. On the list's page, click **Add products**.+2. Search, tick each product you want, and click **Add**. Products already on the list are marked **Added**.+3. Click **Save** at the top of the page.-Next, you’ll need to add some products to the price list. To do so, click **Add Products** in Products subsection to open the product selector side panel.+Until the page is saved, new products show as **New** with **After save** in the price column. Removing one works the same way: the cross at the end of a row strikes it through with an undo arrow beside it, and it is only removed on save.-+Once saved, every variant of each product carries a price with a badge. **Entered** means an amount was typed on this list, and **Shop price** means the list holds no amount for it so the normal price is shown instead. Where quantity breaks exist, a marker beside the price says how many, and hovering it shows the price at each quantity.-Search for products by name or SKU, select one or more products and click **Add Selected** to add them to the price list.+-The selected products will now appear in the product list. Each product lists its variants beneath it with what this list charges for each one, where that amount comes from, and how many quantity breaks it carries; hover the tier count to see the full ladder.+## How to Enter Prices and Quantity Breaks-### Setting Prices+-To define custom prices for the list, click **Edit Prices** in the top right of the product list to open the price edit form.+A price list has no currency of its own. A price is entered for each currency you sell in, and a shopper paying in that currency gets that price.-+1. Click **Edit prices**. A full-screen grid opens with one row per variant.+2. Choose the currency at the top. The table on the list's page shows one currency at a time, so this grid is where the others are checked.+3. Click into a **Price** cell and type the amount, adding a **Compare-at price** where you show a crossed-out price.+4. For a lower price on larger orders, type a quantity in the empty row beneath a product's first price, then the price for that quantity. The first price always starts at **From qty** 1.+5. Click **Save prices**.-Select which currency you'd like to update prices for, and update the values in the **Price** column and optionally in the **Compare At** column.+The grid stays open after saving, so you can switch currency and carry on. The header counts unsaved changes, and **Discard** throws them away.-<Note>You can highlight multiple fields and copy + paste like you would in a spreadsheet.</Note>+### Quantity Breaks-+A quantity break lowers the price of every unit in the cart once the quantity is reached, not just the units above it. Take a product priced at 35.00 with a break from 10 units at 30.00:-Once you’ve finished entering the custom prices, click **Save** to apply your changes.+- A shopper with **9 in the cart** pays 35.00 each, so 315.00 in total.+- A shopper with **10 in the cart** pays 30.00 each, so 300.00 in total.-<Note>A currency you start selling in later, by adding a market or changing an existing one, appears in every price list automatically: the list's products show up in that currency with empty prices, ready to fill in.</Note>+Adding the tenth unit makes the whole order cheaper than nine, which is the effect a case price is meant to have.-### Quantity Breaks+<Warning>+Two kinds of quantity break are refused, and the list will not save until they are fixed:++- **A quantity with no price against it.** Enter a price for the break, or clear the quantity to remove it.+- **A break costing more than the price below it.** A buyer taking more should never pay more per unit.+</Warning>++Prices on a list are separate from the prices on the product itself, so changing a product's own price leaves its price list amounts as they were. See [<u>Adding Products</u>](/user/products/adding-products).++## How to Activate a Price List-A price list can charge less per unit from a given quantity up. In the price edit form, click **Add quantity break** under a variant, enter the quantity the break starts at and the unit price from that quantity, then **Save**. A variant can carry up to ten breaks per currency on one price list, and each break must start at a different quantity.+A new list starts as a **Draft** and reaches nobody. Click **Activate** to start enforcing it.-When a customer's order line reaches a break, the line is priced at that break's unit price. A variant with breaks is priced by its breaks alone: a catalog's percentage adjustment does not apply on top of them.+What happens next depends on the dates set on the list. With no start date, or one that has already passed, the status changes to **Active** and shoppers matching the rules see its prices straight away on the product page and in the cart. With a start date still in the future, the status changes to **Scheduled** instead, and the prices begin applying when that date arrives.-A break must not cost more than the quantity below it buys, and saving is refused if it does — otherwise a customer would pay more for ordering more. The price a break is measured against is the one directly beneath it: the break below, or the variant's regular price on this list. You may leave that regular price empty, which means the list does not change the price until the first break is reached; the break is then measured against the shop price the customer pays up to that point.+**Deactivate** switches it off again and keeps everything it holds, so activating it later brings its prices back.-A price list may be dearer than the shop overall — only the breaks within it have to go down.+Fill in every price you mean to charge before activating. A list carrying no rules, no products and no catalog cannot be activated at all, because it would price nothing.-### Importing and Exporting Prices+<Note>To verify a price list has taken effect, open your storefront as a shopper the list should reach and look at one of its products. That single check tests the rules and the prices together.</Note>-Next to **Edit Prices** you'll find **Export** and **Import**, which move a price list's prices as a CSV file, one row per variant, currency and quantity break.+## How to Update Prices from a Spreadsheet-**Export** downloads every priced row of the list. **Import** merges a file into the list: each row in the file is written or updated, a row with a blank price removes that row from the list (the regular price or a break alike; a variant with no rows left is no longer on the list), and prices the file does not mention are left as they are. Rows the import cannot place are listed in the import report and do not stop the rest: an unknown SKU, a SKU shared by more than one variant, a currency the store does not sell in, a price that is not a plain number like `16.50`, a quantity that is not a whole number, an eleventh break on one variant, or a price that would make a bigger order cost more per unit. Rows are applied one at a time, so to replace a variant's full set of ten breaks with new quantities, import the blank-price rows that clear the old breaks first, then the new ones. For the same reason, when lowering every price on a variant's ladder at once, list the higher quantities first — a file that lowers the regular price before the breaks above it is momentarily a ladder that charges more for a bigger order, and that row is refused.+**Import** and **Export** on the price list's page move its prices as a CSV file, which is how prices are changed in bulk without working through the grid row by row.-| Field | Description |-| -------------------- | ----------------------------------------------------------------------------------------- |-| **sku** | The variant's SKU, matched regardless of letter case. Exactly one variant in the store may carry it |-| currency | The price's currency. Defaults to the store's default currency |-| min_quantity | The quantity the price applies from. Blank or `1` is the variant's regular list price |-| **price** | The unit price from that quantity, as a plain number like `16.50`. Leave blank to remove the row |-| compare_at_price | The optional non-marked-down price shown next to the unit price |+**Export** downloads every price on the list that has an amount. Empty slots are left out.-An exported file has exactly these columns, so it can be edited and imported back as it is. Download a working example from the import form.+**Import** takes the file back:-## Activating the Price List+1. Click **Import**, drop the file in or browse for it, and set the **Column separator** your file uses. **Download CSV template** gives an empty file in the right shape.+2. Click **Continue** and match each column to the field it holds. **SKU** and **Price** are required, and **Currency**, **Minimum quantity** and **Compare at Price** are optional.+3. Click **Start import**.-Once everything is configured, go back to the price list editor, and click **Activate** in the top right corner.+The result says how many rows were imported and how many failed.-+An import changes only the prices its rows name, rather than replacing everything on the list. A price whose row is left out of the file keeps the amount it already had, so deleting a row from an exported file does not remove that price. Clearing the **Price** on a row is what removes it.-The price list will now take effect immediately for any user or order that matches the configured rules.+<Note>Because the minimum quantity is a column, quantity breaks travel as extra rows for the same SKU. The surest way to get a file the import accepts is to export the list first, change the amounts, and import the same file back.</Note>-You can deactivate the price list at any time by clicking the **Deactivate** button.+## Further Reading-<Note>If you set a start date for the price list, the **Activate/Deactivate** button will instead say **Schedule/Unschedule**.</Note>+- [<u>Catalogs</u>](/user/catalogs/catalogs) - Agreed prices and ranges for a company or group+- [<u>Markets</u>](/user/settings/markets) - The regions and currencies a market rule picks from+- [<u>Sales Channels</u>](/user/settings/sales-channels) - The channels a channel rule picks from+- [<u>Adding Products</u>](/user/products/adding-products) - A product's own prices, which a list sits alongside+- [<u>Set Up Volume Pricing</u>](/user/how-to/volume-pricing) - Cheaper prices for bigger ordersdiff --git a/docs/user/translations/translations.mdx b/docs/user/translations/translations.mdxindex 5b44c14900..7ba154cff5 100644--- a/docs/user/translations/translations.mdx+++ b/docs/user/translations/translations.mdx@@ -1,67 +1,123 @@---title: "Translations"-description: "Learn how to manage and track product translations across all your store's locales in Spree Commerce."+description: "Learn how to translate products, categories, collections and options into the languages your store sells in."----The Translations page gives you a single place to see how well your product catalog is translated across every language your store supports. Rather than hunting through individual product pages, you can see at a glance which products have been translated and which still need attention — and use bulk import/export to handle translations in volume.+A translation is a second version of your store's own wording in another language, kept alongside the original rather than replacing it. Four kinds of record can be translated: products, categories, collections and option types. Products, categories and collections each keep their own name, description and web address in every language your store sells in, and an option type keeps its label. A shopper reading the store in German therefore sees a German product name, a German category in the menu and a German web address.-To access Translations, navigate to **Products → Translations** in the admin dashboard.+Translating matters wherever you sell across a language border, because a shopper reads faster, trusts more and buys sooner in their own language. The translated web address matters for a separate reason: search engines index it, and shoppers read it before they click.-+The Translations screen does two jobs. It reports the proportion of each record kind that has already been translated into each language, and it is where the gaps get filled. A record can also be translated from its own page, such as the product form, which is the quicker route when you are already editing it.-<Note>The languages shown on this page are determined by your Markets configuration. If you don't see any locales listed, you'll need to set up additional markets first. See [<u>Settings → Markets</u>](https://spreecommerce.org/docs/user/settings/markets) for more details.</Note>+To manage translations, navigate to **Products → Translations** in the admin dashboard.-## Translation Coverage+<Note>A language only reaches shoppers when a market offers it. Check your [<u>Markets</u>](/user/settings/markets) before translating, so the work goes to the countries that will see it.</Note>-At the top of the page, you'll see a coverage summary table with one row per locale your store supports (excluding your default language). Each row shows:+## Reviewing Translations-- **Locale** - The language code (e.g., `fr`, `de`, `es`)-- **Translated** - How many products have a translation for that locale-- **Total** - The total number of products in your catalog-- **Coverage** - The percentage translated, shown as both a number and a visual progress bar+-This gives you a quick health check on your localization progress without needing to export any data.+The top of the screen is a coverage table with one row per language, each named in its own language with its code beside it.-+| Column | What it means |+|---|---|+| **Locale** | The language, such as Deutsch (de). |+| **Translated** | How many records are translated in full into it. |+| **Total** | How many records of the chosen kind the store has. |+| **Progress** | The same figure as a bar and a percentage. |-## Product Translation Status+Below it, **Records** lists one row per record with a column per language. A dash means nothing has been translated, a count such as 2/5 means two of that record's five fields are filled, and a green checkmark means every field is done.-Below the coverage table, you'll see a paginated list of all your products. Each product has a column for every configured locale, showing either a checkmark (✓) if a translation exists or a dash (—) if it's missing.+The dropdown above the list chooses which kind of record you are working on. Changing it changes the coverage table too, so the figures always answer how much of that one kind is translated rather than how much of the store.-+<Note>Coverage counts only records translated in full. A product with its name translated but its description still in the original language adds nothing to **Translated**, even though the work has started. The **Records** list is where part-finished work shows up.</Note>-To edit a product's translations, click on the product name. This will open the translation drawer where you can add or update translated content for that product.+## What Can Be Translated-+Four kinds of record carry translations, and the fields differ by kind.-## Bulk Export Translations+| Record | Fields |+|---|---|+| **Products** | **Name**, **Description**, **Slug**, **Meta description** and **Meta title** |+| **Categories** | **Name**, **Full name**, **Description** and **Permalink** |+| **Collections** | **Name**, **Description** and **Permalink** |+| **Option types** | **Label**, and the label of each of its values |-If you prefer to manage translations in a spreadsheet, you can export your entire translation dataset as a CSV file.+**Slug** and **Permalink** are the record's web address in that language. **Description** is rich text, with its own toolbar for bold, lists and links.-Click **Export** in the top-right corner of the page.+<Warning>An option type and its values carry separate labels, and coverage counts only the option type's own. Translating the label of an option type called Size can therefore show it as fully translated while Small, Medium and Large are still in the original language. Check the values in the editor before treating an option type as finished.</Warning>-+Translating a record never changes what the dashboard shows. The admin always displays the original wording, whatever languages a record has been translated into, and the translated wording appears only on the storefront, to shoppers in a market that offers that language. Size stays Size for your team while a German shopper reads Größe.-Click **Export** to confirm, and a download link will be sent to the email address associated with your admin account.+<Note>A category's **Full name** is its name with its parents in front of it, so a Kitchen category sitting under Home reads Home → Kitchen. The store maintains it, so it is not a field to compose by hand.</Note>-## Bulk Import Translations+## How to Translate a Record-Once you've updated your translations in the exported file (or built a new file from scratch), you can import them back in bulk.+A record can be translated from its own page or from the Translations screen. Both routes open the same editor, which shows the original wording in one column and the language you are filling in beside it, and both save one language at a time.-Click **Import** in the top-right corner of the page. This opens the import side panel.+### From the Record's Own Page-+-1. Drag and drop your CSV file into the upload area, or click **browse files** to select it from your computer.-2. Select the correct delimiter used in your file (comma, pipe, semicolon, or tab).-3. Click **Create** to proceed to the field mapping step.-4. Review the field mapping and adjust any columns that weren't matched automatically, then click **Continue** to submit.+Products, categories, collections and option types each carry a **Translations** card or a **Manage translations** button on their own page. This is the quicker route if you are already working on a record and have the translations at hand.-Once submitted, you'll be redirected to a processing screen where you can monitor the import progress. Any rows with errors will be flagged with a message so you can fix and re-import them.+1. Open the record and click **Manage translations**.+2. Pick the language at the top of the editor.+3. Fill in the fields beside the original wording.+4. Click **Save translations**.-<Note>The translation import uses the same importer infrastructure as the product importer. If you're familiar with importing products, the process will feel very similar.</Note>+-## Next Steps+The editor stays open after saving, so several languages can be done in one sitting.-- [<u>Settings → Markets</u>](https://spreecommerce.org/docs/user/settings/markets) — Configure which languages and locales your store supports-- [<u>Import & Export</u>](https://spreecommerce.org/docs/user/products/import-and-export) — Learn how to import and export product data+<Note>The **Translations** card appears only once a record exists. A product, category or collection has to be saved before it can be translated.</Note>++### From the Translations Screen++Working from the Translations screen suits translating a batch of records in one sitting, because the coverage figures show how much is left as you go.++1. Choose the kind of record from the dropdown above **Records**.+2. Find the record, using the search box, and click its name.+3. Fill in the fields and click **Save translations**.++Back on the list, the record's cell for that language shows how many of its fields are now filled, or a green checkmark once they all are.++<Note>Translating a product's name fills its slug in for you, so the translated address follows the translated name without being typed. Changing the name later does not rewrite a slug already in use.</Note>++A record's own **Translations** card counts languages it has been started in, while the Translations screen counts fields. The same product can therefore read as one language translated on its page and 2/5 on the translations screen, and both are correct: one language has been started, and two of its five fields are filled.++## How to Import and Export Product Translations++**Import** and **Export** at the top of the Translations screen move translations as a CSV file. Exporting gives you a file to send to a translator, and importing loads their finished work back into the store.++<Warning>Import and export cover products only. Categories, collections and option types are translated in the editor, whichever route you take to it.</Warning>++**Export** offers **Current filter** or **All records**, and prepares the file in the background. The file carries one row per product per language, with these columns:++- **slug** - Which product the row is for. It is the identifier rather than a field to translate, so a translated slug cannot travel in the file.+- **locale** - Which language the row holds, such as `de`.+- **name**, **description**, **meta_title** and **meta_description** - The translated wording.++**Import** takes the file back:++1. Click **Import**, drop the file in or browse for it, and set the **Column separator** your file uses. **Download CSV template** gives an empty file in the right shape.+2. Click **Continue** and match each column to the field it holds. **Slug** and **Locale** are required.+3. Start the import.++<Warning>The export only writes a row where a product already has at least one translated field in that language, so it is not a blank worksheet of everything still to do. A product with nothing translated yet has to be added to the file by hand, as a row carrying its original **slug** and the **locale** being translated into, before a translator has anything to fill in.</Warning>++## What Shoppers See++A translation reaches the storefront as soon as it is saved. A shopper browsing in German sees the translated category name in the menu, the translated product name on the card and the page heading, and the translated slug in the address. The original address still opens the same page, shown in the shopper's own language.++A field left untranslated falls back to the original language rather than appearing blank, which is why a half-translated product reads as a mix of the two.++<Note>A product whose **Meta title** is untranslated keeps its original browser tab title and search listing even when its name is translated. Fill in the meta fields on anything you want found in that language.</Note>++## Further Reading++- [<u>Markets</u>](/user/settings/markets) - Choosing which languages each market offers+- [<u>Set Up Multiple Languages</u>](/user/how-to/multiple-languages) - Getting a second language running across the store+- [<u>Categories</u>](/user/products/categories) - The categories translated here+- [<u>Collections</u>](/user/products/collections) - The collections translated here+- [<u>Product Options</u>](/user/products/options) - The option types and values translated here