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.

Restructure the Settings User Guides to match the dashboard (#14672)

jaburghes031be6fe12fb
diff --git a/docs/docs.json b/docs/docs.json
index 9f2e093559..1643bdde04 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -1097,7 +1097,7 @@
"user/products/categories",
"user/products/collections",
"user/manage-products/product-options",
- "user/manage-products/product-metafields",
+ "user/manage-products/custom-product-fields",
"user/manage-products/import-products",
"user/manage-products/export-products",
"user/manage-products/product-import-file-template",
@@ -1207,28 +1207,68 @@
},
{
"group": "Settings",
+ "icon": "settings",
"pages": [
- "user/settings/store-details",
- "user/settings/sales-channels",
- "user/settings/users",
- "user/settings/emails",
- "user/settings/policies",
- "user/settings/payments",
- "user/settings/markets",
- "user/settings/zones",
- "user/settings/shipping-methods",
- "user/settings/tax",
- "user/settings/locations",
- "user/settings/metafields",
- "user/settings/returns-configuration",
- "user/settings/product-types",
- "user/settings/package-types",
- "user/settings/integrations",
- "user/settings/api-keys",
- "user/settings/webhooks",
- "user/settings/allowed-origins"
- ],
- "icon": "settings"
+ {
+ "group": "Store",
+ "icon": "store",
+ "pages": [
+ "user/settings/store-details",
+ "user/settings/emails",
+ "user/settings/policies",
+ "user/settings/sales-channels",
+ "user/settings/custom-fields",
+ "user/settings/integrations"
+ ]
+ },
+ {
+ "group": "Selling",
+ "icon": "badge-dollar-sign",
+ "pages": [
+ "user/settings/markets",
+ "user/settings/payments",
+ "user/settings/tax-categories",
+ "user/settings/tax-rates"
+ ]
+ },
+ {
+ "group": "Shipping & delivery",
+ "icon": "truck",
+ "pages": [
+ "user/settings/delivery-profiles",
+ "user/settings/locations",
+ "user/settings/package-types",
+ "user/settings/product-types",
+ "user/settings/returns-and-reasons"
+ ]
+ },
+ {
+ "group": "Marketplace",
+ "icon": "handshake",
+ "pages": [
+ "user/settings/payouts",
+ "user/settings/seller-requirements"
+ ]
+ },
+ {
+ "group": "Users & permissions",
+ "icon": "user-cog",
+ "pages": [
+ "user/settings/staff",
+ "user/settings/roles"
+ ]
+ },
+ {
+ "group": "Developer",
+ "icon": "code",
+ "pages": [
+ "user/settings/api-keys",
+ "user/settings/webhooks",
+ "user/settings/allowed-origins",
+ "user/settings/imports"
+ ]
+ }
+ ]
},
{
"group": "How-to Guides",
@@ -1237,9 +1277,7 @@
"user/how-to/multi-currency-pricing",
"user/how-to/multiple-languages",
"user/how-to/multi-region-pricing",
- "user/how-to/wholesale-pricing",
"user/how-to/volume-pricing",
- "user/how-to/regional-wholesale",
"user/how-to/regional-volume",
"user/how-to/schedule-sale-pricing"
],
diff --git a/docs/integrations/payments/stripe.mdx b/docs/integrations/payments/stripe.mdx
index e81e1b4195..36b6f687b6 100644
--- a/docs/integrations/payments/stripe.mdx
+++ b/docs/integrations/payments/stripe.mdx
@@ -118,7 +118,7 @@ To enable it in Spree:
2. Set the **Calculator** field to **Stripe Tax Calculator**.
3. Make sure any products you want Stripe to calculate tax on are assigned the tax category associated with that rate. You can assign a tax category from the **Tax** section of the product editor.
-See [<u>Settings → Tax</u>](/user/settings/tax) for more on configuring tax rates and categories, and [<u>Create a Product</u>](/user/products/creating-products) for details on assigning tax categories.
+See [<u>Settings → Tax Rates</u>](/user/settings/tax-rates) for more on configuring tax rates and categories, and [<u>Create a Product</u>](/user/products/creating-products) for details on assigning tax categories.
## Stripe Connect for Marketplaces
diff --git a/docs/user/how-to/multiple-languages.mdx b/docs/user/how-to/multiple-languages.mdx
index 10497c6a91..7f790d64fa 100644
--- a/docs/user/how-to/multiple-languages.mdx
+++ b/docs/user/how-to/multiple-languages.mdx
@@ -20,8 +20,6 @@ When creating or editing a market, set the following:
- **Default Locale** — the primary language for this market (e.g., `FR` for French, `DE` for German)
- **Supported Locales** — any additional languages customers can switch to within that market
-<Note>Before you can set up a Market for a country, make sure that country is included in a configured Zone. See [<u>Settings → Zones</u>](https://spreecommerce.org/docs/user/settings/zones) for setup instructions.</Note>
-
Click **Create** once you've configured the new market. Once your markets are saved, the locales you've configured will appear in the **Products → Translations** page, ready for you to start filling in translated content.
## 2. Translate Products in Bulk Using the Translations Importer
diff --git a/docs/user/manage-products/custom-product-fields.mdx b/docs/user/manage-products/custom-product-fields.mdx
new file mode 100644
index 0000000000..eac2796aec
--- /dev/null
+++ b/docs/user/manage-products/custom-product-fields.mdx
@@ -0,0 +1,258 @@
+---
+title: "Custom Product Fields"
+description: "Learn how to use custom product fields in Spree Commerce to enrich your product data."
+---
+
+Custom Product Fields allow you to add custom attributes to products beyond the default fields included in Spree. Whether you want to display additional product specifications on the storefront, store internal merchandising notes, or support advanced integrations, custom fields give you complete flexibility directly from the admin dashboard.
+
+Unlike legacy product properties, custom fields are structured, scalable, and work seamlessly with imports, APIs, and storefront display settings.
+
+<Note>Earlier versions of Spree called these *metafields*. The dashboard now says **Custom fields** throughout.</Note>
+
+## Why Use Custom Product Fields?
+
+Custom product fields are ideal when you need to:
+
+- Add **technical specifications** (e.g., voltage, dimensions, fabric composition)
+- Display **care instructions**
+- Highlight **sustainability certifications**
+- Store **supplier or internal notes**
+- Add **regulatory information**
+- Include **SEO enhancements**
+- Attach **structured product data**
+- Power custom storefront sections
+- Support third-party integrations
+
+Because custom fields can be created and managed entirely from the dashboard, they reduce development time and eliminate the need for database changes or code deployments.
+
+## How to Create a Custom Product Field
+
+To create a new custom product field, navigate to **Settings → Custom fields**, under the **Store** group.
+
+![How to add custom product fields in Spree Commerce](/docs/images/user/products/product-metafields/1-product-metafields.png)
+
+Click **Add custom field** to open the creation panel. It opens with the line *"Define a typed field your team can fill in on any matching record."*
+
+![Adding a new custom product field in the Spree Commerce dashboard](/docs/images/user/products/product-metafields/2-add-metafields.png)
+
+Complete the form fields as described below.
+
+## **Custom Field Definition Fields**
+
+### **Label**
+
+The display name shown in the admin panel and (optionally) on the storefront.\
+Example:
+
+- Material
+- Care Instructions
+- Sustainability Rating
+
+### **Namespace**
+
+Used to group custom fields and avoid naming conflicts. Pre-filled with **custom**.
+
+- Leave it on **custom** for merchant-defined product fields unless you have a reason to group fields separately.
+- Avoid using reserved model names like **product**, **variant**, or **order**.
+
+### **Key**
+
+The unique identifier for the custom field (combined with the namespace).
+
+Example:
+
+- **custom.material**
+- **custom.care_instructions**
+- **custom.sustainability_score**
+
+### **Applies to**
+
+For custom product fields, select **Products**.
+
+To learn more about creating custom fields for other records, see [<u>Custom Fields</u>](/user/settings/custom-fields).
+
+<Warning>Neither **Applies to** nor **Type** can be changed once values exist for a field. Decide both before you start filling the field in.</Warning>
+
+## **Choosing the Right Data Type**
+
+Each custom field must have a type. Selecting the appropriate type ensures your data is structured correctly.
+
+### **Short Text**
+
+Single-line text values.
+
+Examples:
+
+- "Denim"
+- "Made in Italy"
+- "BPA Free"
+
+### **Long Text**
+
+Multi-line text without formatting.
+
+Examples:
+
+- Care instructions
+- Ingredient lists
+- Warranty information
+
+### **Rich Text**
+
+Formatted content with styling options.
+
+Examples:
+
+- Marketing descriptions
+- Detailed sustainability breakdowns
+- Compliance disclaimers
+
+### **Number**
+
+Numeric values.
+
+Examples:
+
+- 4.8 (average rating)
+- 32 (waist size)
+- 750 (capacity in ml)
+
+### **Boolean**
+
+True/false values.
+
+Examples:
+
+- Is this product eco-friendly?
+- Is this item fragile?
+- Limited edition?
+
+### **JSON**
+
+Structured data or multiple related values.
+
+Examples:
+
+- Technical specifications object
+- Nutritional breakdown
+- Multi-attribute certification data
+
+## Display Settings
+
+Three switches at the foot of the panel decide where the field appears and what the storefront can do with it:
+
+- **Visible on storefront** - off by default. Leave it off for internal use (e.g., supplier notes, internal margin classification); switch it on for values customers should see on product pages.
+- **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)."*
+
+If displayed on the storefront, custom fields can be used within your theme to enhance the Product Detail Page (PDP).
+
+<Warning>**Searchable** and **Sortable** 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. The switch alone does not update what is already there.</Warning>
+
+## Adding Custom Product Field Values
+
+Once the definition is created, you can assign values to individual products.
+
+### Adding Values Individually
+
+![Adding custom field values to a product in Spree Commerce](/docs/images/user/products/product-metafields/3-metafields-values.png)
+
+To add custom field values for individual products:
+
+1. Navigate to **Products**
+2. Open the product you want to update
+3. Find the **Custom fields** card on the product page
+4. Enter the desired values
+5. Click **Save product**
+
+This method is ideal for updating a small number of products.
+
+<Note>To make a field appear on a product form automatically, add it to a [<u>product type</u>](/user/settings/product-types).</Note>
+
+### Updating Custom Product Fields in Bulk
+
+You can also import custom field values via CSV.
+
+#### Step 1: Add a Column to the product CSV file
+
+Use this format:
+
+**custom_field.namespace.key**
+
+Example:
+
+- **custom_field.custom.material**
+- **custom_field.custom.care_instructions**
+- **custom_field.custom.sustainability_score**
+
+#### Step 2: Add Values Per Product Row
+
+Fill in the values for each product.
+
+#### Step 3: Import the File
+
+- Upload during a new product import **or**
+- Export your existing catalog, update it, and reimport with the newly added columns to apply changes
+
+This is especially useful when enriching large product catalogs.
+
+<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 — so you may not need to add the columns by hand.</Note>
+
+Please refer to the following support articles for more information about product imports:
+
+- [<u>Import Products</u>](/user/manage-products/import-products)
+- [<u>Import File Template</u>](/user/manage-products/product-import-file-template)
+
+## Real-World Custom Product Field Examples
+
+Here are some practical examples of how merchants use custom product fields:
+
+### Apparel
+
+- Material: "100% Organic Cotton"
+- Care Instructions: "Machine wash cold, tumble dry low"
+- Fit Type: "Slim Fit"
+- Fabric Weight (gsm): 180
+
+### Electronics
+
+- Battery Life: 12 (hours)
+- Warranty Period: 24 (months)
+- Waterproof: true
+- Voltage: 110–240V
+
+### Food & Supplements
+
+- Allergens: "Contains nuts"
+- Ingredients: Long text field
+- Nutritional Info: JSON structure
+- Expiration Period: 18 (months)
+
+### Furniture
+
+- Assembly Required: true
+- Weight Capacity: 250 (lbs)
+- Material Finish: "Matte Walnut"
+- Care Instructions: Rich text
+
+### B2B Use Cases
+
+- Internal Margin Tier (admin only)
+- Supplier SKU
+- Minimum Order Quantity
+- Packaging Type
+- Compliance Classification
+
+## Replacing Product Properties
+
+Product Properties are no longer supported in the latest version of Spree. Custom product fields provide a more flexible, scalable, and structured solution for managing custom product attributes.
+
+If you previously relied on properties for product enrichment, custom fields are now the recommended approach.
+
+Custom product fields give you the flexibility to tailor your product data model to your business - without relying on developers - while keeping your catalog structured, scalable, and integration-ready.
+
+## Related
+
+- [<u>Settings → Custom Fields</u>](/user/settings/custom-fields)
+- [<u>Settings → Product Types</u>](/user/settings/product-types)
+- [<u>Import Products</u>](/user/manage-products/import-products)
diff --git a/docs/user/manage-products/product-import-file-template.mdx b/docs/user/manage-products/product-import-file-template.mdx
index 56ddfc60a2..e580b42118 100644
--- a/docs/user/manage-products/product-import-file-template.mdx
+++ b/docs/user/manage-products/product-import-file-template.mdx
@@ -41,13 +41,13 @@ For an example of **how to structure multi-variant products**, please download t
| image1_src | A link to the primary image product/variant image |
| image2_src | A link to the second product/variant image |
| image3_src | A link to the third product/variant image |
-| option1_name | The name of the 1st [product option](https://spreecommerce.org/docs/user/manage-products/product-options)|
+| option1_name | The name of the 1st [product option](/user/manage-products/product-options)|
| option1_value | The value of the 1st product option |
| option2_name | The name of the 2nd product option |
| option2_value | The value of the 2nd product option |
| option3_name | The name of the 3rd product option |
| option3_value | The value of the 3rd product option |
-| category1 | The 1st [category](https://spreecommerce.org/docs/user/products/categories) to which the product should be assigned|
+| category1 | The 1st [category](/user/products/categories) to which the product should be assigned|
| category2 | The 2nd category to which the product should be assigned |
| category3 | The 3rd category to which the product should be assigned |
-| custom_field.namespace.key | The value for the product custom field [namespace.key](https://spreecommerce.org/docs/user/settings/metafields)|
+| custom_field.namespace.key | The value for the custom field [namespace.key](/user/settings/custom-fields)|
diff --git a/docs/user/orders/claims.mdx b/docs/user/orders/claims.mdx
index c730b47728..802a9cb820 100644
--- a/docs/user/orders/claims.mdx
+++ b/docs/user/orders/claims.mdx
@@ -41,4 +41,4 @@ For a refund, set the **refund amount** and where it goes: the original payment
- [Returns](/user/orders/returns) — the customer sends items back for a refund
- [Exchanges](/user/orders/exchanges) — the customer sends items back for different ones
-- [Returns & reasons](/user/settings/returns-configuration) — managing the claim-reasons list
+- [Returns & reasons](/user/settings/returns-and-reasons) — managing the claim-reasons list
diff --git a/docs/user/orders/discounts-fees-and-taxes.mdx b/docs/user/orders/discounts-fees-and-taxes.mdx
index 7899f201b6..61a8a37bdd 100644
--- a/docs/user/orders/discounts-fees-and-taxes.mdx
+++ b/docs/user/orders/discounts-fees-and-taxes.mdx
@@ -39,7 +39,7 @@ Fees are taxable: the tax lines are recalculated to include them, using the same
## Taxes
-The **Taxes** card shows what tax was charged, grouped by rate — the amount comes from your [tax setup](/user/settings/tax) or a connected tax provider, applied to the delivery address. You cannot edit a tax line; change the address, the items, the fees or the tax rates and the lines are recalculated.
+The **Taxes** card shows what tax was charged, grouped by rate — the amount comes from your [tax setup](/user/settings/tax-rates) or a connected tax provider, applied to the delivery address. You cannot edit a tax line; change the address, the items, the fees or the tax rates and the lines are recalculated.
Two things the card tells you when something is off:
@@ -60,4 +60,4 @@ Once the totals match again the order returns to **Paid**.
- [Order statuses](/user/orders/order-statuses) — what Partially paid and Overcharged mean
- [Editing orders](/user/orders/editing-orders) — changing the items themselves
- [Promotions](/user/promotions/create-a-promotion) — the source of promotion discounts
-- [Tax settings](/user/settings/tax) — the rates behind the tax lines
+- [Tax rates](/user/settings/tax-rates) — the rates behind the tax lines
diff --git a/docs/user/orders/exchanges.mdx b/docs/user/orders/exchanges.mdx
index 8939ad32e8..06dc8a5b5e 100644
--- a/docs/user/orders/exchanges.mdx
+++ b/docs/user/orders/exchanges.mdx
@@ -46,4 +46,4 @@ An exchange can be cancelled at any point before the goods are received. Cancell
- [Returns](/user/orders/returns) — money back instead of different items
- [Claims](/user/orders/claims) — when the delivery went wrong
-- [Returns & reasons](/user/settings/returns-configuration) — the reason list exchanges share with returns
+- [Returns & reasons](/user/settings/returns-and-reasons) — the reason list exchanges share with returns
diff --git a/docs/user/orders/returns.mdx b/docs/user/orders/returns.mdx
index b68cc35f5a..971b07404b 100644
--- a/docs/user/orders/returns.mdx
+++ b/docs/user/orders/returns.mdx
@@ -56,7 +56,7 @@ Spree keeps two separate lists of reasons, managed under **Settings → Returns
- **Return reasons** explain why a customer is sending something back — "wrong size", "changed my mind", "no longer needed". These apply to both returns and exchanges.
- **Claim reasons** explain what went wrong on your end — "arrived damaged", "never arrived", "wrong item sent".
-They are kept separate because they answer different questions, and mixing them makes reporting less useful. See [Settings → Returns Configuration](/user/settings/returns-configuration) for how to manage them.
+They are kept separate because they answer different questions, and mixing them makes reporting less useful. See [Settings → Returns & Reasons](/user/settings/returns-and-reasons) for how to manage them.
## Return policy
@@ -68,4 +68,4 @@ Instead, your developers can attach your policy to the point where a return is c
- [Exchanges](/user/orders/exchanges) — swapping items rather than refunding
- [Claims](/user/orders/claims) — damaged, missing or wrong deliveries
-- [Returns & reasons](/user/settings/returns-configuration) — the reason lists staff pick from
+- [Returns & Reasons](/user/settings/returns-and-reasons) — the reason lists staff pick from
diff --git a/docs/user/settings/api-keys.mdx b/docs/user/settings/api-keys.mdx
index 6c22e6b83d..5c4673fa9c 100644
--- a/docs/user/settings/api-keys.mdx
+++ b/docs/user/settings/api-keys.mdx
@@ -34,4 +34,4 @@ The list shows when each key was last used, which is how you spot ones that are
- [Sales Channels](/user/settings/sales-channels) — the channel a publishable key can be bound to
- [Webhooks](/user/settings/webhooks) — the other direction: your store calling your systems
-- [Users](/user/settings/users) — staff access, which is separate from API keys
+- [Roles](/user/settings/roles) — dashboard access, which is separate from API keys
diff --git a/docs/user/settings/custom-fields.mdx b/docs/user/settings/custom-fields.mdx
new file mode 100644
index 0000000000..51f243efe5
--- /dev/null
+++ b/docs/user/settings/custom-fields.mdx
@@ -0,0 +1,135 @@
+---
+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."
+---
+
+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.
+
+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.
+
+<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>
+
+## Creating a New Custom Field
+
+To create a custom field definition go to **Settings → Custom fields**, under the **Store** group.
+
+![Spree Commerce custom fields](/docs/images/user/settings/metafields/1-settings-metafields.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**.
+
+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."*
+
+![Creating custom fields in Spree](/docs/images/user/settings/metafields/2-create-a-metafield.png)
+
+Fill out the form with the required details:
+
+- **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)."*
+
+Then click **Create custom field**.
+
+<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>
+
+### Supported Records
+
+![Add a custom field definition in Spree](/docs/images/user/settings/metafields/3-metafield-resource.png)
+
+You can define custom fields for nearly any record in Spree. **Applies to** offers 31:
+
+- **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
+
+### Supported Data Types
+
+![Spree Commerce custom field types](/docs/images/user/settings/metafields/4-metafield-type.png)
+
+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.
+
+- **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
+
+<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>
+
+## Adding Custom Field Values
+
+Once your custom field definition has been created, you can enter values in a few different ways:
+
+### Individually in the Admin Dashboard
+
+First, navigate to the relevant record (e.g., Product, Order, Fulfillment).
+
+![Spree Commerce custom field values](/docs/images/user/settings/metafields/5-add-metafield-value.png)
+
+Open the **Custom fields** card on the record, or use the **three-dot menu** in the top right corner.
+
+![Adding custom field values in Spree](/docs/images/user/settings/metafields/6-select-metafields.png)
+
+Enter the desired values in the form and click **Save** to finalize your changes.
+
+![Product custom fields in Spree](/docs/images/user/settings/metafields/7-enter-metafield-values.png)
+
+This works for any individual record type and is perfect for adding or editing a few custom fields manually.
+
+<Note>To make a field appear on a product form automatically, add it to a [<u>product type</u>](/user/settings/product-types).</Note>
+
+### In Bulk (Products Only)
+
+Product custom fields can also be imported or updated in bulk by:
+
+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
+
+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.
+
+This is ideal for large-scale changes across multiple products, especially when onboarding a large catalog.
+
+<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)
diff --git a/docs/user/settings/delivery-profiles.mdx b/docs/user/settings/delivery-profiles.mdx
new file mode 100644
index 0000000000..d1e8ee3e4d
--- /dev/null
+++ b/docs/user/settings/delivery-profiles.mdx
@@ -0,0 +1,105 @@
+---
+title: "Delivery Profiles"
+description: "Learn how to set up delivery profiles in Spree Commerce — the origins, zones and delivery methods that decide what a customer is offered at checkout."
+---
+
+If you want to run a successful online business, having shipping methods in place is essential. These methods appear at checkout, representing the carriers and services used to deliver your products to customers.
+
+<Warning>If you don’t set up at least one shipping method for each region you sell to, customers in those regions won’t be able to complete their checkout.</Warning>
+
+To set up shipping methods, navigate to **Settings → Shipping** in the Spree dashboard.
+
+![Shipping section of the Spree dashboard](/docs/images/user/settings/shipping/1-shipping-methods.png)
+
+## Add a New Shipping Method
+
+To add a new shipping method, click **New Shipping Method** in the top right corner. This will open the shipping method creation form.
+
+![Adding a new shipping method in Spree](/docs/images/user/settings/shipping/2-new-shipping-method.png)
+
+This page is divided into seven distinct sections, so let’s take a look at each individually:
+
+### Presentation
+
+![Spree shipping methods presentation settings](/docs/images/user/settings/shipping/3-shipping-method-presentation.png)
+
+Here you can set a descriptive name for the shipping method (e.g., UPS Standard, FedEx Next Day), and choose where it should be displayed.
+
+<Warning>Make sure the **Display on** setting includes **storefront** if you want customers to see this shipping method on the checkout.</Warning>
+
+### Tracking URL
+
+![Spree shipping method tracking url](/docs/images/user/settings/shipping/4-tracking-url.png)
+
+Here you can add the tracking URL format for the shipping carrier that’s associated with the shipping method, e.g.:
+
+- [<u>https://www.fedex.com/wtrk/track/?trknbr=:tracking</u>](https://www.fedex.com/wtrk/track/?trknbr=:tracking)
+- [<u>https://www.ups.com/track?loc=en_US&tracknum=:tracking</u>](https://www.ups.com/track?loc=en_US&tracknum=:tracking)
+- [<u>https://tools.usps.com/go/TrackConfirmAction?qtc_tLabels1=:tracking</u>](https://tools.usps.com/go/TrackConfirmAction?qtc_tLabels1=:tracking)
+
+This way, you can simply enter the tracking number when fulfilling an order that’s using the associated shipping method, and the customer will receive the correct tracking link for their order.
+
+<Warning>Make sure to verify the tracking link format for each shipping carrier you plan on using and test them before going live.</Warning>
+
+### Zones
+
+![Set shipping zones in Spree Commerce](/docs/images/user/settings/shipping/5-shipping-method-zones.png)
+
+Not all shipping methods should be available in every region - especially if you serve customers across multiple countries or continents. Zones allow you to define regional availability for each shipping method.
+
+Simply select the appropriate Zone(s) to ensure the method only appears for customers in those regions. This helps you prevent invalid shipping options and tailor your delivery strategy to each market.
+
+<Note>Customers will only see shipping methods that apply to their delivery address based on the assigned Zones.</Note>
+
+### Shipping Categories
+
+![Choose shipping categories in Spree Commerce](/docs/images/user/settings/shipping/6-shipping-categories.png)
+
+Shipping Categories are especially useful when your store includes products with very different delivery needs. For example:
+
+- Assigning a “Digital” category to non-physical products ensures they skip the shipping step during checkout.
+- Creating a “Heavy” category for large or heavy items allows you to limit specific shipping methods to those products.
+
+### Tax Category
+
+![Set a shipping method tax category in Spree](/docs/images/user/settings/shipping/7-tax-category.png)
+
+Use this setting to assign a Tax Category to the shipping method. This determines how taxes are applied to shipping charges at checkout.
+
+Different types of products may be subject to different tax rules, and assigning a tax category here ensures that shipping is taxed appropriately based on the contents of the order.
+
+For example:
+
+- In some regions, digital goods may be exempt from shipping tax, while physical goods are not.
+- Shipping charges related to tax-exempt products might also need to be excluded from tax calculations entirely.
+
+Assigning the correct tax category helps you stay compliant with local tax regulations and ensures customers are charged accurately.
+
+### Calculator
+
+![Choosing a shipping calculator in Spree](/docs/images/user/settings/shipping/8-shipping-calculator.png)
+
+This section determines how the shipping cost will be calculated for this method. Spree offers several calculator types to support different pricing strategies:
+
+- **Flat Percent** - charges a percentage of the order total as the shipping cost.
+- **Flat Rate** - charges a fixed shipping amount, regardless of order size or value.
+- **Flexible Rate per package item** - charges a base rate plus an additional amount for each item in the package (ideal for variable-size orders).
+- **Flat Rate per package item** - Applies the same fixed fee to every item in the shipment.
+- **Price Sack** - offers tiered pricing based on the total order value (e.g., \$5 for orders under \$50, free over \$100).
+- **Digital Delivery** - used for digital products that don’t require physical shipping (typically results in no shipping cost).
+
+Each calculator type may reveal different fields depending on its configuration. Choose the one that best aligns with your fulfillment strategy.
+
+For a more detailed guide on shipping calculators, please refer to another support article.
+
+### Estimated Transit Business Days
+
+![Set shipping method estimated transits days in Spree](/docs/images/user/settings/shipping/9-estimated-delivery.png)
+
+This optional setting allows you to display an estimated delivery time for the shipping method, visible on both the product detail page (PDP) and during checkout.
+
+While not required, showing delivery estimates can help build trust, reduce cart abandonment, and improve conversions by setting clear expectations about when customers will receive their orders.
+
+### Create Shipping Method
+
+Once you’ve configured all of the above settings, simply click **Create** at the bottom of the page to save your new shipping method. It will become immediately available to customers provided the order details match the method’s configuration.
diff --git a/docs/user/settings/imports.mdx b/docs/user/settings/imports.mdx
new file mode 100644
index 0000000000..8d91b8e553
--- /dev/null
+++ b/docs/user/settings/imports.mdx
@@ -0,0 +1,45 @@
+---
+title: "Imports"
+description: "Review the history of CSV files you have uploaded to Spree and how each import went."
+---
+
+The Imports screen shows **CSV files you have uploaded, and how each one went**. It is a history screen, not a place to start work.
+
+<Warning>**You cannot start an import here.** There is no upload button on this screen. To import products, go to **Products → Import**, and see [<u>Import Products</u>](/user/manage-products/import-products). Come back to this screen to watch the import run and to see what happened to each row.</Warning>
+
+To reach it, navigate to **Settings → Imports**, under the **Developer** group.
+
+## What's on the screen
+
+A search box (**Search by number…**), the standard **Add filter**, **Sort** and **Columns** controls, and a table:
+
+| Column | What it shows |
+|---|---|
+| **Number** | The reference Spree gives each import |
+| **Type** | What kind of records the file held |
+| **Status** | How far the import has got |
+| **Rows** | How many rows were read, and how many failed |
+| **Created at** | When the file was uploaded |
+
+Each row has three actions: **View**, **Download original**, and **Delete**.
+
+## How to check on an import
+
+1. Start the import from its own screen — for products, that is [<u>Products → Import</u>](/user/manage-products/import-products).
+2. Go to **Settings → Imports**.
+3. Find the import by its number, or by the date it was created.
+4. Watch **Status** as it runs, and read **Rows** to see how many were read and how many failed.
+5. Click the row to open it and see what happened to each individual row.
+
+## Good to know
+
+- **Download original** gives you back the file exactly as it was uploaded, which is the quickest way to correct and retry a failed import.
+- **Delete** removes the import record, its rows and the uploaded file. An import that is still running cannot be deleted.
+- The screen shows **"No imports yet"** until you have uploaded a file.
+- Imports sits under **Developer**, alongside API keys and webhooks, even though importing is a catalogue job. That is where to look for it.
+
+## Related
+
+- [<u>Import Products</u>](/user/manage-products/import-products)
+- [<u>Import File Template</u>](/user/manage-products/product-import-file-template)
+- [<u>Export Products</u>](/user/manage-products/export-products)
diff --git a/docs/user/settings/integrations.mdx b/docs/user/settings/integrations.mdx
index 576640242b..2711db1a75 100644
--- a/docs/user/settings/integrations.mdx
+++ b/docs/user/settings/integrations.mdx
@@ -31,5 +31,5 @@ Once active, the integration is picked from wherever a provider needs it. A deli
## Related
-- [Shipping Methods](/user/settings/shipping-methods) — delivery methods that quote through a carrier integration
-- [Tax](/user/settings/tax) — choosing a tax provider per market
+- [Delivery Profiles](/user/settings/delivery-profiles) — delivery methods that quote through a carrier integration
+- [Tax Rates](/user/settings/tax-rates) — choosing a tax provider per market
diff --git a/docs/user/settings/markets.mdx b/docs/user/settings/markets.mdx
index ec35d10561..d08cd09dd6 100644
--- a/docs/user/settings/markets.mdx
+++ b/docs/user/settings/markets.mdx
@@ -15,8 +15,6 @@ their preferred currency and language.
Markets can also be used as a rule condition in Price Lists, making it easy to apply
region-specific pricing without duplicating products.
-<Note>Before you can set up a Market for a country, you need to make sure that country is included in a configured Zone. See [<u>Zones</u>](https://spreecommerce.org/docs/user/settings/zones) for setup instructions.</Note>
-
To manage markets, navigate to **Settings → Markets** in the admin dashboard.
![The Markets overview page showing all configured markets](/docs/images/user/settings/markets/1-markets-overview.png)
@@ -70,6 +68,7 @@ bottom of the page.
## Related
-- [<u>Zones</u>](https://spreecommerce.org/docs/user/settings/zones)
-- [<u>Tax</u>](https://spreecommerce.org/docs/user/settings/tax)
-- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/pricing/price-lists)
+- [<u>Delivery Profiles</u>](/user/settings/delivery-profiles)
+- [<u>Tax Rates</u>](/user/settings/tax-rates)
+- [<u>Tax Categories</u>](/user/settings/tax-categories)
+- [<u>Price Lists</u>](/user/pricing/price-lists)
diff --git a/docs/user/settings/package-types.mdx b/docs/user/settings/package-types.mdx
index 70b802a287..f6cc83ab3d 100644
--- a/docs/user/settings/package-types.mdx
+++ b/docs/user/settings/package-types.mdx
@@ -35,5 +35,5 @@ Sellers keep their own package types in the seller panel, alongside the marketpl
## Related
-- [Shipping Methods](/user/settings/shipping-methods) — the delivery methods that use these dimensions when quoting
+- [Delivery Profiles](/user/settings/delivery-profiles) — the delivery methods that use these dimensions when quoting
- [Purchase Orders](/user/inventory/purchase-orders) — stock arriving in cartons
diff --git a/docs/user/settings/payments.mdx b/docs/user/settings/payments.mdx
index ca895fb972..bbae5022f2 100644
--- a/docs/user/settings/payments.mdx
+++ b/docs/user/settings/payments.mdx
@@ -1,5 +1,5 @@
---
-title: "Payments"
+title: "Payment Methods"
description: "Learn how to view, add, edit, and remove payment methods in Spree."
---
@@ -116,4 +116,4 @@ To remove a payment method, simply open the edit form as shown above and click D
<Note>
Deleting a payment method moves it from the enabled payment methods list back into the available payments list. It does not uninstall the associated gem. A developer would need to remove it from the codebase if complete deactivation is desired.
-</Note>
\ No newline at end of file
+</Note>
diff --git a/docs/user/settings/payouts.mdx b/docs/user/settings/payouts.mdx
new file mode 100644
index 0000000000..f2e4f7886b
--- /dev/null
+++ b/docs/user/settings/payouts.mdx
@@ -0,0 +1,39 @@
+---
+title: "Payouts"
+description: "Set who pays your sellers, how often earnings are settled, and the minimum balance worth sending."
+---
+
+The Payouts settings screen decides **how and when this marketplace pays its sellers**. It holds three settings and applies to every seller unless one carries its own schedule.
+
+To reach it, navigate to **Settings → Payouts**, under the **Marketplace** group.
+
+## What's on the screen
+
+| Setting | What it does |
+|---|---|
+| **Paid through** | *"Who moves the money. Keeping your own books means you send the transfers yourself and mark each one paid."* Two choices: **Your own books** and **Stripe Connect**. |
+| **Settle sellers** | *"How often earnings are batched into a payment. A seller can carry their own schedule instead."* Five choices: **Daily**, **Weekly**, **Every two weeks**, **Monthly**, and **Only when you say so**. |
+| **Minimum payout** | *"Below this, a seller's balance carries to the next period rather than being sent. Zero pays whatever is owed."* A number. |
+
+**Save** stays greyed out until you change something.
+
+<Note>**Stripe Connect** appears in the **Paid through** list but could not be selected on the build this page was written against. If you need it, check with your developers whether it is available on your edition and set up.</Note>
+
+## How to set your payout terms
+
+1. Go to **Settings → Payouts**.
+2. Choose **Paid through**. On **Your own books**, Spree tracks what each seller is owed and you send the transfers yourself, marking each one paid.
+3. Choose how often to **Settle sellers**. Pick **Only when you say so** if you would rather run each payout by hand.
+4. Set a **Minimum payout**, or leave it at zero to pay whatever is owed each period.
+5. Click **Save**.
+
+## Good to know
+
+- A seller can carry their own settlement schedule, which overrides the store-wide setting for that seller.
+- Setting a minimum does not cancel a small balance — it carries forward to the next period.
+
+## Related
+
+- [<u>Sellers → Payouts</u>](/user/sellers/payouts)
+- [<u>Sellers → Commission Rates</u>](/user/sellers/commission-rates)
+- [<u>Settings → Seller Requirements</u>](/user/settings/seller-requirements)
diff --git a/docs/user/settings/product-types.mdx b/docs/user/settings/product-types.mdx
index 7bd80a2fda..942eb5b8c9 100644
--- a/docs/user/settings/product-types.mdx
+++ b/docs/user/settings/product-types.mdx
@@ -34,4 +34,4 @@ If you do want to push a type's option types and categories onto the products th
- [Creating Products](/user/products/creating-products) — choosing a type when a product is created
- [Product Options](/user/manage-products/product-options) — the option types a product type seeds
-- [Custom Fields](/user/settings/metafields) — the field definitions a type can ask for
+- [Custom Fields](/user/settings/custom-fields) — the field definitions a type can ask for
diff --git a/docs/user/settings/returns-and-reasons.mdx b/docs/user/settings/returns-and-reasons.mdx
new file mode 100644
index 0000000000..b687b7f0da
--- /dev/null
+++ b/docs/user/settings/returns-and-reasons.mdx
@@ -0,0 +1,59 @@
+---
+title: "Returns & Reasons"
+description: "Define the return, claim, and refund reasons your team chooses from when handling returns."
+---
+
+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.
+
+Not all ecommerce platforms offer built-in tools for managing returns, but fortunately Spree does — no extra plugins or custom development needed.
+
+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.
+
+## Return Reasons
+
+Return reasons record why a customer is sending something back. They apply to both returns and exchanges.
+
+Typical examples are "Wrong size", "No longer needed", "Different from description", and "Arrived too late".
+
+Each reason has two fields:
+
+- **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.
+
+## Claim Reasons
+
+Claim reasons record what went wrong with a delivery — problems on your end rather than a customer changing their mind.
+
+Typical examples are "Arrived damaged", "Never arrived", "Wrong item sent", and "Missing item from order".
+
+They have the same two fields as return reasons: a name and a status.
+
+<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>
+
+## Refund Reasons
+
+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.
+
+Typical examples are "Return processing" and "Order cancelled".
+
+## Managing reasons
+
+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.
+
+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.
+
+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.
+
+## What about return windows and restocking fees?
+
+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.
+
+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.
+
+## Processing Returns
+
+Once your reasons are set up, you are ready to handle returns, exchanges, and claims.
+
+To learn how, see [Returns → Returns Processing](/user/orders/returns).
diff --git a/docs/user/settings/roles.mdx b/docs/user/settings/roles.mdx
new file mode 100644
index 0000000000..b0b7aea4b6
--- /dev/null
+++ b/docs/user/settings/roles.mdx
@@ -0,0 +1,77 @@
+---
+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."
+---
+
+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.
+
+To manage roles, navigate to **Settings → Roles**, under the **Users & permissions** group.
+
+The table has three columns:
+
+- **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
+
+A role that Spree protects carries a **Protected** badge.
+
+## Create a Role
+
+Click **Add role**. A panel opens, headed *"Choose what this role can view and manage."*
+
+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.
+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.
+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>
+
+## What You Can Grant
+
+The grid holds 28 resources in 9 groups. Each row can be granted **View**, **Manage**, or both.
+
+| Group | Resource | What it covers |
+|---|---|---|
+| **Analytics** | Dashboard | Sales and performance analytics |
+| | Reports | — |
+| **Orders** | Orders | Orders, line items, returns, exchanges and claims |
+| | Payments | Order payments and payment capture |
+| | Fulfillments | Pack, ship and track order fulfillments |
+| | Refunds | Issue and view refunds |
+| **Catalog** | Products | Products, variants, options, prices and media |
+| | Product types | Product type definitions and their custom fields |
+| | Publishing | What is visible in the storefront and when |
+| | Media | Images, video and files in the media library |
+| | Categories | Category tree and taxonomies |
+| | Collections | Manual and rule-based product collections |
+| | Stock | Stock levels, locations, movements and transfers |
+| | Purchasing | Suppliers and purchase orders |
+| **Customers** | Customers | Customer accounts, addresses, cards and groups |
+| **Sellers** | Sellers | Seller accounts, onboarding and approval |
+| | Commissions | Commission rates and what each seller is charged |
+| | Payouts | Money paid out to sellers and its schedule |
+| **Loyalty** | Gift cards | Gift cards and gift card batches |
+| | Store credits | Customer store credit balances |
+| **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 | — |
+| | Webhooks | Webhook endpoints and deliveries |
+| | Integrations | Provider credentials and connections |
+| **Access** | API keys | Create and revoke API credentials |
+| | Staff & roles | Team members, invitations, roles and their permissions |
+
+<Note>**Dashboard** can be viewed but not managed, so it offers only one of the two tick boxes.</Note>
+
+## Edit a Role
+
+Open the role's row actions and choose **Edit**, then adjust the grid and save.
+
+<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>
+
+## Related
+
+- [<u>Settings → Staff</u>](/user/settings/staff)
+- [<u>Customization → Permissions</u>](/developer/customization/permissions)
diff --git a/docs/user/settings/seller-requirements.mdx b/docs/user/settings/seller-requirements.mdx
new file mode 100644
index 0000000000..c8fb6b661f
--- /dev/null
+++ b/docs/user/settings/seller-requirements.mdx
@@ -0,0 +1,55 @@
+---
+title: "Seller Requirements"
+description: "Build the checklist sellers complete before they can be approved to sell on your marketplace."
+---
+
+Seller requirements are **the checklist sellers complete before they can be approved**. Each item appears on the seller's own onboarding checklist, and the required ones gate approval.
+
+To reach it, navigate to **Settings → Seller requirements**, under the **Marketplace** group.
+
+## What's on the screen
+
+A drag-ordered list of requirements — the order you set here is the order sellers work through. There is no sort control; drag the handle to reorder.
+
+A new store starts with five requirements, each marked **Required** and **Active**:
+
+- **Accept terms**
+- **Complete profile**
+- **Billing address**
+- **Returns address**
+- **Minimum products**
+
+## Add a requirement
+
+Click **Add requirement**. The panel opens with a single **Type** dropdown, reading *"Choose what to ask for."* It offers the kinds not already in use:
+
+- **Delivery method**
+- **Shipping box**
+- **Payout account**
+- **Required custom fields**
+- **Seller policy**
+- **Seller confirmation**
+- **Manual check**
+- **Document**
+
+## Edit a requirement
+
+Opening a requirement gives you three settings:
+
+| Setting | What the screen says |
+|---|---|
+| **Name** | *"What the seller sees on their checklist."* |
+| **Required** | *"Required items must be done before a seller can be approved. Others are shown as recommended."* |
+| **Active** | *"Switch off to stop asking for this without deleting it."* |
+
+## Good to know
+
+- A requirement type can only be used once, so the **Add requirement** list shrinks as you add them.
+- Switching a requirement to inactive retires it without losing the record of sellers who already completed it.
+- Marking an item **Required** is what gates approval — anything left unrequired is shown to the seller as recommended.
+
+## Related
+
+- [<u>Sellers → Onboarding</u>](/user/sellers/onboarding)
+- [<u>Sellers → Managing Sellers</u>](/user/sellers/managing-sellers)
+- [<u>Settings → Payouts</u>](/user/settings/payouts)
diff --git a/docs/user/settings/staff.mdx b/docs/user/settings/staff.mdx
new file mode 100644
index 0000000000..9b01b3acec
--- /dev/null
+++ b/docs/user/settings/staff.mdx
@@ -0,0 +1,68 @@
+---
+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."
+---
+
+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.
+
+To manage staff, navigate to **Settings → Staff**, under the **Users & permissions** group.
+
+![](/images/user/settings/users/2.users_tab.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>
+
+## 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."*
+
+![](/images/user/settings/users/3.invite_user.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).
+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.
+
+![](/images/user/settings/users/4.user_signup.png)
+
+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**.
+
+![](/images/user/settings/users/8.edit_form.png)
+
+Change the fields as needed and click **Save**. This is also where you add a second role to somebody who already has one.
+
+## Remove a Teammate
+
+To take somebody's access away, open the row actions and choose **Remove from staff**.
+
+## Pending Invitations
+
+Invitations that have been sent but not yet accepted appear under **Pending invitations**, where **Resend** is available.
+
+![](/images/user/settings/users/5.invitations.png)
+
+Each invitation records:
+
+- **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
+
+## Related
+
+- [<u>Settings → Roles</u>](/user/settings/roles)
+- [<u>Settings → API Keys</u>](/user/settings/api-keys)
diff --git a/docs/user/settings/tax-categories.mdx b/docs/user/settings/tax-categories.mdx
new file mode 100644
index 0000000000..6bd3006087
--- /dev/null
+++ b/docs/user/settings/tax-categories.mdx
@@ -0,0 +1,59 @@
+---
+title: "Tax Categories"
+description: "Learn how to create and manage tax categories in Spree — the tax classes you assign to products."
+---
+
+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.
+
+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)
+
+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.
+
+<Note>A tax category charges nothing on its own. Until a tax rate names it, products carrying it are not taxed.</Note>
+
+## 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.
+
+## Related
+
+- [<u>Settings → Tax Rates</u>](/user/settings/tax-rates)
+- [<u>Settings → Markets</u>](/user/settings/markets)
diff --git a/docs/user/settings/tax-rates.mdx b/docs/user/settings/tax-rates.mdx
new file mode 100644
index 0000000000..a4d9e44302
--- /dev/null
+++ b/docs/user/settings/tax-rates.mdx
@@ -0,0 +1,82 @@
+---
+title: "Tax Rates"
+description: "Learn how to create and manage tax rates in Spree — the percentages applied per market and region at checkout."
+---
+
+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** 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.
+
+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:
+
+- **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 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.
+- **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 region.
+
+### 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.
+
+## 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 → 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)
diff --git a/docs/user/user-quickstart-guide.mdx b/docs/user/user-quickstart-guide.mdx
index c8d7da4028..c3f65b153a 100644
--- a/docs/user/user-quickstart-guide.mdx
+++ b/docs/user/user-quickstart-guide.mdx
@@ -90,7 +90,7 @@ From here, you can configure:
- Tax rates (manual or through third-party services like Avalara)
- Tax categories
-For full instructions, please refer to our [<u>Tax support article</u>](https://spreecommerce.org/docs/user/settings/tax).
+For full instructions, please refer to our [<u>Tax Rates support article</u>](/user/settings/tax-rates).
## Shipping Methods
@@ -106,7 +106,7 @@ To configure a shipping methods, go to **Settings → Shipping** and click **New
- Shipping and Tax categories
- Tracking links
-See [<u>Shipping Methods</u>](https://spreecommerce.org/docs/user/settings/shipping-methods) for a full breakdown of settings and examples.
+See [<u>Delivery Profiles</u>](/user/settings/delivery-profiles) for a full breakdown of settings and examples.
<Note>By default, all Spree stores have a Digital Delivery method pre-configured. If you plan on selling digital products, be sure to assign those products the Digital shipping category.</Note>