@mercurjs/docs 2.2.1 → 2.3.0-canary.1

package/content/user-guide/admin/attributes/how-tos/create-an-attribute.mdx

@@ -0,0 +1,64 @@
+---
+title: "Create a Product Attribute"
+sidebarTitle: "Create an attribute"
+description: "Add a new attribute and choose how it stores its value."
+---
+
+> Define a reusable property that sellers apply to their products.
+
+## Overview
+
+Creating an attribute is a two-step form. The "Details" step names the attribute and sets how it behaves. The "Type" step chooses how the value is stored, such as a single choice, multiple choices, a number with a unit, a toggle, or free text.
+
+## Step 1: Start a new attribute
+
+1. Go to "Settings" in the sidebar, then "Attributes".
+2. Click "Create".
+
+{/* screenshot: /settings/attributes list with Create button */}
+
+## Step 2: Enter the details
+
+In the "Details" step:
+
+1. Enter a "Name", for example Material.
+2. Optionally enter a "Handle". If left blank, Mercur generates one from the name.
+3. Optionally enter a "Description".
+4. Set the switches as needed:
+   - "Required attribute". If checked, a value must be set for this attribute on every product.
+   - "Filterable attribute". If checked, customers can filter products by this attribute on the storefront.
+   - "Global attribute". If checked, the attribute applies to all products across all categories. If unchecked, choose the "Categories" it applies to.
+5. Click "Continue".
+
+{/* screenshot: Create Attribute wizard, Details tab */}
+
+## Step 3: Choose the type
+
+In the "Type" step:
+
+1. Select a "Type":
+   - "Single Select". The seller picks one value from a list.
+   - "Multi Select". The seller picks one or more values from a list.
+   - "Unit". A number with a unit of measurement.
+   - "Toggle". A simple on or off value.
+   - "Text Area". Free text.
+2. For "Single Select" and "Multi Select", add the possible values sellers can choose from.
+3. For "Multi Select" only, you can turn on "Use for variants". When checked, the attribute defines product variants, for example size or color.
+
+{/* screenshot: Create Attribute wizard, Type tab */}
+
+## Step 4: Create
+
+Click "Create". The new attribute appears in the list and is available to sellers.
+
+<Note>
+  Only a "Multi Select" attribute can be used as a variant axis. Choose "Use for variants" when the attribute should split a product into separately purchasable variants.
+</Note>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Manage possible values" href="/user-guide/admin/attributes/how-tos/manage-possible-values">
+    Add or reorder the values for a select attribute.
+  </Card>
+</CardGroup>

package/content/user-guide/admin/attributes/how-tos/manage-possible-values.mdx

@@ -0,0 +1,40 @@
+---
+title: "Manage an Attribute's Possible Values"
+sidebarTitle: "Manage possible values"
+description: "Add or reorder the values sellers can choose from for a select attribute."
+---
+
+> Keep the choices behind a Single Select or Multi Select attribute up to date.
+
+## Overview
+
+For select attributes ("Single Select" and "Multi Select"), the possible values are the choices sellers pick from. You can add new values or change their display order at any time.
+
+## Step 1: Open the attribute
+
+1. Go to "Settings" in the sidebar, then "Attributes".
+2. Choose the attribute from the list.
+
+{/* screenshot: Attribute detail page showing possible values */}
+
+## Step 2: Add or reorder values
+
+Use the section actions to:
+
+- Create a new possible value.
+- Edit an existing value.
+- Edit the ranking that controls the order values appear in.
+
+{/* screenshot: Create / edit possible value drawer */}
+
+<Warning>
+  A possible value cannot be deleted while a seller is using it on a product variant. Ask the seller to update their products first.
+</Warning>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Create an attribute" href="/user-guide/admin/attributes/how-tos/create-an-attribute">
+    Add another attribute to your catalog.
+  </Card>
+</CardGroup>

package/content/user-guide/admin/attributes/overview.mdx

@@ -0,0 +1,22 @@
+---
+title: "Product Attributes"
+sidebarTitle: "Overview"
+description: "Create the typed attributes sellers use to describe products and customers use to filter them."
+---
+
+> Reusable product properties like Size, Color, or Material, defined once and used everywhere.
+
+An attribute is a reusable property that describes products. You define attributes once, and sellers apply them to their products. Some attributes can also generate product variants or act as storefront filters.
+
+You manage attributes from "Settings", then "Attributes".
+
+## How-tos
+
+<CardGroup cols={2}>
+  <Card title="Create an attribute" href="/user-guide/admin/attributes/how-tos/create-an-attribute">
+    Add a new attribute and choose how it stores its value.
+  </Card>
+  <Card title="Manage possible values" href="/user-guide/admin/attributes/how-tos/manage-possible-values">
+    Add or reorder the values sellers can choose from.
+  </Card>
+</CardGroup>

package/content/user-guide/admin/commissions/how-tos/create-a-commission-rule.mdx

@@ -0,0 +1,63 @@
+---
+title: "Create a Commission Rule"
+sidebarTitle: "Create a commission rule"
+description: "Override the global commission for a specific store, product type, or category."
+---
+
+> Charge a different fee for certain stores or products than your global commission.
+
+## Overview
+
+A commission rule overrides the global commission for a specific scope, such as a single store or a product category. When several rules could apply to a sale, the most specific rule wins. If no rule matches, the global commission is used.
+
+Creating a rule is a two-step form: "Details" defines what the rule applies to, and "Commission" sets the fee.
+
+## Step 1: Start a new rule
+
+1. Go to "Settings" in the sidebar, then "Commissions".
+2. Click "Create" in the "Commission Rules" section.
+
+{/* screenshot: /settings/commissions, Commission Rules section with Create button */}
+
+## Step 2: Define the scope
+
+In the "Details" step:
+
+1. Enter a "Title" so you can recognise the rule later.
+2. Enter a "Code". This is a unique identifier for the rule.
+3. Select the scope "Type":
+   - "Store". Apply to specific stores.
+   - "Product Type". Apply to specific product types.
+   - "Category". Apply to specific categories.
+   - "Store + Product Type". Apply to product types within specific stores.
+   - "Store + Category". Apply to categories within specific stores.
+4. Depending on the scope, select the specific stores, product types, or categories the rule applies to.
+5. Click "Continue".
+
+{/* screenshot: Create Commission Rule wizard, Details tab with scope Type open */}
+
+## Step 3: Set the fee
+
+In the "Commission" step:
+
+1. Select the "Type". Choose "Percentage" to charge a percentage of the order total, or "Fixed" to charge a set amount per order.
+2. Enter the "Value". For a percentage, enter a number between 0 and 100. For a fixed fee, enter an amount for each store currency.
+3. Set "Tax included" and "Shipping included" as needed. These work the same way as for the global commission.
+
+{/* screenshot: Create Commission Rule wizard, Commission tab */}
+
+## Step 4: Save
+
+Click "Save". The new rule appears in the "Commission Rules" list and applies immediately to matching sales.
+
+<Note>
+  When several rules could apply to the same sale, the most specific rule wins.
+</Note>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Manage a commission rule" href="/user-guide/admin/commissions/how-tos/manage-a-commission-rule">
+    Edit, enable, disable, or delete the rule later.
+  </Card>
+</CardGroup>

package/content/user-guide/admin/commissions/how-tos/edit-the-global-commission.mdx

@@ -0,0 +1,48 @@
+---
+title: "Edit the Global Commission"
+sidebarTitle: "Edit the global commission"
+description: "Change the default fee your marketplace takes on every sale."
+---
+
+> Set the commission that applies whenever no specific rule matches a sale.
+
+## Overview
+
+The global commission is the default fee applied to every sale across the marketplace. When no commission rule matches a sale, this is the fee that is used. You can charge either a percentage of the order total or a fixed amount.
+
+## Step 1: Open the commissions settings
+
+1. Go to "Settings" in the sidebar.
+2. Select "Commissions".
+
+The "Global Commission" section shows the current default fee.
+
+{/* screenshot: /settings/commissions page, Global Commission section */}
+
+## Step 2: Open the edit window
+
+1. Click the icon in the "Global Commission" section header.
+2. Choose "Edit" from the dropdown.
+
+## Step 3: Set the fee
+
+In the side window that opens, set:
+
+- "Type". Choose "Percentage" to charge a percentage of the order total, or "Fixed" to charge a set amount per order.
+- "Value". For a percentage, enter a number between 0 and 100. For a fixed fee, enter an amount for each store currency.
+- "Tax included". If checked, commission is calculated on the total including tax. If unchecked, tax is excluded and goes entirely to the store.
+- "Shipping included". If checked, commission is calculated on the total including shipping. If unchecked, shipping fees go entirely to the store.
+
+{/* screenshot: Edit Global Commission drawer */}
+
+## Step 4: Save
+
+Click "Save". The new global commission applies immediately to any sale that no rule overrides.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Create a commission rule" href="/user-guide/admin/commissions/how-tos/create-a-commission-rule">
+    Override the global commission for specific stores or products.
+  </Card>
+</CardGroup>

package/content/user-guide/admin/commissions/how-tos/manage-a-commission-rule.mdx

@@ -0,0 +1,45 @@
+---
+title: "Manage a Commission Rule"
+sidebarTitle: "Manage a commission rule"
+description: "Edit, enable, disable, or delete an existing commission rule."
+---
+
+> Review a rule and change its scope, fee, or status.
+
+## Overview
+
+Once a commission rule exists, you can review it, change its scope or fee, or remove it entirely. Each rule shows a status badge: "Active" rules apply to matching sales, "Inactive" rules do not.
+
+## Step 1: Open the rule
+
+1. Go to "Settings" in the sidebar, then "Commissions".
+2. Choose the rule from the "Commission Rules" list.
+
+This opens the rule detail page, showing its scope, status, and commission.
+
+{/* screenshot: Commission rule detail page */}
+
+## Step 2: Edit the scope or the fee
+
+- To change the title, code, or scope, click the icon in the scope section header and choose "Edit".
+- To change the fee, click the icon in the "Commission" section header and choose "Edit".
+
+Make your changes in the side window, then click "Save".
+
+{/* screenshot: Commission rule edit drawer */}
+
+## Step 3: Delete the rule
+
+If you no longer need the rule, click the icon in the scope section header and choose "Delete", then confirm.
+
+<Warning>
+  Deleting a rule cannot be undone. Sales that the rule covered fall back to a more general rule, or to the global commission.
+</Warning>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Edit the global commission" href="/user-guide/admin/commissions/how-tos/edit-the-global-commission">
+    Change the default fee used when no rule matches.
+  </Card>
+</CardGroup>

package/content/user-guide/admin/commissions/overview.mdx

@@ -0,0 +1,25 @@
+---
+title: "Commissions"
+sidebarTitle: "Overview"
+description: "Set the fee your marketplace takes on each seller's sales."
+---
+
+> How the marketplace charges commission, and how to override it for specific stores or products.
+
+A commission is the fee your marketplace keeps on every sale. You set one global commission that applies to all sales, and optionally add rules that override it for specific stores, product types, or categories.
+
+You manage commissions from "Settings", then "Commissions". The page has two parts: the "Global Commission" that applies by default, and the "Commission Rules" that override it.
+
+## How-tos
+
+<CardGroup cols={2}>
+  <Card title="Edit the global commission" href="/user-guide/admin/commissions/how-tos/edit-the-global-commission">
+    Change the default fee applied to every sale.
+  </Card>
+  <Card title="Create a commission rule" href="/user-guide/admin/commissions/how-tos/create-a-commission-rule">
+    Override the global commission for a store, type, or category.
+  </Card>
+  <Card title="Manage a commission rule" href="/user-guide/admin/commissions/how-tos/manage-a-commission-rule">
+    Edit, enable, disable, or delete an existing rule.
+  </Card>
+</CardGroup>

package/content/user-guide/admin/overview.mdx

@@ -1,23 +1,31 @@
 ---
 title: "Admin Panel"
-description: "What marketplace operators do in the Admin Panel — no technical knowledge required."
+description: "What marketplace operators do in the Admin Panel, with no technical knowledge required."
 ---
 
-<Note>
-  This guide is being written. The outline below is the intended structure.
-</Note>
+The Admin Panel is where you run the marketplace. You approve sellers, set commissions, review the products sellers submit, and configure how the catalog works.
 
-## What you can do here
+## Areas
 
-Manage sellers, configure commissions, monitor orders and payouts, and control marketplace settings.
-
-## Common tasks
-
-Links to the per-area guides as they are added.
+<CardGroup cols={2}>
+  <Card title="Stores" href="/user-guide/admin/stores">
+    Create, approve, and manage seller stores.
+  </Card>
+  <Card title="Commissions" href="/user-guide/admin/commissions/overview">
+    Set the fee your marketplace takes on each sale.
+  </Card>
+  <Card title="Product Requests" href="/user-guide/admin/product-requests/overview">
+    Approve or reject the products and edits sellers submit.
+  </Card>
+  <Card title="Product Attributes" href="/user-guide/admin/attributes/overview">
+    Create the attributes sellers use to describe products.
+  </Card>
+</CardGroup>
 
 ## Next steps
 
 <CardGroup cols={2}>
-  <Card title="Stores" href="/rc/user-guide/admin/stores" />
-  <Card title="Vendor Panel" href="/rc/user-guide/vendor/overview" />
+  <Card title="Vendor Panel" href="/user-guide/vendor/overview">
+    See the marketplace from a seller's point of view.
+  </Card>
 </CardGroup>

package/content/user-guide/admin/product-requests/how-tos/review-a-new-product.mdx

@@ -0,0 +1,58 @@
+---
+title: "Review a New Product Request"
+sidebarTitle: "Review a new product"
+description: "Confirm, request changes to, or reject a product a seller submitted."
+---
+
+> Decide whether a seller's newly submitted product goes live on the storefront.
+
+## Overview
+
+When a seller submits a new product, it is created with a "Proposed" status and waits for your review. On the product detail page, a "Product request" panel shows the submitting store and the product details. You have three choices: confirm and publish, request an update, or reject.
+
+## Step 1: Open the product
+
+1. Go to "Products" in the sidebar.
+2. Open a product with the "Proposed" status.
+3. Review the product details and the "Product request" panel at the top of the page.
+
+{/* screenshot: /products/:id with the Product request panel */}
+
+## Step 2: Choose an outcome
+
+### Confirm and publish
+
+1. Click "Confirm" in the "Product request" panel.
+2. Optionally add a "Note for store", then confirm.
+
+The product is published. Any offers created for it appear on the storefront, as long as the seller has set stock levels and prices.
+
+{/* screenshot: Confirm request prompt */}
+
+### Request an update
+
+1. Click "Request update".
+2. Add a "Note for store" describing what needs to change, for example missing images or an incorrect price.
+3. Click "Send".
+
+The seller is notified and can revise the product and resubmit it.
+
+{/* screenshot: Request update prompt */}
+
+### Reject the request
+
+1. Click "Reject".
+2. Optionally add a "Note for store" explaining why.
+3. Click "Reject" to confirm.
+
+<Note>
+  Every decision can carry a note for the store, and the seller is notified of the outcome.
+</Note>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Review a product edit" href="/user-guide/admin/product-requests/how-tos/review-a-product-edit">
+    Handle changes to products that are already published.
+  </Card>
+</CardGroup>

package/content/user-guide/admin/product-requests/how-tos/review-a-product-edit.mdx

@@ -0,0 +1,48 @@
+---
+title: "Review a Product Update Request"
+sidebarTitle: "Review a product edit"
+description: "Approve or reject the changes a seller made to a published product."
+---
+
+> Decide whether a seller's edits to a live product take effect on the storefront.
+
+## Overview
+
+When a seller edits a product that is already published, the change does not go live immediately. On the product detail page, a "Product update request" panel shows the requested changes so you can compare them against the current product, then confirm or reject them.
+
+## Step 1: Open the product
+
+1. Go to "Products" in the sidebar.
+2. Open the product that has a pending update.
+3. Review the requested changes in the "Product update request" panel.
+
+{/* screenshot: Product update request panel showing the requested changes */}
+
+## Step 2: Approve or reject
+
+### Confirm the changes
+
+1. Click "Confirm".
+2. Optionally add a "Note for store", then confirm.
+
+The product is updated on the storefront.
+
+### Reject the changes
+
+1. Click "Reject".
+2. Optionally add a "Note for store" explaining why.
+3. Click "Reject" to confirm.
+
+The product keeps its current details.
+
+<Note>
+  The seller is notified of your decision. Use the note to explain what you changed or why a request was declined.
+</Note>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Review a new product" href="/user-guide/admin/product-requests/how-tos/review-a-new-product">
+    Handle brand-new products awaiting approval.
+  </Card>
+</CardGroup>

package/content/user-guide/admin/product-requests/overview.mdx

@@ -0,0 +1,25 @@
+---
+title: "Product Requests"
+sidebarTitle: "Overview"
+description: "Review, approve, or reject the products and edits sellers submit."
+---
+
+> How new products and product edits reach you for review before they go live.
+
+When a seller submits a new product or edits an existing one, it does not go live immediately. It waits for your review on the product detail page. There are two kinds of request:
+
+- A **new product request**, when a seller submits a brand-new product. Its status is "Proposed".
+- A **product update request**, when a seller edits a product that is already published.
+
+To review either, go to "Products" in the sidebar and open the product. The request appears in a panel at the top of the product detail page.
+
+## How-tos
+
+<CardGroup cols={2}>
+  <Card title="Review a new product" href="/user-guide/admin/product-requests/how-tos/review-a-new-product">
+    Confirm, request changes, or reject a proposed product.
+  </Card>
+  <Card title="Review a product edit" href="/user-guide/admin/product-requests/how-tos/review-a-product-edit">
+    Approve or reject changes to a published product.
+  </Card>
+</CardGroup>

package/content/user-guide/vendor/offers/how-tos/create-an-offer.mdx

@@ -0,0 +1,59 @@
+---
+title: "Create an Offer"
+sidebarTitle: "Create an offer"
+description: "List one or more catalog products for sale with your SKU, price, and stock."
+---
+
+> Sell a catalog product by adding your SKU, price, stock, and shipping profile.
+
+## Overview
+
+Creating an offer is a two-step form. In "Products" you pick which catalog products you want to sell. In "Stock Levels & Prices" you set your SKU, shipping profile, price, and inventory for each variant. You can list several products in one flow.
+
+## Step 1: Start a new offer
+
+1. Go to "Products" in the sidebar, then "Offers".
+2. Click "Create".
+
+{/* screenshot: /offers list with Create button */}
+
+## Step 2: Choose products
+
+In the "Products" step:
+
+1. Browse or search the product list.
+2. Select the checkbox next to every product you want to list.
+3. Click "Continue".
+
+{/* screenshot: Create offer wizard, Products tab with items selected */}
+
+<Tip>
+  Select all the products that match your inventory in one go, then set stock and prices for all of them in the next step.
+</Tip>
+
+## Step 3: Set stock and prices
+
+In the "Stock Levels & Prices" step, for every variant row:
+
+1. Enter a "SKU". Your SKU must be unique across your store.
+2. Select a "Shipping Profile".
+3. Enter a "Price" for each currency.
+4. Enter the stocked quantity for each of your stock locations.
+
+{/* screenshot: Create offer wizard, Stock Levels & Prices grid */}
+
+## Step 4: Publish
+
+Click "Publish". Your offers are created.
+
+<Note>
+  An offer only appears on the storefront once it has both stock levels and a price set. Offers missing either stay hidden until you complete them.
+</Note>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Update prices and stock" href="/user-guide/vendor/offers/how-tos/update-prices-and-stock">
+    Adjust an offer's prices or inventory later.
+  </Card>
+</CardGroup>

package/content/user-guide/vendor/offers/how-tos/update-prices-and-stock.mdx

@@ -0,0 +1,40 @@
+---
+title: "Update Offer Prices and Stock"
+sidebarTitle: "Update prices and stock"
+description: "Change an existing offer's prices or inventory without recreating it."
+---
+
+> Adjust what you charge and how much you have in stock for an offer you already listed.
+
+## Overview
+
+After an offer exists, you can update its prices and inventory at any time from the "Offers" list, without going through the create flow again.
+
+## Step 1: Open your offers
+
+Go to "Products" in the sidebar, then "Offers".
+
+{/* screenshot: /offers list page */}
+
+## Step 2: Manage prices or inventory
+
+Use the row actions on the offer to:
+
+- "Manage prices" to change the price for each currency.
+- "Manage inventory" to update stocked quantities at your locations.
+
+Make your changes and save.
+
+{/* screenshot: Offer row actions: Manage prices / Manage inventory */}
+
+<Note>
+  Keep both a price and stock set, or the offer will stop showing on the storefront.
+</Note>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Create an offer" href="/user-guide/vendor/offers/how-tos/create-an-offer">
+    List more products for sale.
+  </Card>
+</CardGroup>

package/content/user-guide/vendor/offers/overview.mdx

@@ -0,0 +1,22 @@
+---
+title: "Offers"
+sidebarTitle: "Overview"
+description: "List a product for sale with your SKU, price, and stock."
+---
+
+> How you sell a product: an offer carries your SKU, price, stock, and shipping profile.
+
+Products in Mercur live in a shared catalog. To sell one, you create an offer against it. The offer carries your own SKU, price, stock levels, and shipping profile. An offer only appears on the storefront once it has both stock levels and a price set.
+
+You manage offers from "Products", then "Offers".
+
+## How-tos
+
+<CardGroup cols={2}>
+  <Card title="Create an offer" href="/user-guide/vendor/offers/how-tos/create-an-offer">
+    List one or more catalog products for sale.
+  </Card>
+  <Card title="Update prices and stock" href="/user-guide/vendor/offers/how-tos/update-prices-and-stock">
+    Change an existing offer's prices or inventory.
+  </Card>
+</CardGroup>