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.

Update/user guides settings (#14826)

jaburghes52f06dabce89
diff --git a/docs/docs.json b/docs/docs.json
index 6bab056e0a..47155ce078 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -579,6 +579,34 @@
{
"source": "/developer/tutorial/dashboard-plugin",
"destination": "/developer/tutorial/dashboard"
+ },
+ {
+ "source": "/user/settings/users",
+ "destination": "/user/settings/staff"
+ },
+ {
+ "source": "/user/settings/tax",
+ "destination": "/user/settings/tax-rates"
+ },
+ {
+ "source": "/user/settings/returns-configuration",
+ "destination": "/user/settings/returns-and-reasons"
+ },
+ {
+ "source": "/user/settings/metafields",
+ "destination": "/user/settings/custom-fields"
+ },
+ {
+ "source": "/user/settings/shipping-methods",
+ "destination": "/user/settings/delivery-profiles"
+ },
+ {
+ "source": "/user/settings/zones",
+ "destination": "/user/settings/delivery-profiles"
+ },
+ {
+ "source": "/user/manage-products/product-metafields",
+ "destination": "/user/manage-products/custom-product-fields"
}
],
"contextual": {
diff --git a/docs/images/user/settings/custom-fields/1-custom-fields-overview.png b/docs/images/user/settings/custom-fields/1-custom-fields-overview.png
new file mode 100644
index 0000000000..708d0f2150
Binary files /dev/null and b/docs/images/user/settings/custom-fields/1-custom-fields-overview.png differ
diff --git a/docs/images/user/settings/custom-fields/2-add-custom-field.png b/docs/images/user/settings/custom-fields/2-add-custom-field.png
new file mode 100644
index 0000000000..dd66b41018
Binary files /dev/null and b/docs/images/user/settings/custom-fields/2-add-custom-field.png differ
diff --git a/docs/images/user/settings/custom-fields/3-custom-fields-on-product.png b/docs/images/user/settings/custom-fields/3-custom-fields-on-product.png
new file mode 100644
index 0000000000..5be4d63413
Binary files /dev/null and b/docs/images/user/settings/custom-fields/3-custom-fields-on-product.png differ
diff --git a/docs/images/user/settings/metafields/1-settings-metafields.png b/docs/images/user/settings/metafields/1-settings-metafields.png
deleted file mode 100644
index 48664b961c..0000000000
Binary files a/docs/images/user/settings/metafields/1-settings-metafields.png and /dev/null differ
diff --git a/docs/images/user/settings/metafields/2-create-a-metafield.png b/docs/images/user/settings/metafields/2-create-a-metafield.png
deleted file mode 100644
index 0ec70b8fef..0000000000
Binary files a/docs/images/user/settings/metafields/2-create-a-metafield.png and /dev/null differ
diff --git a/docs/images/user/settings/metafields/3-metafield-resource.png b/docs/images/user/settings/metafields/3-metafield-resource.png
deleted file mode 100644
index 672b3f6ffc..0000000000
Binary files a/docs/images/user/settings/metafields/3-metafield-resource.png and /dev/null differ
diff --git a/docs/images/user/settings/metafields/4-metafield-type.png b/docs/images/user/settings/metafields/4-metafield-type.png
deleted file mode 100644
index 54a6c55768..0000000000
Binary files a/docs/images/user/settings/metafields/4-metafield-type.png and /dev/null differ
diff --git a/docs/images/user/settings/metafields/5-add-metafield-value.png b/docs/images/user/settings/metafields/5-add-metafield-value.png
deleted file mode 100644
index 12c8ac448c..0000000000
Binary files a/docs/images/user/settings/metafields/5-add-metafield-value.png and /dev/null differ
diff --git a/docs/images/user/settings/metafields/6-select-metafields.png b/docs/images/user/settings/metafields/6-select-metafields.png
deleted file mode 100644
index 480c935684..0000000000
Binary files a/docs/images/user/settings/metafields/6-select-metafields.png and /dev/null differ
diff --git a/docs/images/user/settings/metafields/7-enter-metafield-values.png b/docs/images/user/settings/metafields/7-enter-metafield-values.png
deleted file mode 100644
index 6a7df17134..0000000000
Binary files a/docs/images/user/settings/metafields/7-enter-metafield-values.png and /dev/null differ
diff --git a/docs/images/user/settings/returns-and-reasons/1-returns-and-reasons.png b/docs/images/user/settings/returns-and-reasons/1-returns-and-reasons.png
new file mode 100644
index 0000000000..7c5e3bb330
Binary files /dev/null and b/docs/images/user/settings/returns-and-reasons/1-returns-and-reasons.png differ
diff --git a/docs/images/user/settings/roles/1-roles-overview.png b/docs/images/user/settings/roles/1-roles-overview.png
new file mode 100644
index 0000000000..fc2ec7a87f
Binary files /dev/null and b/docs/images/user/settings/roles/1-roles-overview.png differ
diff --git a/docs/images/user/settings/roles/2-new-role.png b/docs/images/user/settings/roles/2-new-role.png
new file mode 100644
index 0000000000..6e63fd1e03
Binary files /dev/null and b/docs/images/user/settings/roles/2-new-role.png differ
diff --git a/docs/images/user/settings/roles/3-permission-grid.png b/docs/images/user/settings/roles/3-permission-grid.png
new file mode 100644
index 0000000000..08df938807
Binary files /dev/null and b/docs/images/user/settings/roles/3-permission-grid.png differ
diff --git a/docs/images/user/settings/staff/1-staff-overview.png b/docs/images/user/settings/staff/1-staff-overview.png
new file mode 100644
index 0000000000..8e4a4a1aee
Binary files /dev/null and b/docs/images/user/settings/staff/1-staff-overview.png differ
diff --git a/docs/images/user/settings/staff/2-invite-teammate.png b/docs/images/user/settings/staff/2-invite-teammate.png
new file mode 100644
index 0000000000..423689b5ca
Binary files /dev/null and b/docs/images/user/settings/staff/2-invite-teammate.png differ
diff --git a/docs/images/user/settings/staff/3-pending-invitation.png b/docs/images/user/settings/staff/3-pending-invitation.png
new file mode 100644
index 0000000000..fc447d379e
Binary files /dev/null and b/docs/images/user/settings/staff/3-pending-invitation.png differ
diff --git a/docs/images/user/settings/tax-categories/1-tax-categories-overview.png b/docs/images/user/settings/tax-categories/1-tax-categories-overview.png
new file mode 100644
index 0000000000..19cb67a88a
Binary files /dev/null and b/docs/images/user/settings/tax-categories/1-tax-categories-overview.png differ
diff --git a/docs/images/user/settings/tax-categories/2-add-tax-category.png b/docs/images/user/settings/tax-categories/2-add-tax-category.png
new file mode 100644
index 0000000000..b6cebd1c1b
Binary files /dev/null and b/docs/images/user/settings/tax-categories/2-add-tax-category.png differ
diff --git a/docs/images/user/settings/tax-rates/1-tax-rates-overview.png b/docs/images/user/settings/tax-rates/1-tax-rates-overview.png
new file mode 100644
index 0000000000..6ad64cae2b
Binary files /dev/null and b/docs/images/user/settings/tax-rates/1-tax-rates-overview.png differ
diff --git a/docs/images/user/settings/tax-rates/2-add-tax-rate.png b/docs/images/user/settings/tax-rates/2-add-tax-rate.png
new file mode 100644
index 0000000000..b15be7e832
Binary files /dev/null and b/docs/images/user/settings/tax-rates/2-add-tax-rate.png differ
diff --git a/docs/images/user/settings/tax/1-tax-settings-tab.png b/docs/images/user/settings/tax/1-tax-settings-tab.png
deleted file mode 100644
index 8fc653218c..0000000000
Binary files a/docs/images/user/settings/tax/1-tax-settings-tab.png and /dev/null differ
diff --git a/docs/images/user/settings/tax/2-tax-subtabs.png b/docs/images/user/settings/tax/2-tax-subtabs.png
deleted file mode 100644
index e45b928f4e..0000000000
Binary files a/docs/images/user/settings/tax/2-tax-subtabs.png and /dev/null differ
diff --git a/docs/images/user/settings/tax/3-tax-rates-overview.png b/docs/images/user/settings/tax/3-tax-rates-overview.png
deleted file mode 100644
index 6ec295a6b3..0000000000
Binary files a/docs/images/user/settings/tax/3-tax-rates-overview.png and /dev/null differ
diff --git a/docs/images/user/settings/tax/4-new-tax-rate-form.png b/docs/images/user/settings/tax/4-new-tax-rate-form.png
deleted file mode 100644
index 295f9b6680..0000000000
Binary files a/docs/images/user/settings/tax/4-new-tax-rate-form.png and /dev/null differ
diff --git a/docs/images/user/settings/tax/5-edit-tax-rate-form.png b/docs/images/user/settings/tax/5-edit-tax-rate-form.png
deleted file mode 100644
index e8a7b7a768..0000000000
Binary files a/docs/images/user/settings/tax/5-edit-tax-rate-form.png and /dev/null differ
diff --git a/docs/images/user/settings/tax/6-tax-categories-overview.png b/docs/images/user/settings/tax/6-tax-categories-overview.png
deleted file mode 100644
index 93d6982712..0000000000
Binary files a/docs/images/user/settings/tax/6-tax-categories-overview.png and /dev/null differ
diff --git a/docs/images/user/settings/tax/7-new-tax-category-form.png b/docs/images/user/settings/tax/7-new-tax-category-form.png
deleted file mode 100644
index 7b03820479..0000000000
Binary files a/docs/images/user/settings/tax/7-new-tax-category-form.png and /dev/null differ
diff --git a/docs/images/user/settings/users/1.users.png b/docs/images/user/settings/users/1.users.png
deleted file mode 100644
index e9d140979c..0000000000
Binary files a/docs/images/user/settings/users/1.users.png and /dev/null differ
diff --git a/docs/images/user/settings/users/2.users_tab.png b/docs/images/user/settings/users/2.users_tab.png
deleted file mode 100644
index 27ef0eb7d3..0000000000
Binary files a/docs/images/user/settings/users/2.users_tab.png and /dev/null differ
diff --git a/docs/images/user/settings/users/3.invite_user.png b/docs/images/user/settings/users/3.invite_user.png
deleted file mode 100644
index 3c09adb11b..0000000000
Binary files a/docs/images/user/settings/users/3.invite_user.png and /dev/null differ
diff --git a/docs/images/user/settings/users/4.user_signup.png b/docs/images/user/settings/users/4.user_signup.png
deleted file mode 100644
index 0c41bd69ac..0000000000
Binary files a/docs/images/user/settings/users/4.user_signup.png and /dev/null differ
diff --git a/docs/images/user/settings/users/5.invitations.png b/docs/images/user/settings/users/5.invitations.png
deleted file mode 100644
index 44c893f922..0000000000
Binary files a/docs/images/user/settings/users/5.invitations.png and /dev/null differ
diff --git a/docs/images/user/settings/users/6.roles.png b/docs/images/user/settings/users/6.roles.png
deleted file mode 100644
index 8c78ee8a70..0000000000
Binary files a/docs/images/user/settings/users/6.roles.png and /dev/null differ
diff --git a/docs/images/user/settings/users/7.edit_user.png b/docs/images/user/settings/users/7.edit_user.png
deleted file mode 100644
index d09ece6193..0000000000
Binary files a/docs/images/user/settings/users/7.edit_user.png and /dev/null differ
diff --git a/docs/images/user/settings/users/8.edit_form.png b/docs/images/user/settings/users/8.edit_form.png
deleted file mode 100644
index 52f93dc955..0000000000
Binary files a/docs/images/user/settings/users/8.edit_form.png and /dev/null differ
diff --git a/docs/user/settings/custom-fields.mdx b/docs/user/settings/custom-fields.mdx
index 51f243efe5..81daa4130b 100644
--- a/docs/user/settings/custom-fields.mdx
+++ b/docs/user/settings/custom-fields.mdx
@@ -1,135 +1,133 @@
---
title: "Custom Fields"
-description: "Define and manage custom fields in Spree to attach extra structured data to products, orders, customers and other records without code changes."
+description: "Learn how to add your own fields to products, orders, customers and other records in Spree Commerce, without writing any code."
---
-Custom fields in Spree allow you to attach extra data to nearly any record in your store — without needing to write a single line of code or modify the database.
+Custom fields let you store information Spree does not have a field for. A clothing store needs fabric composition, a food store needs allergens, a supplier-managed catalogue needs an internal margin tier. Rather than waiting on a developer to add a database column, you define the field once and your team fills it in.
-From product materials to internal order notes, custom fields give you the flexibility to store, manage, and display extra information that doesn't come out of the box. This reduces reliance on developer deployments, makes experimentation easier, and enables faster iteration directly from the admin dashboard.
+A definition says what the field is called, which records carry it, and what kind of value it holds. Once defined, it appears on every matching record for anyone to fill in.
-<Note>The screen heading reads **Custom field definitions** and the menu entry reads **Custom fields**. Both mean the same thing. Earlier versions of Spree called these *metafields*.</Note>
+To manage custom fields, navigate to **Settings → Custom fields**, under the **Store** group.
-## Creating a New Custom Field
+<Note>Earlier versions of Spree called these metafields. The dashboard says custom fields throughout.</Note>
-To create a custom field definition go to **Settings → Custom fields**, under the **Store** group.
+## Reviewing Your Custom Fields
-![Spree Commerce custom fields](/docs/images/user/settings/metafields/1-settings-metafields.png)
+![The Custom field definitions list](/docs/images/user/settings/custom-fields/1-custom-fields-overview.png)
-Here you'll see a list of all existing custom field definitions in your store. Each row shows the **Label** with its full key beneath it — such as `custom.warranty` — along with **Applies to**, **Type**, and **Storefront**.
+Each row shows:
-To add a new one, click **Add custom field** in the top right corner. The panel opens with the line *"Define a typed field your team can fill in on any matching record."*
+- **Label** - What the field is called, with its full key beneath, such as `custom.warranty`.
+- **Applies to** - Which kind of record carries this field.
+- **Type** - What kind of value it holds.
+- **Storefront** - Whether shoppers can see the value.
-![Creating custom fields in Spree](/docs/images/user/settings/metafields/2-create-a-metafield.png)
+Use the search box to find a definition by label, namespace or key.
-Fill out the form with the required details:
+## How to Create a Custom Field
-- **Label** - the display name for the field, shown in the dashboard and/or storefront, e.g. `Material`
-- **Namespace** - used to group custom fields and avoid naming conflicts. Pre-filled with `custom`
- - Leave it on `custom` for internal or merchant-defined fields unless you have a reason to group fields separately
- - Avoid using common Spree model names like product, order, or variant as these may conflict with existing integrations
-- **Key** - the unique identifier for the field, combined with the namespace
- - e.g.: custom.material, custom.internal_note
-- **Applies to** - choose the record the custom field applies to (see full list below)
-- **Type** - the format of data the field should accept (see examples below)
-- **Visible on storefront** - a switch. Turn it on if shoppers should see the value
-- **Searchable** - *"Include values in storefront product text search (short text, long text, and number only)."*
-- **Sortable** - *"Allow storefront product listings to sort by this field (short text and number only)."*
+Click **Add custom field**.
-Then click **Create custom field**.
+![The Add custom field panel](/docs/images/user/settings/custom-fields/2-add-custom-field.png)
-<Warning>The **Searchable** and **Sortable** switches need a follow-up step your developers have to run: after enabling either one with Meilisearch, somebody must run `rake spree:search:reindex` so existing products are updated. Ask whoever maintains your store to do this — the switch alone does not update what is already there.</Warning>
+- **Label** - What your team reads on the form, such as `Warranty`.
+- **Namespace** - Groups fields and avoids naming collisions. Pre-filled with `custom`, which is right unless you have a reason to separate a set of fields.
+- **Key** - A short lower-case identifier, such as `warranty`. The namespace and key together make the full name shown in the list, `custom.warranty`.
+- **Applies to** - Which kind of record the field belongs to.
+- **Type** - What kind of value it holds. See below.
+- **Visible on storefront** - Whether shoppers see the value.
+- **Searchable** - Include values in storefront product text search. Short text, long text and number only.
+- **Sortable** - Allow storefront listings to sort by this field. Short text and number only.
-### Supported Records
+Click **Create custom field**.
-![Add a custom field definition in Spree](/docs/images/user/settings/metafields/3-metafield-resource.png)
+<Warning>Neither **Applies to** nor **Type** can be changed once values exist for a field. Changing the type would leave stored values misinterpreted, so decide both before your team starts filling it in.</Warning>
-You can define custom fields for nearly any record in Spree. **Applies to** offers 31:
+<Warning>**Searchable** and **Sortable** need a follow-up step. After enabling either one with Meilisearch, somebody has to run a reindex so existing products pick it up. Ask whoever maintains your store to do this, because the switch alone does not update what is already there.</Warning>
-- **Addresses** - e.g., delivery instructions
-- **Categories** - e.g., display badge ("New", "Sustainable")
-- **Claims**
-- **Collections**
-- **Credit Cards** - e.g., vault token
-- **Customers** - e.g., loyalty tier
-- **Delivery Methods** - e.g., carrier code
-- **Exchanges**
-- **Fulfillments** - e.g., fragile/handling notes
-- **Gift Cards** - e.g., personal message
-- **Line Items** - e.g., engraving or personalization notes
-- **Media** - e.g., alt text, copyright, or display priority
-- **Newsletter Subscribers** - e.g., subscription source
-- **Option Types** - e.g., an extended description for color choices
-- **Option Values** - e.g., color hex code
-- **Orders** - e.g., internal comment, PO number
-- **Payment Methods** - e.g., risk profile or processor ID
-- **Payment Sources** - e.g., metadata from payment gateway
-- **Payments** - e.g., external transaction reference
-- **Product Types**
-- **Products** - e.g., material, sustainability rating, care instructions
-- **Promotions** - e.g., campaign name
-- **Refunds** - e.g., refund reason detail
-- **Returns** - e.g., return reason detail
-- **Sellers** - e.g., seller profile details
-- **Stock Levels** - e.g., warehouse bin location
-- **Stock Transfers** - e.g., batch ID or receiving note
-- **Store Credits** - e.g., usage restrictions
-- **Stores** - e.g., store tagline or branding metadata
-- **Tax Rates** - e.g., compliance category
-- **Variants** - e.g., spec sheet URL, sizing details
+### Choosing a type
-### Supported Data Types
+| Type | What it holds |
+|---|---|
+| **Short text** | A single line, such as "100% Organic Cotton" |
+| **Long text** | Several lines without formatting, such as care instructions |
+| **Rich text** | Formatted content with headings, lists and links |
+| **Number** | Any numeric value, such as a rating or a capacity |
+| **Boolean** | True or false, such as whether an item is fragile |
+| **JSON** | Structured data holding several related values at once |
-![Spree Commerce custom field types](/docs/images/user/settings/metafields/4-metafield-type.png)
+Pick the narrowest type that fits. A number stored as short text still sorts, but alphabetically rather than numerically, so 10 comes before 9. Switching the type later means starting the field again.
-Each custom field must be assigned a **type**, which determines the format of the stored value. Choosing the right type helps keep data structured, valid, and useful across the storefront and admin.
+### What can carry a custom field
-- **Short Text** - for single-line strings, e.g., "Cotton" or "Blue"
-- **Long Text** - multi-line content, e.g., care instructions
-- **Rich Text** - text with formatting options, e.g., marketing blocks
-- **Number** - any numeric value, e.g., 4.5 (rating), 12 (inches)
-- **Boolean** - true/false flags, e.g., "Is this product fragile?" = true
-- **JSON** - for structured data or multiple related attributes
+**Applies to** offers 31 kinds of record, covering most of what your store holds.
-<Warning>Neither **Applies to** nor **Type** can be changed once values exist for a field. The edit panel says so: *"The type can't be changed once values exist — switching it would leave stored values misinterpreted."* Decide both before you start filling the field in.</Warning>
+| Record | What you might store on it |
+|---|---|
+| **Addresses** | Delivery instructions, such as a gate code |
+| **Categories** | A display badge, such as "New" or "Sustainable" |
+| **Claims** | The carrier's own claim reference |
+| **Collections** | The campaign or season a collection belongs to |
+| **Credit Cards** | A vault token from your payment provider |
+| **Customers** | Loyalty tier, or the account manager who looks after them |
+| **Delivery Methods** | The carrier's service code |
+| **Exchanges** | The tracking reference for the replacement |
+| **Fulfillments** | Handling notes, such as fragile or upright |
+| **Gift Cards** | The personal message printed on it |
+| **Line Items** | Engraving text or personalisation notes |
+| **Media** | Copyright holder, or display priority |
+| **Newsletter Subscribers** | Where the subscription came from |
+| **Option Types** | A longer description of what the option means |
+| **Option Values** | The hex code behind a colour swatch |
+| **Orders** | An internal comment, or a buyer's purchase order number |
+| **Payment Methods** | A risk profile or processor identifier |
+| **Payment Sources** | Metadata returned by the payment gateway |
+| **Payments** | An external transaction reference |
+| **Product Types** | The team responsible for products of this type |
+| **Products** | Material, care instructions, sustainability rating |
+| **Promotions** | The campaign a promotion belongs to |
+| **Refunds** | Detail behind the refund reason |
+| **Returns** | Detail behind the return reason |
+| **Sellers** | A seller's profile details or onboarding notes |
+| **Stock Levels** | The bin location within a warehouse |
+| **Stock Transfers** | A batch identifier or receiving note |
+| **Store Credits** | Restrictions on what the credit can be spent on |
+| **Stores** | A store tagline or branding detail |
+| **Tax Rates** | A compliance classification |
+| **Variants** | A spec sheet address, or detailed sizing |
-## Adding Custom Field Values
+## How to Fill In a Custom Field
-Once your custom field definition has been created, you can enter values in a few different ways:
+Open the record the field applies to. Products carry a **Custom fields** card showing every definition that applies to them.
-### Individually in the Admin Dashboard
+![The Custom fields card on a product](/docs/images/user/settings/custom-fields/3-custom-fields-on-product.png)
-First, navigate to the relevant record (e.g., Product, Order, Fulfillment).
+Enter the values and save the record.
-![Spree Commerce custom field values](/docs/images/user/settings/metafields/5-add-metafield-value.png)
+<Note>To have a field appear on a product automatically, add it to a [<u>product type</u>](/user/settings/product-types). Products carrying that type then show the field without anyone assigning it.</Note>
-Open the **Custom fields** card on the record, or use the **three-dot menu** in the top right corner.
+### Filling them in bulk
-![Adding custom field values in Spree](/docs/images/user/settings/metafields/6-select-metafields.png)
+Product custom fields can be set through the product CSV. Add a column named `custom_field.<namespace>.<key>`, such as `custom_field.custom.material`, and fill in a value for each product row.
-Enter the desired values in the form and click **Save** to finalize your changes.
+The import template generated for your store already ends with one column per custom field you have defined for products, so you may not need to add the columns by hand.
-![Product custom fields in Spree](/docs/images/user/settings/metafields/7-enter-metafield-values.png)
+<Warning>The column prefix is `custom_field.`. A file using the older `metafield.` prefix imports without its custom field values rather than failing, so the import looks successful and the values are silently missing.</Warning>
-This works for any individual record type and is perfect for adding or editing a few custom fields manually.
+## How to Edit a Custom Field
-<Note>To make a field appear on a product form automatically, add it to a [<u>product type</u>](/user/settings/product-types).</Note>
+Open the row menu and choose **Edit**. You can change the **Label**, the **Key** and the storefront switches at any time.
-### In Bulk (Products Only)
+**Applies to** and **Type** are fixed once values exist.
-Product custom fields can also be imported or updated in bulk by:
+## How to Delete a Custom Field
-1. Adding columns to your CSV file using this format: `custom_field.<namespace>.<key>` (e.g. `custom_field.custom.material`)
-2. Entering the desired values for each product row.
-3. Importing the file when uploading a new product catalog
+Open the row menu and choose **Delete**.
-You can also update your existing catalog by exporting the product file, updating it as described above, and then reimporting it to apply custom field updates.
+<Warning>Deleting a definition removes the values stored against it on every record. Export anything you need first, because there is no way to recover them afterwards.</Warning>
-This is ideal for large-scale changes across multiple products, especially when onboarding a large catalog.
+## Further Reading
-<Note>The import template you download is generated for your store, and already ends with one column per custom field you have defined for products. See [<u>Import File Template</u>](/user/manage-products/product-import-file-template).</Note>
-
-## Related
-
-- [<u>Settings → Product Types</u>](/user/settings/product-types)
-- [<u>Import Products</u>](/user/manage-products/import-products)
-- [<u>Import File Template</u>](/user/manage-products/product-import-file-template)
+- [<u>Product Types</u>](/user/settings/product-types) - Making a field appear on a product automatically
+- [<u>Custom Product Fields</u>](/user/manage-products/custom-product-fields) - Using custom fields on products specifically
+- [<u>Import Products</u>](/user/manage-products/import-products) - Setting values in bulk
diff --git a/docs/user/settings/returns-and-reasons.mdx b/docs/user/settings/returns-and-reasons.mdx
index b687b7f0da..3fab609226 100644
--- a/docs/user/settings/returns-and-reasons.mdx
+++ b/docs/user/settings/returns-and-reasons.mdx
@@ -1,59 +1,106 @@
---
title: "Returns & Reasons"
-description: "Define the return, claim, and refund reasons your team chooses from when handling returns."
+description: "Learn how to set up the reasons your team picks from when handling returns, claims, refunds and cancellations in Spree Commerce."
---
-Returns management is a crucial part of ecommerce operations. It builds customer trust, streamlines support workflows, and helps maintain clarity around inventory and financial adjustments.
+Every time your team sends money back, takes goods back, or calls off an order, Spree asks them why. This screen holds the lists they pick from.
-Not all ecommerce platforms offer built-in tools for managing returns, but fortunately Spree does — no extra plugins or custom development needed.
+Keeping these as fixed lists rather than free text is what makes the answers countable. "Damaged in transit" chosen 40 times this month is a conversation with your carrier. Forty differently worded notes are not.
-Before you start processing returns, it is worth setting up the three lists of reasons Spree uses. Each answers a different question, which is why they are kept apart: mixing them together makes your reporting far less useful.
+To manage them, navigate to **Settings → Returns & reasons**, under the **Shipping & delivery** group.
-## Return Reasons
+![The Returns and reasons page, showing the four separate reason lists](/docs/images/user/settings/returns-and-reasons/1-returns-and-reasons.png)
-Return reasons record why a customer is sending something back. They apply to both returns and exchanges.
+## The Four Lists
-Typical examples are "Wrong size", "No longer needed", "Different from description", and "Arrived too late".
+The page holds four independent lists, each in its own card. A reason added to one does not appear in the others, because each answers a different question.
-Each reason has two fields:
+### Return Reasons
-- **Name**: the reason itself, as your team and customers will see it.
-- **Status**: whether the reason is available for use. Setting a reason to inactive hides it from new returns without deleting the history of returns that already used it.
+Why a customer is sending something back. Shared by returns and exchanges, so one list covers both.
-## Claim Reasons
+These are the reasons your team picks when a customer wants to send goods back, and they are the most revealing list on the page. Read together over a few months they tell you whether you have a product problem, a sizing problem, a photography problem or a delivery problem.
-Claim reasons record what went wrong with a delivery — problems on your end rather than a customer changing their mind.
+A new store arrives with nine:
-Typical examples are "Arrived damaged", "Never arrived", "Wrong item sent", and "Missing item from order".
+- Accidental order
+- Better price available
+- Damaged/Defective
+- Different from description
+- Different from what was ordered
+- Missed estimated delivery date
+- Missing parts or accessories
+- No longer needed/wanted
+- Unauthorized purchase
-They have the same two fields as return reasons: a name and a status.
+It's worth noting that these reasons can separate causes you control from causes you do not. For exmaple, "Different from description" is something you can fix. "No longer needed/wanted" is not.
-<Note>
- Claims also have a separate **type** field — damaged, missing, wrong item, or other — which is a broader grouping than the reason. Your developers can add more types if the standard four do not fit your business.
-</Note>
+### Claim Reasons
-## Refund Reasons
+What went wrong with a delivery: damaged, missing or wrong item.
-Refund reasons explain why money was sent back. They are used internally for tracking, reporting, and communication across teams, and they apply to any refund, whether or not a return was involved.
+A claim is opened when the order did not arrive as it should have, rather than when the customer simply wants to send something back. The distinction matters because a claim usually means a cost to recover from a carrier or a supplier, where a return is a normal cost of selling.
-Typical examples are "Return processing" and "Order cancelled".
+A new store arrives with five:
-## Managing reasons
+- Arrived damaged
+- Item not as described
+- Missing item from order
+- Never arrived
+- Wrong item sent
-All three lists live together under **Settings → Returns & reasons**. Spree seeds a starting set when your store is created, so returns, claims, and refunds work out of the box, and you can add, rename, deactivate, or delete entries from there.
+<Note>Ideally, claim reasons should convey what went wrong on your side rather than issues reported on the customer side. Mixing the two makes it impossible to tell a preference problem from a fulfilment problem, which is the main thing this list is for.</Note>
-Each reason has two fields: its **name**, and whether it is **available on new records**. Turning that switch off retires a reason — it stops appearing when staff open a new return, claim, or refund, while every record that already used it keeps its explanation.
+### Refund Reasons
-A reason that is already attached to a record cannot be deleted, because the records that used it would lose their explanation. Those reasons are marked **In use**. Deactivate one instead to retire it, and rename it at any time — every record pointing at it follows the new name.
+Why money went back. Used for reporting across every refund.
-## What about return windows and restocking fees?
+This list applies to any refund, whether or not goods came back. That makes it the one your finance team is most likely to want extended, because "Return processing" does not distinguish a goodwill gesture from a price correction from a cancelled order.
-Spree does not ship with a fixed return window, restocking fee, or final-sale setting. Return policy varies enormously between merchants, and often has to differ by country for legal reasons — the European Union, for example, requires a minimum withdrawal period that many other markets do not.
+A new store arrives with one, **Return processing**, so this is usually the first list worth adding to.
-Rather than guessing, Spree gives your developers a place to attach your own policy when a return is created. A common arrangement enforces the policy for customers opening returns themselves, while letting your staff override it, so a supervisor can accept a late return for a loyal customer without needing any code changes.
+### Order Cancellation Reasons
-## Processing Returns
+Why an order was called off before it shipped. Staff pick one when cancelling.
-Once your reasons are set up, you are ready to handle returns, exchanges, and claims.
+A new store arrives with seven:
-To learn how, see [Returns → Returns Processing](/user/orders/returns).
+- Customer changed their mind
+- Duplicate order
+- Order expired
+- Out of stock
+- Payment declined
+- Staff error
+- Suspected fraud
+
+These reasons separate cancellations you can do something about from the ones you cannot. A rise in **Out of stock** or **Payment declined** points at a problem worth fixing, where **Customer changed their mind** is a normal risk of selling.
+
+<Note>A reason is not required when cancelling an order. The picker reads **No reason given** until somebody chooses one, so cancellations can still go unexplained even with the list in place.</Note>
+
+## How to Add a Reason
+
+Find the card for the kind of reason you are adding, then click **Add reason** on that card.
+
+<Warning>All four cards carry a button labelled **Add reason**. The card you click on decides which list the reason joins, and a reason cannot be moved afterwards.</Warning>
+
+- **Name** - A description of the reason that staff will pick from a dropdown. Keep it short and unambiguous.
+- **Available on new records** - On by default. Controls whether the reason is offered when staff open a new return, claim, refund or cancellation.
+
+Click **Create**.
+
+## How to Retire a Reason
+
+A reason that has been used on a record carries an **In use** badge, and can be edited but not deleted. That is deliberate: deleting it would leave those past records without an explanation.
+
+To stop offering a reason without losing your history, open it and turn off **Available on new records**. It disappears from the dropdowns staff see, and every record that already used it keeps its reason.
+
+Unused reasons can be deleted outright from the row menu.
+
+<Note>Renaming a reason is safe. Every record pointing at it follows the new name, so correcting a spelling or sharpening the wording does not orphan anything.</Note>
+
+## Further Reading
+
+- [<u>Returns</u>](/user/orders/returns) - Processing a return once the reasons are set up
+- [<u>Claims</u>](/user/orders/claims) - Handling a delivery that went wrong
+- [<u>Refunding Orders</u>](/user/orders/refunding-orders) - Sending money back
+- [<u>Policies</u>](/user/settings/policies) - Publishing your returns policy
diff --git a/docs/user/settings/roles.mdx b/docs/user/settings/roles.mdx
index b0b7aea4b6..8e25679b76 100644
--- a/docs/user/settings/roles.mdx
+++ b/docs/user/settings/roles.mdx
@@ -1,41 +1,53 @@
---
title: "Roles"
-description: "Define what each staff role can see and do in Spree — build permission sets from a grid of resources, or start from a ready-made template."
+description: "Learn how to define what each staff role can see and do in Spree Commerce, using the permission grid."
---
-A **role** is a permission set you assign to staff. It decides which parts of the dashboard a person can open, and which of those they can change.
+A role is a permission set you give to staff. It decides which parts of the dashboard somebody has access to, and which of those they can change.
+
+Most stores need three or four. A warehouse team needs stock and fulfilment but not payouts or API keys. A support agent needs orders and customers but has no reason to edit product prices. Giving everybody full access might be quicker on day one, but it can be harder to audit later, when you cannot tell who changed what.
To manage roles, navigate to **Settings → Roles**, under the **Users & permissions** group.
-The table has three columns:
+![The Roles list, showing each role's permissions and how many staff hold it](/docs/images/user/settings/roles/1-roles-overview.png)
+
+Each row shows:
-- **Role**: the role's name
-- **Permissions**: a badge reading **Full access**, **No permissions**, or a count such as **+4 more**
-- **Members**: how many staff hold the role
+- **Role** - What the role is called.
+- **Permissions** - A badge reading **Full access**, **No permissions**, or a count of what is granted.
+- **Members** - How many staff hold it.
-A role that Spree protects carries a **Protected** badge.
+A role Spree protects carries a **Protected** badge.
-## Create a Role
+## How to Create a Role
-Click **Add role**. A panel opens, headed *"Choose what this role can view and manage."*
+Click **Add role**.
-1. Optionally click one of the three **Start from** buttons — **Order manager**, **Merchandiser** or **Support** — to fill the grid with a ready-made set rather than starting empty.
+![The New Role panel, with the starting templates and permission grid](/docs/images/user/settings/roles/2-new-role.png)
+
+1. Optionally click one of the three **Start from** templates, **Order manager**, **Merchandiser** or **Support**, to fill the grid with a sensible starting set rather than an empty one.
2. Give the role a **Name**, and a **Description** if the name is not self-explanatory.
-3. Set the permissions. The grid has a row per resource and two tick boxes — **View** and **Manage**. Tick **View** for everything the role should be able to open, and **Manage** for everything it should be able to change.
+3. Set the permissions in the grid below.
4. Click **Save**.
The role is then offered when you [<u>invite or edit a teammate</u>](/user/settings/staff).
-<Note>Three buttons above the grid set every row at once: **Read only**, **Full access**, and **Clear**. Use one of them as a starting point, then adjust the individual rows.</Note>
+### Setting permissions
+
+The grid has a row per resource and two tick boxes on each: **View** for being able to open it, **Manage** for being able to change it.
-## What You Can Grant
+Three buttons above the grid set every row at once: **Read only**, **Full access** and **Clear**. Starting from one of these and adjusting is usually faster than working down 28 rows.
-The grid holds 28 resources in 9 groups. Each row can be granted **View**, **Manage**, or both.
+![The permission grid, with View and Manage per resource](/docs/images/user/settings/roles/3-permission-grid.png)
+
+### What you can grant
+
+The grid holds 28 resources in 9 groups.
| Group | Resource | What it covers |
|---|---|---|
| **Analytics** | Dashboard | Sales and performance analytics |
-| | Reports | — |
+| | Reports | Saved and built-in reports |
| **Orders** | Orders | Orders, line items, returns, exchanges and claims |
| | Payments | Order payments and payment capture |
| | Fulfillments | Pack, ship and track order fulfillments |
@@ -57,7 +69,7 @@ The grid holds 28 resources in 9 groups. Each row can be granted **View**, **Man
| **Marketing** | Promotions | Promotions, rules and coupon codes |
| **Settings** | Settings | Store, payment, delivery, tax and channel configuration |
| | Delivery methods | Shipping options, rates and the rules that gate them |
-| | Package types | — |
+| | Package types | Boxes, cartons and pallets |
| | Webhooks | Webhook endpoints and deliveries |
| | Integrations | Provider credentials and connections |
| **Access** | API keys | Create and revoke API credentials |
@@ -65,13 +77,17 @@ The grid holds 28 resources in 9 groups. Each row can be granted **View**, **Man
<Note>**Dashboard** can be viewed but not managed, so it offers only one of the two tick boxes.</Note>
-## Edit a Role
+<Warning>**Staff & roles** lets somebody change permissions, including their own. Grant **Manage** on it only to people you would trust with full access to everything, because they can give it to themselves.</Warning>
+
+## How to Edit a Role
+
+Open the row actions and choose **Edit**, then adjust the grid and save.
-Open the role's row actions and choose **Edit**, then adjust the grid and save.
+Changes take effect for everybody holding that role, so narrowing a role narrows it for every member at once.
-<Warning>The built-in **Admin** role is protected and cannot be edited. Opening it shows the full permission grid and a **Save** button, but reads *"This role is protected and cannot be edited."* — none of those controls will take. To run a variation on Admin, create a new role instead.</Warning>
+<Note>The built-in **Admin** role is protected and cannot be edited. To run a variation on it, create a new role and start from **Full access**.</Note>
-## Related
+## Further Reading
-- [<u>Settings → Staff</u>](/user/settings/staff)
-- [<u>Customization → Permissions</u>](/developer/customization/permissions)
+- [<u>Staff</u>](/user/settings/staff) - The people you assign roles to
+- [<u>API Keys</u>](/user/settings/api-keys) - Access for applications rather than people
diff --git a/docs/user/settings/staff.mdx b/docs/user/settings/staff.mdx
index 9b01b3acec..9cf5d41022 100644
--- a/docs/user/settings/staff.mdx
+++ b/docs/user/settings/staff.mdx
@@ -1,68 +1,58 @@
---
title: "Staff"
-description: "Invite, edit, and manage the people with access to your Spree dashboard — send invitations, assign roles, track pending invites, and remove access."
+description: "Learn how to invite teammates to your Spree dashboard, assign their roles, and remove access when someone leaves."
---
-Effectively managing who can reach your store's backend is essential for operational security and team collaboration. The Staff screen lists everyone with access to the dashboard, lets you invite new teammates, and lets you change or remove their access.
+Staff are the people who can reach your dashboard. Each one holds one or more [<u>roles</u>](/user/settings/roles), and those roles decide what they can see and change.
+
+Keeping this list current is extremely important. What someone can reach depends on the roles they hold, and every role touches something that matters. Orders and customer records are the most sensitive, but a merchandiser editing product information or a marketer building promotions can change what you sell and what you charge for it. An ex-staff member who keeps access is a genuine risk rather than an untidy record.
To manage staff, navigate to **Settings → Staff**, under the **Users & permissions** group.
-![](/images/user/settings/users/2.users_tab.png)
+![The Staff list, showing each member and the roles they hold](/docs/images/user/settings/staff/1-staff-overview.png)
The table has two columns:
-- **Member**: the person's initials, name, and email address
-- **Roles**: one badge per role they hold
-
-<Note>The column is **Roles**, plural — a person can hold more than one. The invitation panel offers only a single **Role**, so the way to give somebody a second role is to invite them first and edit them afterwards.</Note>
+- **Member** - The person's name and email address.
+- **Roles** - One badge per role they hold.
-## Invite a Teammate
+## How to Invite a Teammate
-To invite somebody, click **Invite teammate** in the top-right corner. A panel opens, headed *"We'll email them a link to set their password."*
+Click **Invite teammate**.
-![](/images/user/settings/users/3.invite_user.png)
+![The Invite teammate panel](/docs/images/user/settings/staff/2-invite-teammate.png)
-Then follow these steps:
-
-1. Enter their email address.
-2. Choose the **Role** they should have. The dropdown lists the roles that exist in your store, so it grows as you [<u>create roles</u>](/user/settings/roles).
+1. Enter their work email address.
+2. Choose the **Role** they should have. The list is your store's roles, so it grows as you [<u>create</u>](/user/settings/roles) more.
3. Click **Send invitation**.
-Spree emails them a link to set their own password, so nobody types a password on their behalf.
-
-When they click the invitation link, they're taken to an account creation page.
+Spree emails them a link to set their own password, so nobody types a password on anyone else's behalf.
-![](/images/user/settings/users/4.user_signup.png)
+<Note>The invitation offers a single **Role** while the table column reads **Roles**, plural. A person can hold several, so to give somebody a second role, invite them first and edit them afterwards.</Note>
-Once they complete the form, they're redirected to the admin dashboard.
-
-## Edit a Teammate
-
-To change somebody's details or roles, open the row actions and choose **Edit**. The panel is titled **Edit teammate**.
+## Pending Invitations
-![](/images/user/settings/users/8.edit_form.png)
+Invitations that have been sent but not yet accepted appear under **Pending invitations**. The row actions give you two options:
-Change the fields as needed and click **Save**. This is also where you add a second role to somebody who already has one.
+- **Resend** - Sends the invitation email again, for anyone who has lost the original.
+- **Copy invitation link** - Puts the link on your clipboard so you can pass it on yourself, which is useful when the email is not reaching them.
-## Remove a Teammate
+![Pending invitations awaiting acceptance](/docs/images/user/settings/staff/3-pending-invitations.png)
-To take somebody's access away, open the row actions and choose **Remove from staff**.
+## How to Edit a Teammate
-## Pending Invitations
+Open the row actions on a teammate and choose **Edit**. A side panel opens where you can change:
-Invitations that have been sent but not yet accepted appear under **Pending invitations**, where **Resend** is available.
+- **First name** and **Last name** - Correct a spelling, or update a name that has changed.
+- **Roles** - Add a second role, swap one for another, or narrow somebody's access after a change of job.
-![](/images/user/settings/users/5.invitations.png)
+## How to Remove Someone
-Each invitation records:
+Open the row actions and choose **Remove from staff**.
-- **Email**: The email address the invitation was sent to
-- **Inviter**: The person who sent the invitation
-- **Role**: The role assigned on acceptance
-- **Created at**: Date the invitation was created
-- **Status**: Accepted, Pending, or Expired
+<Warning>Do this the day somebody leaves rather than at the end of the month. Until you do, their access is exactly what it was.</Warning>
-## Related
+## Further Reading
-- [<u>Settings → Roles</u>](/user/settings/roles)
-- [<u>Settings → API Keys</u>](/user/settings/api-keys)
+- [<u>Roles</u>](/user/settings/roles) - Defining what each role can see and do
+- [<u>API Keys</u>](/user/settings/api-keys) - Access for applications, which is separate from staff access
diff --git a/docs/user/settings/tax-categories.mdx b/docs/user/settings/tax-categories.mdx
index 6bd3006087..af1e05d25f 100644
--- a/docs/user/settings/tax-categories.mdx
+++ b/docs/user/settings/tax-categories.mdx
@@ -1,59 +1,63 @@
---
title: "Tax Categories"
-description: "Learn how to create and manage tax categories in Spree — the tax classes you assign to products."
+description: "Learn how to group products by tax treatment in Spree Commerce, so the right rate applies to the right goods."
---
-A **tax category** is a tax class you assign to products. It does not set a percentage itself; it groups products by how they should be taxed, and a [<u>tax rate</u>](/user/settings/tax-rates) then names the category and supplies the figure.
+A tax category groups products by how they should be taxed. Most stores need at least two, because not everything you sell is taxed the same way: standard goods at the full rate, and whatever your region treats differently, such as books, children's clothing or food.
+
+A category holds no percentage of its own. It is a label you attach to products, and a [<u>tax rate</u>](/user/settings/tax-rates) then names the category and supplies the figure. Splitting it this way means one category can carry a different rate in every country you sell to.
To manage tax categories, navigate to **Settings → Tax categories**, under the **Selling** group.
-![The Tax Categories overview page listing all configured tax categories](/docs/images/user/settings/tax/6-tax-categories-overview.png)
+![The Tax categories list, showing each category and which is the default](/docs/images/user/settings/tax-categories/1-tax-categories-overview.png)
-Tax categories organize your products based on how they're taxed.
+Each row shows:
-For example, if you sell both clothing and electronics, you might create a **Clothing** category taxed at a reduced or exempt rate (common in regions where apparel gets special tax treatment) and a **Standard** category for electronics taxed at the full rate — each product is then assigned to whichever category matches how it should be taxed.
+- **Name** - What the category is called, with its description beneath.
+- **Tax code** - The code an external tax service knows this category by, if you use one.
+- **Default** - The category products fall back to when none is set.
-<Note>A product variant can only be assigned one tax category at a time.</Note>
+## How to Create a Tax Category
-The Tax Categories overview displays all existing tax categories with key information such as:
+Click **Add tax category**.
-- **Name**: e.g., Standard, Reduced, Exempt
-- **Tax Code**: Optional code for integrations or accounting
-- **Description**: Internal notes on what this category covers
-- **Default**: Whether this is the default category for new products
+![The Add tax category panel](/docs/images/user/settings/tax-categories/2-add-tax-category.png)
-From here, you can add new tax categories or edit existing ones.
+- **Name** - Name it after the tax treatment rather than the product type, such as Reduced rate or Zero rated. The same category usually covers several kinds of goods.
+- **Tax code** - Only needed when an external tax provider such as Avalara expects its own code. Leave it blank otherwise.
+- **Description** - An optional internal note on what belongs in this category. Worth filling in, because "Reduced Rate" means different things in different countries.
+- **Default** - Products with no category of their own fall back to this one.
-## Add a New Tax Category
+Click **Create tax category**.
-To add a new tax category, click **New Tax Category** in the top-right corner. You'll be taken to the tax category creation form.
+<Warning>Setting **Default** demotes whichever category held it before. Only one category can be the default, and the switch does not warn you which one it is replacing.</Warning>
-![The New Tax Category creation form](/docs/images/user/settings/tax/7-new-tax-category-form.png)
+<Note>A tax category charges nothing on its own. Until a tax rate names it, products carrying it are taxed at nothing. Create the category here, then give it a rate on the [<u>Tax Rates</u>](/user/settings/tax-rates) screen.</Note>
-Fill in the form with the relevant information:
+## How a Tax Category is Assigned
-- **Name** — A label for this tax category, e.g., Standard, Reduced, or Exempt.
-- **Tax Code** — An optional code used by integrations or your accounting system to classify this category.
-- **Description** — Optional internal notes on what this category covers.
-- **Default** — Whether new products should automatically be assigned this tax category.
+Categories are assigned on the product and on the variant within the product editor. When Spree works out the tax on a line item, it takes the first of these it finds:
-Once the data has been entered, click **Create** to save the new tax category.
+1. **The variant's own tax category**, if it has one.
+2. **The product's tax category**, if the variant has none.
+3. **The store's default category**, if neither has one.
-This category will now be available for assignment to products and tax rates.
+A product's category is therefore the default for all of its variants, and you only set one on a variant where it needs to differ from the rest.
-<Note>A tax category charges nothing on its own. Until a tax rate names it, products carrying it are not taxed.</Note>
+<Note>A product whose variants are taxed differently does not need splitting into separate products. Set the product's category to whatever most variants need, then override it on the ones that differ.</Note>
-## Edit a Tax Category
+## How to Edit a Tax Category
-To edit a tax category, click its row in the Tax Categories overview, update the fields as needed, then click **Update** to save your changes.
+Open the row menu and choose **Edit**. Renaming a category is safe, because products and rates point at the category itself rather than its name.
-<Note>You can switch the default tax category if needed, but only one can be default at a time.</Note>
+## How to Delete a Tax Category
-## Delete a Tax Category
+Open the row menu and choose **Delete**.
-To delete a tax category, open its edit form and click **Delete** in the lower-right corner.
+<Warning>Deleting a category moves its goods onto a fallback. A variant falls back to its product's category, and a product without one falls back to the store's default. Check that the fallback has a rate covering everywhere you sell before deleting, because goods landing on a category with no applicable rate will be taxed nothing.</Warning>
-## Related
+## Further Reading
-- [<u>Settings → Tax Rates</u>](/user/settings/tax-rates)
-- [<u>Settings → Markets</u>](/user/settings/markets)
+- [<u>Tax Rates</u>](/user/settings/tax-rates) - Giving a category an actual percentage
+- [<u>Markets</u>](/user/settings/markets) - The regions your rates apply in
+- [<u>Create a Product</u>](/user/products/creating-products) - Where a product's tax category is set
diff --git a/docs/user/settings/tax-rates.mdx b/docs/user/settings/tax-rates.mdx
index a4d9e44302..d6a17e1411 100644
--- a/docs/user/settings/tax-rates.mdx
+++ b/docs/user/settings/tax-rates.mdx
@@ -1,82 +1,70 @@
---
title: "Tax Rates"
-description: "Learn how to create and manage tax rates in Spree — the percentages applied per market and region at checkout."
+description: "Learn how to set the tax charged on each category of goods, in each place you sell, in Spree Commerce."
---
-Tax management is critical in eCommerce to ensure legal compliance, avoid costly penalties, and provide accurate pricing for customers across different regions.
+A tax rate records a percentage of tax you are required to collect, and where it applies. Each rate ties a [<u>tax category</u>](/user/settings/tax-categories) to a place, so goods carrying that category are taxed at that figure when they ship there.
-A **tax rate** is the percentage Spree charges, and the rules that decide when it applies. Each rate ties a [<u>tax category</u>](/user/settings/tax-categories) to a region, so a product carrying that category is taxed at that rate when it ships there.
+The figures themselves come from the tax authority in each place you sell. What you need to do is tell Spree what they are, so it applies the right rate to each order.
-To manage tax rates, navigate to **Settings → Tax rates**, under the **Selling** group.
-
-![The Tax Rates overview page listing all configured tax rates](/docs/images/user/settings/tax/3-tax-rates-overview.png)
-
-The Tax Rates overview displays all existing tax rates with key information such as:
+Most stores end up with several: one per category per country, and more where a country taxes by state. For example, a store selling standard and reduced-rate goods into three countries needs six rates.
-- **Name**: A label for storefront and internal display
-- **Tax Category**: Which group of products this rate applies to
-- **Zone**: Where the tax applies
-- **Amount**: The tax percentage (e.g., 20%)
-- **Included in Price**: Whether this tax is part of the listed price
-- **Show Rate in Label**: Whether this tax rate appears as part of the price label on the storefront
-
-From here, you can add new tax rates or edit existing ones.
-
-## Add a New Tax Rate
+To manage tax rates, navigate to **Settings → Tax rates**, under the **Selling** group.
-To add a new tax rate, click **New Tax Rate** in the top-right corner. You'll be taken to the tax rate creation form.
+<Note>Tax rates configure Spree's built-in tax engine. They do not decide which engine a market uses. If you have connected an external tax provider, select it in **Tax engine** on each [<u>market</u>](/user/settings/markets) rather than configuring rates here.</Note>
-![The New Tax Rate creation form](/docs/images/user/settings/tax/4-new-tax-rate-form.png)
+## Reviewing Your Tax Rates
-Fill in the form with the relevant information:
+![The Tax rates list, showing each rate, what it applies to and whether it is included in the price](/docs/images/user/settings/tax-rates/1-tax-rates-overview.png)
-- **Name** — A label for this tax rate, shown internally and, if enabled, on the storefront.
-- **Zone** — The geographic region this rate applies to.
-- **Tax Category** — The group of products this rate applies to, selected from your existing tax categories.
-- **Calculator** — Determines how tax is calculated for this rate — see Calculators below.
-- **Amount** — The tax rate as a decimal (e.g., enter `0.05` for 5%).
-- **Included in Price** — Whether this tax is already built into the listed price (Yes) or added at checkout (No).
-- **Show Rate in Label** — Whether this rate's percentage appears alongside the price on the storefront.
+Each row shows:
-Once the data has been entered, click **Create** to save the new tax rate.
+- **Name** - What the rate is called.
+- **Rate** - The percentage charged.
+- **Applies to** - The country, and the state where one is set.
+- **Included in price** - Whether displayed prices already contain this tax.
-This tax rate can now be applied to products with the matching category and shipping to the selected region.
+## How to Create a Tax Rate
-### Calculators
+Click **Add tax rate**.
-Spree offers three calculators for determining how tax is calculated on a tax rate:
+![The Add tax rate panel](/docs/images/user/settings/tax-rates/2-add-tax-rate.png)
-- **Default Tax Calculator** — A simple calculator that applies the tax rate's **Amount** directly to any product assigned to the associated tax category.
-- **Stripe Tax Calculator** — Automatically calculates tax at checkout based on the customer's shipping address. Only works if you're using Stripe as your payment gateway, and requires tax nexus to be set up in your Stripe dashboard. See the [<u>Stripe integration guide</u>](/integrations/payments/stripe) for setup details.
-- **AvaTax Transaction Calculator** — Automatically calculates tax at checkout based on the customer's shipping address. Requires an Avalara account, with the AvaTax integration installed and configured in Spree. See the [<u>Avalara AvaTax integration guide</u>](/integrations/tax/avalara) for setup details.
+- **Name** - What customers see on the tax line, so use the name they would recognise, such as VAT or Sales Tax.
+- **Rate** - The percentage, entered as a whole number. Enter `20` for 20%.
+- **Tax category** - Which products this rate taxes. Only goods carrying this category are affected.
+- **Country** - Where the rate applies. Leave it empty to tax every country.
+- **State** - Narrows the rate to one state. This field only appears once you pick a country that has states.
+- **Included in price** - Prices already carry this tax, so it is backed out of the displayed price rather than added at checkout.
+- **Show rate in the tax label** - Adds the percentage to the tax line the customer sees, so it reads "VAT (20%)" rather than "VAT".
-<Note>If you're using the AvaTax Transaction Calculator, you don't need to manually create tax rates here — it's enough to set up your tax categories and assign them to products. Spree creates the matching tax rates automatically as orders are placed.</Note>
+Click **Create tax rate**.
-## Edit a Tax Rate
+<Warning>A rate that names no country taxes every country. Leaving **Country** empty is occasionally what you want, but more often it is an oversight that taxes customers who should not be charged.</Warning>
-To edit a tax rate, click its row in the Tax Rates overview.
+### Included in price, or added at checkout
-![The Edit Tax Rate form, pre-filled with an existing rate's data](/docs/images/user/settings/tax/5-edit-tax-rate-form.png)
+This switch is the difference between how European and North American stores usually work, and getting it wrong misprices everything on the affected goods.
-The edit form looks the same as the New Tax Rate form, but pre-filled with the existing data, and with an **Update** button instead of **Create**.
+- **On** suits regions where advertised prices include tax. A product shown at 120 with a 20% rate is treated as 100 plus 20 tax, and the customer pays 120.
+- **Off** suits regions where tax is added at the end. A product shown at 120 with a 20% rate becomes 144 at checkout.
-Update the fields as needed, then click **Update** to save your changes.
+<Note>Whether a market displays prices with tax included is set on the market itself. Set **Tax-inclusive pricing** on the [<u>market</u>](/user/settings/markets) and **Included in price** on its rates to match, or displayed prices and charged tax will disagree.</Note>
-<Note>Changing a tax rate will affect all future orders using that rate, but not past orders.</Note>
+## How to Edit a Tax Rate
-## Delete a Tax Rate
+Open the row menu and choose **Edit**.
-To delete a tax rate, open its edit form and click **Delete** in the lower-right corner.
+Changes apply to new calculations only. Orders already placed keep the tax they were charged, so correcting a rate does not rewrite your history.
-## Other Tax Integrations
+## How to Delete a Tax Rate
-In addition to the Stripe Tax and AvaTax calculators covered above, Spree's tax system is extensible — developers can build custom calculators to connect with other tax services (such as TaxJar) or implement custom tax logic specific to your business.
+Open the row menu and choose **Delete**.
-Get in touch with us if you'd like help implementing a custom tax integration.
+<Warning>Deleting a rate stops tax being charged on its category in that location. Be sure to check that another rate covers those goods before removing one.</Warning>
-## Related
+## Further Reading
-- [<u>Settings → Tax Categories</u>](/user/settings/tax-categories)
-- [<u>Settings → Markets</u>](/user/settings/markets)
-- [<u>Stripe integration guide</u>](/integrations/payments/stripe)
-- [<u>Avalara AvaTax integration guide</u>](/integrations/tax/avalara)
+- [<u>Tax Categories</u>](/user/settings/tax-categories) - The groupings a rate applies to
+- [<u>Markets</u>](/user/settings/markets) - Where tax-inclusive pricing and the tax engine are set
+- [<u>Discounts, Fees and Taxes</u>](/user/orders/discounts-fees-and-taxes) - How tax appears on an order
diff --git a/docs/user/settings/tax.mdx b/docs/user/settings/tax.mdx
deleted file mode 100644
index 82c67b8e1e..0000000000
--- a/docs/user/settings/tax.mdx
+++ /dev/null
@@ -1,139 +0,0 @@
----
-title: "Tax"
-description: "Learn how to configure tax rates and categories for your Spree store."
----
-
-Tax management is critical in eCommerce to ensure legal compliance, avoid costly penalties, and provide accurate pricing for customers across different regions.
-
-Spree gives you a clear and customizable way to set up and manage taxes for any region, product type, or pricing style, whether you include tax in your prices (like VAT) or apply it at checkout (like U.S. sales tax).
-
-To manage tax configurations, navigate to **Settings → Tax** in the admin dashboard.
-
-![The Tax tab in the Spree admin Settings menu](/docs/images/user/settings/tax/1-tax-settings-tab.png)
-
-You'll see two subtabs here — **Tax Rates** and **Tax Categories** — for managing each.
-
-![The Tax Rates and Tax Categories subtabs on the Tax settings page](/docs/images/user/settings/tax/2-tax-subtabs.png)
-
-Let's look at each in more detail:
-
-## Tax Rates
-
-![The Tax Rates overview page listing all configured tax rates](/docs/images/user/settings/tax/3-tax-rates-overview.png)
-
-The Tax Rates overview displays all existing tax rates with key information such as:
-
-- **Name**: A label for storefront and internal display
-- **Tax Category**: Which group of products this rate applies to
-- **Zone**: Where the tax applies (configured separately in the Zones section)
-- **Amount**: The tax percentage (e.g., 20%)
-- **Included in Price**: Whether this tax is part of the listed price
-- **Show Rate in Label**: Whether this tax rate appears as part of the price label on the storefront
-
-From here, you can add new tax rates or edit existing ones.
-
-<Note>Tax rates in Spree rely on the Zones feature to determine where each rate applies. Zones define geographic regions (like countries or states), allowing you to target specific tax rules based on a customer's shipping address. See [<u>Settings → Zones</u>](/user/settings/zones) for more.</Note>
-
-### Add a New Tax Rate
-
-To add a new tax rate, click **New Tax Rate** in the top-right corner. You'll be taken to the tax rate creation form.
-
-![The New Tax Rate creation form](/docs/images/user/settings/tax/4-new-tax-rate-form.png)
-
-Fill in the form with the relevant information:
-
-- **Name** — A label for this tax rate, shown internally and, if enabled, on the storefront.
-- **Zone** — The geographic region this rate applies to, selected from your existing zones.
-- **Tax Category** — The group of products this rate applies to, selected from your existing tax categories.
-- **Calculator** — Determines how tax is calculated for this rate — see Calculators below.
-- **Amount** — The tax rate as a decimal (e.g., enter `0.05` for 5%).
-- **Included in Price** — Whether this tax is already built into the listed price (Yes) or added at checkout (No).
-- **Show Rate in Label** — Whether this rate's percentage appears alongside the price on the storefront.
-
-Once the data has been entered, click **Create** to save the new tax rate.
-
-This tax rate can now be applied to products with the matching category and shipping to the selected zone.
-
-#### Calculators
-
-Spree offers three calculators for determining how tax is calculated on a tax rate:
-
-- **Default Tax Calculator** — A simple calculator that applies the tax rate's **Amount** directly to any product assigned to the associated tax category.
-- **Stripe Tax Calculator** — Automatically calculates tax at checkout based on the customer's shipping address. Only works if you're using Stripe as your payment gateway, and requires tax nexus to be set up in your Stripe dashboard. See the [<u>Stripe integration guide</u>](/integrations/payments/stripe) for setup details.
-- **AvaTax Transaction Calculator** — Automatically calculates tax at checkout based on the customer's shipping address. Requires an Avalara account, with the AvaTax integration installed and configured in Spree. See the [<u>Avalara AvaTax integration guide</u>](/integrations/tax/avalara) for setup details.
-
-<Note>If you're using the AvaTax Transaction Calculator, you don't need to manually create tax rates here — it's enough to set up your tax categories and assign them to products. Spree creates the matching tax rates automatically as orders are placed.</Note>
-
-### Edit a Tax Rate
-
-To edit a tax rate, click its row in the Tax Rates overview.
-
-![The Edit Tax Rate form, pre-filled with an existing rate's data](/docs/images/user/settings/tax/5-edit-tax-rate-form.png)
-
-The edit form looks the same as the New Tax Rate form, but pre-filled with the existing data, and with an **Update** button instead of **Create**.
-
-Update the fields as needed, then click **Update** to save your changes.
-
-<Note>Changing a tax rate will affect all future orders using that rate, but not past orders.</Note>
-
-### Delete a Tax Rate
-
-To delete a tax rate, open its edit form and click **Delete** in the lower-right corner.
-
-## Tax Categories
-
-![The Tax Categories overview page listing all configured tax categories](/docs/images/user/settings/tax/6-tax-categories-overview.png)
-
-Tax categories organize your products based on how they're taxed.
-
-For example, if you sell both clothing and electronics, you might create a **Clothing** category taxed at a reduced or exempt rate (common in regions where apparel gets special tax treatment) and a **Standard** category for electronics taxed at the full rate — each product is then assigned to whichever category matches how it should be taxed.
-
-<Note>A product variant can only be assigned one tax category at a time.</Note>
-
-The Tax Categories overview displays all existing tax categories with key information such as:
-
-- **Name**: e.g., Standard, Reduced, Exempt
-- **Tax Code**: Optional code for integrations or accounting
-- **Description**: Internal notes on what this category covers
-- **Default**: Whether this is the default category for new products
-
-From here, you can add new tax categories or edit existing ones.
-
-### Add a New Tax Category
-
-To add a new tax category, click **New Tax Category** in the top-right corner. You'll be taken to the tax category creation form.
-
-![The New Tax Category creation form](/docs/images/user/settings/tax/7-new-tax-category-form.png)
-
-Fill in the form with the relevant information:
-
-- **Name** — A label for this tax category, e.g., Standard, Reduced, or Exempt.
-- **Tax Code** — An optional code used by integrations or your accounting system to classify this category.
-- **Description** — Optional internal notes on what this category covers.
-- **Default** — Whether new products should automatically be assigned this tax category.
-
-Once the data has been entered, click **Create** to save the new tax category.
-
-This category will now be available for assignment to products and tax rates.
-
-### Edit a Tax Category
-
-To edit a tax category, click its row in the Tax Categories overview, update the fields as needed, then click **Update** to save your changes.
-
-<Note>You can switch the default tax category if needed, but only one can be default at a time.</Note>
-
-### Delete a Tax Category
-
-To delete a tax category, open its edit form and click **Delete** in the lower-right corner.
-
-## Other Tax Integrations
-
-In addition to the Stripe Tax and AvaTax calculators covered above, Spree's tax system is extensible — developers can build custom calculators to connect with other tax services (such as TaxJar) or implement custom tax logic specific to your business.
-
-Get in touch with us if you'd like help implementing a custom tax integration.
-
-## Related
-
-- [<u>Settings → Zones</u>](/user/settings/zones)
-- [<u>Stripe integration guide</u>](/integrations/payments/stripe)
-- [<u>Avalara AvaTax integration guide</u>](/integrations/tax/avalara)
diff --git a/docs/user/settings/users.mdx b/docs/user/settings/users.mdx
deleted file mode 100644
index 1b6f44e58d..0000000000
--- a/docs/user/settings/users.mdx
+++ /dev/null
@@ -1,81 +0,0 @@
----
-title: "Users"
-description: "Invite, edit, and manage admin users in the Spree dashboard — send invitations, assign roles, track pending invites, and control backend access for your team."
----
-
-Effectively managing user access to your store’s backend is essential for operational security and team collaboration. The Users settings section allows you to view active users, track invitations, and (eventually) create roles to define permissions.
-
-To manage admin users, navigate to the Users tab of the admin dashboard.
-
-![](/images/user/settings/users/1.users.png)
-
-This page is split into three subsections for Users, Invitations, and Roles. Let’s take a look at each in detail:
-
-## Users
-
-![](/images/user/settings/users/2.users_tab.png)
-
-This section displays a list of all active users with access to the dashboard. From here, you can invite new users, view existing user details, and remove access if needed.
-
-### Invite a User
-
-To invite a new user, click ‘Send Invitation’ in the top right corner. 
-
-![](/images/user/settings/users/3.invite_user.png)
-
-Then follow these steps:
-
-1. Enter the users email address
-2. Set their user role
-3. Set an invitation expiry date 
-4. Click ‘Send Invitation’
-
-The user will then receive an email invitation to the specified email address.
-
-When they click on the invitation link, they’ll be redirected to an account creation page.
-
-![](/images/user/settings/users/4.user_signup.png)
-
-Once they complete the form and click ‘Create a new account’ they’ll be redirected to the admin dashboard.
-
-### Edit a User
-
-To edit a user, click on their corresponding row to open their admin profile.
-
-![](/images/user/settings/users/7.edit_user.png)
-
-Click Edit in the details section to reveal the edit form.
-
-![](/images/user/settings/users/8.edit_form.png)
-
-Change the fields as needed and click Update to save.
-
-### Delete a User
-
-It’s not possible to outright delete a user, but you can block their access by removing their role in the edit form shown above.
-
-## Invitations
-
-![](/images/user/settings/users/5.invitations.png)
-
-This section shows a record of all invitations that have been sent, whether accepted, pending, or expired. This helps you monitor who’s been invited, by whom, and what role they’ve been assigned.
-
-Each invitation includes:
-
-- **Email**: The email address the invitation was sent to
-- **Inviter**: The user who sent the invitation
-- **Role**: The assigned role upon acceptance
-- **Created at**: Date the invitation was created
-- **Status**: Accepted, Pending, or Expired
-
-<Note>
- Pending invitations can be Resent or Deleted by clicking on the three dots on the right hand side of the corresponding row and selecting the desired action.
-</Note>
-
-## Roles
-
-![](/images/user/settings/users/6.roles.png)
-
-Role-based access control is not yet fully implemented in the admin UI. While you can create new role names, they do not affect permission levels.
-
-However, you can currently create roles and apply permissions to them via code. Please refer to our developer docs for more info: [<u>Customization → Permissions</u>](/developer/customization/permissions).