@mercurjs/docs 2.2.0-canary.40

package/content/resources/integrations/stripe-connect.mdx

@@ -0,0 +1,395 @@
+---
+title: "Stripe Connect Integration"
+description: "Set up Stripe Connect for marketplace payments and seller payouts — from Stripe Dashboard configuration to the full end-to-end payment lifecycle."
+---
+
+A Mercur marketplace needs **two** Stripe integrations working together. The first is the standard Medusa payment provider, which charges customers at checkout. The second is the Mercur payout provider, which transfers funds from the platform to sellers after orders are fulfilled.
+
+This guide covers both — setting up Stripe, configuring both providers, wiring up webhooks, and understanding how money flows from customer to seller.
+
+<Tip>
+  This page is the configuration reference. For a hands-on walkthrough that takes one seller from onboarding to a settled payout, follow the [Set up seller payouts](/rc/resources/tutorials/seller-payouts-stripe) tutorial after completing the setup below.
+</Tip>
+
+<Info>
+  Mercur uses Stripe's [Separate Charges and Transfers](https://docs.stripe.com/connect/separate-charges-and-transfers) model. The platform collects the full payment from the customer, then creates transfers to each seller's connected account. This makes the platform the **Merchant of Record**, responsible for VAT, disputes, and chargebacks.
+</Info>
+
+## Prerequisites
+
+- A [Stripe account](https://dashboard.stripe.com) with Connect enabled
+- Stripe Secret API key and Publishable API key
+- A running Mercur project ([installation guide](/rc/learn/installation))
+- Node.js 20+
+
+## Architecture overview
+
+The payment lifecycle in a Mercur marketplace flows through two distinct Stripe integrations:
+
+```mermaid
+flowchart LR
+    C[Customer] -->|PaymentIntent| P[Platform Stripe Account]
+    P -->|Transfer| S1[Seller A Connected Account]
+    P -->|Transfer| S2[Seller B Connected Account]
+    S1 -->|Payout| B1[Seller A Bank]
+    S2 -->|Payout| B2[Seller B Bank]
+```
+
+The two integrations serve different purposes:
+
+| Integration | Package | Purpose | Webhook endpoint |
+|---|---|---|---|
+| Customer payments | `@medusajs/medusa/payment-stripe` | Charges customers at checkout | `/hooks/payment/stripe_stripe` |
+| Seller payouts | `@mercurjs/payout-stripe-connect` | Transfers funds to sellers | `/hooks/payout` |
+
+## Stripe Dashboard setup
+
+<Steps>
+  <Step title="Enable Connect">
+    In your Stripe Dashboard, go to **Settings → Connect settings** and enable Connect. If you're starting fresh, Stripe will walk you through an onboarding flow to activate your platform account.
+  </Step>
+  <Step title="Find your API keys">
+    Go to **Developers → API keys**. You'll need:
+
+    - **Secret key** — starts with `sk_test_` (test mode) or `sk_live_` (production)
+    - **Publishable key** — starts with `pk_test_` or `pk_live_`
+  </Step>
+  <Step title="Set environment variables">
+    Add the following to your `.env` file:
+
+    ```bash
+    STRIPE_API_KEY=sk_test_...
+    STRIPE_WEBHOOK_SECRET=whsec_...
+    STRIPE_PAYOUT_WEBHOOK_SECRET=whsec_...
+    ```
+  </Step>
+</Steps>
+
+## Configure Medusa payment provider
+
+The Medusa payment provider handles customer-facing charges. Add it to your `medusa-config.ts`:
+
+```ts
+module.exports = defineConfig({
+  // ...
+  modules: [
+    {
+      resolve: "@medusajs/medusa/payment",
+      options: {
+        providers: [
+          {
+            resolve: "@medusajs/medusa/payment-stripe",
+            id: "stripe",
+            options: {
+              apiKey: process.env.STRIPE_API_KEY,
+              webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
+              capture: false, // Use manual capture for marketplace flow
+              automatic_payment_methods: true,
+            },
+          },
+        ],
+      },
+    },
+  ],
+})
+```
+
+### Provider options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `apiKey` | `string` | Stripe secret API key |
+| `webhookSecret` | `string` | Signing secret for the payment webhook endpoint |
+| `capture` | `boolean` | Set to `false` for manual capture (required for marketplace split flow) |
+| `automatic_payment_methods` | `boolean` | Enable Stripe's automatic payment method detection |
+| `paymentDescription` | `string` | Optional description shown on customer's bank statement |
+
+<Info>
+  After configuring the provider, enable Stripe as a payment method in your Admin Panel: **Settings → Regions → Edit region → Payment providers → Stripe**.
+</Info>
+
+## Configure Mercur payout provider
+
+The payout provider handles transfers from the platform to seller connected accounts. Add it alongside the payment provider in `medusa-config.ts`:
+
+```ts
+module.exports = defineConfig({
+  // ...
+  modules: [
+    // ... payment provider above
+    {
+      resolve: "@mercurjs/core/modules/payout",
+      options: {
+        providers: [
+          {
+            resolve: "@mercurjs/payout-stripe-connect",
+            id: "stripe-connect",
+            options: {
+              apiKey: process.env.STRIPE_API_KEY,
+              webhookSecret: process.env.STRIPE_PAYOUT_WEBHOOK_SECRET,
+              accountValidation: {
+                detailsSubmitted: true,
+                chargesEnabled: true,
+                payoutsEnabled: true,
+                noOutstandingRequirements: true,
+                requiredCapabilities: [],
+              },
+            },
+          },
+        ],
+      },
+    },
+  ],
+})
+```
+
+### Payout provider options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | — | Stripe secret API key |
+| `webhookSecret` | `string` | — | Signing secret for the payout webhook endpoint |
+| `accountValidation` | `object` | See below | Controls when a connected account is considered `ACTIVE` |
+
+### Account validation options
+
+These options determine what conditions a Stripe connected account must meet before Mercur marks it as `ACTIVE` and allows payouts:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `detailsSubmitted` | `boolean` | `true` | Require Stripe to mark onboarding details as submitted |
+| `chargesEnabled` | `boolean` | `true` | Require the account to be enabled for charges |
+| `payoutsEnabled` | `boolean` | `true` | Require the account to be enabled for payouts |
+| `noOutstandingRequirements` | `boolean` | `true` | Treat any pending Stripe requirements as a restricted account |
+| `requiredCapabilities` | `string[]` | `[]` | Require specific Stripe capabilities to be active (e.g. `["card_payments", "transfers"]`) |
+
+### Payout module options
+
+The payout module itself accepts timing options that control the capture and payout pipeline:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `disabled` | `boolean` | `false` | Disable automatic capture checks and daily payout jobs |
+| `authorizationWindowMs` | `number` | `604800000` (7 days) | How long a payment authorization remains valid |
+| `sellerActionWindowMs` | `number` | `259200000` (72 hours) | How long sellers have to accept/fulfill before cancellation |
+| `captureSafetyBufferMs` | `number` | `86400000` (24 hours) | Safety margin before authorization expiry — capture happens before `authorization expiry - buffer` |
+| `requiredFulfillmentStatus` | `string` | `"fulfilled"` | Minimum fulfillment status before an order is eligible for capture |
+
+## Set up webhooks
+
+You need **two separate webhook endpoints** in Stripe — one for payment events, one for payout events.
+
+<Warning>
+  These are two distinct webhook endpoints, each with its own signing secret. Do not combine them into a single endpoint.
+</Warning>
+
+<Steps>
+  <Step title="Add the payment webhook (Medusa)">
+    In the Stripe Dashboard, go to **Developers → Webhooks → Add endpoint**.
+
+    - **Endpoint URL**: `https://{your-backend-url}/hooks/payment/stripe_stripe`
+    - **Events to subscribe to**:
+      - `payment_intent.succeeded`
+      - `payment_intent.amount_capturable_updated`
+      - `payment_intent.payment_failed`
+      - `charge.refunded`
+
+    Copy the signing secret and set it as `STRIPE_WEBHOOK_SECRET` in your `.env`.
+  </Step>
+  <Step title="Add the payout webhook (Mercur)">
+    Add a second webhook endpoint in the Stripe Dashboard.
+
+    - **Endpoint URL**: `https://{your-backend-url}/hooks/payout`
+    - **Events to subscribe to**:
+      - `account.updated`
+
+    Copy the signing secret and set it as `STRIPE_PAYOUT_WEBHOOK_SECRET` in your `.env`.
+  </Step>
+</Steps>
+
+## How the payment flow works
+
+Here's a concrete example. A customer buys items from two sellers:
+
+- **Seller A**: €40 (product)
+- **Seller B**: €30 (product)
+- **Shipping**: €10
+- **Cart total**: €80
+
+### Step 1 — Authorize payment
+
+At checkout, a single `PaymentIntent` is created for €80 with `capture_method: "manual"`. The customer authenticates once (SCA-compliant). No money moves yet — the funds are held on the customer's card.
+
+### Step 2 — Split orders
+
+Mercur's `completeCartWithSplitOrdersWorkflow` groups items by seller and creates separate orders — one for Seller A (€40) and one for Seller B (€30), plus shipping allocation.
+
+### Step 3 — Seller acceptance and fulfillment
+
+Each seller reviews and fulfills their order through the Vendor Portal. The payout module's `sellerActionWindowMs` (default: 72 hours) defines how long sellers have to act.
+
+### Step 4 — Capture payment
+
+Once orders meet the `requiredFulfillmentStatus` (default: `"fulfilled"`), the platform captures the authorized payment. The capture-check job runs automatically and respects the `captureSafetyBufferMs` to ensure capture happens before authorization expiry.
+
+<Warning>
+  Card authorizations typically expire after **7 days**. The default configuration gives sellers 72 hours to fulfill, with a 24-hour safety buffer before capture. If your business requires longer seller action windows, consider whether the 7-day authorization window is sufficient.
+</Warning>
+
+### Step 5 — Commission calculation and transfers
+
+After capture, Mercur calculates commission for each order and creates Stripe Transfers for the net amounts:
+
+```
+Seller A net = €40 - commission
+Seller B net = €30 - commission
+```
+
+Each transfer is linked to the original charge via `source_transaction` and grouped by `transfer_group` (the order ID).
+
+### Step 6 — Bank payouts
+
+Stripe automatically pays out connected account balances to sellers' bank accounts on the configured payout schedule. Mercur tracks payout status changes via the `account.updated` webhook.
+
+## Seller onboarding
+
+When a seller creates a payout account, the following lifecycle begins:
+
+```
+PENDING → (Stripe onboarding) → ACTIVE
+                                   ↓
+                               RESTRICTED → ACTIVE (remediation)
+                                   ↓
+                               REJECTED (permanent)
+```
+
+1. **Account creation** — Mercur calls `stripe.accounts.create({ type: "express" })`, creating a Stripe Express connected account. The payout account starts in `PENDING` status.
+
+2. **Onboarding link** — The seller receives a Stripe-hosted onboarding URL via `stripe.accountLinks.create()`. They complete identity verification, bank account setup, and any required compliance steps directly on Stripe.
+
+3. **Webhook activation** — When the seller completes onboarding, Stripe sends an `account.updated` webhook. The provider evaluates the account against the `accountValidation` options and transitions the status:
+   - All validation checks pass → `ACTIVE`
+   - Missing requirements or disabled reason → `RESTRICTED`
+   - Disabled reason starts with `rejected.` → `REJECTED`
+
+4. **Ongoing monitoring** — Stripe may send additional `account.updated` events if requirements change. The provider re-evaluates and updates the status accordingly.
+
+For more details on payout accounts, balances, and transactions, see [Payout](/rc/learn/payouts).
+
+## Transfers vs payouts
+
+Stripe uses two distinct concepts for moving money, and it's important to understand the difference:
+
+| | Transfer | Payout |
+|---|---|---|
+| **What it does** | Moves funds from platform balance to connected account balance | Moves funds from connected account balance to seller's bank account |
+| **Speed** | Instant ledger movement | 1–3 business days (varies by country) |
+| **Status lifecycle** | None — transfers are immediate | `pending` → `in_transit` → `paid` / `failed` |
+| **Who triggers it** | Mercur (via `stripe.transfers.create()`) | Stripe (on the connected account's payout schedule) |
+| **Mercur tracking** | Transfer created with status `PAID` immediately | Status tracked via webhooks |
+
+When Mercur's `createPayout` method is called, the Stripe Connect provider creates a **Transfer** (platform → connected account). The actual bank payout (connected account → bank) happens automatically on Stripe's schedule.
+
+## Refunds and reversals
+
+Refunding a charge does **not** automatically reverse the associated transfers. These are two separate operations:
+
+1. **Refund the PaymentIntent** — Returns funds to the customer's payment method
+2. **Reverse the Transfer(s)** — Claws back funds from the connected account(s)
+
+For a full refund of a multi-seller order, you would need to reverse each seller's transfer individually. For partial refunds, you need to calculate how much to reverse from each seller based on which items are being refunded.
+
+<Info>
+  Refund and transfer reversal orchestration is an area where custom workflow logic may be needed depending on your business rules. See Stripe's documentation on [reversing transfers](https://docs.stripe.com/connect/separate-charges-and-transfers#reverse-transfers) for the API details.
+</Info>
+
+## EU/EEA considerations
+
+### Merchant of Record
+
+Using Separate Charges and Transfers makes the platform the Merchant of Record. This means:
+
+- The platform collects and remits VAT
+- The platform handles consumer disputes and chargebacks
+- The platform is responsible for PSD2 compliance
+
+### Strong Customer Authentication (SCA)
+
+SCA is enforced at **authorization time**, not capture time. Since the customer authenticates once during checkout, no additional SCA step is needed when the platform captures later. The single authorization at checkout satisfies the SCA requirement for the entire order.
+
+### Authorization windows
+
+Card authorizations in Europe typically last **7 days**. Design your seller acceptance workflow to complete well within this window. The payout module options give you control over the timing:
+
+```ts
+{
+  resolve: "@mercurjs/core/modules/payout",
+  options: {
+    authorizationWindowMs: 7 * 24 * 60 * 60 * 1000,    // 7 days
+    sellerActionWindowMs: 72 * 60 * 60 * 1000,          // 72 hours
+    captureSafetyBufferMs: 24 * 60 * 60 * 1000,         // 24 hours
+    // ...providers
+  },
+}
+```
+
+## Testing
+
+### Test mode
+
+Use Stripe test mode keys (`sk_test_`, `pk_test_`) during development. All connected accounts and payments created in test mode are isolated from production.
+
+**Test card number**: `4242 4242 4242 4242` (any future expiry, any CVC)
+
+### Webhook forwarding with Stripe CLI
+
+Since webhooks need to reach your local machine during development, use the [Stripe CLI](https://docs.stripe.com/stripe-cli) to forward events. You need **two separate listeners** — one for each webhook endpoint:
+
+```bash
+# Terminal 1 — Payment webhooks
+stripe listen --forward-to localhost:9000/hooks/payment/stripe_stripe
+
+# Terminal 2 — Payout webhooks
+stripe listen --forward-to localhost:9000/hooks/payout
+```
+
+<Tip>
+  Each `stripe listen` process outputs its own webhook signing secret. Use these as your `STRIPE_WEBHOOK_SECRET` and `STRIPE_PAYOUT_WEBHOOK_SECRET` respectively during local development.
+</Tip>
+
+### Testing the full flow
+
+1. Create a seller and complete Stripe's test onboarding flow
+2. Add products from the seller to a cart
+3. Complete checkout using the test card
+4. Verify orders are split by seller in the Admin Panel
+5. Fulfill the orders through the Vendor Portal
+6. Confirm transfers appear in the Stripe Dashboard under the connected account
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="Why do I need two webhook endpoints with two secrets?">
+    They belong to two different integrations: the payment webhook feeds Medusa's payment provider (charges, captures, refunds), while the payout webhook feeds Mercur's payout provider (connected-account status, transfer status). Each endpoint verifies its own signing secret — combining them silently breaks whichever side's signature doesn't match.
+  </Accordion>
+  <Accordion title="Why must capture be set to false on the payment provider?">
+    The marketplace flow authorizes at checkout and captures later, after sellers fulfill. Automatic capture would take the money before the split-order pipeline (fulfillment checks, commission, payouts) has run — `capture: false` hands that timing to the payout module's capture job.
+  </Accordion>
+  <Accordion title="A seller finished Stripe onboarding but is still not ACTIVE — why?">
+    Check the `accountValidation` options: by default the account must have details submitted, charges and payouts enabled, and **no outstanding requirements**. Stripe often adds follow-up requirements (e.g. extra KYC) after initial onboarding — the account shows as `RESTRICTED` until they're cleared.
+  </Accordion>
+  <Accordion title="Who handles VAT, disputes, and chargebacks?">
+    The platform. Separate Charges and Transfers makes the platform the Merchant of Record — see [EU/EEA considerations](#eueea-considerations) for what that entails.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Set up seller payouts" href="/rc/resources/tutorials/seller-payouts-stripe">
+    Hands-on: one seller from onboarding to a settled payout.
+  </Card>
+  <Card title="Payout" href="/rc/learn/payouts">
+    The pipeline reference — statuses, jobs, and webhook events.
+  </Card>
+</CardGroup>

package/content/resources/tutorials/add-a-block.mdx

@@ -0,0 +1,74 @@
+---
+title: "Add a feature with a block"
+description: "Install the reviews block end-to-end and see it live across the admin, vendor, and storefront surfaces."
+---
+
+Blocks are complete features — backend module, workflows, API routes, and panel UI — installed as **source code** into your project. This tutorial installs the `reviews` block and follows it across every surface it touches.
+
+<Info>
+  **Blocks are copied, not installed as dependencies.** `add` writes the block's source files into your project via the aliases in `blocks.json` — you own and can edit every file afterwards. Updates are opt-in through `diff` and `add --overwrite`. When you outgrow the catalog, [build your own block](/rc/resources/tutorials/build-a-block).
+</Info>
+
+## Goal
+
+Install reviews as a block and see it running everywhere it appears.
+
+## Install the block
+
+<Steps>
+  <Step title="Discover the block">
+    Search the registry and inspect what the block ships before installing:
+
+    ```bash
+    bunx @mercurjs/cli@rc search --query reviews
+    bunx @mercurjs/cli@rc view reviews
+    ```
+
+    `view` lists the block's files by target (API, admin, vendor) and its dependencies.
+  </Step>
+  <Step title="Install it">
+    ```bash
+    bunx @mercurjs/cli@rc add reviews
+    ```
+
+    The CLI copies the source into the directories mapped by your `blocks.json` aliases and prints the block's post-install instructions — module registration, middlewares, migrations.
+  </Step>
+  <Step title="Run migrations and codegen">
+    The block introduced a reviews module, so generate and run its migrations, then refresh the typed route map:
+
+    ```bash
+    cd packages/api
+    bunx medusa db:generate reviews
+    bunx medusa db:migrate
+    bunx @mercurjs/cli@rc codegen
+    ```
+  </Step>
+  <Step title="See it live">
+    Start the project — reviews now appear in the admin panel (moderation), the vendor portal (per-seller reviews), and the Store API (customer-facing review routes).
+  </Step>
+</Steps>
+
+## Verify
+
+1. The block's files exist in your repo under the alias-mapped paths.
+2. Migrations ran cleanly and the API boots.
+3. The admin and vendor panels show their reviews pages; the store review endpoints respond.
+4. `bunx @mercurjs/cli@rc diff reviews` reports no drift from the registry.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="What if I've already modified files the block wants to write?">
+    The CLI asks before overwriting existing files (or force it with `--overwrite`). If you've customized a page the block also ships, merge by hand — you're merging source, not resolving package versions.
+  </Accordion>
+  <Accordion title="How do I update a block later?">
+    `bunx @mercurjs/cli@rc diff reviews` shows what changed in the registry since you installed. Take updates with `add reviews --overwrite`, re-applying any local edits afterwards.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Add a custom panel page" href="/rc/resources/tutorials/custom-panel-page" />
+  <Card title="Build your own block" href="/rc/resources/tutorials/build-a-block" />
+</CardGroup>

package/content/resources/tutorials/attributes-and-variant-axes.mdx

@@ -0,0 +1,111 @@
+---
+title: "Create attributes and variant axes"
+description: "Build the attribute catalog: a filterable attribute, a variant axis backed by a native product option, and an inline product-scoped axis."
+---
+
+Attributes give the shared catalog structured, typed data — and for `multi_select` attributes, they can drive variant generation. This tutorial sets up the two kinds that matter most: a plain filterable attribute and a **variant axis**, which under the hood is a native Medusa global product option.
+
+<Warning>
+  This is a release-candidate feature built on Medusa's global product options (Medusa 2.16 preview). Details may still shift before the stable release.
+</Warning>
+
+<Info>
+  **A variant axis IS a product option.** Attributes marked `is_variant_axis` aren't a parallel system bolted onto products — each one mirrors one-to-one onto a Medusa `ProductOption` and its values. Variants are then built with Medusa's standard machinery (`variants[].options`), exactly as in a plain Medusa project. Non-axis attributes never become options; they attach as plain value links. This is why only `multi_select` attributes can be axes — an axis needs an enumerable set of values to combine into variants.
+</Info>
+
+## What you'll build
+
+- A global `Material` attribute (multi-select, filterable) used for storefront filtering.
+- A global `Color` variant axis shared across the catalog.
+- An inline, product-scoped `Fit` axis created on the fly from a product form.
+
+## Global vs product-scoped
+
+| Kind | Backed by | Appears in the global catalog? | Use for |
+|------|-----------|-------------------------------|---------|
+| Global attribute | Shared `ProductOption` (when axis) or value links | Yes | Data every product can use — Material, Color, Condition |
+| Product-scoped attribute | Exclusive, product-owned option (when axis) | No | One-off fields or axes for a single product |
+
+## Build the attribute catalog
+
+<Steps>
+  <Step title="Create a filterable attribute">
+    In the Admin Panel, the operator owns the attribute catalog. Create **Material** as a global `multi_select` attribute with values like Cotton, Wool, Linen, and turn on `is_filterable`. Global attributes (`product_id = null`) can be attached to any product and linked to categories so the right attributes surface for the right product types.
+
+    Since it's not a variant axis, Material describes the product — it will never generate variants.
+  </Step>
+  <Step title="Create a variant axis">
+    Create **Color** the same way, but enable `is_variant_axis`. This is only allowed for `multi_select` attributes — the platform rejects the flag on any other type.
+
+    Because Color is a **global** axis, it's backed by one shared product option. Every product that uses it links to that option, restricted to the subset of values the product actually offers — so "Color" means the same thing across the whole catalog, while one product can offer only Red and Blue.
+  </Step>
+  <Step title="Attach attributes to a product">
+    Products manage attributes through one **batch** endpoint that adds, removes, and updates in a single request:
+
+    ```bash
+    curl -X POST "http://localhost:9000/vendor/products/prod_123/attributes/batch" \
+      -H "Authorization: Bearer <token>" \
+      -H "Content-Type: application/json" \
+      -d '{
+        "add": [
+          { "id": "pattr_material", "value_ids": ["pattrval_cotton"] },
+          { "id": "pattr_color", "value_ids": ["pattrval_red", "pattrval_blue"] }
+        ]
+      }'
+    ```
+
+    At product create time, the same entry shape is passed as a unified `attributes[]` array. Because Color is an axis, selecting Red and Blue makes them available as variant options — variants are then defined with standard Medusa `variants[].options` mapping `"Color"` to `"Red"` or `"Blue"`.
+  </Step>
+  <Step title="Add an inline product-scoped axis">
+    Sometimes one product needs an axis that doesn't belong in the shared catalog. Define it **inline** by `title` instead of referencing an `id`:
+
+    ```bash
+    curl -X POST "http://localhost:9000/vendor/products/prod_123/attributes/batch" \
+      -H "Authorization: Bearer <token>" \
+      -H "Content-Type: application/json" \
+      -d '{
+        "add": [
+          { "title": "Fit", "values": ["Slim", "Regular"], "is_variant_axis": true }
+        ]
+      }'
+    ```
+
+    This creates a product-scoped attribute on the fly, backed by an **exclusive**, product-owned option. It won't appear in the global attribute list — it belongs to this product alone.
+  </Step>
+</Steps>
+
+<Note>
+  Attribute changes on products submitted by vendors flow through the same [change-request pipeline](/rc/learn/product-requests) as other product edits — `ATTRIBUTE_ADD` / `ATTRIBUTE_UPDATE` / `ATTRIBUTE_REMOVE` actions the operator reviews.
+</Note>
+
+## Verify
+
+1. **Material** and **Color** appear in the Admin Panel's attribute catalog; **Fit** does not (it's product-scoped).
+2. The product detail shows Material as descriptive data and Color/Fit as variant axes.
+3. The product's variants combine the selected Color and Fit values, built from real product options.
+4. The Store API exposes Material for filtering on product listings (`is_filterable`).
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="Why can't a text or toggle attribute be a variant axis?">
+    An axis needs an enumerable, finite value set to combine into variants — Red/Blue × Slim/Regular. Free text has no enumerable values, and a toggle's two fixed values rarely describe purchasable variations. Only `multi_select` qualifies, and the platform enforces it.
+  </Accordion>
+  <Accordion title="What's the difference between a value link and an option?">
+    Non-axis attributes attach to a product as plain **value links** — descriptive data for display and filtering. Axis attributes are mirrored onto real Medusa **product options**, which participate in variant generation. Same authoring UI, structurally different underneath.
+  </Accordion>
+  <Accordion title="Can I promote a product-scoped attribute to a global one later?">
+    Not automatically — a product-scoped axis is backed by an exclusive option owned by that product. Create the global attribute in the catalog and re-attach products to it; treat inline attributes as intentionally local.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Product Attributes" href="/rc/learn/attributes">
+    Types, fields, and the full attribute-to-option mapping.
+  </Card>
+  <Card title="Master products & offers" href="/rc/resources/tutorials/master-products-and-offers">
+    How sellers list against the variants your axes generate.
+  </Card>
+</CardGroup>