Skip to content

The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.

docs: rewrite platform module docs and add module figures (#1680)

Viktor Holik85e69645f1c7
diff --git a/apps/docs/figures/attribute-overview.mjs b/apps/docs/figures/attribute-overview.mjs
new file mode 100644
index 000000000..8ed205932
--- /dev/null
+++ b/apps/docs/figures/attribute-overview.mjs
@@ -0,0 +1,88 @@
+export default {
+ name: "attribute-overview",
+ width: 1040,
+ height: 640,
+ alt: "The global attribute catalog lists Size, Material, Thread count, Gift wrap, and Care with their types, and Size is the one variant axis, backed by the global Medusa product option Size behind it.",
+ draw(f) {
+ f.tiles({ seed: 7 })
+ f.cascade({ x: 40, y: 150, w: 900, h: 451 }, [
+ (p) => {
+ p.header({
+ marker: "mid",
+ title: "Product options",
+ tabs: ["Global", "Exclusive"],
+ note: "opt",
+ })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Title", w: 300 },
+ { label: "Values", w: 300 },
+ { label: "is_exclusive", w: 236, align: "right" },
+ ],
+ rows: [
+ ["Size", "S, M, L", { text: "false", tone: "mid" }],
+ ],
+ })
+ },
+ (p) => {
+ p.header({
+ marker: "violet",
+ title: "Attributes",
+ tabs: ["Global", "Inline"],
+ note: "pattr",
+ })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Name", w: 200 },
+ { label: "Type", w: 190 },
+ { label: "Axis", w: 110 },
+ { label: "Filterable", w: 140 },
+ { label: "Values", w: 196, align: "right" },
+ ],
+ rows: [
+ {
+ accent: true,
+ cells: [
+ "Size",
+ "multi_select",
+ { toggle: true },
+ { toggle: true },
+ "S, M, L",
+ ],
+ },
+ [
+ "Material",
+ { text: "single_select", tone: "text" },
+ { toggle: false },
+ { toggle: true },
+ { text: "Cotton, Linen", tone: "mid" },
+ ],
+ [
+ "Thread count",
+ { text: "unit", tone: "text" },
+ { toggle: false },
+ { toggle: false },
+ "",
+ ],
+ [
+ "Gift wrap",
+ { text: "toggle", tone: "text" },
+ { toggle: false },
+ { toggle: false },
+ { text: "true, false", tone: "mid" },
+ ],
+ [
+ "Care",
+ { text: "text", tone: "text" },
+ { toggle: false },
+ { toggle: false },
+ "",
+ ],
+ ],
+ })
+ },
+ ])
+ },
+}
diff --git a/apps/docs/figures/attribute-variant-axis.mjs b/apps/docs/figures/attribute-variant-axis.mjs
new file mode 100644
index 000000000..29c761653
--- /dev/null
+++ b/apps/docs/figures/attribute-variant-axis.mjs
@@ -0,0 +1,53 @@
+export default {
+ name: "attribute-variant-axis",
+ width: 1040,
+ height: 560,
+ alt: "The Size axis attribute maps each value to a Medusa option value, S to optval_01JD8Q1 and so on, and the Linen shirt selects only S and M, so its variants behind it are S and M.",
+ draw(f) {
+ f.tiles({ seed: 19 })
+ f.cascade({ x: 40, y: 150, w: 900, h: 323 }, [
+ (p) => {
+ p.header({
+ marker: "mid",
+ title: "Linen shirt",
+ tabs: ["Variants", "Attributes"],
+ note: "prod_01JD8Q1",
+ })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Variant", w: 300 },
+ { label: "Size", w: 200 },
+ { label: "SKU", w: 336, align: "right" },
+ ],
+ rows: [
+ ["Linen shirt / S", "S", { text: "SHIRT-S", tone: "mid" }],
+ ["Linen shirt / M", "M", { text: "SHIRT-M", tone: "mid" }],
+ ],
+ })
+ },
+ (p) => {
+ p.header({
+ marker: "violet",
+ title: "Size",
+ tabs: ["Values", "Products"],
+ note: "opt_01JD8Q1",
+ })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Value", w: 120 },
+ { label: "Attribute value", w: 260 },
+ { label: "Option value", w: 240 },
+ { label: "Linen shirt", w: 216, align: "right" },
+ ],
+ rows: [
+ ["S", { text: "pattrval_01JD8Q1", tone: "text" }, { text: "optval_01JD8Q1", tone: "text" }, { toggle: true }],
+ ["M", { text: "pattrval_01JD8Q2", tone: "text" }, { text: "optval_01JD8Q2", tone: "text" }, { toggle: true }],
+ ["L", { text: "pattrval_01JD8Q3", tone: "text" }, { text: "optval_01JD8Q3", tone: "text" }, { toggle: false }],
+ ],
+ })
+ },
+ ])
+ },
+}
diff --git a/apps/docs/figures/catalog-overview.mjs b/apps/docs/figures/catalog-overview.mjs
new file mode 100644
index 000000000..e34d54794
--- /dev/null
+++ b/apps/docs/figures/catalog-overview.mjs
@@ -0,0 +1,51 @@
+export default {
+ name: "catalog-overview",
+ width: 1040,
+ height: 560,
+ alt: "A product_seller link table behind a Products list of the shared catalog: each master product shows its status, the stores on its allowlist, and its offer count, with the Linen shirt restricted to ACME highlighted.",
+ draw(f) {
+ f.tiles({ seed: 7 })
+ f.cascade({ x: 40, y: 140, w: 900, h: 390 }, [
+ (p) => {
+ p.header({ marker: "hi", title: "product_seller", tabs: ["Links"], note: "Product ↔ Seller" })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "product_id", w: 420 },
+ { label: "seller_id", w: 416, align: "right" },
+ ],
+ rows: [
+ ["prod_01JD8Q1234567", "sel_01JD8Q1234567"],
+ ["prod_01JD8Q1234568", "sel_01JD8Q1234568"],
+ ],
+ })
+ },
+ (p) => {
+ p.header({
+ marker: "violet",
+ title: "Products",
+ tabs: ["All", "Proposed", "Rejected"],
+ note: "shared catalog",
+ })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Product", w: 230 },
+ { label: "Status", w: 220 },
+ { label: "Allowlist", w: 250 },
+ { label: "Offers", w: 136, align: "right" },
+ ],
+ rows: [
+ ["Aeron Chair", { chip: "Published", tone: "green" }, { text: "All stores", tone: "mid" }, "3"],
+ {
+ accent: true,
+ cells: ["Linen shirt", { chip: "Published", tone: "green" }, { tag: "ACME" }, "1"],
+ },
+ ["Desk lamp", { chip: "Proposed", tone: "amber" }, { text: "All stores", tone: "mid" }, { text: "0", tone: "mid" }],
+ ["Wool throw", { chip: "Rejected", tone: "red" }, { text: "All stores", tone: "mid" }, { text: "0", tone: "mid" }],
+ ],
+ })
+ },
+ ])
+ },
+}
diff --git a/apps/docs/figures/catalog-status-lifecycle.mjs b/apps/docs/figures/catalog-status-lifecycle.mjs
new file mode 100644
index 000000000..4eec51262
--- /dev/null
+++ b/apps/docs/figures/catalog-status-lifecycle.mjs
@@ -0,0 +1,45 @@
+export default {
+ name: "catalog-status-lifecycle",
+ width: 1040,
+ height: 540,
+ alt: "A Status transitions table: createProductsWorkflow creates a product as proposed, then confirmProductsWorkflow, rejectProductWorkflow, and requestProductChangeWorkflow move it to published, to rejected, or keep it proposed, with a product_change audit table behind.",
+ draw(f) {
+ f.tiles({ seed: 19 })
+ f.cascade({ x: 40, y: 120, w: 920, h: 392 }, [
+ (p) => {
+ p.header({ marker: "hi", title: "product_change", tabs: ["Audit"], note: "STATUS_CHANGE" })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Action", w: 400 },
+ { label: "Created by", w: 456, align: "right" },
+ ],
+ rows: [
+ ["PRODUCT_ADD", "sel_01JD8Q1234567"],
+ ["STATUS_CHANGE", "user_01JD8Q1234568"],
+ ],
+ })
+ },
+ (p) => {
+ p.header({ marker: "violet", title: "Status transitions", tabs: ["Product"], note: "ProductStatus" })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "From", w: 170 },
+ { label: "To", w: 170 },
+ { label: "Workflow", w: 516 },
+ ],
+ rows: [
+ [{ text: "new", tone: "mid" }, { chip: "Proposed", tone: "amber" }, "createProductsWorkflow"],
+ {
+ accent: true,
+ cells: [{ chip: "Proposed", tone: "amber" }, { chip: "Published", tone: "green" }, "confirmProductsWorkflow"],
+ },
+ [{ chip: "Proposed", tone: "amber" }, { chip: "Rejected", tone: "red" }, "rejectProductWorkflow"],
+ [{ chip: "Proposed", tone: "amber" }, { chip: "Proposed", tone: "amber" }, "requestProductChangeWorkflow"],
+ ],
+ })
+ },
+ ])
+ },
+}
diff --git a/apps/docs/figures/commission-overview.mjs b/apps/docs/figures/commission-overview.mjs
new file mode 100644
index 000000000..ac7dc9024
--- /dev/null
+++ b/apps/docs/figures/commission-overview.mjs
@@ -0,0 +1,73 @@
+export default {
+ name: "commission-overview",
+ width: 1040,
+ height: 610,
+ alt: "Commission rates behind the commission lines of order #100: the Linen shirt line matches the 12% acme-apparel rate for € 5.64, while the Desk lamp line and the shipping method fall back to the 10% default rate.",
+ draw(f) {
+ f.tiles({ seed: 23 })
+ f.cascade({ x: 40, y: 168, w: 900, h: 387 }, [
+ (p) => {
+ p.header({ marker: "mid", title: "Commission rates", tabs: ["Rates", "Rules", "Values"], note: "commission_rate" })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Code", w: 300 },
+ { label: "Type", w: 200 },
+ { label: "Rules", w: 160 },
+ { label: "Value", w: 176, align: "right" },
+ ],
+ rows: [
+ ["default", "percentage", "0", "10"],
+ ["acme-apparel", "percentage", "1", "12"],
+ ["flat-fee", "fixed", "1", "2.50"],
+ ],
+ })
+ },
+ (p) => {
+ p.header({
+ marker: "violet",
+ title: "Commission lines",
+ tabs: ["Items", "Shipping"],
+ note: "order #100",
+ })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Line", w: 196 },
+ { label: "Code", w: 210 },
+ { label: "Rate", w: 110, align: "right" },
+ { label: "Subtotal", w: 160, align: "right" },
+ { label: "Amount", w: 160, align: "right" },
+ ],
+ rows: [
+ {
+ accent: true,
+ cells: ["Linen shirt", "acme-apparel", "12", "€ 47.00", "€ 5.64"],
+ },
+ [
+ "Desk lamp",
+ { text: "default", tone: "mid" },
+ { text: "10", tone: "mid" },
+ { text: "€ 40.00", tone: "mid" },
+ "€ 4.00",
+ ],
+ [
+ "Shipping",
+ { text: "default", tone: "mid" },
+ { text: "10", tone: "mid" },
+ { text: "€ 5.00", tone: "mid" },
+ "€ 0.50",
+ ],
+ [
+ { text: "Total", tone: "mid" },
+ "",
+ "",
+ { text: "€ 92.00", tone: "mid" },
+ "€ 10.14",
+ ],
+ ],
+ })
+ },
+ ])
+ },
+}
diff --git a/apps/docs/figures/commission-rule-matching.mjs b/apps/docs/figures/commission-rule-matching.mjs
new file mode 100644
index 000000000..b03b0050c
--- /dev/null
+++ b/apps/docs/figures/commission-rule-matching.mjs
@@ -0,0 +1,54 @@
+export default {
+ name: "commission-rule-matching",
+ width: 1040,
+ height: 672,
+ alt: "Resolving the rate for a Linen shirt sold by ACME in the Shirts category: four enabled rates match, the acme-shirts rate scopes on two dimensions and wins, lighting does not match, and the default rate ranks last.",
+ draw(f) {
+ f.tiles({ seed: 41 })
+ f.cascade({ x: 40, y: 168, w: 900, h: 451 }, [
+ (p) => {
+ p.header({ marker: "mid", title: "Line item", tabs: ["Product", "Offer"], note: "ordli_01JD8Q" })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Dimension", w: 360 },
+ { label: "Value", w: 476, align: "right" },
+ ],
+ rows: [
+ ["product", "prod_01JD8Q"],
+ ["product_type", "ptyp_apparel"],
+ ["product_category", "pcat_shirts"],
+ ["seller", "sel_acme"],
+ ],
+ })
+ },
+ (p) => {
+ p.header({
+ marker: "violet",
+ title: "Candidate rates",
+ tabs: ["Enabled"],
+ note: "most specific wins",
+ })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Rate", w: 220 },
+ { label: "Rules", w: 290 },
+ { label: "Dims", w: 90, align: "right" },
+ { label: "Match", w: 236, align: "right" },
+ ],
+ rows: [
+ {
+ accent: true,
+ cells: ["acme-shirts", "seller · category", "2", { chip: "Wins", tone: "green" }],
+ },
+ ["acme-apparel", { text: "seller", tone: "mid" }, { text: "1", tone: "mid" }, { chip: "Match", tone: "green" }],
+ ["shirts-flat", { text: "category", tone: "mid" }, { text: "1", tone: "mid" }, { chip: "Match", tone: "green" }],
+ ["lighting", { text: "product_type", tone: "mid" }, { text: "1", tone: "mid" }, { chip: "No match", tone: "red" }],
+ ["default", { text: "none", tone: "mid" }, { text: "0", tone: "mid" }, { chip: "Match", tone: "green" }],
+ ],
+ })
+ },
+ ])
+ },
+}
diff --git a/apps/docs/figures/offer-overview.mjs b/apps/docs/figures/offer-overview.mjs
new file mode 100644
index 000000000..7d7d17c57
--- /dev/null
+++ b/apps/docs/figures/offer-overview.mjs
@@ -0,0 +1,71 @@
+export default {
+ name: "offer-overview",
+ width: 1040,
+ height: 610,
+ alt: "The Linen shirt master product sits behind an Offers list for its M variant: ACME, GLOBEX, and INITECH each list the same variant with their own SKU, condition, price, and stock.",
+ draw(f) {
+ f.tiles({ seed: 23 })
+ f.cascade({ x: 40, y: 168, w: 900, h: 387 }, [
+ (p) => {
+ p.header({
+ marker: "mid",
+ title: "Linen shirt",
+ tabs: ["Variants", "Attributes", "Media"],
+ note: "prod_01JD8Q",
+ })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Variant", w: 300 },
+ { label: "Variant id", w: 336 },
+ { label: "Offers", w: 200, align: "right" },
+ ],
+ rows: [
+ ["S", { text: "variant_01JD8Q1", tone: "mid" }, "2"],
+ ["M", { text: "variant_01JD8Q2", tone: "mid" }, "4"],
+ ["L", { text: "variant_01JD8Q3", tone: "mid" }, "1"],
+ ],
+ })
+ },
+ (p) => {
+ p.header({
+ marker: "violet",
+ title: "Offers",
+ tabs: ["Linen shirt / M"],
+ note: "variant_01JD8Q2",
+ })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Store", w: 140 },
+ { label: "SKU", w: 230 },
+ { label: "Condition", w: 170 },
+ { label: "Price", w: 150, align: "right" },
+ { label: "Stock", w: 146, align: "right" },
+ ],
+ rows: [
+ {
+ accent: true,
+ cells: ["ACME", "ACME-LS-M", { tag: "new" }, "€ 47.00", "50"],
+ },
+ [
+ "ACME",
+ "ACME-LS-M-RF",
+ { tag: "refurbished" },
+ "€ 32.00",
+ "4",
+ ],
+ ["GLOBEX", "GBX-1042", { tag: "new" }, "€ 45.00", "12"],
+ [
+ "INITECH",
+ "INI-SHIRT-M",
+ { tag: "new" },
+ "€ 49.00",
+ { text: "0", tone: "mid" },
+ ],
+ ],
+ })
+ },
+ ])
+ },
+}
diff --git a/apps/docs/figures/offer-price-rules.mjs b/apps/docs/figures/offer-price-rules.mjs
new file mode 100644
index 000000000..3c4cdf794
--- /dev/null
+++ b/apps/docs/figures/offer-price-rules.mjs
@@ -0,0 +1,69 @@
+export default {
+ name: "offer-price-rules",
+ width: 1040,
+ height: 610,
+ alt: "The shared price set of the Linen shirt M variant holds price rows for three offers; each row carries an offer_id rule, and the two rows for offer_01JD8QA form a quantity tier. Behind it, that offer links to its own inventory items.",
+ draw(f) {
+ f.tiles({ seed: 31 })
+ f.cascade({ x: 40, y: 168, w: 900, h: 387 }, [
+ (p) => {
+ p.header({
+ marker: "mid",
+ title: "Offer",
+ tabs: ["Prices", "Inventory"],
+ active: 1,
+ note: "offer_01JD8QA",
+ })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Inventory item", w: 336 },
+ { label: "Location", w: 300 },
+ { label: "Required", w: 200, align: "right" },
+ ],
+ rows: [
+ [{ text: "iitem_01JD8Q1", tone: "mid" }, "Warehouse A", "1"],
+ [{ text: "iitem_01JD8Q2", tone: "mid" }, "Warehouse A", "1"],
+ [{ text: "iitem_01JD8Q3", tone: "mid" }, "Warehouse B", "2"],
+ ],
+ })
+ },
+ (p) => {
+ p.header({
+ marker: "violet",
+ title: "Price set",
+ tabs: ["Linen shirt / M"],
+ note: "pset_01JD8Q2",
+ })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Price", w: 230 },
+ { label: "Amount", w: 150, align: "right" },
+ { label: "Min qty", w: 150, align: "right" },
+ { label: "Rule offer_id", w: 306, align: "right" },
+ ],
+ rows: [
+ {
+ accent: true,
+ cells: ["price_01JD8Q1", "€ 47.00", "", "offer_01JD8QA"],
+ },
+ ["price_01JD8Q2", "€ 42.00", "10", "offer_01JD8QA"],
+ [
+ "price_01JD8Q3",
+ "€ 32.00",
+ "",
+ { text: "offer_01JD8QB", tone: "mid" },
+ ],
+ [
+ "price_01JD8Q4",
+ "€ 45.00",
+ "",
+ { text: "offer_01JD8QC", tone: "mid" },
+ ],
+ ],
+ })
+ },
+ ])
+ },
+}
diff --git a/apps/docs/figures/order-group-overview.mjs b/apps/docs/figures/order-group-overview.mjs
new file mode 100644
index 000000000..9ad0922a4
--- /dev/null
+++ b/apps/docs/figures/order-group-overview.mjs
@@ -0,0 +1,59 @@
+export default {
+ name: "order-group-overview",
+ width: 1040,
+ height: 860,
+ alt: "The order_group record og_01JD8Q1234567 in front, with display_id 98, its customer and read-only cart link, and computed seller_count 2 and total 87.00. Behind it, the order_group_order link lists the two child orders it sums: 47.00 for ACME and 40.00 for GLOBEX.",
+ draw(f) {
+ f.tiles({ seed: 7 })
+ f.cascade({ x: 40, y: 302, w: 900, h: 514, dy: 262 }, [
+ (p) => {
+ p.header({
+ marker: "hi",
+ title: "orders",
+ tabs: ["order_group_order", "order_seller"],
+ note: "link",
+ })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "order_id", w: 330 },
+ { label: "seller.name", w: 230 },
+ { label: "current_order_total", w: 276, align: "right" },
+ ],
+ rows: [
+ ["order_01JD8Q1234568", "ACME", "47.00"],
+ ["order_01JD8Q1234569", "GLOBEX", "40.00"],
+ ["", "", ""],
+ ],
+ })
+ },
+ (p) => {
+ p.header({
+ marker: "violet",
+ title: "order_group",
+ tabs: ["Fields", "Links"],
+ note: "MercurModules.SELLER",
+ })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Field", w: 230 },
+ { label: "Type", w: 330 },
+ { label: "Value", w: 276, align: "right" },
+ ],
+ rows: [
+ ["id", { text: "id, prefix og", tone: "text" }, "og_01JD8Q1234567"],
+ ["display_id", { text: "autoincrement", tone: "text" }, "98"],
+ ["customer_id", { text: "text, nullable", tone: "text" }, "cus_01JD8Q1234567"],
+ ["cart_id", { text: "text, read-only link", tone: "text" }, "cart_01JD8Q1234567"],
+ ["seller_count", { text: "number, computed", tone: "text" }, "2"],
+ {
+ accent: true,
+ cells: ["total", { text: "bigNumber, computed", tone: "text" }, "87.00"],
+ },
+ ],
+ })
+ },
+ ])
+ },
+}
diff --git a/apps/docs/figures/payout-account-lifecycle.mjs b/apps/docs/figures/payout-account-lifecycle.mjs
new file mode 100644
index 000000000..ab6fc648c
--- /dev/null
+++ b/apps/docs/figures/payout-account-lifecycle.mjs
@@ -0,0 +1,45 @@
+export default {
+ name: "payout-account-lifecycle",
+ width: 1040,
+ height: 600,
+ alt: "A Stripe account.updated webhook behind the process-payout-for-webhook workflow. The workflow maps account.activated to the activate-payout-account step and the Active status, account.restricted to Restricted, account.rejected to Rejected, and not_supported to no change.",
+ draw(f) {
+ f.tiles({ seed: 5 })
+ f.cascade({ x: 40, y: 168, w: 900, h: 386 }, [
+ (p) => {
+ p.header({ marker: "mid", title: "Stripe webhook", tabs: ["Event", "Headers"], note: "/hooks/payout" })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Field", w: 420 },
+ { label: "Value", w: 416, align: "right" },
+ ],
+ rows: [
+ ["type", "account.updated"],
+ ["metadata.account_id", "pacc_01JD8Q1A"],
+ ],
+ })
+ },
+ (p) => {
+ p.header({ marker: "violet", title: "process-payout-for-webhook", tabs: ["Accounts", "Payouts"], note: "when(action)" })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Action", w: 270 },
+ { label: "Step", w: 330 },
+ { label: "Status", w: 236, align: "right" },
+ ],
+ rows: [
+ {
+ accent: true,
+ cells: ["account.activated", { text: "activate-payout-account", tone: "text" }, { chip: "Active", tone: "green" }],
+ },
+ ["account.restricted", { text: "restrict-payout-account", tone: "text" }, { chip: "Restricted", tone: "amber" }],
+ ["account.rejected", { text: "reject-payout-account", tone: "text" }, { chip: "Rejected", tone: "red" }],
+ [{ text: "not_supported", tone: "mid" }, { text: "no step", tone: "mid" }, { text: "unchanged", tone: "mid" }],
+ ],
+ })
+ },
+ ])
+ },
+}
diff --git a/apps/docs/figures/payout-overview.mjs b/apps/docs/figures/payout-overview.mjs
new file mode 100644
index 000000000..fc25aa3c6
--- /dev/null
+++ b/apps/docs/figures/payout-overview.mjs
@@ -0,0 +1,48 @@
+export default {
+ name: "payout-overview",
+ width: 1040,
+ height: 540,
+ alt: "A Payouts list in front of a Payout accounts list. Payout #12 for ACME is accented: an order total of € 47.00 minus € 4.70 commission gives a € 42.30 payout, marked Paid. Behind it, ACME's payout account is Active and GLOBEX's is Restricted.",
+ draw(f) {
+ f.tiles({ seed: 7 })
+ f.cascade({ x: 40, y: 168, w: 900, h: 322 }, [
+ (p) => {
+ p.header({ marker: "mid", title: "Payout accounts", tabs: ["Accounts", "Onboarding"], note: "seller_payout_account" })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Account", w: 300 },
+ { label: "Store", w: 260 },
+ { label: "Status", w: 276, align: "right" },
+ ],
+ rows: [
+ ["pacc_01JD8Q1A", "ACME", { chip: "Active", tone: "green" }],
+ ["pacc_01JD8Q2B", "GLOBEX", { chip: "Restricted", tone: "amber" }],
+ ],
+ })
+ },
+ (p) => {
+ p.header({ marker: "violet", title: "Payouts", tabs: ["All", "Paid", "Failed"], note: "create-payout" })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Payout", w: 110 },
+ { label: "Store", w: 130 },
+ { label: "Order total", w: 150, align: "right" },
+ { label: "Commission", w: 150, align: "right" },
+ { label: "Amount", w: 130, align: "right" },
+ { label: "Status", w: 166, align: "right" },
+ ],
+ rows: [
+ {
+ accent: true,
+ cells: ["#12", "ACME", "€ 47.00", { text: "€ 4.70", tone: "mid" }, "€ 42.30", { chip: "Paid", tone: "green" }],
+ },
+ ["#11", "GLOBEX", "€ 40.00", { text: "€ 4.00", tone: "mid" }, "€ 36.00", { chip: "Pending", tone: "amber" }],
+ ["#10", "ACME", "€ 21.00", { text: "€ 2.10", tone: "mid" }, "€ 18.90", { chip: "Failed", tone: "red" }],
+ ],
+ })
+ },
+ ])
+ },
+}
diff --git a/apps/docs/figures/product-edit-lifecycle.mjs b/apps/docs/figures/product-edit-lifecycle.mjs
new file mode 100644
index 000000000..828081adf
--- /dev/null
+++ b/apps/docs/figures/product-edit-lifecycle.mjs
@@ -0,0 +1,52 @@
+export default {
+ name: "product-edit-lifecycle",
+ width: 1040,
+ height: 580,
+ alt: "The ProductChangeStatus table: a change enters pending through stageProductChangeWorkflow, then confirmProductChangeWorkflow, rejectProductChangeWorkflow, or cancelProductChangeWorkflow moves it to confirmed, declined, or canceled, each emitting its own event and stamping its own actor field.",
+ draw(f) {
+ f.tiles({ seed: 19 })
+ f.cascade({ x: 40, y: 150, w: 960, h: 386, dx: -40 }, [
+ (p) => {
+ p.header({ marker: "mid", title: "prodch_01JD8Q", tabs: ["Actions", "Notes"], note: "prod_01JD8Q" })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Action", w: 260 },
+ { label: "Details", w: 380 },
+ { label: "Applied", w: 256, align: "right" },
+ ],
+ rows: [
+ ["UPDATE", "{ field: \"title\" }", { toggle: false }],
+ ["UPDATE", "{ field: \"material\" }", { toggle: false }],
+ ],
+ })
+ },
+ (p) => {
+ p.header({
+ marker: "violet",
+ title: "ProductChangeStatus",
+ tabs: ["Transitions"],
+ toggle: { on: true, label: "product_request" },
+ })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Status", w: 186 },
+ { label: "Reached by", w: 290 },
+ { label: "Event", w: 270 },
+ { label: "Stamps", w: 150, align: "right" },
+ ],
+ rows: [
+ [{ chip: "Pending", tone: "amber" }, "stageProductChangeWorkflow", { text: "product-change.created", tone: "text" }, { text: "created_by", tone: "mid" }],
+ {
+ accent: true,
+ cells: [{ chip: "Confirmed", tone: "green" }, "confirmProductChangeWorkflow", { text: "product-change.confirmed", tone: "text" }, { text: "confirmed_by", tone: "mid" }],
+ },
+ [{ chip: "Declined", tone: "red" }, "rejectProductChangeWorkflow", { text: "product-change.declined", tone: "text" }, { text: "declined_by", tone: "mid" }],
+ [{ chip: "Canceled", tone: "lo" }, "cancelProductChangeWorkflow", { text: "product-change.canceled", tone: "text" }, { text: "canceled_by", tone: "mid" }],
+ ],
+ })
+ },
+ ])
+ },
+}
diff --git a/apps/docs/figures/product-edit-overview.mjs b/apps/docs/figures/product-edit-overview.mjs
new file mode 100644
index 000000000..e7b7afe92
--- /dev/null
+++ b/apps/docs/figures/product-edit-overview.mjs
@@ -0,0 +1,53 @@
+export default {
+ name: "product-edit-overview",
+ width: 1040,
+ height: 640,
+ alt: "A product's Changes list read through product.changes: a pending UPDATE from the seller sits on top of confirmed PRODUCT_ADD, CHANGE_REQUESTED, UPDATE, and STATUS_CHANGE records that form the audit trail.",
+ draw(f) {
+ f.tiles({ seed: 7 })
+ f.cascade({ x: 40, y: 150, w: 900, h: 450 }, [
+ (p) => {
+ p.header({ marker: "green", title: "Linen shirt", tabs: ["Details", "Variants", "Attributes"], note: "prod_01JD8Q" })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Field", w: 300 },
+ { label: "Value", w: 536, align: "right" },
+ ],
+ rows: [
+ ["title", "Linen shirt"],
+ ["status", "published"],
+ ["material", "Linen"],
+ ],
+ })
+ },
+ (p) => {
+ p.header({
+ marker: "violet",
+ title: "Changes",
+ tabs: ["All", "Pending", "Audit"],
+ note: "product.changes",
+ })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Change", w: 180 },
+ { label: "Actions", w: 290 },
+ { label: "By", w: 170 },
+ { label: "Status", w: 196, align: "right" },
+ ],
+ rows: [
+ {
+ accent: true,
+ cells: ["prodch_05", "UPDATE × 2", "sel_01JD8Q", { chip: "Pending", tone: "amber" }],
+ },
+ [{ text: "prodch_04", tone: "mid" }, "STATUS_CHANGE", "user_01JD8R", { chip: "Confirmed", tone: "green" }],
+ [{ text: "prodch_03", tone: "mid" }, "UPDATE", "sel_01JD8Q", { chip: "Confirmed", tone: "green" }],
+ [{ text: "prodch_02", tone: "mid" }, "CHANGE_REQUESTED", "user_01JD8R", { chip: "Confirmed", tone: "green" }],
+ [{ text: "prodch_01", tone: "mid" }, "PRODUCT_ADD", "sel_01JD8Q", { chip: "Confirmed", tone: "green" }],
+ ],
+ })
+ },
+ ])
+ },
+}
diff --git a/apps/docs/figures/review-moderation.mjs b/apps/docs/figures/review-moderation.mjs
new file mode 100644
index 000000000..3b159edfe
--- /dev/null
+++ b/apps/docs/figures/review-moderation.mjs
@@ -0,0 +1,58 @@
+export default {
+ name: "review-moderation",
+ width: 1040,
+ height: 680,
+ alt: "Behind, a review record. In front, the changes each workflow makes: updateReviewWorkflow moves status between pending, published, and rejected in any direction, respondReviewWorkflow sets seller_note once, and deleteReviewWorkflow sets deleted_at.",
+ draw(f) {
+ f.tiles({ seed: 5 })
+ f.cascade({ x: 40, y: 196, w: 900, h: 450 }, [
+ (p) => {
+ p.header({ marker: "mid", title: "review", note: "Review module" })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Field", w: 300 },
+ { label: "Value", w: 536 },
+ ],
+ rows: [
+ ["status", { text: "pending", tone: "mid" }],
+ ["seller_note", { text: "null", tone: "mid" }],
+ ["deleted_at", { text: "null", tone: "mid" }],
+ ],
+ })
+ },
+ (p) => {
+ p.header({ marker: "violet", title: "Review changes", note: "rev_01JD8Q1234567" })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "From", w: 160 },
+ { label: "To", w: 190 },
+ { label: "Workflow", w: 300 },
+ { label: "Surface", w: 186, align: "right" },
+ ],
+ rows: [
+ {
+ accent: true,
+ cells: ["pending", { chip: "Published", tone: "green" }, "updateReviewWorkflow", "admin"],
+ },
+ ["pending", { chip: "Rejected", tone: "red" }, "updateReviewWorkflow", "admin"],
+ ["published", { chip: "Pending", tone: "amber" }, "updateReviewWorkflow", "admin"],
+ [
+ { text: "null", tone: "mid" },
+ { text: "seller_note", tone: "text" },
+ "respondReviewWorkflow",
+ "vendor, admin",
+ ],
+ [
+ { text: "null", tone: "mid" },
+ { text: "deleted_at", tone: "text" },
+ "deleteReviewWorkflow",
+ "admin, store",
+ ],
+ ],
+ })
+ },
+ ])
+ },
+}
diff --git a/apps/docs/figures/review-overview.mjs b/apps/docs/figures/review-overview.mjs
new file mode 100644
index 000000000..3fb4c85a3
--- /dev/null
+++ b/apps/docs/figures/review-overview.mjs
@@ -0,0 +1,60 @@
+export default {
+ name: "review-overview",
+ width: 1040,
+ height: 600,
+ alt: "Behind, createReviewWorkflow, which writes every review. In front, the review table: order #1001 backs a published seller review of ACME and a pending product review of the linen shirt, beside a rejected review from order #998.",
+ draw(f) {
+ f.tiles({ seed: 7 })
+ f.cascade({ x: 40, y: 196, w: 900, h: 330 }, [
+ (p) => {
+ p.header({ marker: "mid", title: "createReviewWorkflow", note: "CreateReviewDTO" })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Step", w: 300 },
+ { label: "Does", w: 536 },
+ ],
+ rows: [
+ ["validate-review", { text: "order belongs to customer, no duplicate", tone: "mid" }],
+ ["create-review", { text: "review, customer and order links", tone: "mid" }],
+ ["create-remote-links", { text: "product or seller link", tone: "mid" }],
+ ],
+ })
+ },
+ (p) => {
+ p.header({
+ marker: "violet",
+ title: "Reviews",
+ tabs: ["All", "Product", "Seller"],
+ note: "rev_",
+ })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Review", w: 110 },
+ { label: "Reference", w: 150 },
+ { label: "Target", w: 160 },
+ { label: "Order", w: 110 },
+ { label: "Rating", w: 90, align: "right" },
+ { label: "Status", w: 216, align: "right" },
+ ],
+ rows: [
+ {
+ accent: true,
+ cells: ["#1043", "seller", "ACME", "#1001", "5", { chip: "Published", tone: "green" }],
+ },
+ ["#1042", "product", "Linen shirt", "#1001", "4", { chip: "Pending", tone: "amber" }],
+ [
+ { text: "#1041", tone: "mid" },
+ { text: "product", tone: "mid" },
+ { text: "Desk lamp", tone: "mid" },
+ { text: "#998", tone: "mid" },
+ { text: "2", tone: "mid" },
+ { chip: "Rejected", tone: "red" },
+ ],
+ ],
+ })
+ },
+ ])
+ },
+}
diff --git a/apps/docs/figures/store-lifecycle.mjs b/apps/docs/figures/store-lifecycle.mjs
new file mode 100644
index 000000000..e5ad9c84d
--- /dev/null
+++ b/apps/docs/figures/store-lifecycle.mjs
@@ -0,0 +1,52 @@
+export default {
+ name: "store-lifecycle",
+ width: 1040,
+ height: 620,
+ alt: "A Status transitions table for the Seller module listing each lifecycle workflow with the status it starts from, the status it sets, and the event it emits, with the terminate row highlighted because only a suspended or pending store can be terminated.",
+ draw(f) {
+ f.tiles({ seed: 19 })
+ f.cascade({ x: 40, y: 130, w: 920, h: 451 }, [
+ (p) => {
+ p.header({ marker: "hi", title: "initech", tabs: ["Details", "Status", "Team"], active: 1, note: "sel_01JD8Q1234567" })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Field", w: 400 },
+ { label: "Value", w: 456, align: "right" },
+ ],
+ rows: [
+ ["status", "suspended"],
+ ["status_reason", "Chargeback review"],
+ ],
+ })
+ },
+ (p) => {
+ p.header({
+ marker: "violet",
+ title: "Status transitions",
+ tabs: ["Workflows", "Events"],
+ note: "SellerStatus",
+ })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Workflow", w: 270 },
+ { label: "From", w: 214 },
+ { label: "To", w: 172 },
+ { label: "Event", w: 200, align: "right" },
+ ],
+ rows: [
+ ["approveSellerWorkflow", { chip: "Pending approval", tone: "amber" }, { chip: "Open", tone: "green" }, { text: "seller.approved", tone: "mid" }],
+ ["suspendSellerWorkflow", { chip: "Open", tone: "green" }, { chip: "Suspended", tone: "red" }, { text: "seller.suspended", tone: "mid" }],
+ ["unsuspendSellerWorkflow", { chip: "Suspended", tone: "red" }, { chip: "Open", tone: "green" }, { text: "seller.unsuspended", tone: "mid" }],
+ {
+ accent: true,
+ cells: ["terminateSellerWorkflow", { chip: "Suspended", tone: "red" }, { chip: "Terminated", tone: "lo" }, { text: "seller.terminated", tone: "mid" }],
+ },
+ ["unterminateSellerWorkflow", { chip: "Terminated", tone: "lo" }, { chip: "Suspended", tone: "red" }, { text: "seller.unterminated", tone: "mid" }],
+ ],
+ })
+ },
+ ])
+ },
+}
diff --git a/apps/docs/figures/store-overview.mjs b/apps/docs/figures/store-overview.mjs
new file mode 100644
index 000000000..89d00fd7a
--- /dev/null
+++ b/apps/docs/figures/store-overview.mjs
@@ -0,0 +1,60 @@
+export default {
+ name: "store-overview",
+ width: 1040,
+ height: 560,
+ alt: "A Stores list from the Seller module showing four stores, each with its status, currency, member count, and premium flag, in front of the Team panel for acme-supplies with three members and their seller roles.",
+ draw(f) {
+ f.tiles({ seed: 7 })
+ f.cascade({ x: 40, y: 130, w: 900, h: 387 }, [
+ (p) => {
+ p.header({ marker: "hi", title: "Team", tabs: ["Members", "Invites"], note: "acme-supplies" })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Email", w: 300 },
+ { label: "Role", w: 400 },
+ { label: "Owner", w: 136, align: "right" },
+ ],
+ rows: [
+ ["[email protected]", "role_seller_administration", { toggle: true }],
+ ["[email protected]", "role_seller_order_management", { toggle: false }],
+ ["[email protected]", "role_seller_accounting", { toggle: false }],
+ ],
+ })
+ },
+ (p) => {
+ p.header({
+ marker: "violet",
+ title: "Stores",
+ tabs: ["All", "Pending", "Suspended"],
+ note: "MercurModules.SELLER",
+ })
+ p.table({
+ y: 76,
+ columns: [
+ { label: "Handle", w: 220 },
+ { label: "Status", w: 236 },
+ { label: "Currency", w: 130 },
+ { label: "Members", w: 120, align: "right" },
+ { label: "Premium", w: 130, align: "right" },
+ ],
+ rows: [
+ {
+ accent: true,
+ cells: ["acme-supplies", { chip: "Open", tone: "green" }, "usd", "3", { toggle: true }],
+ },
+ ["globex", { chip: "Pending approval", tone: "amber" }, "eur", "1", { toggle: false }],
+ ["initech", { chip: "Suspended", tone: "red" }, "usd", "2", { toggle: false }],
+ [
+ { text: "hooli", tone: "mid" },
+ { chip: "Terminated", tone: "lo" },
+ { text: "gbp", tone: "mid" },
+ { text: "1", tone: "mid" },
+ { toggle: false },
+ ],
+ ],
+ })
+ },
+ ])
+ },
+}
diff --git a/apps/docs/images/figures/attribute-overview-dark.svg b/apps/docs/images/figures/attribute-overview-dark.svg
new file mode 100644
index 000000000..d41b4721a
--- /dev/null
+++ b/apps/docs/images/figures/attribute-overview-dark.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="640" viewBox="0 0 1040 640" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="The global attribute catalog lists Size, Material, Thread count, Gift wrap, and Care with their types, and Size is the one variant axis, backed by the global Medusa product option Size behind it.">
+<title>The global attribute catalog lists Size, Material, Thread count, Gift wrap, and Care with their types, and Size is the one variant axis, backed by the global Medusa product option Size behind it.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000000" flood-opacity="0.55"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#2c2737"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="451"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="451"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="-88" width="88" height="88" fill="#1d1926"/><rect x="1056" y="-88" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="-88" y="0" width="88" height="88" fill="#1d1926"/><rect x="-88" y="0" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="0.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="352" y="0" width="88" height="88" fill="#1d1926"/><rect x="352" y="0" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="1056.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="-87.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="0.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88" y="176" width="88" height="88" fill="url(#dt)"/><rect x="616" y="176" width="88" height="88" fill="url(#dt)"/><rect x="264" y="264" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="352.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616" y="352" width="88" height="88" fill="url(#dt)"/><rect x="968" y="352" width="88" height="88" fill="#1d1926"/><rect x="968" y="352" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="176" y="440" width="88" height="88" fill="#1d1926"/><rect x="176" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="440.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528" y="440" width="88" height="88" fill="#1d1926"/><rect x="528" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="88" y="528" width="88" height="88" fill="url(#dt)"/><rect x="352" y="528" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056" y="528" width="88" height="88" fill="#1d1926"/><rect x="1056" y="528" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="0.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440" y="616" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="616" width="88" height="88" fill="url(#dt)"/><rect x="0.5" y="704.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="352.5" y="704.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528.5" y="704.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792" y="704" width="88" height="88" fill="#1d1926"/><rect x="792" y="704" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="968.5" y="704.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="100" y="64" width="900" height="451" fill="#15121d" filter="url(#sh)"/><rect x="100" y="64" width="900" height="451" fill="#15121d"/><g transform="translate(100 64)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#a1a1aa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Product options</text><line x1="232" y1="20" x2="232" y2="56" stroke="#2b2636" stroke-width="1"/><text x="264" y="44" font-size="17" fill="#f4f4f5">Global</text><rect x="246" y="73" width="97.2" height="3" fill="#f4f4f5"/><text x="365.2" y="44" font-size="17" fill="#a1a1aa">Exclusive</text><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">opt</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">TITLE</text><text x="332" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">VALUES</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">IS_EXCLUSIVE</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">Size</text><text x="332" y="167.6" font-size="16" fill="#f4f4f5">S, M, L</text><text x="868" y="167.6" font-size="16" fill="#a1a1aa" text-anchor="end">false</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/></g></g><rect x="100.5" y="64.5" width="899" height="450" fill="none" stroke="#2b2636" stroke-width="1"/><rect x="40" y="150" width="900" height="451" fill="#15121d" filter="url(#sh)"/><rect x="40" y="150" width="900" height="451" fill="#15121d"/><g transform="translate(40 150)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#a78bfa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Attributes</text><line x1="178" y1="20" x2="178" y2="56" stroke="#2b2636" stroke-width="1"/><text x="210" y="44" font-size="17" fill="#f4f4f5">Global</text><rect x="192" y="73" width="97.2" height="3" fill="#f4f4f5"/><text x="311.2" y="44" font-size="17" fill="#a1a1aa">Inline</text><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">pattr</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">NAME</text><text x="232" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">TYPE</text><text x="422" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">AXIS</text><text x="532" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">FILTERABLE</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">VALUES</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#a78bfa"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">Size</text><text x="232" y="167.6" font-size="16" fill="#f4f4f5">multi_select</text><rect x="422" y="151" width="46" height="22" fill="#6fbf68"/><rect x="446" y="154" width="19" height="16" fill="#15121d"/><rect x="532" y="151" width="46" height="22" fill="#6fbf68"/><rect x="556" y="154" width="19" height="16" fill="#15121d"/><text x="868" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">S, M, L</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">Material</text><text x="232" y="231.6" font-size="16" fill="#d4d4d8">single_select</text><rect x="422" y="215" width="46" height="22" fill="#3f3a4b"/><rect x="425" y="218" width="19" height="16" fill="#15121d"/><rect x="532" y="215" width="46" height="22" fill="#6fbf68"/><rect x="556" y="218" width="19" height="16" fill="#15121d"/><text x="868" y="231.6" font-size="16" fill="#a1a1aa" text-anchor="end">Cotton, Linen</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">Thread count</text><text x="232" y="295.6" font-size="16" fill="#d4d4d8">unit</text><rect x="422" y="279" width="46" height="22" fill="#3f3a4b"/><rect x="425" y="282" width="19" height="16" fill="#15121d"/><rect x="532" y="279" width="46" height="22" fill="#3f3a4b"/><rect x="535" y="282" width="19" height="16" fill="#15121d"/><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#f4f4f5">Gift wrap</text><text x="232" y="359.6" font-size="16" fill="#d4d4d8">toggle</text><rect x="422" y="343" width="46" height="22" fill="#3f3a4b"/><rect x="425" y="346" width="19" height="16" fill="#15121d"/><rect x="532" y="343" width="46" height="22" fill="#3f3a4b"/><rect x="535" y="346" width="19" height="16" fill="#15121d"/><text x="868" y="359.6" font-size="16" fill="#a1a1aa" text-anchor="end">true, false</text><line x1="0" y1="386" x2="900" y2="386" stroke="#221e2b" stroke-width="1"/><text x="32" y="423.6" font-size="16" fill="#f4f4f5">Care</text><text x="232" y="423.6" font-size="16" fill="#d4d4d8">text</text><rect x="422" y="407" width="46" height="22" fill="#3f3a4b"/><rect x="425" y="410" width="19" height="16" fill="#15121d"/><rect x="532" y="407" width="46" height="22" fill="#3f3a4b"/><rect x="535" y="410" width="19" height="16" fill="#15121d"/><line x1="0" y1="450" x2="900" y2="450" stroke="#221e2b" stroke-width="1"/></g></g><rect x="40.5" y="150.5" width="899" height="450" fill="none" stroke="#2b2636" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/attribute-overview-light.svg b/apps/docs/images/figures/attribute-overview-light.svg
new file mode 100644
index 000000000..2ad7d960a
--- /dev/null
+++ b/apps/docs/images/figures/attribute-overview-light.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="640" viewBox="0 0 1040 640" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="The global attribute catalog lists Size, Material, Thread count, Gift wrap, and Care with their types, and Size is the one variant axis, backed by the global Medusa product option Size behind it.">
+<title>The global attribute catalog lists Size, Material, Thread count, Gift wrap, and Care with their types, and Size is the one variant axis, backed by the global Medusa product option Size behind it.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#18181b" flood-opacity="0.07"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#d9d9de"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="451"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="451"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="-88" width="88" height="88" fill="#e4e4e7"/><rect x="1056" y="-88" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="-88" y="0" width="88" height="88" fill="#e4e4e7"/><rect x="-88" y="0" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="0.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="352" y="0" width="88" height="88" fill="#e4e4e7"/><rect x="352" y="0" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="1056.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="-87.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="0.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88" y="176" width="88" height="88" fill="url(#dt)"/><rect x="616" y="176" width="88" height="88" fill="url(#dt)"/><rect x="264" y="264" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="352.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616" y="352" width="88" height="88" fill="url(#dt)"/><rect x="968" y="352" width="88" height="88" fill="#e4e4e7"/><rect x="968" y="352" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="176" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="176" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="440.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="528" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="88" y="528" width="88" height="88" fill="url(#dt)"/><rect x="352" y="528" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056" y="528" width="88" height="88" fill="#e4e4e7"/><rect x="1056" y="528" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="0.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440" y="616" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="616" width="88" height="88" fill="url(#dt)"/><rect x="0.5" y="704.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="352.5" y="704.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528.5" y="704.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792" y="704" width="88" height="88" fill="#e4e4e7"/><rect x="792" y="704" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="968.5" y="704.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="100" y="64" width="900" height="451" fill="#ffffff" filter="url(#sh)"/><rect x="100" y="64" width="900" height="451" fill="#ffffff"/><g transform="translate(100 64)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#71717a"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Product options</text><line x1="232" y1="20" x2="232" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="264" y="44" font-size="17" fill="#18181b">Global</text><rect x="246" y="73" width="97.2" height="3" fill="#18181b"/><text x="365.2" y="44" font-size="17" fill="#71717a">Exclusive</text><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">opt</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">TITLE</text><text x="332" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">VALUES</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">IS_EXCLUSIVE</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#18181b">Size</text><text x="332" y="167.6" font-size="16" fill="#18181b">S, M, L</text><text x="868" y="167.6" font-size="16" fill="#71717a" text-anchor="end">false</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/></g></g><rect x="100.5" y="64.5" width="899" height="450" fill="none" stroke="#e4e4e7" stroke-width="1"/><rect x="40" y="150" width="900" height="451" fill="#ffffff" filter="url(#sh)"/><rect x="40" y="150" width="900" height="451" fill="#ffffff"/><g transform="translate(40 150)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#7c3aed"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Attributes</text><line x1="178" y1="20" x2="178" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="210" y="44" font-size="17" fill="#18181b">Global</text><rect x="192" y="73" width="97.2" height="3" fill="#18181b"/><text x="311.2" y="44" font-size="17" fill="#71717a">Inline</text><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">pattr</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">NAME</text><text x="232" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">TYPE</text><text x="422" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">AXIS</text><text x="532" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">FILTERABLE</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">VALUES</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#7c3aed"/><text x="32" y="167.6" font-size="16" fill="#18181b">Size</text><text x="232" y="167.6" font-size="16" fill="#18181b">multi_select</text><rect x="422" y="151" width="46" height="22" fill="#3f7d3a"/><rect x="446" y="154" width="19" height="16" fill="#ffffff"/><rect x="532" y="151" width="46" height="22" fill="#3f7d3a"/><rect x="556" y="154" width="19" height="16" fill="#ffffff"/><text x="868" y="167.6" font-size="16" fill="#18181b" text-anchor="end">S, M, L</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">Material</text><text x="232" y="231.6" font-size="16" fill="#3f3f46">single_select</text><rect x="422" y="215" width="46" height="22" fill="#d4d4d8"/><rect x="425" y="218" width="19" height="16" fill="#ffffff"/><rect x="532" y="215" width="46" height="22" fill="#3f7d3a"/><rect x="556" y="218" width="19" height="16" fill="#ffffff"/><text x="868" y="231.6" font-size="16" fill="#71717a" text-anchor="end">Cotton, Linen</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">Thread count</text><text x="232" y="295.6" font-size="16" fill="#3f3f46">unit</text><rect x="422" y="279" width="46" height="22" fill="#d4d4d8"/><rect x="425" y="282" width="19" height="16" fill="#ffffff"/><rect x="532" y="279" width="46" height="22" fill="#d4d4d8"/><rect x="535" y="282" width="19" height="16" fill="#ffffff"/><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#18181b">Gift wrap</text><text x="232" y="359.6" font-size="16" fill="#3f3f46">toggle</text><rect x="422" y="343" width="46" height="22" fill="#d4d4d8"/><rect x="425" y="346" width="19" height="16" fill="#ffffff"/><rect x="532" y="343" width="46" height="22" fill="#d4d4d8"/><rect x="535" y="346" width="19" height="16" fill="#ffffff"/><text x="868" y="359.6" font-size="16" fill="#71717a" text-anchor="end">true, false</text><line x1="0" y1="386" x2="900" y2="386" stroke="#ededf0" stroke-width="1"/><text x="32" y="423.6" font-size="16" fill="#18181b">Care</text><text x="232" y="423.6" font-size="16" fill="#3f3f46">text</text><rect x="422" y="407" width="46" height="22" fill="#d4d4d8"/><rect x="425" y="410" width="19" height="16" fill="#ffffff"/><rect x="532" y="407" width="46" height="22" fill="#d4d4d8"/><rect x="535" y="410" width="19" height="16" fill="#ffffff"/><line x1="0" y1="450" x2="900" y2="450" stroke="#ededf0" stroke-width="1"/></g></g><rect x="40.5" y="150.5" width="899" height="450" fill="none" stroke="#e4e4e7" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/attribute-variant-axis-dark.svg b/apps/docs/images/figures/attribute-variant-axis-dark.svg
new file mode 100644
index 000000000..198b95b50
--- /dev/null
+++ b/apps/docs/images/figures/attribute-variant-axis-dark.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="560" viewBox="0 0 1040 560" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="The Size axis attribute maps each value to a Medusa option value, S to optval_01JD8Q1 and so on, and the Linen shirt selects only S and M, so its variants behind it are S and M.">
+<title>The Size axis attribute maps each value to a Medusa option value, S to optval_01JD8Q1 and so on, and the Linen shirt selects only S and M, so its variants behind it are S and M.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000000" flood-opacity="0.55"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#2c2737"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="323"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="323"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="616" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="968.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="176.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264" y="0" width="88" height="88" fill="url(#dt)"/><rect x="352.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528" y="0" width="88" height="88" fill="#1d1926"/><rect x="528" y="0" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="792.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968" y="176" width="88" height="88" fill="url(#dt)"/><rect x="88.5" y="264.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="176" y="264" width="88" height="88" fill="#1d1926"/><rect x="176" y="264" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="880.5" y="264.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="352" y="352" width="88" height="88" fill="url(#dt)"/><rect x="968" y="352" width="88" height="88" fill="#1d1926"/><rect x="968" y="352" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="88" y="440" width="88" height="88" fill="#1d1926"/><rect x="88" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="440.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="704" y="440" width="88" height="88" fill="#1d1926"/><rect x="704" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="792.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528" y="528" width="88" height="88" fill="#1d1926"/><rect x="528" y="528" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="616.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="704.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880" y="528" width="88" height="88" fill="#1d1926"/><rect x="880" y="528" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="-87.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440" y="616" width="88" height="88" fill="url(#dt)"/><rect x="528.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792" y="616" width="88" height="88" fill="#1d1926"/><rect x="792" y="616" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="1056" y="616" width="88" height="88" fill="#1d1926"/><rect x="1056" y="616" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="100" y="64" width="900" height="323" fill="#15121d" filter="url(#sh)"/><rect x="100" y="64" width="900" height="323" fill="#15121d"/><g transform="translate(100 64)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#a1a1aa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Linen shirt</text><line x1="188.8" y1="20" x2="188.8" y2="56" stroke="#2b2636" stroke-width="1"/><text x="220.8" y="44" font-size="17" fill="#f4f4f5">Variants</text><rect x="202.8" y="73" width="117.6" height="3" fill="#f4f4f5"/><text x="342.4" y="44" font-size="17" fill="#a1a1aa">Attributes</text><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">prod_01JD8Q1</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">VARIANT</text><text x="332" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">SIZE</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">SKU</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">Linen shirt / S</text><text x="332" y="167.6" font-size="16" fill="#f4f4f5">S</text><text x="868" y="167.6" font-size="16" fill="#a1a1aa" text-anchor="end">SHIRT-S</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">Linen shirt / M</text><text x="332" y="231.6" font-size="16" fill="#f4f4f5">M</text><text x="868" y="231.6" font-size="16" fill="#a1a1aa" text-anchor="end">SHIRT-M</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/></g></g><rect x="100.5" y="64.5" width="899" height="322" fill="none" stroke="#2b2636" stroke-width="1"/><rect x="40" y="150" width="900" height="323" fill="#15121d" filter="url(#sh)"/><rect x="40" y="150" width="900" height="323" fill="#15121d"/><g transform="translate(40 150)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#a78bfa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Size</text><line x1="113.2" y1="20" x2="113.2" y2="56" stroke="#2b2636" stroke-width="1"/><text x="145.2" y="44" font-size="17" fill="#f4f4f5">Values</text><rect x="127.2" y="73" width="97.2" height="3" fill="#f4f4f5"/><text x="246.4" y="44" font-size="17" fill="#a1a1aa">Products</text><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">opt_01JD8Q1</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">VALUE</text><text x="152" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">ATTRIBUTE VALUE</text><text x="412" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">OPTION VALUE</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">LINEN SHIRT</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">S</text><text x="152" y="167.6" font-size="16" fill="#d4d4d8">pattrval_01JD8Q1</text><text x="412" y="167.6" font-size="16" fill="#d4d4d8">optval_01JD8Q1</text><rect x="822" y="151" width="46" height="22" fill="#6fbf68"/><rect x="846" y="154" width="19" height="16" fill="#15121d"/><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">M</text><text x="152" y="231.6" font-size="16" fill="#d4d4d8">pattrval_01JD8Q2</text><text x="412" y="231.6" font-size="16" fill="#d4d4d8">optval_01JD8Q2</text><rect x="822" y="215" width="46" height="22" fill="#6fbf68"/><rect x="846" y="218" width="19" height="16" fill="#15121d"/><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">L</text><text x="152" y="295.6" font-size="16" fill="#d4d4d8">pattrval_01JD8Q3</text><text x="412" y="295.6" font-size="16" fill="#d4d4d8">optval_01JD8Q3</text><rect x="822" y="279" width="46" height="22" fill="#3f3a4b"/><rect x="825" y="282" width="19" height="16" fill="#15121d"/><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/></g></g><rect x="40.5" y="150.5" width="899" height="322" fill="none" stroke="#2b2636" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/attribute-variant-axis-light.svg b/apps/docs/images/figures/attribute-variant-axis-light.svg
new file mode 100644
index 000000000..165845b6f
--- /dev/null
+++ b/apps/docs/images/figures/attribute-variant-axis-light.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="560" viewBox="0 0 1040 560" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="The Size axis attribute maps each value to a Medusa option value, S to optval_01JD8Q1 and so on, and the Linen shirt selects only S and M, so its variants behind it are S and M.">
+<title>The Size axis attribute maps each value to a Medusa option value, S to optval_01JD8Q1 and so on, and the Linen shirt selects only S and M, so its variants behind it are S and M.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#18181b" flood-opacity="0.07"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#d9d9de"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="323"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="323"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="616" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="968.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="176.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264" y="0" width="88" height="88" fill="url(#dt)"/><rect x="352.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528" y="0" width="88" height="88" fill="#e4e4e7"/><rect x="528" y="0" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="792.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968" y="176" width="88" height="88" fill="url(#dt)"/><rect x="88.5" y="264.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="176" y="264" width="88" height="88" fill="#e4e4e7"/><rect x="176" y="264" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="880.5" y="264.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="352" y="352" width="88" height="88" fill="url(#dt)"/><rect x="968" y="352" width="88" height="88" fill="#e4e4e7"/><rect x="968" y="352" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="88" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="88" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="440.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="704" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="704" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="792.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528" y="528" width="88" height="88" fill="#e4e4e7"/><rect x="528" y="528" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="616.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="704.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880" y="528" width="88" height="88" fill="#e4e4e7"/><rect x="880" y="528" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="-87.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440" y="616" width="88" height="88" fill="url(#dt)"/><rect x="528.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792" y="616" width="88" height="88" fill="#e4e4e7"/><rect x="792" y="616" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="1056" y="616" width="88" height="88" fill="#e4e4e7"/><rect x="1056" y="616" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="100" y="64" width="900" height="323" fill="#ffffff" filter="url(#sh)"/><rect x="100" y="64" width="900" height="323" fill="#ffffff"/><g transform="translate(100 64)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#71717a"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Linen shirt</text><line x1="188.8" y1="20" x2="188.8" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="220.8" y="44" font-size="17" fill="#18181b">Variants</text><rect x="202.8" y="73" width="117.6" height="3" fill="#18181b"/><text x="342.4" y="44" font-size="17" fill="#71717a">Attributes</text><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">prod_01JD8Q1</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">VARIANT</text><text x="332" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">SIZE</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">SKU</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#18181b">Linen shirt / S</text><text x="332" y="167.6" font-size="16" fill="#18181b">S</text><text x="868" y="167.6" font-size="16" fill="#71717a" text-anchor="end">SHIRT-S</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">Linen shirt / M</text><text x="332" y="231.6" font-size="16" fill="#18181b">M</text><text x="868" y="231.6" font-size="16" fill="#71717a" text-anchor="end">SHIRT-M</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/></g></g><rect x="100.5" y="64.5" width="899" height="322" fill="none" stroke="#e4e4e7" stroke-width="1"/><rect x="40" y="150" width="900" height="323" fill="#ffffff" filter="url(#sh)"/><rect x="40" y="150" width="900" height="323" fill="#ffffff"/><g transform="translate(40 150)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#7c3aed"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Size</text><line x1="113.2" y1="20" x2="113.2" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="145.2" y="44" font-size="17" fill="#18181b">Values</text><rect x="127.2" y="73" width="97.2" height="3" fill="#18181b"/><text x="246.4" y="44" font-size="17" fill="#71717a">Products</text><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">opt_01JD8Q1</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">VALUE</text><text x="152" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">ATTRIBUTE VALUE</text><text x="412" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">OPTION VALUE</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">LINEN SHIRT</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#18181b">S</text><text x="152" y="167.6" font-size="16" fill="#3f3f46">pattrval_01JD8Q1</text><text x="412" y="167.6" font-size="16" fill="#3f3f46">optval_01JD8Q1</text><rect x="822" y="151" width="46" height="22" fill="#3f7d3a"/><rect x="846" y="154" width="19" height="16" fill="#ffffff"/><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">M</text><text x="152" y="231.6" font-size="16" fill="#3f3f46">pattrval_01JD8Q2</text><text x="412" y="231.6" font-size="16" fill="#3f3f46">optval_01JD8Q2</text><rect x="822" y="215" width="46" height="22" fill="#3f7d3a"/><rect x="846" y="218" width="19" height="16" fill="#ffffff"/><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">L</text><text x="152" y="295.6" font-size="16" fill="#3f3f46">pattrval_01JD8Q3</text><text x="412" y="295.6" font-size="16" fill="#3f3f46">optval_01JD8Q3</text><rect x="822" y="279" width="46" height="22" fill="#d4d4d8"/><rect x="825" y="282" width="19" height="16" fill="#ffffff"/><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/></g></g><rect x="40.5" y="150.5" width="899" height="322" fill="none" stroke="#e4e4e7" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/catalog-overview-dark.svg b/apps/docs/images/figures/catalog-overview-dark.svg
new file mode 100644
index 000000000..a1d364854
--- /dev/null
+++ b/apps/docs/images/figures/catalog-overview-dark.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="560" viewBox="0 0 1040 560" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="A product_seller link table behind a Products list of the shared catalog: each master product shows its status, the stores on its allowlist, and its offer count, with the Linen shirt restricted to ACME highlighted.">
+<title>A product_seller link table behind a Products list of the shared catalog: each master product shows its status, the stores on its allowlist, and its offer count, with the Linen shirt restricted to ACME highlighted.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000000" flood-opacity="0.55"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#2c2737"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="390"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="390"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="-88" width="88" height="88" fill="#1d1926"/><rect x="1056" y="-88" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="-88" y="0" width="88" height="88" fill="#1d1926"/><rect x="-88" y="0" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="0.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="352" y="0" width="88" height="88" fill="#1d1926"/><rect x="352" y="0" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="1056.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="-87.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="0.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88" y="176" width="88" height="88" fill="url(#dt)"/><rect x="616" y="176" width="88" height="88" fill="url(#dt)"/><rect x="264" y="264" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="352.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616" y="352" width="88" height="88" fill="url(#dt)"/><rect x="968" y="352" width="88" height="88" fill="#1d1926"/><rect x="968" y="352" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="176" y="440" width="88" height="88" fill="#1d1926"/><rect x="176" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="440.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528" y="440" width="88" height="88" fill="#1d1926"/><rect x="528" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="88" y="528" width="88" height="88" fill="url(#dt)"/><rect x="352" y="528" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056" y="528" width="88" height="88" fill="#1d1926"/><rect x="1056" y="528" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="0.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88" y="616" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792" y="616" width="88" height="88" fill="url(#dt)"/><rect x="880" y="616" width="88" height="88" fill="url(#dt)"/><rect x="1056.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="100" y="54" width="900" height="390" fill="#15121d" filter="url(#sh)"/><rect x="100" y="54" width="900" height="390" fill="#15121d"/><g transform="translate(100 54)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#f4f4f5"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">product_seller</text><line x1="221.2" y1="20" x2="221.2" y2="56" stroke="#2b2636" stroke-width="1"/><text x="253.2" y="44" font-size="17" fill="#f4f4f5">Links</text><rect x="235.2" y="73" width="87" height="3" fill="#f4f4f5"/><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">Product ↔ Seller</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">PRODUCT_ID</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">SELLER_ID</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">prod_01JD8Q1234567</text><text x="868" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">sel_01JD8Q1234567</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">prod_01JD8Q1234568</text><text x="868" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">sel_01JD8Q1234568</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/></g></g><rect x="100.5" y="54.5" width="899" height="389" fill="none" stroke="#2b2636" stroke-width="1"/><rect x="40" y="140" width="900" height="390" fill="#15121d" filter="url(#sh)"/><rect x="40" y="140" width="900" height="390" fill="#15121d"/><g transform="translate(40 140)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#a78bfa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Products</text><line x1="156.4" y1="20" x2="156.4" y2="56" stroke="#2b2636" stroke-width="1"/><text x="188.4" y="44" font-size="17" fill="#f4f4f5">All</text><rect x="170.4" y="73" width="66.6" height="3" fill="#f4f4f5"/><text x="259" y="44" font-size="17" fill="#a1a1aa">Proposed</text><text x="380.6" y="44" font-size="17" fill="#a1a1aa">Rejected</text><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">shared catalog</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">PRODUCT</text><text x="262" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">STATUS</text><text x="482" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">ALLOWLIST</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">OFFERS</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">Aeron Chair</text><rect x="262" y="146" width="130.4" height="32" fill="#1f1b29"/><rect x="274" y="157" width="10" height="10" fill="#6fbf68"/><text x="296" y="166.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">PUBLISHED</text><text x="482" y="167.6" font-size="16" fill="#a1a1aa">All stores</text><text x="868" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">3</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><rect x="0" y="194" width="3" height="64" fill="#a78bfa"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">Linen shirt</text><rect x="262" y="210" width="130.4" height="32" fill="#1f1b29"/><rect x="274" y="221" width="10" height="10" fill="#6fbf68"/><text x="296" y="230.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">PUBLISHED</text><rect x="482" y="211" width="60" height="30" fill="#1f1b29"/><text x="494" y="231.3" font-size="15" fill="#a1a1aa">ACME</text><text x="868" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">1</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">Desk lamp</text><rect x="262" y="274" width="120.8" height="32" fill="#1f1b29"/><rect x="274" y="285" width="10" height="10" fill="#f2a14b"/><text x="296" y="294.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">PROPOSED</text><text x="482" y="295.6" font-size="16" fill="#a1a1aa">All stores</text><text x="868" y="295.6" font-size="16" fill="#a1a1aa" text-anchor="end">0</text><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#f4f4f5">Wool throw</text><rect x="262" y="338" width="120.8" height="32" fill="#1f1b29"/><rect x="274" y="349" width="10" height="10" fill="#f0735a"/><text x="296" y="358.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">REJECTED</text><text x="482" y="359.6" font-size="16" fill="#a1a1aa">All stores</text><text x="868" y="359.6" font-size="16" fill="#a1a1aa" text-anchor="end">0</text><line x1="0" y1="386" x2="900" y2="386" stroke="#221e2b" stroke-width="1"/></g></g><rect x="40.5" y="140.5" width="899" height="389" fill="none" stroke="#2b2636" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/catalog-overview-light.svg b/apps/docs/images/figures/catalog-overview-light.svg
new file mode 100644
index 000000000..160347dae
--- /dev/null
+++ b/apps/docs/images/figures/catalog-overview-light.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="560" viewBox="0 0 1040 560" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="A product_seller link table behind a Products list of the shared catalog: each master product shows its status, the stores on its allowlist, and its offer count, with the Linen shirt restricted to ACME highlighted.">
+<title>A product_seller link table behind a Products list of the shared catalog: each master product shows its status, the stores on its allowlist, and its offer count, with the Linen shirt restricted to ACME highlighted.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#18181b" flood-opacity="0.07"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#d9d9de"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="390"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="390"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="-88" width="88" height="88" fill="#e4e4e7"/><rect x="1056" y="-88" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="-88" y="0" width="88" height="88" fill="#e4e4e7"/><rect x="-88" y="0" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="0.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="352" y="0" width="88" height="88" fill="#e4e4e7"/><rect x="352" y="0" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="1056.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="-87.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="0.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88" y="176" width="88" height="88" fill="url(#dt)"/><rect x="616" y="176" width="88" height="88" fill="url(#dt)"/><rect x="264" y="264" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="352.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616" y="352" width="88" height="88" fill="url(#dt)"/><rect x="968" y="352" width="88" height="88" fill="#e4e4e7"/><rect x="968" y="352" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="176" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="176" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="440.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="528" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="88" y="528" width="88" height="88" fill="url(#dt)"/><rect x="352" y="528" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056" y="528" width="88" height="88" fill="#e4e4e7"/><rect x="1056" y="528" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="0.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88" y="616" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792" y="616" width="88" height="88" fill="url(#dt)"/><rect x="880" y="616" width="88" height="88" fill="url(#dt)"/><rect x="1056.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="100" y="54" width="900" height="390" fill="#ffffff" filter="url(#sh)"/><rect x="100" y="54" width="900" height="390" fill="#ffffff"/><g transform="translate(100 54)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#18181b"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">product_seller</text><line x1="221.2" y1="20" x2="221.2" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="253.2" y="44" font-size="17" fill="#18181b">Links</text><rect x="235.2" y="73" width="87" height="3" fill="#18181b"/><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">Product ↔ Seller</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">PRODUCT_ID</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">SELLER_ID</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#18181b">prod_01JD8Q1234567</text><text x="868" y="167.6" font-size="16" fill="#18181b" text-anchor="end">sel_01JD8Q1234567</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">prod_01JD8Q1234568</text><text x="868" y="231.6" font-size="16" fill="#18181b" text-anchor="end">sel_01JD8Q1234568</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/></g></g><rect x="100.5" y="54.5" width="899" height="389" fill="none" stroke="#e4e4e7" stroke-width="1"/><rect x="40" y="140" width="900" height="390" fill="#ffffff" filter="url(#sh)"/><rect x="40" y="140" width="900" height="390" fill="#ffffff"/><g transform="translate(40 140)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#7c3aed"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Products</text><line x1="156.4" y1="20" x2="156.4" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="188.4" y="44" font-size="17" fill="#18181b">All</text><rect x="170.4" y="73" width="66.6" height="3" fill="#18181b"/><text x="259" y="44" font-size="17" fill="#71717a">Proposed</text><text x="380.6" y="44" font-size="17" fill="#71717a">Rejected</text><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">shared catalog</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">PRODUCT</text><text x="262" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">STATUS</text><text x="482" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">ALLOWLIST</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">OFFERS</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#18181b">Aeron Chair</text><rect x="262" y="146" width="130.4" height="32" fill="#f4f4f5"/><rect x="274" y="157" width="10" height="10" fill="#3f7d3a"/><text x="296" y="166.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">PUBLISHED</text><text x="482" y="167.6" font-size="16" fill="#71717a">All stores</text><text x="868" y="167.6" font-size="16" fill="#18181b" text-anchor="end">3</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><rect x="0" y="194" width="3" height="64" fill="#7c3aed"/><text x="32" y="231.6" font-size="16" fill="#18181b">Linen shirt</text><rect x="262" y="210" width="130.4" height="32" fill="#f4f4f5"/><rect x="274" y="221" width="10" height="10" fill="#3f7d3a"/><text x="296" y="230.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">PUBLISHED</text><rect x="482" y="211" width="60" height="30" fill="#f4f4f5"/><text x="494" y="231.3" font-size="15" fill="#71717a">ACME</text><text x="868" y="231.6" font-size="16" fill="#18181b" text-anchor="end">1</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">Desk lamp</text><rect x="262" y="274" width="120.8" height="32" fill="#f4f4f5"/><rect x="274" y="285" width="10" height="10" fill="#c2680c"/><text x="296" y="294.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">PROPOSED</text><text x="482" y="295.6" font-size="16" fill="#71717a">All stores</text><text x="868" y="295.6" font-size="16" fill="#71717a" text-anchor="end">0</text><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#18181b">Wool throw</text><rect x="262" y="338" width="120.8" height="32" fill="#f4f4f5"/><rect x="274" y="349" width="10" height="10" fill="#b3361f"/><text x="296" y="358.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">REJECTED</text><text x="482" y="359.6" font-size="16" fill="#71717a">All stores</text><text x="868" y="359.6" font-size="16" fill="#71717a" text-anchor="end">0</text><line x1="0" y1="386" x2="900" y2="386" stroke="#ededf0" stroke-width="1"/></g></g><rect x="40.5" y="140.5" width="899" height="389" fill="none" stroke="#e4e4e7" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/catalog-status-lifecycle-dark.svg b/apps/docs/images/figures/catalog-status-lifecycle-dark.svg
new file mode 100644
index 000000000..c9045796d
--- /dev/null
+++ b/apps/docs/images/figures/catalog-status-lifecycle-dark.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="540" viewBox="0 0 1040 540" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="A Status transitions table: createProductsWorkflow creates a product as proposed, then confirmProductsWorkflow, rejectProductWorkflow, and requestProductChangeWorkflow move it to published, to rejected, or keep it proposed, with a product_change audit table behind.">
+<title>A Status transitions table: createProductsWorkflow creates a product as proposed, then confirmProductsWorkflow, rejectProductWorkflow, and requestProductChangeWorkflow move it to published, to rejected, or keep it proposed, with a product_change audit table behind.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000000" flood-opacity="0.55"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#2c2737"/></pattern><clipPath id="c1"><rect x="0" y="0" width="920" height="392"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="920" height="392"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="616" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="968.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="176.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264" y="0" width="88" height="88" fill="url(#dt)"/><rect x="352.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528" y="0" width="88" height="88" fill="#1d1926"/><rect x="528" y="0" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="792.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968" y="176" width="88" height="88" fill="url(#dt)"/><rect x="88.5" y="264.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="176" y="264" width="88" height="88" fill="#1d1926"/><rect x="176" y="264" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="880.5" y="264.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="352" y="352" width="88" height="88" fill="url(#dt)"/><rect x="968" y="352" width="88" height="88" fill="#1d1926"/><rect x="968" y="352" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="88" y="440" width="88" height="88" fill="#1d1926"/><rect x="88" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="440.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="704" y="440" width="88" height="88" fill="#1d1926"/><rect x="704" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="792.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528" y="528" width="88" height="88" fill="#1d1926"/><rect x="528" y="528" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="616.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="704.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880" y="528" width="88" height="88" fill="#1d1926"/><rect x="880" y="528" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="-87.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88" y="616" width="88" height="88" fill="url(#dt)"/><rect x="352" y="616" width="88" height="88" fill="url(#dt)"/><rect x="440.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="704" y="616" width="88" height="88" fill="#1d1926"/><rect x="704" y="616" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="968" y="616" width="88" height="88" fill="#1d1926"/><rect x="968" y="616" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="1056" y="616" width="88" height="88" fill="url(#dt)"/><rect x="100" y="34" width="920" height="392" fill="#15121d" filter="url(#sh)"/><rect x="100" y="34" width="920" height="392" fill="#15121d"/><g transform="translate(100 34)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#f4f4f5"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">product_change</text><line x1="221.2" y1="20" x2="221.2" y2="56" stroke="#2b2636" stroke-width="1"/><text x="253.2" y="44" font-size="17" fill="#f4f4f5">Audit</text><rect x="235.2" y="73" width="87" height="3" fill="#f4f4f5"/><text x="896" y="43.3" font-size="15" fill="#71717a" text-anchor="end">STATUS_CHANGE</text><line x1="0" y1="76" x2="920" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">ACTION</text><text x="888" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">CREATED BY</text><line x1="0" y1="130" x2="920" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">PRODUCT_ADD</text><text x="888" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">sel_01JD8Q1234567</text><line x1="0" y1="194" x2="920" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">STATUS_CHANGE</text><text x="888" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">user_01JD8Q1234568</text><line x1="0" y1="258" x2="920" y2="258" stroke="#221e2b" stroke-width="1"/></g></g><rect x="100.5" y="34.5" width="919" height="391" fill="none" stroke="#2b2636" stroke-width="1"/><rect x="40" y="120" width="920" height="392" fill="#15121d" filter="url(#sh)"/><rect x="40" y="120" width="920" height="392" fill="#15121d"/><g transform="translate(40 120)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#a78bfa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Status transitions</text><line x1="264.4" y1="20" x2="264.4" y2="56" stroke="#2b2636" stroke-width="1"/><text x="296.4" y="44" font-size="17" fill="#f4f4f5">Product</text><rect x="278.4" y="73" width="107.4" height="3" fill="#f4f4f5"/><text x="896" y="43.3" font-size="15" fill="#71717a" text-anchor="end">ProductStatus</text><line x1="0" y1="76" x2="920" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">FROM</text><text x="202" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">TO</text><text x="372" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">WORKFLOW</text><line x1="0" y1="130" x2="920" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#a1a1aa">new</text><rect x="202" y="146" width="120.8" height="32" fill="#1f1b29"/><rect x="214" y="157" width="10" height="10" fill="#f2a14b"/><text x="236" y="166.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">PROPOSED</text><text x="372" y="167.6" font-size="16" fill="#f4f4f5">createProductsWorkflow</text><line x1="0" y1="194" x2="920" y2="194" stroke="#221e2b" stroke-width="1"/><rect x="0" y="194" width="3" height="64" fill="#a78bfa"/><rect x="32" y="210" width="120.8" height="32" fill="#1f1b29"/><rect x="44" y="221" width="10" height="10" fill="#f2a14b"/><text x="66" y="230.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">PROPOSED</text><rect x="202" y="210" width="130.4" height="32" fill="#1f1b29"/><rect x="214" y="221" width="10" height="10" fill="#6fbf68"/><text x="236" y="230.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">PUBLISHED</text><text x="372" y="231.6" font-size="16" fill="#f4f4f5">confirmProductsWorkflow</text><line x1="0" y1="258" x2="920" y2="258" stroke="#221e2b" stroke-width="1"/><rect x="32" y="274" width="120.8" height="32" fill="#1f1b29"/><rect x="44" y="285" width="10" height="10" fill="#f2a14b"/><text x="66" y="294.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">PROPOSED</text><rect x="202" y="274" width="120.8" height="32" fill="#1f1b29"/><rect x="214" y="285" width="10" height="10" fill="#f0735a"/><text x="236" y="294.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">REJECTED</text><text x="372" y="295.6" font-size="16" fill="#f4f4f5">rejectProductWorkflow</text><line x1="0" y1="322" x2="920" y2="322" stroke="#221e2b" stroke-width="1"/><rect x="32" y="338" width="120.8" height="32" fill="#1f1b29"/><rect x="44" y="349" width="10" height="10" fill="#f2a14b"/><text x="66" y="358.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">PROPOSED</text><rect x="202" y="338" width="120.8" height="32" fill="#1f1b29"/><rect x="214" y="349" width="10" height="10" fill="#f2a14b"/><text x="236" y="358.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">PROPOSED</text><text x="372" y="359.6" font-size="16" fill="#f4f4f5">requestProductChangeWorkflow</text><line x1="0" y1="386" x2="920" y2="386" stroke="#221e2b" stroke-width="1"/></g></g><rect x="40.5" y="120.5" width="919" height="391" fill="none" stroke="#2b2636" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/catalog-status-lifecycle-light.svg b/apps/docs/images/figures/catalog-status-lifecycle-light.svg
new file mode 100644
index 000000000..9b2c10fae
--- /dev/null
+++ b/apps/docs/images/figures/catalog-status-lifecycle-light.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="540" viewBox="0 0 1040 540" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="A Status transitions table: createProductsWorkflow creates a product as proposed, then confirmProductsWorkflow, rejectProductWorkflow, and requestProductChangeWorkflow move it to published, to rejected, or keep it proposed, with a product_change audit table behind.">
+<title>A Status transitions table: createProductsWorkflow creates a product as proposed, then confirmProductsWorkflow, rejectProductWorkflow, and requestProductChangeWorkflow move it to published, to rejected, or keep it proposed, with a product_change audit table behind.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#18181b" flood-opacity="0.07"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#d9d9de"/></pattern><clipPath id="c1"><rect x="0" y="0" width="920" height="392"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="920" height="392"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="616" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="968.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="176.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264" y="0" width="88" height="88" fill="url(#dt)"/><rect x="352.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528" y="0" width="88" height="88" fill="#e4e4e7"/><rect x="528" y="0" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="792.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968" y="176" width="88" height="88" fill="url(#dt)"/><rect x="88.5" y="264.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="176" y="264" width="88" height="88" fill="#e4e4e7"/><rect x="176" y="264" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="880.5" y="264.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="352" y="352" width="88" height="88" fill="url(#dt)"/><rect x="968" y="352" width="88" height="88" fill="#e4e4e7"/><rect x="968" y="352" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="88" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="88" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="440.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="704" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="704" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="792.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528" y="528" width="88" height="88" fill="#e4e4e7"/><rect x="528" y="528" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="616.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="704.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880" y="528" width="88" height="88" fill="#e4e4e7"/><rect x="880" y="528" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="-87.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88" y="616" width="88" height="88" fill="url(#dt)"/><rect x="352" y="616" width="88" height="88" fill="url(#dt)"/><rect x="440.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="704" y="616" width="88" height="88" fill="#e4e4e7"/><rect x="704" y="616" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="968" y="616" width="88" height="88" fill="#e4e4e7"/><rect x="968" y="616" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="1056" y="616" width="88" height="88" fill="url(#dt)"/><rect x="100" y="34" width="920" height="392" fill="#ffffff" filter="url(#sh)"/><rect x="100" y="34" width="920" height="392" fill="#ffffff"/><g transform="translate(100 34)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#18181b"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">product_change</text><line x1="221.2" y1="20" x2="221.2" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="253.2" y="44" font-size="17" fill="#18181b">Audit</text><rect x="235.2" y="73" width="87" height="3" fill="#18181b"/><text x="896" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">STATUS_CHANGE</text><line x1="0" y1="76" x2="920" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">ACTION</text><text x="888" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">CREATED BY</text><line x1="0" y1="130" x2="920" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#18181b">PRODUCT_ADD</text><text x="888" y="167.6" font-size="16" fill="#18181b" text-anchor="end">sel_01JD8Q1234567</text><line x1="0" y1="194" x2="920" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">STATUS_CHANGE</text><text x="888" y="231.6" font-size="16" fill="#18181b" text-anchor="end">user_01JD8Q1234568</text><line x1="0" y1="258" x2="920" y2="258" stroke="#ededf0" stroke-width="1"/></g></g><rect x="100.5" y="34.5" width="919" height="391" fill="none" stroke="#e4e4e7" stroke-width="1"/><rect x="40" y="120" width="920" height="392" fill="#ffffff" filter="url(#sh)"/><rect x="40" y="120" width="920" height="392" fill="#ffffff"/><g transform="translate(40 120)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#7c3aed"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Status transitions</text><line x1="264.4" y1="20" x2="264.4" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="296.4" y="44" font-size="17" fill="#18181b">Product</text><rect x="278.4" y="73" width="107.4" height="3" fill="#18181b"/><text x="896" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">ProductStatus</text><line x1="0" y1="76" x2="920" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">FROM</text><text x="202" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">TO</text><text x="372" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">WORKFLOW</text><line x1="0" y1="130" x2="920" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#71717a">new</text><rect x="202" y="146" width="120.8" height="32" fill="#f4f4f5"/><rect x="214" y="157" width="10" height="10" fill="#c2680c"/><text x="236" y="166.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">PROPOSED</text><text x="372" y="167.6" font-size="16" fill="#18181b">createProductsWorkflow</text><line x1="0" y1="194" x2="920" y2="194" stroke="#ededf0" stroke-width="1"/><rect x="0" y="194" width="3" height="64" fill="#7c3aed"/><rect x="32" y="210" width="120.8" height="32" fill="#f4f4f5"/><rect x="44" y="221" width="10" height="10" fill="#c2680c"/><text x="66" y="230.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">PROPOSED</text><rect x="202" y="210" width="130.4" height="32" fill="#f4f4f5"/><rect x="214" y="221" width="10" height="10" fill="#3f7d3a"/><text x="236" y="230.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">PUBLISHED</text><text x="372" y="231.6" font-size="16" fill="#18181b">confirmProductsWorkflow</text><line x1="0" y1="258" x2="920" y2="258" stroke="#ededf0" stroke-width="1"/><rect x="32" y="274" width="120.8" height="32" fill="#f4f4f5"/><rect x="44" y="285" width="10" height="10" fill="#c2680c"/><text x="66" y="294.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">PROPOSED</text><rect x="202" y="274" width="120.8" height="32" fill="#f4f4f5"/><rect x="214" y="285" width="10" height="10" fill="#b3361f"/><text x="236" y="294.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">REJECTED</text><text x="372" y="295.6" font-size="16" fill="#18181b">rejectProductWorkflow</text><line x1="0" y1="322" x2="920" y2="322" stroke="#ededf0" stroke-width="1"/><rect x="32" y="338" width="120.8" height="32" fill="#f4f4f5"/><rect x="44" y="349" width="10" height="10" fill="#c2680c"/><text x="66" y="358.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">PROPOSED</text><rect x="202" y="338" width="120.8" height="32" fill="#f4f4f5"/><rect x="214" y="349" width="10" height="10" fill="#c2680c"/><text x="236" y="358.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">PROPOSED</text><text x="372" y="359.6" font-size="16" fill="#18181b">requestProductChangeWorkflow</text><line x1="0" y1="386" x2="920" y2="386" stroke="#ededf0" stroke-width="1"/></g></g><rect x="40.5" y="120.5" width="919" height="391" fill="none" stroke="#e4e4e7" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/commission-overview-dark.svg b/apps/docs/images/figures/commission-overview-dark.svg
new file mode 100644
index 000000000..ac3f32655
--- /dev/null
+++ b/apps/docs/images/figures/commission-overview-dark.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="610" viewBox="0 0 1040 610" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="Commission rates behind the commission lines of order #100: the Linen shirt line matches the 12% acme-apparel rate for € 5.64, while the Desk lamp line and the shipping method fall back to the 10% default rate.">
+<title>Commission rates behind the commission lines of order #100: the Linen shirt line matches the 12% acme-apparel rate for € 5.64, while the Desk lamp line and the shipping method fall back to the 10% default rate.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000000" flood-opacity="0.55"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#2c2737"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="387"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="387"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="176" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="440" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="528.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="0" y="0" width="88" height="88" fill="#1d1926"/><rect x="0" y="0" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264" y="0" width="88" height="88" fill="url(#dt)"/><rect x="-87.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792" y="88" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="88" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528" y="176" width="88" height="88" fill="url(#dt)"/><rect x="792.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264.5" y="264.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792" y="264" width="88" height="88" fill="url(#dt)"/><rect x="968" y="264" width="88" height="88" fill="url(#dt)"/><rect x="-88" y="352" width="88" height="88" fill="#1d1926"/><rect x="-88" y="352" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="528" y="352" width="88" height="88" fill="url(#dt)"/><rect x="-88" y="440" width="88" height="88" fill="url(#dt)"/><rect x="0" y="440" width="88" height="88" fill="#1d1926"/><rect x="0" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="176.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="352.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528" y="440" width="88" height="88" fill="#1d1926"/><rect x="528" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="968.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="-88" y="528" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="704" y="528" width="88" height="88" fill="#1d1926"/><rect x="704" y="528" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="880" y="528" width="88" height="88" fill="url(#dt)"/><rect x="1056.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="176.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264" y="616" width="88" height="88" fill="#1d1926"/><rect x="264" y="616" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="352" y="616" width="88" height="88" fill="url(#dt)"/><rect x="616" y="616" width="88" height="88" fill="url(#dt)"/><rect x="968" y="616" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="616" width="88" height="88" fill="url(#dt)"/><rect x="100" y="82" width="900" height="387" fill="#15121d" filter="url(#sh)"/><rect x="100" y="82" width="900" height="387" fill="#15121d"/><g transform="translate(100 82)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#a1a1aa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Commission rates</text><line x1="242.8" y1="20" x2="242.8" y2="56" stroke="#2b2636" stroke-width="1"/><text x="274.8" y="44" font-size="17" fill="#f4f4f5">Rates</text><rect x="256.8" y="73" width="87" height="3" fill="#f4f4f5"/><text x="365.8" y="44" font-size="17" fill="#a1a1aa">Rules</text><text x="456.8" y="44" font-size="17" fill="#a1a1aa">Values</text><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">commission_rate</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">CODE</text><text x="332" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">TYPE</text><text x="532" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">RULES</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">VALUE</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">default</text><text x="332" y="167.6" font-size="16" fill="#f4f4f5">percentage</text><text x="532" y="167.6" font-size="16" fill="#f4f4f5">0</text><text x="868" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">10</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">acme-apparel</text><text x="332" y="231.6" font-size="16" fill="#f4f4f5">percentage</text><text x="532" y="231.6" font-size="16" fill="#f4f4f5">1</text><text x="868" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">12</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">flat-fee</text><text x="332" y="295.6" font-size="16" fill="#f4f4f5">fixed</text><text x="532" y="295.6" font-size="16" fill="#f4f4f5">1</text><text x="868" y="295.6" font-size="16" fill="#f4f4f5" text-anchor="end">2.50</text><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/></g></g><rect x="100.5" y="82.5" width="899" height="386" fill="none" stroke="#2b2636" stroke-width="1"/><rect x="40" y="168" width="900" height="387" fill="#15121d" filter="url(#sh)"/><rect x="40" y="168" width="900" height="387" fill="#15121d"/><g transform="translate(40 168)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#a78bfa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Commission lines</text><line x1="242.8" y1="20" x2="242.8" y2="56" stroke="#2b2636" stroke-width="1"/><text x="274.8" y="44" font-size="17" fill="#f4f4f5">Items</text><rect x="256.8" y="73" width="87" height="3" fill="#f4f4f5"/><text x="365.8" y="44" font-size="17" fill="#a1a1aa">Shipping</text><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">order #100</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">LINE</text><text x="228" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">CODE</text><text x="548" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">RATE</text><text x="708" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">SUBTOTAL</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">AMOUNT</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#a78bfa"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">Linen shirt</text><text x="228" y="167.6" font-size="16" fill="#f4f4f5">acme-apparel</text><text x="548" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">12</text><text x="708" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 47.00</text><text x="868" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 5.64</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">Desk lamp</text><text x="228" y="231.6" font-size="16" fill="#a1a1aa">default</text><text x="548" y="231.6" font-size="16" fill="#a1a1aa" text-anchor="end">10</text><text x="708" y="231.6" font-size="16" fill="#a1a1aa" text-anchor="end">€ 40.00</text><text x="868" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 4.00</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">Shipping</text><text x="228" y="295.6" font-size="16" fill="#a1a1aa">default</text><text x="548" y="295.6" font-size="16" fill="#a1a1aa" text-anchor="end">10</text><text x="708" y="295.6" font-size="16" fill="#a1a1aa" text-anchor="end">€ 5.00</text><text x="868" y="295.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 0.50</text><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#a1a1aa">Total</text><text x="708" y="359.6" font-size="16" fill="#a1a1aa" text-anchor="end">€ 92.00</text><text x="868" y="359.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 10.14</text><line x1="0" y1="386" x2="900" y2="386" stroke="#221e2b" stroke-width="1"/></g></g><rect x="40.5" y="168.5" width="899" height="386" fill="none" stroke="#2b2636" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/commission-overview-light.svg b/apps/docs/images/figures/commission-overview-light.svg
new file mode 100644
index 000000000..bc42804eb
--- /dev/null
+++ b/apps/docs/images/figures/commission-overview-light.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="610" viewBox="0 0 1040 610" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="Commission rates behind the commission lines of order #100: the Linen shirt line matches the 12% acme-apparel rate for € 5.64, while the Desk lamp line and the shipping method fall back to the 10% default rate.">
+<title>Commission rates behind the commission lines of order #100: the Linen shirt line matches the 12% acme-apparel rate for € 5.64, while the Desk lamp line and the shipping method fall back to the 10% default rate.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#18181b" flood-opacity="0.07"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#d9d9de"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="387"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="387"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="176" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="440" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="528.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="0" y="0" width="88" height="88" fill="#e4e4e7"/><rect x="0" y="0" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264" y="0" width="88" height="88" fill="url(#dt)"/><rect x="-87.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792" y="88" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="88" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528" y="176" width="88" height="88" fill="url(#dt)"/><rect x="792.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264.5" y="264.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792" y="264" width="88" height="88" fill="url(#dt)"/><rect x="968" y="264" width="88" height="88" fill="url(#dt)"/><rect x="-88" y="352" width="88" height="88" fill="#e4e4e7"/><rect x="-88" y="352" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="528" y="352" width="88" height="88" fill="url(#dt)"/><rect x="-88" y="440" width="88" height="88" fill="url(#dt)"/><rect x="0" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="0" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="176.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="352.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="528" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="968.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="-88" y="528" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="704" y="528" width="88" height="88" fill="#e4e4e7"/><rect x="704" y="528" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="880" y="528" width="88" height="88" fill="url(#dt)"/><rect x="1056.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="176.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264" y="616" width="88" height="88" fill="#e4e4e7"/><rect x="264" y="616" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="352" y="616" width="88" height="88" fill="url(#dt)"/><rect x="616" y="616" width="88" height="88" fill="url(#dt)"/><rect x="968" y="616" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="616" width="88" height="88" fill="url(#dt)"/><rect x="100" y="82" width="900" height="387" fill="#ffffff" filter="url(#sh)"/><rect x="100" y="82" width="900" height="387" fill="#ffffff"/><g transform="translate(100 82)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#71717a"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Commission rates</text><line x1="242.8" y1="20" x2="242.8" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="274.8" y="44" font-size="17" fill="#18181b">Rates</text><rect x="256.8" y="73" width="87" height="3" fill="#18181b"/><text x="365.8" y="44" font-size="17" fill="#71717a">Rules</text><text x="456.8" y="44" font-size="17" fill="#71717a">Values</text><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">commission_rate</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">CODE</text><text x="332" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">TYPE</text><text x="532" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">RULES</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">VALUE</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#18181b">default</text><text x="332" y="167.6" font-size="16" fill="#18181b">percentage</text><text x="532" y="167.6" font-size="16" fill="#18181b">0</text><text x="868" y="167.6" font-size="16" fill="#18181b" text-anchor="end">10</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">acme-apparel</text><text x="332" y="231.6" font-size="16" fill="#18181b">percentage</text><text x="532" y="231.6" font-size="16" fill="#18181b">1</text><text x="868" y="231.6" font-size="16" fill="#18181b" text-anchor="end">12</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">flat-fee</text><text x="332" y="295.6" font-size="16" fill="#18181b">fixed</text><text x="532" y="295.6" font-size="16" fill="#18181b">1</text><text x="868" y="295.6" font-size="16" fill="#18181b" text-anchor="end">2.50</text><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/></g></g><rect x="100.5" y="82.5" width="899" height="386" fill="none" stroke="#e4e4e7" stroke-width="1"/><rect x="40" y="168" width="900" height="387" fill="#ffffff" filter="url(#sh)"/><rect x="40" y="168" width="900" height="387" fill="#ffffff"/><g transform="translate(40 168)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#7c3aed"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Commission lines</text><line x1="242.8" y1="20" x2="242.8" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="274.8" y="44" font-size="17" fill="#18181b">Items</text><rect x="256.8" y="73" width="87" height="3" fill="#18181b"/><text x="365.8" y="44" font-size="17" fill="#71717a">Shipping</text><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">order #100</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">LINE</text><text x="228" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">CODE</text><text x="548" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">RATE</text><text x="708" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">SUBTOTAL</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">AMOUNT</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#7c3aed"/><text x="32" y="167.6" font-size="16" fill="#18181b">Linen shirt</text><text x="228" y="167.6" font-size="16" fill="#18181b">acme-apparel</text><text x="548" y="167.6" font-size="16" fill="#18181b" text-anchor="end">12</text><text x="708" y="167.6" font-size="16" fill="#18181b" text-anchor="end">€ 47.00</text><text x="868" y="167.6" font-size="16" fill="#18181b" text-anchor="end">€ 5.64</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">Desk lamp</text><text x="228" y="231.6" font-size="16" fill="#71717a">default</text><text x="548" y="231.6" font-size="16" fill="#71717a" text-anchor="end">10</text><text x="708" y="231.6" font-size="16" fill="#71717a" text-anchor="end">€ 40.00</text><text x="868" y="231.6" font-size="16" fill="#18181b" text-anchor="end">€ 4.00</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">Shipping</text><text x="228" y="295.6" font-size="16" fill="#71717a">default</text><text x="548" y="295.6" font-size="16" fill="#71717a" text-anchor="end">10</text><text x="708" y="295.6" font-size="16" fill="#71717a" text-anchor="end">€ 5.00</text><text x="868" y="295.6" font-size="16" fill="#18181b" text-anchor="end">€ 0.50</text><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#71717a">Total</text><text x="708" y="359.6" font-size="16" fill="#71717a" text-anchor="end">€ 92.00</text><text x="868" y="359.6" font-size="16" fill="#18181b" text-anchor="end">€ 10.14</text><line x1="0" y1="386" x2="900" y2="386" stroke="#ededf0" stroke-width="1"/></g></g><rect x="40.5" y="168.5" width="899" height="386" fill="none" stroke="#e4e4e7" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/commission-rule-matching-dark.svg b/apps/docs/images/figures/commission-rule-matching-dark.svg
new file mode 100644
index 000000000..fbea2e22c
--- /dev/null
+++ b/apps/docs/images/figures/commission-rule-matching-dark.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="672" viewBox="0 0 1040 672" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="Resolving the rate for a Linen shirt sold by ACME in the Shirts category: four enabled rates match, the acme-shirts rate scopes on two dimensions and wins, lighting does not match, and the default rate ranks last.">
+<title>Resolving the rate for a Linen shirt sold by ACME in the Shirts category: four enabled rates match, the acme-shirts rate scopes on two dimensions and wins, lighting does not match, and the default rate ranks last.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000000" flood-opacity="0.55"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#2c2737"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="451"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="451"/></clipPath></defs>
+<rect x="616" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="792.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="352" y="0" width="88" height="88" fill="url(#dt)"/><rect x="440.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056" y="0" width="88" height="88" fill="url(#dt)"/><rect x="88.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="704.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880" y="88" width="88" height="88" fill="url(#dt)"/><rect x="968.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="176.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88.5" y="264.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="-88" y="352" width="88" height="88" fill="#1d1926"/><rect x="-88" y="352" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="0" y="352" width="88" height="88" fill="url(#dt)"/><rect x="88" y="352" width="88" height="88" fill="#1d1926"/><rect x="88" y="352" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="704.5" y="352.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968" y="352" width="88" height="88" fill="#1d1926"/><rect x="968" y="352" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="264.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968" y="440" width="88" height="88" fill="url(#dt)"/><rect x="0.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88" y="616" width="88" height="88" fill="url(#dt)"/><rect x="176" y="616" width="88" height="88" fill="url(#dt)"/><rect x="264" y="616" width="88" height="88" fill="#1d1926"/><rect x="264" y="616" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="440.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="704.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="176" y="704" width="88" height="88" fill="url(#dt)"/><rect x="264" y="704" width="88" height="88" fill="url(#dt)"/><rect x="352.5" y="704.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528.5" y="704.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="704.5" y="704.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968" y="704" width="88" height="88" fill="url(#dt)"/><rect x="1056.5" y="704.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="100" y="82" width="900" height="451" fill="#15121d" filter="url(#sh)"/><rect x="100" y="82" width="900" height="451" fill="#15121d"/><g transform="translate(100 82)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#a1a1aa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Line item</text><line x1="167.2" y1="20" x2="167.2" y2="56" stroke="#2b2636" stroke-width="1"/><text x="199.2" y="44" font-size="17" fill="#f4f4f5">Product</text><rect x="181.2" y="73" width="107.4" height="3" fill="#f4f4f5"/><text x="310.6" y="44" font-size="17" fill="#a1a1aa">Offer</text><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">ordli_01JD8Q</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">DIMENSION</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">VALUE</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">product</text><text x="868" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">prod_01JD8Q</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">product_type</text><text x="868" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">ptyp_apparel</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">product_category</text><text x="868" y="295.6" font-size="16" fill="#f4f4f5" text-anchor="end">pcat_shirts</text><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#f4f4f5">seller</text><text x="868" y="359.6" font-size="16" fill="#f4f4f5" text-anchor="end">sel_acme</text><line x1="0" y1="386" x2="900" y2="386" stroke="#221e2b" stroke-width="1"/></g></g><rect x="100.5" y="82.5" width="899" height="450" fill="none" stroke="#2b2636" stroke-width="1"/><rect x="40" y="168" width="900" height="451" fill="#15121d" filter="url(#sh)"/><rect x="40" y="168" width="900" height="451" fill="#15121d"/><g transform="translate(40 168)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#a78bfa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Candidate rates</text><line x1="232" y1="20" x2="232" y2="56" stroke="#2b2636" stroke-width="1"/><text x="264" y="44" font-size="17" fill="#f4f4f5">Enabled</text><rect x="246" y="73" width="107.4" height="3" fill="#f4f4f5"/><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">most specific wins</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">RATE</text><text x="252" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">RULES</text><text x="632" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">DIMS</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">MATCH</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#a78bfa"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">acme-shirts</text><text x="252" y="167.6" font-size="16" fill="#f4f4f5">seller · category</text><text x="632" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">2</text><rect x="785.6" y="146" width="82.4" height="32" fill="#1f1b29"/><rect x="797.6" y="157" width="10" height="10" fill="#6fbf68"/><text x="819.6" y="166.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">WINS</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">acme-apparel</text><text x="252" y="231.6" font-size="16" fill="#a1a1aa">seller</text><text x="632" y="231.6" font-size="16" fill="#a1a1aa" text-anchor="end">1</text><rect x="776" y="210" width="92" height="32" fill="#1f1b29"/><rect x="788" y="221" width="10" height="10" fill="#6fbf68"/><text x="810" y="230.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">MATCH</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">shirts-flat</text><text x="252" y="295.6" font-size="16" fill="#a1a1aa">category</text><text x="632" y="295.6" font-size="16" fill="#a1a1aa" text-anchor="end">1</text><rect x="776" y="274" width="92" height="32" fill="#1f1b29"/><rect x="788" y="285" width="10" height="10" fill="#6fbf68"/><text x="810" y="294.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">MATCH</text><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#f4f4f5">lighting</text><text x="252" y="359.6" font-size="16" fill="#a1a1aa">product_type</text><text x="632" y="359.6" font-size="16" fill="#a1a1aa" text-anchor="end">1</text><rect x="747.2" y="338" width="120.8" height="32" fill="#1f1b29"/><rect x="759.2" y="349" width="10" height="10" fill="#f0735a"/><text x="781.2" y="358.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">NO MATCH</text><line x1="0" y1="386" x2="900" y2="386" stroke="#221e2b" stroke-width="1"/><text x="32" y="423.6" font-size="16" fill="#f4f4f5">default</text><text x="252" y="423.6" font-size="16" fill="#a1a1aa">none</text><text x="632" y="423.6" font-size="16" fill="#a1a1aa" text-anchor="end">0</text><rect x="776" y="402" width="92" height="32" fill="#1f1b29"/><rect x="788" y="413" width="10" height="10" fill="#6fbf68"/><text x="810" y="422.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">MATCH</text><line x1="0" y1="450" x2="900" y2="450" stroke="#221e2b" stroke-width="1"/></g></g><rect x="40.5" y="168.5" width="899" height="450" fill="none" stroke="#2b2636" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/commission-rule-matching-light.svg b/apps/docs/images/figures/commission-rule-matching-light.svg
new file mode 100644
index 000000000..88dfe94d9
--- /dev/null
+++ b/apps/docs/images/figures/commission-rule-matching-light.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="672" viewBox="0 0 1040 672" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="Resolving the rate for a Linen shirt sold by ACME in the Shirts category: four enabled rates match, the acme-shirts rate scopes on two dimensions and wins, lighting does not match, and the default rate ranks last.">
+<title>Resolving the rate for a Linen shirt sold by ACME in the Shirts category: four enabled rates match, the acme-shirts rate scopes on two dimensions and wins, lighting does not match, and the default rate ranks last.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#18181b" flood-opacity="0.07"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#d9d9de"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="451"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="451"/></clipPath></defs>
+<rect x="616" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="792.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="352" y="0" width="88" height="88" fill="url(#dt)"/><rect x="440.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056" y="0" width="88" height="88" fill="url(#dt)"/><rect x="88.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="704.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880" y="88" width="88" height="88" fill="url(#dt)"/><rect x="968.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="176.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88.5" y="264.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="-88" y="352" width="88" height="88" fill="#e4e4e7"/><rect x="-88" y="352" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="0" y="352" width="88" height="88" fill="url(#dt)"/><rect x="88" y="352" width="88" height="88" fill="#e4e4e7"/><rect x="88" y="352" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="704.5" y="352.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968" y="352" width="88" height="88" fill="#e4e4e7"/><rect x="968" y="352" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="264.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968" y="440" width="88" height="88" fill="url(#dt)"/><rect x="0.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88" y="616" width="88" height="88" fill="url(#dt)"/><rect x="176" y="616" width="88" height="88" fill="url(#dt)"/><rect x="264" y="616" width="88" height="88" fill="#e4e4e7"/><rect x="264" y="616" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="440.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="704.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="176" y="704" width="88" height="88" fill="url(#dt)"/><rect x="264" y="704" width="88" height="88" fill="url(#dt)"/><rect x="352.5" y="704.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528.5" y="704.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="704.5" y="704.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968" y="704" width="88" height="88" fill="url(#dt)"/><rect x="1056.5" y="704.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="100" y="82" width="900" height="451" fill="#ffffff" filter="url(#sh)"/><rect x="100" y="82" width="900" height="451" fill="#ffffff"/><g transform="translate(100 82)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#71717a"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Line item</text><line x1="167.2" y1="20" x2="167.2" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="199.2" y="44" font-size="17" fill="#18181b">Product</text><rect x="181.2" y="73" width="107.4" height="3" fill="#18181b"/><text x="310.6" y="44" font-size="17" fill="#71717a">Offer</text><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">ordli_01JD8Q</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">DIMENSION</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">VALUE</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#18181b">product</text><text x="868" y="167.6" font-size="16" fill="#18181b" text-anchor="end">prod_01JD8Q</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">product_type</text><text x="868" y="231.6" font-size="16" fill="#18181b" text-anchor="end">ptyp_apparel</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">product_category</text><text x="868" y="295.6" font-size="16" fill="#18181b" text-anchor="end">pcat_shirts</text><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#18181b">seller</text><text x="868" y="359.6" font-size="16" fill="#18181b" text-anchor="end">sel_acme</text><line x1="0" y1="386" x2="900" y2="386" stroke="#ededf0" stroke-width="1"/></g></g><rect x="100.5" y="82.5" width="899" height="450" fill="none" stroke="#e4e4e7" stroke-width="1"/><rect x="40" y="168" width="900" height="451" fill="#ffffff" filter="url(#sh)"/><rect x="40" y="168" width="900" height="451" fill="#ffffff"/><g transform="translate(40 168)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#7c3aed"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Candidate rates</text><line x1="232" y1="20" x2="232" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="264" y="44" font-size="17" fill="#18181b">Enabled</text><rect x="246" y="73" width="107.4" height="3" fill="#18181b"/><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">most specific wins</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">RATE</text><text x="252" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">RULES</text><text x="632" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">DIMS</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">MATCH</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#7c3aed"/><text x="32" y="167.6" font-size="16" fill="#18181b">acme-shirts</text><text x="252" y="167.6" font-size="16" fill="#18181b">seller · category</text><text x="632" y="167.6" font-size="16" fill="#18181b" text-anchor="end">2</text><rect x="785.6" y="146" width="82.4" height="32" fill="#f4f4f5"/><rect x="797.6" y="157" width="10" height="10" fill="#3f7d3a"/><text x="819.6" y="166.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">WINS</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">acme-apparel</text><text x="252" y="231.6" font-size="16" fill="#71717a">seller</text><text x="632" y="231.6" font-size="16" fill="#71717a" text-anchor="end">1</text><rect x="776" y="210" width="92" height="32" fill="#f4f4f5"/><rect x="788" y="221" width="10" height="10" fill="#3f7d3a"/><text x="810" y="230.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">MATCH</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">shirts-flat</text><text x="252" y="295.6" font-size="16" fill="#71717a">category</text><text x="632" y="295.6" font-size="16" fill="#71717a" text-anchor="end">1</text><rect x="776" y="274" width="92" height="32" fill="#f4f4f5"/><rect x="788" y="285" width="10" height="10" fill="#3f7d3a"/><text x="810" y="294.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">MATCH</text><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#18181b">lighting</text><text x="252" y="359.6" font-size="16" fill="#71717a">product_type</text><text x="632" y="359.6" font-size="16" fill="#71717a" text-anchor="end">1</text><rect x="747.2" y="338" width="120.8" height="32" fill="#f4f4f5"/><rect x="759.2" y="349" width="10" height="10" fill="#b3361f"/><text x="781.2" y="358.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">NO MATCH</text><line x1="0" y1="386" x2="900" y2="386" stroke="#ededf0" stroke-width="1"/><text x="32" y="423.6" font-size="16" fill="#18181b">default</text><text x="252" y="423.6" font-size="16" fill="#71717a">none</text><text x="632" y="423.6" font-size="16" fill="#71717a" text-anchor="end">0</text><rect x="776" y="402" width="92" height="32" fill="#f4f4f5"/><rect x="788" y="413" width="10" height="10" fill="#3f7d3a"/><text x="810" y="422.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">MATCH</text><line x1="0" y1="450" x2="900" y2="450" stroke="#ededf0" stroke-width="1"/></g></g><rect x="40.5" y="168.5" width="899" height="450" fill="none" stroke="#e4e4e7" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/offer-overview-dark.svg b/apps/docs/images/figures/offer-overview-dark.svg
new file mode 100644
index 000000000..4c3340658
--- /dev/null
+++ b/apps/docs/images/figures/offer-overview-dark.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="610" viewBox="0 0 1040 610" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="The Linen shirt master product sits behind an Offers list for its M variant: ACME, GLOBEX, and INITECH each list the same variant with their own SKU, condition, price, and stock.">
+<title>The Linen shirt master product sits behind an Offers list for its M variant: ACME, GLOBEX, and INITECH each list the same variant with their own SKU, condition, price, and stock.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000000" flood-opacity="0.55"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#2c2737"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="387"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="387"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="176" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="440" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="528.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="0" y="0" width="88" height="88" fill="#1d1926"/><rect x="0" y="0" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264" y="0" width="88" height="88" fill="url(#dt)"/><rect x="-87.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792" y="88" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="88" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528" y="176" width="88" height="88" fill="url(#dt)"/><rect x="792.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264.5" y="264.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792" y="264" width="88" height="88" fill="url(#dt)"/><rect x="968" y="264" width="88" height="88" fill="url(#dt)"/><rect x="-88" y="352" width="88" height="88" fill="#1d1926"/><rect x="-88" y="352" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="528" y="352" width="88" height="88" fill="url(#dt)"/><rect x="-88" y="440" width="88" height="88" fill="url(#dt)"/><rect x="0" y="440" width="88" height="88" fill="#1d1926"/><rect x="0" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="176.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="352.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528" y="440" width="88" height="88" fill="#1d1926"/><rect x="528" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="968.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="-88" y="528" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="704" y="528" width="88" height="88" fill="#1d1926"/><rect x="704" y="528" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="880" y="528" width="88" height="88" fill="url(#dt)"/><rect x="1056.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="176.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264" y="616" width="88" height="88" fill="#1d1926"/><rect x="264" y="616" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="352" y="616" width="88" height="88" fill="url(#dt)"/><rect x="616" y="616" width="88" height="88" fill="url(#dt)"/><rect x="968" y="616" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="616" width="88" height="88" fill="url(#dt)"/><rect x="100" y="82" width="900" height="387" fill="#15121d" filter="url(#sh)"/><rect x="100" y="82" width="900" height="387" fill="#15121d"/><g transform="translate(100 82)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#a1a1aa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Linen shirt</text><line x1="188.8" y1="20" x2="188.8" y2="56" stroke="#2b2636" stroke-width="1"/><text x="220.8" y="44" font-size="17" fill="#f4f4f5">Variants</text><rect x="202.8" y="73" width="117.6" height="3" fill="#f4f4f5"/><text x="342.4" y="44" font-size="17" fill="#a1a1aa">Attributes</text><text x="484.4" y="44" font-size="17" fill="#a1a1aa">Media</text><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">prod_01JD8Q</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">VARIANT</text><text x="332" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">VARIANT ID</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">OFFERS</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">S</text><text x="332" y="167.6" font-size="16" fill="#a1a1aa">variant_01JD8Q1</text><text x="868" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">2</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">M</text><text x="332" y="231.6" font-size="16" fill="#a1a1aa">variant_01JD8Q2</text><text x="868" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">4</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">L</text><text x="332" y="295.6" font-size="16" fill="#a1a1aa">variant_01JD8Q3</text><text x="868" y="295.6" font-size="16" fill="#f4f4f5" text-anchor="end">1</text><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/></g></g><rect x="100.5" y="82.5" width="899" height="386" fill="none" stroke="#2b2636" stroke-width="1"/><rect x="40" y="168" width="900" height="387" fill="#15121d" filter="url(#sh)"/><rect x="40" y="168" width="900" height="387" fill="#15121d"/><g transform="translate(40 168)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#a78bfa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Offers</text><line x1="134.8" y1="20" x2="134.8" y2="56" stroke="#2b2636" stroke-width="1"/><text x="166.8" y="44" font-size="17" fill="#f4f4f5">Linen shirt / M</text><rect x="148.8" y="73" width="189" height="3" fill="#f4f4f5"/><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">variant_01JD8Q2</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">STORE</text><text x="172" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">SKU</text><text x="402" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">CONDITION</text><text x="722" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">PRICE</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">STOCK</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#a78bfa"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">ACME</text><text x="172" y="167.6" font-size="16" fill="#f4f4f5">ACME-LS-M</text><rect x="402" y="147" width="51" height="30" fill="#1f1b29"/><text x="414" y="167.3" font-size="15" fill="#a1a1aa">new</text><text x="722" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 47.00</text><text x="868" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">50</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">ACME</text><text x="172" y="231.6" font-size="16" fill="#f4f4f5">ACME-LS-M-RF</text><rect x="402" y="211" width="123" height="30" fill="#1f1b29"/><text x="414" y="231.3" font-size="15" fill="#a1a1aa">refurbished</text><text x="722" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 32.00</text><text x="868" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">4</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">GLOBEX</text><text x="172" y="295.6" font-size="16" fill="#f4f4f5">GBX-1042</text><rect x="402" y="275" width="51" height="30" fill="#1f1b29"/><text x="414" y="295.3" font-size="15" fill="#a1a1aa">new</text><text x="722" y="295.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 45.00</text><text x="868" y="295.6" font-size="16" fill="#f4f4f5" text-anchor="end">12</text><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#f4f4f5">INITECH</text><text x="172" y="359.6" font-size="16" fill="#f4f4f5">INI-SHIRT-M</text><rect x="402" y="339" width="51" height="30" fill="#1f1b29"/><text x="414" y="359.3" font-size="15" fill="#a1a1aa">new</text><text x="722" y="359.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 49.00</text><text x="868" y="359.6" font-size="16" fill="#a1a1aa" text-anchor="end">0</text><line x1="0" y1="386" x2="900" y2="386" stroke="#221e2b" stroke-width="1"/></g></g><rect x="40.5" y="168.5" width="899" height="386" fill="none" stroke="#2b2636" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/offer-overview-light.svg b/apps/docs/images/figures/offer-overview-light.svg
new file mode 100644
index 000000000..4b86a545d
--- /dev/null
+++ b/apps/docs/images/figures/offer-overview-light.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="610" viewBox="0 0 1040 610" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="The Linen shirt master product sits behind an Offers list for its M variant: ACME, GLOBEX, and INITECH each list the same variant with their own SKU, condition, price, and stock.">
+<title>The Linen shirt master product sits behind an Offers list for its M variant: ACME, GLOBEX, and INITECH each list the same variant with their own SKU, condition, price, and stock.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#18181b" flood-opacity="0.07"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#d9d9de"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="387"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="387"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="176" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="440" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="528.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="0" y="0" width="88" height="88" fill="#e4e4e7"/><rect x="0" y="0" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264" y="0" width="88" height="88" fill="url(#dt)"/><rect x="-87.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792" y="88" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="88" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528" y="176" width="88" height="88" fill="url(#dt)"/><rect x="792.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264.5" y="264.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792" y="264" width="88" height="88" fill="url(#dt)"/><rect x="968" y="264" width="88" height="88" fill="url(#dt)"/><rect x="-88" y="352" width="88" height="88" fill="#e4e4e7"/><rect x="-88" y="352" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="528" y="352" width="88" height="88" fill="url(#dt)"/><rect x="-88" y="440" width="88" height="88" fill="url(#dt)"/><rect x="0" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="0" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="176.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="352.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="528" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="968.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="-88" y="528" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="704" y="528" width="88" height="88" fill="#e4e4e7"/><rect x="704" y="528" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="880" y="528" width="88" height="88" fill="url(#dt)"/><rect x="1056.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="176.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264" y="616" width="88" height="88" fill="#e4e4e7"/><rect x="264" y="616" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="352" y="616" width="88" height="88" fill="url(#dt)"/><rect x="616" y="616" width="88" height="88" fill="url(#dt)"/><rect x="968" y="616" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="616" width="88" height="88" fill="url(#dt)"/><rect x="100" y="82" width="900" height="387" fill="#ffffff" filter="url(#sh)"/><rect x="100" y="82" width="900" height="387" fill="#ffffff"/><g transform="translate(100 82)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#71717a"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Linen shirt</text><line x1="188.8" y1="20" x2="188.8" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="220.8" y="44" font-size="17" fill="#18181b">Variants</text><rect x="202.8" y="73" width="117.6" height="3" fill="#18181b"/><text x="342.4" y="44" font-size="17" fill="#71717a">Attributes</text><text x="484.4" y="44" font-size="17" fill="#71717a">Media</text><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">prod_01JD8Q</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">VARIANT</text><text x="332" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">VARIANT ID</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">OFFERS</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#18181b">S</text><text x="332" y="167.6" font-size="16" fill="#71717a">variant_01JD8Q1</text><text x="868" y="167.6" font-size="16" fill="#18181b" text-anchor="end">2</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">M</text><text x="332" y="231.6" font-size="16" fill="#71717a">variant_01JD8Q2</text><text x="868" y="231.6" font-size="16" fill="#18181b" text-anchor="end">4</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">L</text><text x="332" y="295.6" font-size="16" fill="#71717a">variant_01JD8Q3</text><text x="868" y="295.6" font-size="16" fill="#18181b" text-anchor="end">1</text><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/></g></g><rect x="100.5" y="82.5" width="899" height="386" fill="none" stroke="#e4e4e7" stroke-width="1"/><rect x="40" y="168" width="900" height="387" fill="#ffffff" filter="url(#sh)"/><rect x="40" y="168" width="900" height="387" fill="#ffffff"/><g transform="translate(40 168)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#7c3aed"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Offers</text><line x1="134.8" y1="20" x2="134.8" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="166.8" y="44" font-size="17" fill="#18181b">Linen shirt / M</text><rect x="148.8" y="73" width="189" height="3" fill="#18181b"/><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">variant_01JD8Q2</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">STORE</text><text x="172" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">SKU</text><text x="402" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">CONDITION</text><text x="722" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">PRICE</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">STOCK</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#7c3aed"/><text x="32" y="167.6" font-size="16" fill="#18181b">ACME</text><text x="172" y="167.6" font-size="16" fill="#18181b">ACME-LS-M</text><rect x="402" y="147" width="51" height="30" fill="#f4f4f5"/><text x="414" y="167.3" font-size="15" fill="#71717a">new</text><text x="722" y="167.6" font-size="16" fill="#18181b" text-anchor="end">€ 47.00</text><text x="868" y="167.6" font-size="16" fill="#18181b" text-anchor="end">50</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">ACME</text><text x="172" y="231.6" font-size="16" fill="#18181b">ACME-LS-M-RF</text><rect x="402" y="211" width="123" height="30" fill="#f4f4f5"/><text x="414" y="231.3" font-size="15" fill="#71717a">refurbished</text><text x="722" y="231.6" font-size="16" fill="#18181b" text-anchor="end">€ 32.00</text><text x="868" y="231.6" font-size="16" fill="#18181b" text-anchor="end">4</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">GLOBEX</text><text x="172" y="295.6" font-size="16" fill="#18181b">GBX-1042</text><rect x="402" y="275" width="51" height="30" fill="#f4f4f5"/><text x="414" y="295.3" font-size="15" fill="#71717a">new</text><text x="722" y="295.6" font-size="16" fill="#18181b" text-anchor="end">€ 45.00</text><text x="868" y="295.6" font-size="16" fill="#18181b" text-anchor="end">12</text><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#18181b">INITECH</text><text x="172" y="359.6" font-size="16" fill="#18181b">INI-SHIRT-M</text><rect x="402" y="339" width="51" height="30" fill="#f4f4f5"/><text x="414" y="359.3" font-size="15" fill="#71717a">new</text><text x="722" y="359.6" font-size="16" fill="#18181b" text-anchor="end">€ 49.00</text><text x="868" y="359.6" font-size="16" fill="#71717a" text-anchor="end">0</text><line x1="0" y1="386" x2="900" y2="386" stroke="#ededf0" stroke-width="1"/></g></g><rect x="40.5" y="168.5" width="899" height="386" fill="none" stroke="#e4e4e7" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/offer-price-rules-dark.svg b/apps/docs/images/figures/offer-price-rules-dark.svg
new file mode 100644
index 000000000..b444ca139
--- /dev/null
+++ b/apps/docs/images/figures/offer-price-rules-dark.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="610" viewBox="0 0 1040 610" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="The shared price set of the Linen shirt M variant holds price rows for three offers; each row carries an offer_id rule, and the two rows for offer_01JD8QA form a quantity tier. Behind it, that offer links to its own inventory items.">
+<title>The shared price set of the Linen shirt M variant holds price rows for three offers; each row carries an offer_id rule, and the two rows for offer_01JD8QA form a quantity tier. Behind it, that offer links to its own inventory items.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000000" flood-opacity="0.55"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#2c2737"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="387"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="387"/></clipPath></defs>
+<rect x="176.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="0" y="0" width="88" height="88" fill="#1d1926"/><rect x="0" y="0" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="616.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="704" y="0" width="88" height="88" fill="url(#dt)"/><rect x="792.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440" y="88" width="88" height="88" fill="#1d1926"/><rect x="440" y="88" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="528.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="0" y="176" width="88" height="88" fill="#1d1926"/><rect x="0" y="176" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="-88" y="264" width="88" height="88" fill="url(#dt)"/><rect x="176" y="264" width="88" height="88" fill="#1d1926"/><rect x="176" y="264" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="264" y="264" width="88" height="88" fill="#1d1926"/><rect x="264" y="264" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="880" y="264" width="88" height="88" fill="url(#dt)"/><rect x="88" y="352" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="352.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="704" y="352" width="88" height="88" fill="#1d1926"/><rect x="704" y="352" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="880.5" y="352.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="0.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056" y="440" width="88" height="88" fill="url(#dt)"/><rect x="-88" y="528" width="88" height="88" fill="#1d1926"/><rect x="-88" y="528" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="264.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="704" y="528" width="88" height="88" fill="#1d1926"/><rect x="704" y="528" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="968.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="0" y="616" width="88" height="88" fill="#1d1926"/><rect x="0" y="616" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="264" y="616" width="88" height="88" fill="url(#dt)"/><rect x="440" y="616" width="88" height="88" fill="url(#dt)"/><rect x="528" y="616" width="88" height="88" fill="url(#dt)"/><rect x="792.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968" y="616" width="88" height="88" fill="url(#dt)"/><rect x="100" y="82" width="900" height="387" fill="#15121d" filter="url(#sh)"/><rect x="100" y="82" width="900" height="387" fill="#15121d"/><g transform="translate(100 82)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#a1a1aa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Offer</text><line x1="124" y1="20" x2="124" y2="56" stroke="#2b2636" stroke-width="1"/><text x="156" y="44" font-size="17" fill="#a1a1aa">Prices</text><text x="257.2" y="44" font-size="17" fill="#f4f4f5">Inventory</text><rect x="239.2" y="73" width="127.8" height="3" fill="#f4f4f5"/><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">offer_01JD8QA</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">INVENTORY ITEM</text><text x="368" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">LOCATION</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">REQUIRED</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#a1a1aa">iitem_01JD8Q1</text><text x="368" y="167.6" font-size="16" fill="#f4f4f5">Warehouse A</text><text x="868" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">1</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#a1a1aa">iitem_01JD8Q2</text><text x="368" y="231.6" font-size="16" fill="#f4f4f5">Warehouse A</text><text x="868" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">1</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#a1a1aa">iitem_01JD8Q3</text><text x="368" y="295.6" font-size="16" fill="#f4f4f5">Warehouse B</text><text x="868" y="295.6" font-size="16" fill="#f4f4f5" text-anchor="end">2</text><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/></g></g><rect x="100.5" y="82.5" width="899" height="386" fill="none" stroke="#2b2636" stroke-width="1"/><rect x="40" y="168" width="900" height="387" fill="#15121d" filter="url(#sh)"/><rect x="40" y="168" width="900" height="387" fill="#15121d"/><g transform="translate(40 168)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#a78bfa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Price set</text><line x1="167.2" y1="20" x2="167.2" y2="56" stroke="#2b2636" stroke-width="1"/><text x="199.2" y="44" font-size="17" fill="#f4f4f5">Linen shirt / M</text><rect x="181.2" y="73" width="189" height="3" fill="#f4f4f5"/><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">pset_01JD8Q2</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">PRICE</text><text x="412" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">AMOUNT</text><text x="562" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">MIN QTY</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">RULE OFFER_ID</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#a78bfa"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">price_01JD8Q1</text><text x="412" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 47.00</text><text x="868" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">offer_01JD8QA</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">price_01JD8Q2</text><text x="412" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 42.00</text><text x="562" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">10</text><text x="868" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">offer_01JD8QA</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">price_01JD8Q3</text><text x="412" y="295.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 32.00</text><text x="868" y="295.6" font-size="16" fill="#a1a1aa" text-anchor="end">offer_01JD8QB</text><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#f4f4f5">price_01JD8Q4</text><text x="412" y="359.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 45.00</text><text x="868" y="359.6" font-size="16" fill="#a1a1aa" text-anchor="end">offer_01JD8QC</text><line x1="0" y1="386" x2="900" y2="386" stroke="#221e2b" stroke-width="1"/></g></g><rect x="40.5" y="168.5" width="899" height="386" fill="none" stroke="#2b2636" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/offer-price-rules-light.svg b/apps/docs/images/figures/offer-price-rules-light.svg
new file mode 100644
index 000000000..46cdd6441
--- /dev/null
+++ b/apps/docs/images/figures/offer-price-rules-light.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="610" viewBox="0 0 1040 610" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="The shared price set of the Linen shirt M variant holds price rows for three offers; each row carries an offer_id rule, and the two rows for offer_01JD8QA form a quantity tier. Behind it, that offer links to its own inventory items.">
+<title>The shared price set of the Linen shirt M variant holds price rows for three offers; each row carries an offer_id rule, and the two rows for offer_01JD8QA form a quantity tier. Behind it, that offer links to its own inventory items.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#18181b" flood-opacity="0.07"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#d9d9de"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="387"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="387"/></clipPath></defs>
+<rect x="176.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="0" y="0" width="88" height="88" fill="#e4e4e7"/><rect x="0" y="0" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="616.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="704" y="0" width="88" height="88" fill="url(#dt)"/><rect x="792.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440" y="88" width="88" height="88" fill="#e4e4e7"/><rect x="440" y="88" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="528.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="0" y="176" width="88" height="88" fill="#e4e4e7"/><rect x="0" y="176" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="-88" y="264" width="88" height="88" fill="url(#dt)"/><rect x="176" y="264" width="88" height="88" fill="#e4e4e7"/><rect x="176" y="264" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="264" y="264" width="88" height="88" fill="#e4e4e7"/><rect x="264" y="264" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="880" y="264" width="88" height="88" fill="url(#dt)"/><rect x="88" y="352" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="352.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="704" y="352" width="88" height="88" fill="#e4e4e7"/><rect x="704" y="352" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="880.5" y="352.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="0.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056" y="440" width="88" height="88" fill="url(#dt)"/><rect x="-88" y="528" width="88" height="88" fill="#e4e4e7"/><rect x="-88" y="528" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="264.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="704" y="528" width="88" height="88" fill="#e4e4e7"/><rect x="704" y="528" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="968.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="0" y="616" width="88" height="88" fill="#e4e4e7"/><rect x="0" y="616" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="264" y="616" width="88" height="88" fill="url(#dt)"/><rect x="440" y="616" width="88" height="88" fill="url(#dt)"/><rect x="528" y="616" width="88" height="88" fill="url(#dt)"/><rect x="792.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968" y="616" width="88" height="88" fill="url(#dt)"/><rect x="100" y="82" width="900" height="387" fill="#ffffff" filter="url(#sh)"/><rect x="100" y="82" width="900" height="387" fill="#ffffff"/><g transform="translate(100 82)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#71717a"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Offer</text><line x1="124" y1="20" x2="124" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="156" y="44" font-size="17" fill="#71717a">Prices</text><text x="257.2" y="44" font-size="17" fill="#18181b">Inventory</text><rect x="239.2" y="73" width="127.8" height="3" fill="#18181b"/><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">offer_01JD8QA</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">INVENTORY ITEM</text><text x="368" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">LOCATION</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">REQUIRED</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#71717a">iitem_01JD8Q1</text><text x="368" y="167.6" font-size="16" fill="#18181b">Warehouse A</text><text x="868" y="167.6" font-size="16" fill="#18181b" text-anchor="end">1</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#71717a">iitem_01JD8Q2</text><text x="368" y="231.6" font-size="16" fill="#18181b">Warehouse A</text><text x="868" y="231.6" font-size="16" fill="#18181b" text-anchor="end">1</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#71717a">iitem_01JD8Q3</text><text x="368" y="295.6" font-size="16" fill="#18181b">Warehouse B</text><text x="868" y="295.6" font-size="16" fill="#18181b" text-anchor="end">2</text><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/></g></g><rect x="100.5" y="82.5" width="899" height="386" fill="none" stroke="#e4e4e7" stroke-width="1"/><rect x="40" y="168" width="900" height="387" fill="#ffffff" filter="url(#sh)"/><rect x="40" y="168" width="900" height="387" fill="#ffffff"/><g transform="translate(40 168)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#7c3aed"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Price set</text><line x1="167.2" y1="20" x2="167.2" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="199.2" y="44" font-size="17" fill="#18181b">Linen shirt / M</text><rect x="181.2" y="73" width="189" height="3" fill="#18181b"/><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">pset_01JD8Q2</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">PRICE</text><text x="412" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">AMOUNT</text><text x="562" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">MIN QTY</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">RULE OFFER_ID</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#7c3aed"/><text x="32" y="167.6" font-size="16" fill="#18181b">price_01JD8Q1</text><text x="412" y="167.6" font-size="16" fill="#18181b" text-anchor="end">€ 47.00</text><text x="868" y="167.6" font-size="16" fill="#18181b" text-anchor="end">offer_01JD8QA</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">price_01JD8Q2</text><text x="412" y="231.6" font-size="16" fill="#18181b" text-anchor="end">€ 42.00</text><text x="562" y="231.6" font-size="16" fill="#18181b" text-anchor="end">10</text><text x="868" y="231.6" font-size="16" fill="#18181b" text-anchor="end">offer_01JD8QA</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">price_01JD8Q3</text><text x="412" y="295.6" font-size="16" fill="#18181b" text-anchor="end">€ 32.00</text><text x="868" y="295.6" font-size="16" fill="#71717a" text-anchor="end">offer_01JD8QB</text><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#18181b">price_01JD8Q4</text><text x="412" y="359.6" font-size="16" fill="#18181b" text-anchor="end">€ 45.00</text><text x="868" y="359.6" font-size="16" fill="#71717a" text-anchor="end">offer_01JD8QC</text><line x1="0" y1="386" x2="900" y2="386" stroke="#ededf0" stroke-width="1"/></g></g><rect x="40.5" y="168.5" width="899" height="386" fill="none" stroke="#e4e4e7" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/order-group-overview-dark.svg b/apps/docs/images/figures/order-group-overview-dark.svg
new file mode 100644
index 000000000..ef18a1d6f
--- /dev/null
+++ b/apps/docs/images/figures/order-group-overview-dark.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="860" viewBox="0 0 1040 860" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="The order_group record og_01JD8Q1234567 in front, with display_id 98, its customer and read-only cart link, and computed seller_count 2 and total 87.00. Behind it, the order_group_order link lists the two child orders it sums: 47.00 for ACME and 40.00 for GLOBEX.">
+<title>The order_group record og_01JD8Q1234567 in front, with display_id 98, its customer and read-only cart link, and computed seller_count 2 and total 87.00. Behind it, the order_group_order link lists the two child orders it sums: 47.00 for ACME and 40.00 for GLOBEX.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000000" flood-opacity="0.55"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#2c2737"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="514"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="514"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="-88" width="88" height="88" fill="#1d1926"/><rect x="1056" y="-88" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="-88" y="0" width="88" height="88" fill="#1d1926"/><rect x="-88" y="0" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="0.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="352" y="0" width="88" height="88" fill="#1d1926"/><rect x="352" y="0" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="1056.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="-87.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="0.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88" y="176" width="88" height="88" fill="url(#dt)"/><rect x="616" y="176" width="88" height="88" fill="url(#dt)"/><rect x="264" y="264" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="352.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616" y="352" width="88" height="88" fill="url(#dt)"/><rect x="968" y="352" width="88" height="88" fill="#1d1926"/><rect x="968" y="352" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="176" y="440" width="88" height="88" fill="#1d1926"/><rect x="176" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="968.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="0.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="176" y="616" width="88" height="88" fill="#1d1926"/><rect x="176" y="616" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="352.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528.5" y="704.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="-87.5" y="792.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="704" y="792" width="88" height="88" fill="#1d1926"/><rect x="704" y="792" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="352" y="880" width="88" height="88" fill="url(#dt)"/><rect x="440" y="880" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="880.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="704" y="880" width="88" height="88" fill="url(#dt)"/><rect x="968.5" y="880.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056" y="880" width="88" height="88" fill="url(#dt)"/><rect x="100" y="40" width="900" height="514" fill="#15121d" filter="url(#sh)"/><rect x="100" y="40" width="900" height="514" fill="#15121d"/><g transform="translate(100 40)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#f4f4f5"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">orders</text><line x1="134.8" y1="20" x2="134.8" y2="56" stroke="#2b2636" stroke-width="1"/><text x="166.8" y="44" font-size="17" fill="#f4f4f5">order_group_order</text><rect x="148.8" y="73" width="209.4" height="3" fill="#f4f4f5"/><text x="380.2" y="44" font-size="17" fill="#a1a1aa">order_seller</text><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">link</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">ORDER_ID</text><text x="362" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">SELLER.NAME</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">CURRENT_ORDER_TOTAL</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">order_01JD8Q1234568</text><text x="362" y="167.6" font-size="16" fill="#f4f4f5">ACME</text><text x="868" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">47.00</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">order_01JD8Q1234569</text><text x="362" y="231.6" font-size="16" fill="#f4f4f5">GLOBEX</text><text x="868" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">40.00</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/></g></g><rect x="100.5" y="40.5" width="899" height="513" fill="none" stroke="#2b2636" stroke-width="1"/><rect x="40" y="302" width="900" height="514" fill="#15121d" filter="url(#sh)"/><rect x="40" y="302" width="900" height="514" fill="#15121d"/><g transform="translate(40 302)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#a78bfa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">order_group</text><line x1="188.8" y1="20" x2="188.8" y2="56" stroke="#2b2636" stroke-width="1"/><text x="220.8" y="44" font-size="17" fill="#f4f4f5">Fields</text><rect x="202.8" y="73" width="97.2" height="3" fill="#f4f4f5"/><text x="322" y="44" font-size="17" fill="#a1a1aa">Links</text><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">MercurModules.SELLER</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">FIELD</text><text x="262" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">TYPE</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">VALUE</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">id</text><text x="262" y="167.6" font-size="16" fill="#d4d4d8">id, prefix og</text><text x="868" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">og_01JD8Q1234567</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">display_id</text><text x="262" y="231.6" font-size="16" fill="#d4d4d8">autoincrement</text><text x="868" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">98</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">customer_id</text><text x="262" y="295.6" font-size="16" fill="#d4d4d8">text, nullable</text><text x="868" y="295.6" font-size="16" fill="#f4f4f5" text-anchor="end">cus_01JD8Q1234567</text><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#f4f4f5">cart_id</text><text x="262" y="359.6" font-size="16" fill="#d4d4d8">text, read-only link</text><text x="868" y="359.6" font-size="16" fill="#f4f4f5" text-anchor="end">cart_01JD8Q1234567</text><line x1="0" y1="386" x2="900" y2="386" stroke="#221e2b" stroke-width="1"/><text x="32" y="423.6" font-size="16" fill="#f4f4f5">seller_count</text><text x="262" y="423.6" font-size="16" fill="#d4d4d8">number, computed</text><text x="868" y="423.6" font-size="16" fill="#f4f4f5" text-anchor="end">2</text><line x1="0" y1="450" x2="900" y2="450" stroke="#221e2b" stroke-width="1"/><rect x="0" y="450" width="3" height="64" fill="#a78bfa"/><text x="32" y="487.6" font-size="16" fill="#f4f4f5">total</text><text x="262" y="487.6" font-size="16" fill="#d4d4d8">bigNumber, computed</text><text x="868" y="487.6" font-size="16" fill="#f4f4f5" text-anchor="end">87.00</text><line x1="0" y1="514" x2="900" y2="514" stroke="#221e2b" stroke-width="1"/></g></g><rect x="40.5" y="302.5" width="899" height="513" fill="none" stroke="#2b2636" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/order-group-overview-light.svg b/apps/docs/images/figures/order-group-overview-light.svg
new file mode 100644
index 000000000..99c0ff828
--- /dev/null
+++ b/apps/docs/images/figures/order-group-overview-light.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="860" viewBox="0 0 1040 860" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="The order_group record og_01JD8Q1234567 in front, with display_id 98, its customer and read-only cart link, and computed seller_count 2 and total 87.00. Behind it, the order_group_order link lists the two child orders it sums: 47.00 for ACME and 40.00 for GLOBEX.">
+<title>The order_group record og_01JD8Q1234567 in front, with display_id 98, its customer and read-only cart link, and computed seller_count 2 and total 87.00. Behind it, the order_group_order link lists the two child orders it sums: 47.00 for ACME and 40.00 for GLOBEX.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#18181b" flood-opacity="0.07"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#d9d9de"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="514"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="514"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="-88" width="88" height="88" fill="#e4e4e7"/><rect x="1056" y="-88" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="-88" y="0" width="88" height="88" fill="#e4e4e7"/><rect x="-88" y="0" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="0.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="352" y="0" width="88" height="88" fill="#e4e4e7"/><rect x="352" y="0" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="1056.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="-87.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="0.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88" y="176" width="88" height="88" fill="url(#dt)"/><rect x="616" y="176" width="88" height="88" fill="url(#dt)"/><rect x="264" y="264" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="352.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616" y="352" width="88" height="88" fill="url(#dt)"/><rect x="968" y="352" width="88" height="88" fill="#e4e4e7"/><rect x="968" y="352" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="176" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="176" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="968.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="0.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="176" y="616" width="88" height="88" fill="#e4e4e7"/><rect x="176" y="616" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="352.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528.5" y="704.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="-87.5" y="792.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="704" y="792" width="88" height="88" fill="#e4e4e7"/><rect x="704" y="792" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="352" y="880" width="88" height="88" fill="url(#dt)"/><rect x="440" y="880" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="880.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="704" y="880" width="88" height="88" fill="url(#dt)"/><rect x="968.5" y="880.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056" y="880" width="88" height="88" fill="url(#dt)"/><rect x="100" y="40" width="900" height="514" fill="#ffffff" filter="url(#sh)"/><rect x="100" y="40" width="900" height="514" fill="#ffffff"/><g transform="translate(100 40)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#18181b"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">orders</text><line x1="134.8" y1="20" x2="134.8" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="166.8" y="44" font-size="17" fill="#18181b">order_group_order</text><rect x="148.8" y="73" width="209.4" height="3" fill="#18181b"/><text x="380.2" y="44" font-size="17" fill="#71717a">order_seller</text><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">link</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">ORDER_ID</text><text x="362" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">SELLER.NAME</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">CURRENT_ORDER_TOTAL</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#18181b">order_01JD8Q1234568</text><text x="362" y="167.6" font-size="16" fill="#18181b">ACME</text><text x="868" y="167.6" font-size="16" fill="#18181b" text-anchor="end">47.00</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">order_01JD8Q1234569</text><text x="362" y="231.6" font-size="16" fill="#18181b">GLOBEX</text><text x="868" y="231.6" font-size="16" fill="#18181b" text-anchor="end">40.00</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/></g></g><rect x="100.5" y="40.5" width="899" height="513" fill="none" stroke="#e4e4e7" stroke-width="1"/><rect x="40" y="302" width="900" height="514" fill="#ffffff" filter="url(#sh)"/><rect x="40" y="302" width="900" height="514" fill="#ffffff"/><g transform="translate(40 302)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#7c3aed"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">order_group</text><line x1="188.8" y1="20" x2="188.8" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="220.8" y="44" font-size="17" fill="#18181b">Fields</text><rect x="202.8" y="73" width="97.2" height="3" fill="#18181b"/><text x="322" y="44" font-size="17" fill="#71717a">Links</text><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">MercurModules.SELLER</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">FIELD</text><text x="262" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">TYPE</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">VALUE</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#18181b">id</text><text x="262" y="167.6" font-size="16" fill="#3f3f46">id, prefix og</text><text x="868" y="167.6" font-size="16" fill="#18181b" text-anchor="end">og_01JD8Q1234567</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">display_id</text><text x="262" y="231.6" font-size="16" fill="#3f3f46">autoincrement</text><text x="868" y="231.6" font-size="16" fill="#18181b" text-anchor="end">98</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">customer_id</text><text x="262" y="295.6" font-size="16" fill="#3f3f46">text, nullable</text><text x="868" y="295.6" font-size="16" fill="#18181b" text-anchor="end">cus_01JD8Q1234567</text><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#18181b">cart_id</text><text x="262" y="359.6" font-size="16" fill="#3f3f46">text, read-only link</text><text x="868" y="359.6" font-size="16" fill="#18181b" text-anchor="end">cart_01JD8Q1234567</text><line x1="0" y1="386" x2="900" y2="386" stroke="#ededf0" stroke-width="1"/><text x="32" y="423.6" font-size="16" fill="#18181b">seller_count</text><text x="262" y="423.6" font-size="16" fill="#3f3f46">number, computed</text><text x="868" y="423.6" font-size="16" fill="#18181b" text-anchor="end">2</text><line x1="0" y1="450" x2="900" y2="450" stroke="#ededf0" stroke-width="1"/><rect x="0" y="450" width="3" height="64" fill="#7c3aed"/><text x="32" y="487.6" font-size="16" fill="#18181b">total</text><text x="262" y="487.6" font-size="16" fill="#3f3f46">bigNumber, computed</text><text x="868" y="487.6" font-size="16" fill="#18181b" text-anchor="end">87.00</text><line x1="0" y1="514" x2="900" y2="514" stroke="#ededf0" stroke-width="1"/></g></g><rect x="40.5" y="302.5" width="899" height="513" fill="none" stroke="#e4e4e7" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/payout-account-lifecycle-dark.svg b/apps/docs/images/figures/payout-account-lifecycle-dark.svg
new file mode 100644
index 000000000..fe600b681
--- /dev/null
+++ b/apps/docs/images/figures/payout-account-lifecycle-dark.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="600" viewBox="0 0 1040 600" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="A Stripe account.updated webhook behind the process-payout-for-webhook workflow. The workflow maps account.activated to the activate-payout-account step and the Active status, account.restricted to Restricted, account.rejected to Rejected, and not_supported to no change.">
+<title>A Stripe account.updated webhook behind the process-payout-for-webhook workflow. The workflow maps account.activated to the activate-payout-account step and the Active status, account.restricted to Restricted, account.rejected to Rejected, and not_supported to no change.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000000" flood-opacity="0.55"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#2c2737"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="386"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="386"/></clipPath></defs>
+<rect x="88" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="176" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="528" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="792" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="880" y="-88" width="88" height="88" fill="#1d1926"/><rect x="880" y="-88" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="-87.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="176" y="0" width="88" height="88" fill="url(#dt)"/><rect x="352.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880" y="0" width="88" height="88" fill="#1d1926"/><rect x="880" y="0" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="176" y="88" width="88" height="88" fill="url(#dt)"/><rect x="616" y="88" width="88" height="88" fill="#1d1926"/><rect x="616" y="88" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="968.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="-88" y="176" width="88" height="88" fill="#1d1926"/><rect x="-88" y="176" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="0.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="352.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792" y="176" width="88" height="88" fill="url(#dt)"/><rect x="968" y="176" width="88" height="88" fill="url(#dt)"/><rect x="352.5" y="264.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792.5" y="264.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="0.5" y="352.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440" y="352" width="88" height="88" fill="url(#dt)"/><rect x="704.5" y="352.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="352.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056" y="352" width="88" height="88" fill="url(#dt)"/><rect x="-88" y="440" width="88" height="88" fill="#1d1926"/><rect x="-88" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="0" y="440" width="88" height="88" fill="url(#dt)"/><rect x="176" y="440" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056" y="440" width="88" height="88" fill="url(#dt)"/><rect x="0.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="704.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880" y="528" width="88" height="88" fill="#1d1926"/><rect x="880" y="528" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="1056" y="528" width="88" height="88" fill="url(#dt)"/><rect x="0" y="616" width="88" height="88" fill="#1d1926"/><rect x="0" y="616" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="264.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616" y="616" width="88" height="88" fill="url(#dt)"/><rect x="792.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="100" y="82" width="900" height="386" fill="#15121d" filter="url(#sh)"/><rect x="100" y="82" width="900" height="386" fill="#15121d"/><g transform="translate(100 82)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#a1a1aa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Stripe webhook</text><line x1="221.2" y1="20" x2="221.2" y2="56" stroke="#2b2636" stroke-width="1"/><text x="253.2" y="44" font-size="17" fill="#f4f4f5">Event</text><rect x="235.2" y="73" width="87" height="3" fill="#f4f4f5"/><text x="344.2" y="44" font-size="17" fill="#a1a1aa">Headers</text><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">/hooks/payout</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">FIELD</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">VALUE</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">type</text><text x="868" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">account.updated</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">metadata.account_id</text><text x="868" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">pacc_01JD8Q1A</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/></g></g><rect x="100.5" y="82.5" width="899" height="385" fill="none" stroke="#2b2636" stroke-width="1"/><rect x="40" y="168" width="900" height="386" fill="#15121d" filter="url(#sh)"/><rect x="40" y="168" width="900" height="386" fill="#15121d"/><g transform="translate(40 168)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#a78bfa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">process-payout-for-webhook</text><line x1="350.8" y1="20" x2="350.8" y2="56" stroke="#2b2636" stroke-width="1"/><text x="382.8" y="44" font-size="17" fill="#f4f4f5">Accounts</text><rect x="364.8" y="73" width="117.6" height="3" fill="#f4f4f5"/><text x="504.4" y="44" font-size="17" fill="#a1a1aa">Payouts</text><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">when(action)</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">ACTION</text><text x="302" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">STEP</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">STATUS</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#a78bfa"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">account.activated</text><text x="302" y="167.6" font-size="16" fill="#d4d4d8">activate-payout-account</text><rect x="766.4" y="146" width="101.6" height="32" fill="#1f1b29"/><rect x="778.4" y="157" width="10" height="10" fill="#6fbf68"/><text x="800.4" y="166.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">ACTIVE</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">account.restricted</text><text x="302" y="231.6" font-size="16" fill="#d4d4d8">restrict-payout-account</text><rect x="728" y="210" width="140" height="32" fill="#1f1b29"/><rect x="740" y="221" width="10" height="10" fill="#f2a14b"/><text x="762" y="230.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">RESTRICTED</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">account.rejected</text><text x="302" y="295.6" font-size="16" fill="#d4d4d8">reject-payout-account</text><rect x="747.2" y="274" width="120.8" height="32" fill="#1f1b29"/><rect x="759.2" y="285" width="10" height="10" fill="#f0735a"/><text x="781.2" y="294.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">REJECTED</text><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#a1a1aa">not_supported</text><text x="302" y="359.6" font-size="16" fill="#a1a1aa">no step</text><text x="868" y="359.6" font-size="16" fill="#a1a1aa" text-anchor="end">unchanged</text><line x1="0" y1="386" x2="900" y2="386" stroke="#221e2b" stroke-width="1"/></g></g><rect x="40.5" y="168.5" width="899" height="385" fill="none" stroke="#2b2636" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/payout-account-lifecycle-light.svg b/apps/docs/images/figures/payout-account-lifecycle-light.svg
new file mode 100644
index 000000000..4582ec5ea
--- /dev/null
+++ b/apps/docs/images/figures/payout-account-lifecycle-light.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="600" viewBox="0 0 1040 600" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="A Stripe account.updated webhook behind the process-payout-for-webhook workflow. The workflow maps account.activated to the activate-payout-account step and the Active status, account.restricted to Restricted, account.rejected to Rejected, and not_supported to no change.">
+<title>A Stripe account.updated webhook behind the process-payout-for-webhook workflow. The workflow maps account.activated to the activate-payout-account step and the Active status, account.restricted to Restricted, account.rejected to Rejected, and not_supported to no change.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#18181b" flood-opacity="0.07"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#d9d9de"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="386"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="386"/></clipPath></defs>
+<rect x="88" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="176" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="528" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="792" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="880" y="-88" width="88" height="88" fill="#e4e4e7"/><rect x="880" y="-88" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="-87.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="176" y="0" width="88" height="88" fill="url(#dt)"/><rect x="352.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880" y="0" width="88" height="88" fill="#e4e4e7"/><rect x="880" y="0" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="176" y="88" width="88" height="88" fill="url(#dt)"/><rect x="616" y="88" width="88" height="88" fill="#e4e4e7"/><rect x="616" y="88" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="968.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="-88" y="176" width="88" height="88" fill="#e4e4e7"/><rect x="-88" y="176" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="0.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="352.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792" y="176" width="88" height="88" fill="url(#dt)"/><rect x="968" y="176" width="88" height="88" fill="url(#dt)"/><rect x="352.5" y="264.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792.5" y="264.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="0.5" y="352.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440" y="352" width="88" height="88" fill="url(#dt)"/><rect x="704.5" y="352.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="352.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056" y="352" width="88" height="88" fill="url(#dt)"/><rect x="-88" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="-88" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="0" y="440" width="88" height="88" fill="url(#dt)"/><rect x="176" y="440" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056" y="440" width="88" height="88" fill="url(#dt)"/><rect x="0.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="704.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880" y="528" width="88" height="88" fill="#e4e4e7"/><rect x="880" y="528" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="1056" y="528" width="88" height="88" fill="url(#dt)"/><rect x="0" y="616" width="88" height="88" fill="#e4e4e7"/><rect x="0" y="616" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="264.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616" y="616" width="88" height="88" fill="url(#dt)"/><rect x="792.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="100" y="82" width="900" height="386" fill="#ffffff" filter="url(#sh)"/><rect x="100" y="82" width="900" height="386" fill="#ffffff"/><g transform="translate(100 82)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#71717a"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Stripe webhook</text><line x1="221.2" y1="20" x2="221.2" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="253.2" y="44" font-size="17" fill="#18181b">Event</text><rect x="235.2" y="73" width="87" height="3" fill="#18181b"/><text x="344.2" y="44" font-size="17" fill="#71717a">Headers</text><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">/hooks/payout</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">FIELD</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">VALUE</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#18181b">type</text><text x="868" y="167.6" font-size="16" fill="#18181b" text-anchor="end">account.updated</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">metadata.account_id</text><text x="868" y="231.6" font-size="16" fill="#18181b" text-anchor="end">pacc_01JD8Q1A</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/></g></g><rect x="100.5" y="82.5" width="899" height="385" fill="none" stroke="#e4e4e7" stroke-width="1"/><rect x="40" y="168" width="900" height="386" fill="#ffffff" filter="url(#sh)"/><rect x="40" y="168" width="900" height="386" fill="#ffffff"/><g transform="translate(40 168)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#7c3aed"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">process-payout-for-webhook</text><line x1="350.8" y1="20" x2="350.8" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="382.8" y="44" font-size="17" fill="#18181b">Accounts</text><rect x="364.8" y="73" width="117.6" height="3" fill="#18181b"/><text x="504.4" y="44" font-size="17" fill="#71717a">Payouts</text><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">when(action)</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">ACTION</text><text x="302" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">STEP</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">STATUS</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#7c3aed"/><text x="32" y="167.6" font-size="16" fill="#18181b">account.activated</text><text x="302" y="167.6" font-size="16" fill="#3f3f46">activate-payout-account</text><rect x="766.4" y="146" width="101.6" height="32" fill="#f4f4f5"/><rect x="778.4" y="157" width="10" height="10" fill="#3f7d3a"/><text x="800.4" y="166.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">ACTIVE</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">account.restricted</text><text x="302" y="231.6" font-size="16" fill="#3f3f46">restrict-payout-account</text><rect x="728" y="210" width="140" height="32" fill="#f4f4f5"/><rect x="740" y="221" width="10" height="10" fill="#c2680c"/><text x="762" y="230.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">RESTRICTED</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">account.rejected</text><text x="302" y="295.6" font-size="16" fill="#3f3f46">reject-payout-account</text><rect x="747.2" y="274" width="120.8" height="32" fill="#f4f4f5"/><rect x="759.2" y="285" width="10" height="10" fill="#b3361f"/><text x="781.2" y="294.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">REJECTED</text><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#71717a">not_supported</text><text x="302" y="359.6" font-size="16" fill="#71717a">no step</text><text x="868" y="359.6" font-size="16" fill="#71717a" text-anchor="end">unchanged</text><line x1="0" y1="386" x2="900" y2="386" stroke="#ededf0" stroke-width="1"/></g></g><rect x="40.5" y="168.5" width="899" height="385" fill="none" stroke="#e4e4e7" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/payout-overview-dark.svg b/apps/docs/images/figures/payout-overview-dark.svg
new file mode 100644
index 000000000..e2af9ce5d
--- /dev/null
+++ b/apps/docs/images/figures/payout-overview-dark.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="540" viewBox="0 0 1040 540" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="A Payouts list in front of a Payout accounts list. Payout #12 for ACME is accented: an order total of € 47.00 minus € 4.70 commission gives a € 42.30 payout, marked Paid. Behind it, ACME's payout account is Active and GLOBEX's is Restricted.">
+<title>A Payouts list in front of a Payout accounts list. Payout #12 for ACME is accented: an order total of € 47.00 minus € 4.70 commission gives a € 42.30 payout, marked Paid. Behind it, ACME's payout account is Active and GLOBEX's is Restricted.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000000" flood-opacity="0.55"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#2c2737"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="322"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="322"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="-88" width="88" height="88" fill="#1d1926"/><rect x="1056" y="-88" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="-88" y="0" width="88" height="88" fill="#1d1926"/><rect x="-88" y="0" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="0.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="352" y="0" width="88" height="88" fill="#1d1926"/><rect x="352" y="0" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="1056.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="-87.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="0.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88" y="176" width="88" height="88" fill="url(#dt)"/><rect x="616" y="176" width="88" height="88" fill="url(#dt)"/><rect x="264" y="264" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="352.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616" y="352" width="88" height="88" fill="url(#dt)"/><rect x="968" y="352" width="88" height="88" fill="#1d1926"/><rect x="968" y="352" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="176" y="440" width="88" height="88" fill="#1d1926"/><rect x="176" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="440.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528" y="440" width="88" height="88" fill="#1d1926"/><rect x="528" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="88" y="528" width="88" height="88" fill="url(#dt)"/><rect x="352" y="528" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056" y="528" width="88" height="88" fill="#1d1926"/><rect x="1056" y="528" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="0.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88" y="616" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792" y="616" width="88" height="88" fill="url(#dt)"/><rect x="880" y="616" width="88" height="88" fill="url(#dt)"/><rect x="1056.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="100" y="82" width="900" height="322" fill="#15121d" filter="url(#sh)"/><rect x="100" y="82" width="900" height="322" fill="#15121d"/><g transform="translate(100 82)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#a1a1aa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Payout accounts</text><line x1="232" y1="20" x2="232" y2="56" stroke="#2b2636" stroke-width="1"/><text x="264" y="44" font-size="17" fill="#f4f4f5">Accounts</text><rect x="246" y="73" width="117.6" height="3" fill="#f4f4f5"/><text x="385.6" y="44" font-size="17" fill="#a1a1aa">Onboarding</text><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">seller_payout_account</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">ACCOUNT</text><text x="332" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">STORE</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">STATUS</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">pacc_01JD8Q1A</text><text x="332" y="167.6" font-size="16" fill="#f4f4f5">ACME</text><rect x="766.4" y="146" width="101.6" height="32" fill="#1f1b29"/><rect x="778.4" y="157" width="10" height="10" fill="#6fbf68"/><text x="800.4" y="166.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">ACTIVE</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">pacc_01JD8Q2B</text><text x="332" y="231.6" font-size="16" fill="#f4f4f5">GLOBEX</text><rect x="728" y="210" width="140" height="32" fill="#1f1b29"/><rect x="740" y="221" width="10" height="10" fill="#f2a14b"/><text x="762" y="230.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">RESTRICTED</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/></g></g><rect x="100.5" y="82.5" width="899" height="321" fill="none" stroke="#2b2636" stroke-width="1"/><rect x="40" y="168" width="900" height="322" fill="#15121d" filter="url(#sh)"/><rect x="40" y="168" width="900" height="322" fill="#15121d"/><g transform="translate(40 168)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#a78bfa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Payouts</text><line x1="145.6" y1="20" x2="145.6" y2="56" stroke="#2b2636" stroke-width="1"/><text x="177.6" y="44" font-size="17" fill="#f4f4f5">All</text><rect x="159.6" y="73" width="66.6" height="3" fill="#f4f4f5"/><text x="248.2" y="44" font-size="17" fill="#a1a1aa">Paid</text><text x="329" y="44" font-size="17" fill="#a1a1aa">Failed</text><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">create-payout</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">PAYOUT</text><text x="142" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">STORE</text><text x="422" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">ORDER TOTAL</text><text x="572" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">COMMISSION</text><text x="702" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">AMOUNT</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">STATUS</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#a78bfa"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">#12</text><text x="142" y="167.6" font-size="16" fill="#f4f4f5">ACME</text><text x="422" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 47.00</text><text x="572" y="167.6" font-size="16" fill="#a1a1aa" text-anchor="end">€ 4.70</text><text x="702" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 42.30</text><rect x="785.6" y="146" width="82.4" height="32" fill="#1f1b29"/><rect x="797.6" y="157" width="10" height="10" fill="#6fbf68"/><text x="819.6" y="166.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">PAID</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">#11</text><text x="142" y="231.6" font-size="16" fill="#f4f4f5">GLOBEX</text><text x="422" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 40.00</text><text x="572" y="231.6" font-size="16" fill="#a1a1aa" text-anchor="end">€ 4.00</text><text x="702" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 36.00</text><rect x="756.8" y="210" width="111.2" height="32" fill="#1f1b29"/><rect x="768.8" y="221" width="10" height="10" fill="#f2a14b"/><text x="790.8" y="230.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">PENDING</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">#10</text><text x="142" y="295.6" font-size="16" fill="#f4f4f5">ACME</text><text x="422" y="295.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 21.00</text><text x="572" y="295.6" font-size="16" fill="#a1a1aa" text-anchor="end">€ 2.10</text><text x="702" y="295.6" font-size="16" fill="#f4f4f5" text-anchor="end">€ 18.90</text><rect x="766.4" y="274" width="101.6" height="32" fill="#1f1b29"/><rect x="778.4" y="285" width="10" height="10" fill="#f0735a"/><text x="800.4" y="294.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">FAILED</text><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/></g></g><rect x="40.5" y="168.5" width="899" height="321" fill="none" stroke="#2b2636" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/payout-overview-light.svg b/apps/docs/images/figures/payout-overview-light.svg
new file mode 100644
index 000000000..6fbdb6e43
--- /dev/null
+++ b/apps/docs/images/figures/payout-overview-light.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="540" viewBox="0 0 1040 540" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="A Payouts list in front of a Payout accounts list. Payout #12 for ACME is accented: an order total of € 47.00 minus € 4.70 commission gives a € 42.30 payout, marked Paid. Behind it, ACME's payout account is Active and GLOBEX's is Restricted.">
+<title>A Payouts list in front of a Payout accounts list. Payout #12 for ACME is accented: an order total of € 47.00 minus € 4.70 commission gives a € 42.30 payout, marked Paid. Behind it, ACME's payout account is Active and GLOBEX's is Restricted.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#18181b" flood-opacity="0.07"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#d9d9de"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="322"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="322"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="-88" width="88" height="88" fill="#e4e4e7"/><rect x="1056" y="-88" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="-88" y="0" width="88" height="88" fill="#e4e4e7"/><rect x="-88" y="0" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="0.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="352" y="0" width="88" height="88" fill="#e4e4e7"/><rect x="352" y="0" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="1056.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="-87.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="0.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88" y="176" width="88" height="88" fill="url(#dt)"/><rect x="616" y="176" width="88" height="88" fill="url(#dt)"/><rect x="264" y="264" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="352.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616" y="352" width="88" height="88" fill="url(#dt)"/><rect x="968" y="352" width="88" height="88" fill="#e4e4e7"/><rect x="968" y="352" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="176" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="176" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="440.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="528" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="88" y="528" width="88" height="88" fill="url(#dt)"/><rect x="352" y="528" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056" y="528" width="88" height="88" fill="#e4e4e7"/><rect x="1056" y="528" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="0.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88" y="616" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792" y="616" width="88" height="88" fill="url(#dt)"/><rect x="880" y="616" width="88" height="88" fill="url(#dt)"/><rect x="1056.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="100" y="82" width="900" height="322" fill="#ffffff" filter="url(#sh)"/><rect x="100" y="82" width="900" height="322" fill="#ffffff"/><g transform="translate(100 82)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#71717a"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Payout accounts</text><line x1="232" y1="20" x2="232" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="264" y="44" font-size="17" fill="#18181b">Accounts</text><rect x="246" y="73" width="117.6" height="3" fill="#18181b"/><text x="385.6" y="44" font-size="17" fill="#71717a">Onboarding</text><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">seller_payout_account</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">ACCOUNT</text><text x="332" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">STORE</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">STATUS</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#18181b">pacc_01JD8Q1A</text><text x="332" y="167.6" font-size="16" fill="#18181b">ACME</text><rect x="766.4" y="146" width="101.6" height="32" fill="#f4f4f5"/><rect x="778.4" y="157" width="10" height="10" fill="#3f7d3a"/><text x="800.4" y="166.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">ACTIVE</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">pacc_01JD8Q2B</text><text x="332" y="231.6" font-size="16" fill="#18181b">GLOBEX</text><rect x="728" y="210" width="140" height="32" fill="#f4f4f5"/><rect x="740" y="221" width="10" height="10" fill="#c2680c"/><text x="762" y="230.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">RESTRICTED</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/></g></g><rect x="100.5" y="82.5" width="899" height="321" fill="none" stroke="#e4e4e7" stroke-width="1"/><rect x="40" y="168" width="900" height="322" fill="#ffffff" filter="url(#sh)"/><rect x="40" y="168" width="900" height="322" fill="#ffffff"/><g transform="translate(40 168)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#7c3aed"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Payouts</text><line x1="145.6" y1="20" x2="145.6" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="177.6" y="44" font-size="17" fill="#18181b">All</text><rect x="159.6" y="73" width="66.6" height="3" fill="#18181b"/><text x="248.2" y="44" font-size="17" fill="#71717a">Paid</text><text x="329" y="44" font-size="17" fill="#71717a">Failed</text><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">create-payout</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">PAYOUT</text><text x="142" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">STORE</text><text x="422" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">ORDER TOTAL</text><text x="572" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">COMMISSION</text><text x="702" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">AMOUNT</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">STATUS</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#7c3aed"/><text x="32" y="167.6" font-size="16" fill="#18181b">#12</text><text x="142" y="167.6" font-size="16" fill="#18181b">ACME</text><text x="422" y="167.6" font-size="16" fill="#18181b" text-anchor="end">€ 47.00</text><text x="572" y="167.6" font-size="16" fill="#71717a" text-anchor="end">€ 4.70</text><text x="702" y="167.6" font-size="16" fill="#18181b" text-anchor="end">€ 42.30</text><rect x="785.6" y="146" width="82.4" height="32" fill="#f4f4f5"/><rect x="797.6" y="157" width="10" height="10" fill="#3f7d3a"/><text x="819.6" y="166.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">PAID</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">#11</text><text x="142" y="231.6" font-size="16" fill="#18181b">GLOBEX</text><text x="422" y="231.6" font-size="16" fill="#18181b" text-anchor="end">€ 40.00</text><text x="572" y="231.6" font-size="16" fill="#71717a" text-anchor="end">€ 4.00</text><text x="702" y="231.6" font-size="16" fill="#18181b" text-anchor="end">€ 36.00</text><rect x="756.8" y="210" width="111.2" height="32" fill="#f4f4f5"/><rect x="768.8" y="221" width="10" height="10" fill="#c2680c"/><text x="790.8" y="230.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">PENDING</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">#10</text><text x="142" y="295.6" font-size="16" fill="#18181b">ACME</text><text x="422" y="295.6" font-size="16" fill="#18181b" text-anchor="end">€ 21.00</text><text x="572" y="295.6" font-size="16" fill="#71717a" text-anchor="end">€ 2.10</text><text x="702" y="295.6" font-size="16" fill="#18181b" text-anchor="end">€ 18.90</text><rect x="766.4" y="274" width="101.6" height="32" fill="#f4f4f5"/><rect x="778.4" y="285" width="10" height="10" fill="#b3361f"/><text x="800.4" y="294.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">FAILED</text><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/></g></g><rect x="40.5" y="168.5" width="899" height="321" fill="none" stroke="#e4e4e7" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/product-edit-lifecycle-dark.svg b/apps/docs/images/figures/product-edit-lifecycle-dark.svg
new file mode 100644
index 000000000..aced0e27a
--- /dev/null
+++ b/apps/docs/images/figures/product-edit-lifecycle-dark.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="580" viewBox="0 0 1040 580" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="The ProductChangeStatus table: a change enters pending through stageProductChangeWorkflow, then confirmProductChangeWorkflow, rejectProductChangeWorkflow, or cancelProductChangeWorkflow moves it to confirmed, declined, or canceled, each emitting its own event and stamping its own actor field.">
+<title>The ProductChangeStatus table: a change enters pending through stageProductChangeWorkflow, then confirmProductChangeWorkflow, rejectProductChangeWorkflow, or cancelProductChangeWorkflow moves it to confirmed, declined, or canceled, each emitting its own event and stamping its own actor field.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000000" flood-opacity="0.55"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#2c2737"/></pattern><clipPath id="c1"><rect x="0" y="0" width="960" height="386"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="960" height="386"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="616" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="968.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="176.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264" y="0" width="88" height="88" fill="url(#dt)"/><rect x="352.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528" y="0" width="88" height="88" fill="#1d1926"/><rect x="528" y="0" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="792.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968" y="176" width="88" height="88" fill="url(#dt)"/><rect x="88.5" y="264.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="176" y="264" width="88" height="88" fill="#1d1926"/><rect x="176" y="264" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="880.5" y="264.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="352" y="352" width="88" height="88" fill="url(#dt)"/><rect x="968" y="352" width="88" height="88" fill="#1d1926"/><rect x="968" y="352" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="88" y="440" width="88" height="88" fill="#1d1926"/><rect x="88" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="528" y="440" width="88" height="88" fill="url(#dt)"/><rect x="880.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616" y="528" width="88" height="88" fill="#1d1926"/><rect x="616" y="528" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="704.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968" y="528" width="88" height="88" fill="#1d1926"/><rect x="968" y="528" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="0.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528" y="616" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880" y="616" width="88" height="88" fill="#1d1926"/><rect x="880" y="616" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="80" y="64" width="960" height="386" fill="#15121d" filter="url(#sh)"/><rect x="80" y="64" width="960" height="386" fill="#15121d"/><g transform="translate(80 64)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#a1a1aa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">prodch_01JD8Q</text><line x1="210.4" y1="20" x2="210.4" y2="56" stroke="#2b2636" stroke-width="1"/><text x="242.4" y="44" font-size="17" fill="#f4f4f5">Actions</text><rect x="224.4" y="73" width="107.4" height="3" fill="#f4f4f5"/><text x="353.8" y="44" font-size="17" fill="#a1a1aa">Notes</text><text x="936" y="43.3" font-size="15" fill="#71717a" text-anchor="end">prod_01JD8Q</text><line x1="0" y1="76" x2="960" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">ACTION</text><text x="292" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">DETAILS</text><text x="928" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">APPLIED</text><line x1="0" y1="130" x2="960" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">UPDATE</text><text x="292" y="167.6" font-size="16" fill="#f4f4f5">{ field: "title" }</text><rect x="882" y="151" width="46" height="22" fill="#3f3a4b"/><rect x="885" y="154" width="19" height="16" fill="#15121d"/><line x1="0" y1="194" x2="960" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">UPDATE</text><text x="292" y="231.6" font-size="16" fill="#f4f4f5">{ field: "material" }</text><rect x="882" y="215" width="46" height="22" fill="#3f3a4b"/><rect x="885" y="218" width="19" height="16" fill="#15121d"/><line x1="0" y1="258" x2="960" y2="258" stroke="#221e2b" stroke-width="1"/></g></g><rect x="80.5" y="64.5" width="959" height="385" fill="none" stroke="#2b2636" stroke-width="1"/><rect x="40" y="150" width="960" height="386" fill="#15121d" filter="url(#sh)"/><rect x="40" y="150" width="960" height="386" fill="#15121d"/><g transform="translate(40 150)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#a78bfa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">ProductChangeStatus</text><line x1="275.2" y1="20" x2="275.2" y2="56" stroke="#2b2636" stroke-width="1"/><text x="307.2" y="44" font-size="17" fill="#f4f4f5">Transitions</text><rect x="289.2" y="73" width="148.2" height="3" fill="#f4f4f5"/><text x="801" y="43.3" font-size="15" fill="#d4d4d8">product_request</text><rect x="741" y="27" width="46" height="22" fill="#6fbf68"/><rect x="765" y="30" width="19" height="16" fill="#15121d"/><line x1="0" y1="76" x2="960" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">STATUS</text><text x="218" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">REACHED BY</text><text x="508" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">EVENT</text><text x="928" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">STAMPS</text><line x1="0" y1="130" x2="960" y2="130" stroke="#221e2b" stroke-width="1"/><rect x="32" y="146" width="111.2" height="32" fill="#1f1b29"/><rect x="44" y="157" width="10" height="10" fill="#f2a14b"/><text x="66" y="166.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">PENDING</text><text x="218" y="167.6" font-size="16" fill="#f4f4f5">stageProductChangeWorkflow</text><text x="508" y="167.6" font-size="16" fill="#d4d4d8">product-change.created</text><text x="928" y="167.6" font-size="16" fill="#a1a1aa" text-anchor="end">created_by</text><line x1="0" y1="194" x2="960" y2="194" stroke="#221e2b" stroke-width="1"/><rect x="0" y="194" width="3" height="64" fill="#a78bfa"/><rect x="32" y="210" width="130.4" height="32" fill="#1f1b29"/><rect x="44" y="221" width="10" height="10" fill="#6fbf68"/><text x="66" y="230.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">CONFIRMED</text><text x="218" y="231.6" font-size="16" fill="#f4f4f5">confirmProductChangeWorkflow</text><text x="508" y="231.6" font-size="16" fill="#d4d4d8">product-change.confirmed</text><text x="928" y="231.6" font-size="16" fill="#a1a1aa" text-anchor="end">confirmed_by</text><line x1="0" y1="258" x2="960" y2="258" stroke="#221e2b" stroke-width="1"/><rect x="32" y="274" width="120.8" height="32" fill="#1f1b29"/><rect x="44" y="285" width="10" height="10" fill="#f0735a"/><text x="66" y="294.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">DECLINED</text><text x="218" y="295.6" font-size="16" fill="#f4f4f5">rejectProductChangeWorkflow</text><text x="508" y="295.6" font-size="16" fill="#d4d4d8">product-change.declined</text><text x="928" y="295.6" font-size="16" fill="#a1a1aa" text-anchor="end">declined_by</text><line x1="0" y1="322" x2="960" y2="322" stroke="#221e2b" stroke-width="1"/><rect x="32" y="338" width="120.8" height="32" fill="#1f1b29"/><rect x="44" y="349" width="10" height="10" fill="#71717a"/><text x="66" y="358.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">CANCELED</text><text x="218" y="359.6" font-size="16" fill="#f4f4f5">cancelProductChangeWorkflow</text><text x="508" y="359.6" font-size="16" fill="#d4d4d8">product-change.canceled</text><text x="928" y="359.6" font-size="16" fill="#a1a1aa" text-anchor="end">canceled_by</text><line x1="0" y1="386" x2="960" y2="386" stroke="#221e2b" stroke-width="1"/></g></g><rect x="40.5" y="150.5" width="959" height="385" fill="none" stroke="#2b2636" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/product-edit-lifecycle-light.svg b/apps/docs/images/figures/product-edit-lifecycle-light.svg
new file mode 100644
index 000000000..e8143c58b
--- /dev/null
+++ b/apps/docs/images/figures/product-edit-lifecycle-light.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="580" viewBox="0 0 1040 580" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="The ProductChangeStatus table: a change enters pending through stageProductChangeWorkflow, then confirmProductChangeWorkflow, rejectProductChangeWorkflow, or cancelProductChangeWorkflow moves it to confirmed, declined, or canceled, each emitting its own event and stamping its own actor field.">
+<title>The ProductChangeStatus table: a change enters pending through stageProductChangeWorkflow, then confirmProductChangeWorkflow, rejectProductChangeWorkflow, or cancelProductChangeWorkflow moves it to confirmed, declined, or canceled, each emitting its own event and stamping its own actor field.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#18181b" flood-opacity="0.07"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#d9d9de"/></pattern><clipPath id="c1"><rect x="0" y="0" width="960" height="386"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="960" height="386"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="616" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="968.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="176.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264" y="0" width="88" height="88" fill="url(#dt)"/><rect x="352.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528" y="0" width="88" height="88" fill="#e4e4e7"/><rect x="528" y="0" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="792.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968" y="176" width="88" height="88" fill="url(#dt)"/><rect x="88.5" y="264.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="176" y="264" width="88" height="88" fill="#e4e4e7"/><rect x="176" y="264" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="880.5" y="264.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="352" y="352" width="88" height="88" fill="url(#dt)"/><rect x="968" y="352" width="88" height="88" fill="#e4e4e7"/><rect x="968" y="352" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="88" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="88" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="528" y="440" width="88" height="88" fill="url(#dt)"/><rect x="880.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616" y="528" width="88" height="88" fill="#e4e4e7"/><rect x="616" y="528" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="704.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968" y="528" width="88" height="88" fill="#e4e4e7"/><rect x="968" y="528" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="0.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528" y="616" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880" y="616" width="88" height="88" fill="#e4e4e7"/><rect x="880" y="616" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="80" y="64" width="960" height="386" fill="#ffffff" filter="url(#sh)"/><rect x="80" y="64" width="960" height="386" fill="#ffffff"/><g transform="translate(80 64)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#71717a"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">prodch_01JD8Q</text><line x1="210.4" y1="20" x2="210.4" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="242.4" y="44" font-size="17" fill="#18181b">Actions</text><rect x="224.4" y="73" width="107.4" height="3" fill="#18181b"/><text x="353.8" y="44" font-size="17" fill="#71717a">Notes</text><text x="936" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">prod_01JD8Q</text><line x1="0" y1="76" x2="960" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">ACTION</text><text x="292" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">DETAILS</text><text x="928" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">APPLIED</text><line x1="0" y1="130" x2="960" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#18181b">UPDATE</text><text x="292" y="167.6" font-size="16" fill="#18181b">{ field: "title" }</text><rect x="882" y="151" width="46" height="22" fill="#d4d4d8"/><rect x="885" y="154" width="19" height="16" fill="#ffffff"/><line x1="0" y1="194" x2="960" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">UPDATE</text><text x="292" y="231.6" font-size="16" fill="#18181b">{ field: "material" }</text><rect x="882" y="215" width="46" height="22" fill="#d4d4d8"/><rect x="885" y="218" width="19" height="16" fill="#ffffff"/><line x1="0" y1="258" x2="960" y2="258" stroke="#ededf0" stroke-width="1"/></g></g><rect x="80.5" y="64.5" width="959" height="385" fill="none" stroke="#e4e4e7" stroke-width="1"/><rect x="40" y="150" width="960" height="386" fill="#ffffff" filter="url(#sh)"/><rect x="40" y="150" width="960" height="386" fill="#ffffff"/><g transform="translate(40 150)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#7c3aed"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">ProductChangeStatus</text><line x1="275.2" y1="20" x2="275.2" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="307.2" y="44" font-size="17" fill="#18181b">Transitions</text><rect x="289.2" y="73" width="148.2" height="3" fill="#18181b"/><text x="801" y="43.3" font-size="15" fill="#3f3f46">product_request</text><rect x="741" y="27" width="46" height="22" fill="#3f7d3a"/><rect x="765" y="30" width="19" height="16" fill="#ffffff"/><line x1="0" y1="76" x2="960" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">STATUS</text><text x="218" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">REACHED BY</text><text x="508" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">EVENT</text><text x="928" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">STAMPS</text><line x1="0" y1="130" x2="960" y2="130" stroke="#ededf0" stroke-width="1"/><rect x="32" y="146" width="111.2" height="32" fill="#f4f4f5"/><rect x="44" y="157" width="10" height="10" fill="#c2680c"/><text x="66" y="166.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">PENDING</text><text x="218" y="167.6" font-size="16" fill="#18181b">stageProductChangeWorkflow</text><text x="508" y="167.6" font-size="16" fill="#3f3f46">product-change.created</text><text x="928" y="167.6" font-size="16" fill="#71717a" text-anchor="end">created_by</text><line x1="0" y1="194" x2="960" y2="194" stroke="#ededf0" stroke-width="1"/><rect x="0" y="194" width="3" height="64" fill="#7c3aed"/><rect x="32" y="210" width="130.4" height="32" fill="#f4f4f5"/><rect x="44" y="221" width="10" height="10" fill="#3f7d3a"/><text x="66" y="230.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">CONFIRMED</text><text x="218" y="231.6" font-size="16" fill="#18181b">confirmProductChangeWorkflow</text><text x="508" y="231.6" font-size="16" fill="#3f3f46">product-change.confirmed</text><text x="928" y="231.6" font-size="16" fill="#71717a" text-anchor="end">confirmed_by</text><line x1="0" y1="258" x2="960" y2="258" stroke="#ededf0" stroke-width="1"/><rect x="32" y="274" width="120.8" height="32" fill="#f4f4f5"/><rect x="44" y="285" width="10" height="10" fill="#b3361f"/><text x="66" y="294.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">DECLINED</text><text x="218" y="295.6" font-size="16" fill="#18181b">rejectProductChangeWorkflow</text><text x="508" y="295.6" font-size="16" fill="#3f3f46">product-change.declined</text><text x="928" y="295.6" font-size="16" fill="#71717a" text-anchor="end">declined_by</text><line x1="0" y1="322" x2="960" y2="322" stroke="#ededf0" stroke-width="1"/><rect x="32" y="338" width="120.8" height="32" fill="#f4f4f5"/><rect x="44" y="349" width="10" height="10" fill="#a1a1aa"/><text x="66" y="358.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">CANCELED</text><text x="218" y="359.6" font-size="16" fill="#18181b">cancelProductChangeWorkflow</text><text x="508" y="359.6" font-size="16" fill="#3f3f46">product-change.canceled</text><text x="928" y="359.6" font-size="16" fill="#71717a" text-anchor="end">canceled_by</text><line x1="0" y1="386" x2="960" y2="386" stroke="#ededf0" stroke-width="1"/></g></g><rect x="40.5" y="150.5" width="959" height="385" fill="none" stroke="#e4e4e7" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/product-edit-overview-dark.svg b/apps/docs/images/figures/product-edit-overview-dark.svg
new file mode 100644
index 000000000..0e21bba45
--- /dev/null
+++ b/apps/docs/images/figures/product-edit-overview-dark.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="640" viewBox="0 0 1040 640" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="A product's Changes list read through product.changes: a pending UPDATE from the seller sits on top of confirmed PRODUCT_ADD, CHANGE_REQUESTED, UPDATE, and STATUS_CHANGE records that form the audit trail.">
+<title>A product's Changes list read through product.changes: a pending UPDATE from the seller sits on top of confirmed PRODUCT_ADD, CHANGE_REQUESTED, UPDATE, and STATUS_CHANGE records that form the audit trail.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000000" flood-opacity="0.55"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#2c2737"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="450"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="450"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="-88" width="88" height="88" fill="#1d1926"/><rect x="1056" y="-88" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="-88" y="0" width="88" height="88" fill="#1d1926"/><rect x="-88" y="0" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="0.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="352" y="0" width="88" height="88" fill="#1d1926"/><rect x="352" y="0" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="1056.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="-87.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="0.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88" y="176" width="88" height="88" fill="url(#dt)"/><rect x="616" y="176" width="88" height="88" fill="url(#dt)"/><rect x="264" y="264" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="352.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616" y="352" width="88" height="88" fill="url(#dt)"/><rect x="968" y="352" width="88" height="88" fill="#1d1926"/><rect x="968" y="352" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="176" y="440" width="88" height="88" fill="#1d1926"/><rect x="176" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="440.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528" y="440" width="88" height="88" fill="#1d1926"/><rect x="528" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="88" y="528" width="88" height="88" fill="url(#dt)"/><rect x="352" y="528" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056" y="528" width="88" height="88" fill="#1d1926"/><rect x="1056" y="528" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="0.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440" y="616" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="616" width="88" height="88" fill="url(#dt)"/><rect x="0.5" y="704.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="352.5" y="704.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528.5" y="704.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792" y="704" width="88" height="88" fill="#1d1926"/><rect x="792" y="704" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="968.5" y="704.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="100" y="64" width="900" height="450" fill="#15121d" filter="url(#sh)"/><rect x="100" y="64" width="900" height="450" fill="#15121d"/><g transform="translate(100 64)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#6fbf68"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Linen shirt</text><line x1="188.8" y1="20" x2="188.8" y2="56" stroke="#2b2636" stroke-width="1"/><text x="220.8" y="44" font-size="17" fill="#f4f4f5">Details</text><rect x="202.8" y="73" width="107.4" height="3" fill="#f4f4f5"/><text x="332.2" y="44" font-size="17" fill="#a1a1aa">Variants</text><text x="453.8" y="44" font-size="17" fill="#a1a1aa">Attributes</text><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">prod_01JD8Q</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">FIELD</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">VALUE</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">title</text><text x="868" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">Linen shirt</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">status</text><text x="868" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">published</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">material</text><text x="868" y="295.6" font-size="16" fill="#f4f4f5" text-anchor="end">Linen</text><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/></g></g><rect x="100.5" y="64.5" width="899" height="449" fill="none" stroke="#2b2636" stroke-width="1"/><rect x="40" y="150" width="900" height="450" fill="#15121d" filter="url(#sh)"/><rect x="40" y="150" width="900" height="450" fill="#15121d"/><g transform="translate(40 150)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#a78bfa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Changes</text><line x1="145.6" y1="20" x2="145.6" y2="56" stroke="#2b2636" stroke-width="1"/><text x="177.6" y="44" font-size="17" fill="#f4f4f5">All</text><rect x="159.6" y="73" width="66.6" height="3" fill="#f4f4f5"/><text x="248.2" y="44" font-size="17" fill="#a1a1aa">Pending</text><text x="359.6" y="44" font-size="17" fill="#a1a1aa">Audit</text><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">product.changes</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">CHANGE</text><text x="212" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">ACTIONS</text><text x="502" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">BY</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">STATUS</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#a78bfa"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">prodch_05</text><text x="212" y="167.6" font-size="16" fill="#f4f4f5">UPDATE × 2</text><text x="502" y="167.6" font-size="16" fill="#f4f4f5">sel_01JD8Q</text><rect x="756.8" y="146" width="111.2" height="32" fill="#1f1b29"/><rect x="768.8" y="157" width="10" height="10" fill="#f2a14b"/><text x="790.8" y="166.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">PENDING</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#a1a1aa">prodch_04</text><text x="212" y="231.6" font-size="16" fill="#f4f4f5">STATUS_CHANGE</text><text x="502" y="231.6" font-size="16" fill="#f4f4f5">user_01JD8R</text><rect x="737.6" y="210" width="130.4" height="32" fill="#1f1b29"/><rect x="749.6" y="221" width="10" height="10" fill="#6fbf68"/><text x="771.6" y="230.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">CONFIRMED</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#a1a1aa">prodch_03</text><text x="212" y="295.6" font-size="16" fill="#f4f4f5">UPDATE</text><text x="502" y="295.6" font-size="16" fill="#f4f4f5">sel_01JD8Q</text><rect x="737.6" y="274" width="130.4" height="32" fill="#1f1b29"/><rect x="749.6" y="285" width="10" height="10" fill="#6fbf68"/><text x="771.6" y="294.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">CONFIRMED</text><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#a1a1aa">prodch_02</text><text x="212" y="359.6" font-size="16" fill="#f4f4f5">CHANGE_REQUESTED</text><text x="502" y="359.6" font-size="16" fill="#f4f4f5">user_01JD8R</text><rect x="737.6" y="338" width="130.4" height="32" fill="#1f1b29"/><rect x="749.6" y="349" width="10" height="10" fill="#6fbf68"/><text x="771.6" y="358.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">CONFIRMED</text><line x1="0" y1="386" x2="900" y2="386" stroke="#221e2b" stroke-width="1"/><text x="32" y="423.6" font-size="16" fill="#a1a1aa">prodch_01</text><text x="212" y="423.6" font-size="16" fill="#f4f4f5">PRODUCT_ADD</text><text x="502" y="423.6" font-size="16" fill="#f4f4f5">sel_01JD8Q</text><rect x="737.6" y="402" width="130.4" height="32" fill="#1f1b29"/><rect x="749.6" y="413" width="10" height="10" fill="#6fbf68"/><text x="771.6" y="422.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">CONFIRMED</text><line x1="0" y1="450" x2="900" y2="450" stroke="#221e2b" stroke-width="1"/></g></g><rect x="40.5" y="150.5" width="899" height="449" fill="none" stroke="#2b2636" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/product-edit-overview-light.svg b/apps/docs/images/figures/product-edit-overview-light.svg
new file mode 100644
index 000000000..d3306df5d
--- /dev/null
+++ b/apps/docs/images/figures/product-edit-overview-light.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="640" viewBox="0 0 1040 640" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="A product's Changes list read through product.changes: a pending UPDATE from the seller sits on top of confirmed PRODUCT_ADD, CHANGE_REQUESTED, UPDATE, and STATUS_CHANGE records that form the audit trail.">
+<title>A product's Changes list read through product.changes: a pending UPDATE from the seller sits on top of confirmed PRODUCT_ADD, CHANGE_REQUESTED, UPDATE, and STATUS_CHANGE records that form the audit trail.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#18181b" flood-opacity="0.07"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#d9d9de"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="450"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="450"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="-88" width="88" height="88" fill="#e4e4e7"/><rect x="1056" y="-88" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="-88" y="0" width="88" height="88" fill="#e4e4e7"/><rect x="-88" y="0" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="0.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="352" y="0" width="88" height="88" fill="#e4e4e7"/><rect x="352" y="0" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="1056.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="-87.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="0.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88" y="176" width="88" height="88" fill="url(#dt)"/><rect x="616" y="176" width="88" height="88" fill="url(#dt)"/><rect x="264" y="264" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="352.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616" y="352" width="88" height="88" fill="url(#dt)"/><rect x="968" y="352" width="88" height="88" fill="#e4e4e7"/><rect x="968" y="352" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="176" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="176" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="440.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="528" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="88" y="528" width="88" height="88" fill="url(#dt)"/><rect x="352" y="528" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056" y="528" width="88" height="88" fill="#e4e4e7"/><rect x="1056" y="528" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="0.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440" y="616" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="616" width="88" height="88" fill="url(#dt)"/><rect x="0.5" y="704.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="352.5" y="704.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528.5" y="704.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792" y="704" width="88" height="88" fill="#e4e4e7"/><rect x="792" y="704" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="968.5" y="704.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="100" y="64" width="900" height="450" fill="#ffffff" filter="url(#sh)"/><rect x="100" y="64" width="900" height="450" fill="#ffffff"/><g transform="translate(100 64)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#3f7d3a"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Linen shirt</text><line x1="188.8" y1="20" x2="188.8" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="220.8" y="44" font-size="17" fill="#18181b">Details</text><rect x="202.8" y="73" width="107.4" height="3" fill="#18181b"/><text x="332.2" y="44" font-size="17" fill="#71717a">Variants</text><text x="453.8" y="44" font-size="17" fill="#71717a">Attributes</text><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">prod_01JD8Q</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">FIELD</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">VALUE</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#18181b">title</text><text x="868" y="167.6" font-size="16" fill="#18181b" text-anchor="end">Linen shirt</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">status</text><text x="868" y="231.6" font-size="16" fill="#18181b" text-anchor="end">published</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">material</text><text x="868" y="295.6" font-size="16" fill="#18181b" text-anchor="end">Linen</text><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/></g></g><rect x="100.5" y="64.5" width="899" height="449" fill="none" stroke="#e4e4e7" stroke-width="1"/><rect x="40" y="150" width="900" height="450" fill="#ffffff" filter="url(#sh)"/><rect x="40" y="150" width="900" height="450" fill="#ffffff"/><g transform="translate(40 150)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#7c3aed"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Changes</text><line x1="145.6" y1="20" x2="145.6" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="177.6" y="44" font-size="17" fill="#18181b">All</text><rect x="159.6" y="73" width="66.6" height="3" fill="#18181b"/><text x="248.2" y="44" font-size="17" fill="#71717a">Pending</text><text x="359.6" y="44" font-size="17" fill="#71717a">Audit</text><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">product.changes</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">CHANGE</text><text x="212" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">ACTIONS</text><text x="502" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">BY</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">STATUS</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#7c3aed"/><text x="32" y="167.6" font-size="16" fill="#18181b">prodch_05</text><text x="212" y="167.6" font-size="16" fill="#18181b">UPDATE × 2</text><text x="502" y="167.6" font-size="16" fill="#18181b">sel_01JD8Q</text><rect x="756.8" y="146" width="111.2" height="32" fill="#f4f4f5"/><rect x="768.8" y="157" width="10" height="10" fill="#c2680c"/><text x="790.8" y="166.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">PENDING</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#71717a">prodch_04</text><text x="212" y="231.6" font-size="16" fill="#18181b">STATUS_CHANGE</text><text x="502" y="231.6" font-size="16" fill="#18181b">user_01JD8R</text><rect x="737.6" y="210" width="130.4" height="32" fill="#f4f4f5"/><rect x="749.6" y="221" width="10" height="10" fill="#3f7d3a"/><text x="771.6" y="230.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">CONFIRMED</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#71717a">prodch_03</text><text x="212" y="295.6" font-size="16" fill="#18181b">UPDATE</text><text x="502" y="295.6" font-size="16" fill="#18181b">sel_01JD8Q</text><rect x="737.6" y="274" width="130.4" height="32" fill="#f4f4f5"/><rect x="749.6" y="285" width="10" height="10" fill="#3f7d3a"/><text x="771.6" y="294.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">CONFIRMED</text><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#71717a">prodch_02</text><text x="212" y="359.6" font-size="16" fill="#18181b">CHANGE_REQUESTED</text><text x="502" y="359.6" font-size="16" fill="#18181b">user_01JD8R</text><rect x="737.6" y="338" width="130.4" height="32" fill="#f4f4f5"/><rect x="749.6" y="349" width="10" height="10" fill="#3f7d3a"/><text x="771.6" y="358.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">CONFIRMED</text><line x1="0" y1="386" x2="900" y2="386" stroke="#ededf0" stroke-width="1"/><text x="32" y="423.6" font-size="16" fill="#71717a">prodch_01</text><text x="212" y="423.6" font-size="16" fill="#18181b">PRODUCT_ADD</text><text x="502" y="423.6" font-size="16" fill="#18181b">sel_01JD8Q</text><rect x="737.6" y="402" width="130.4" height="32" fill="#f4f4f5"/><rect x="749.6" y="413" width="10" height="10" fill="#3f7d3a"/><text x="771.6" y="422.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">CONFIRMED</text><line x1="0" y1="450" x2="900" y2="450" stroke="#ededf0" stroke-width="1"/></g></g><rect x="40.5" y="150.5" width="899" height="449" fill="none" stroke="#e4e4e7" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/review-moderation-dark.svg b/apps/docs/images/figures/review-moderation-dark.svg
new file mode 100644
index 000000000..b31533e75
--- /dev/null
+++ b/apps/docs/images/figures/review-moderation-dark.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="680" viewBox="0 0 1040 680" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="Behind, a review record. In front, the changes each workflow makes: updateReviewWorkflow moves status between pending, published, and rejected in any direction, respondReviewWorkflow sets seller_note once, and deleteReviewWorkflow sets deleted_at.">
+<title>Behind, a review record. In front, the changes each workflow makes: updateReviewWorkflow moves status between pending, published, and rejected in any direction, respondReviewWorkflow sets seller_note once, and deleteReviewWorkflow sets deleted_at.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000000" flood-opacity="0.55"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#2c2737"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="450"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="450"/></clipPath></defs>
+<rect x="88" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="176" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="528" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="792" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="880" y="-88" width="88" height="88" fill="#1d1926"/><rect x="880" y="-88" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="-87.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="176" y="0" width="88" height="88" fill="url(#dt)"/><rect x="352.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880" y="0" width="88" height="88" fill="#1d1926"/><rect x="880" y="0" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="176" y="88" width="88" height="88" fill="url(#dt)"/><rect x="616" y="88" width="88" height="88" fill="#1d1926"/><rect x="616" y="88" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="968.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="-88" y="176" width="88" height="88" fill="#1d1926"/><rect x="-88" y="176" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="0.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="352.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792" y="176" width="88" height="88" fill="url(#dt)"/><rect x="968" y="176" width="88" height="88" fill="url(#dt)"/><rect x="352.5" y="264.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792.5" y="264.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="0.5" y="352.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440" y="352" width="88" height="88" fill="url(#dt)"/><rect x="704.5" y="352.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="352.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056" y="352" width="88" height="88" fill="url(#dt)"/><rect x="-88" y="440" width="88" height="88" fill="#1d1926"/><rect x="-88" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="0" y="440" width="88" height="88" fill="url(#dt)"/><rect x="176" y="440" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="-88" y="528" width="88" height="88" fill="url(#dt)"/><rect x="88.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="0" y="616" width="88" height="88" fill="url(#dt)"/><rect x="176" y="616" width="88" height="88" fill="#1d1926"/><rect x="176" y="616" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="440.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792" y="616" width="88" height="88" fill="url(#dt)"/><rect x="968.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440.5" y="704.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528" y="704" width="88" height="88" fill="url(#dt)"/><rect x="616" y="704" width="88" height="88" fill="url(#dt)"/><rect x="880" y="704" width="88" height="88" fill="url(#dt)"/><rect x="968.5" y="704.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="100" y="110" width="900" height="450" fill="#15121d" filter="url(#sh)"/><rect x="100" y="110" width="900" height="450" fill="#15121d"/><g transform="translate(100 110)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#a1a1aa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">review</text><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">Review module</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">FIELD</text><text x="332" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">VALUE</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">status</text><text x="332" y="167.6" font-size="16" fill="#a1a1aa">pending</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">seller_note</text><text x="332" y="231.6" font-size="16" fill="#a1a1aa">null</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">deleted_at</text><text x="332" y="295.6" font-size="16" fill="#a1a1aa">null</text><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/></g></g><rect x="100.5" y="110.5" width="899" height="449" fill="none" stroke="#2b2636" stroke-width="1"/><rect x="40" y="196" width="900" height="450" fill="#15121d" filter="url(#sh)"/><rect x="40" y="196" width="900" height="450" fill="#15121d"/><g transform="translate(40 196)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#a78bfa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Review changes</text><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">rev_01JD8Q1234567</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">FROM</text><text x="192" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">TO</text><text x="382" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">WORKFLOW</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">SURFACE</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#a78bfa"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">pending</text><rect x="192" y="146" width="130.4" height="32" fill="#1f1b29"/><rect x="204" y="157" width="10" height="10" fill="#6fbf68"/><text x="226" y="166.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">PUBLISHED</text><text x="382" y="167.6" font-size="16" fill="#f4f4f5">updateReviewWorkflow</text><text x="868" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">admin</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">pending</text><rect x="192" y="210" width="120.8" height="32" fill="#1f1b29"/><rect x="204" y="221" width="10" height="10" fill="#f0735a"/><text x="226" y="230.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">REJECTED</text><text x="382" y="231.6" font-size="16" fill="#f4f4f5">updateReviewWorkflow</text><text x="868" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">admin</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">published</text><rect x="192" y="274" width="111.2" height="32" fill="#1f1b29"/><rect x="204" y="285" width="10" height="10" fill="#f2a14b"/><text x="226" y="294.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">PENDING</text><text x="382" y="295.6" font-size="16" fill="#f4f4f5">updateReviewWorkflow</text><text x="868" y="295.6" font-size="16" fill="#f4f4f5" text-anchor="end">admin</text><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#a1a1aa">null</text><text x="192" y="359.6" font-size="16" fill="#d4d4d8">seller_note</text><text x="382" y="359.6" font-size="16" fill="#f4f4f5">respondReviewWorkflow</text><text x="868" y="359.6" font-size="16" fill="#f4f4f5" text-anchor="end">vendor, admin</text><line x1="0" y1="386" x2="900" y2="386" stroke="#221e2b" stroke-width="1"/><text x="32" y="423.6" font-size="16" fill="#a1a1aa">null</text><text x="192" y="423.6" font-size="16" fill="#d4d4d8">deleted_at</text><text x="382" y="423.6" font-size="16" fill="#f4f4f5">deleteReviewWorkflow</text><text x="868" y="423.6" font-size="16" fill="#f4f4f5" text-anchor="end">admin, store</text><line x1="0" y1="450" x2="900" y2="450" stroke="#221e2b" stroke-width="1"/></g></g><rect x="40.5" y="196.5" width="899" height="449" fill="none" stroke="#2b2636" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/review-moderation-light.svg b/apps/docs/images/figures/review-moderation-light.svg
new file mode 100644
index 000000000..5f9cd4c88
--- /dev/null
+++ b/apps/docs/images/figures/review-moderation-light.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="680" viewBox="0 0 1040 680" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="Behind, a review record. In front, the changes each workflow makes: updateReviewWorkflow moves status between pending, published, and rejected in any direction, respondReviewWorkflow sets seller_note once, and deleteReviewWorkflow sets deleted_at.">
+<title>Behind, a review record. In front, the changes each workflow makes: updateReviewWorkflow moves status between pending, published, and rejected in any direction, respondReviewWorkflow sets seller_note once, and deleteReviewWorkflow sets deleted_at.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#18181b" flood-opacity="0.07"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#d9d9de"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="450"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="450"/></clipPath></defs>
+<rect x="88" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="176" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="528" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="792" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="880" y="-88" width="88" height="88" fill="#e4e4e7"/><rect x="880" y="-88" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="-87.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="176" y="0" width="88" height="88" fill="url(#dt)"/><rect x="352.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880" y="0" width="88" height="88" fill="#e4e4e7"/><rect x="880" y="0" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="176" y="88" width="88" height="88" fill="url(#dt)"/><rect x="616" y="88" width="88" height="88" fill="#e4e4e7"/><rect x="616" y="88" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="968.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="-88" y="176" width="88" height="88" fill="#e4e4e7"/><rect x="-88" y="176" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="0.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="352.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792" y="176" width="88" height="88" fill="url(#dt)"/><rect x="968" y="176" width="88" height="88" fill="url(#dt)"/><rect x="352.5" y="264.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792.5" y="264.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="0.5" y="352.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440" y="352" width="88" height="88" fill="url(#dt)"/><rect x="704.5" y="352.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="352.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056" y="352" width="88" height="88" fill="url(#dt)"/><rect x="-88" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="-88" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="0" y="440" width="88" height="88" fill="url(#dt)"/><rect x="176" y="440" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="-88" y="528" width="88" height="88" fill="url(#dt)"/><rect x="88.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="0" y="616" width="88" height="88" fill="url(#dt)"/><rect x="176" y="616" width="88" height="88" fill="#e4e4e7"/><rect x="176" y="616" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="440.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792" y="616" width="88" height="88" fill="url(#dt)"/><rect x="968.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440.5" y="704.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528" y="704" width="88" height="88" fill="url(#dt)"/><rect x="616" y="704" width="88" height="88" fill="url(#dt)"/><rect x="880" y="704" width="88" height="88" fill="url(#dt)"/><rect x="968.5" y="704.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="100" y="110" width="900" height="450" fill="#ffffff" filter="url(#sh)"/><rect x="100" y="110" width="900" height="450" fill="#ffffff"/><g transform="translate(100 110)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#71717a"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">review</text><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">Review module</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">FIELD</text><text x="332" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">VALUE</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#18181b">status</text><text x="332" y="167.6" font-size="16" fill="#71717a">pending</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">seller_note</text><text x="332" y="231.6" font-size="16" fill="#71717a">null</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">deleted_at</text><text x="332" y="295.6" font-size="16" fill="#71717a">null</text><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/></g></g><rect x="100.5" y="110.5" width="899" height="449" fill="none" stroke="#e4e4e7" stroke-width="1"/><rect x="40" y="196" width="900" height="450" fill="#ffffff" filter="url(#sh)"/><rect x="40" y="196" width="900" height="450" fill="#ffffff"/><g transform="translate(40 196)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#7c3aed"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Review changes</text><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">rev_01JD8Q1234567</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">FROM</text><text x="192" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">TO</text><text x="382" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">WORKFLOW</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">SURFACE</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#7c3aed"/><text x="32" y="167.6" font-size="16" fill="#18181b">pending</text><rect x="192" y="146" width="130.4" height="32" fill="#f4f4f5"/><rect x="204" y="157" width="10" height="10" fill="#3f7d3a"/><text x="226" y="166.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">PUBLISHED</text><text x="382" y="167.6" font-size="16" fill="#18181b">updateReviewWorkflow</text><text x="868" y="167.6" font-size="16" fill="#18181b" text-anchor="end">admin</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">pending</text><rect x="192" y="210" width="120.8" height="32" fill="#f4f4f5"/><rect x="204" y="221" width="10" height="10" fill="#b3361f"/><text x="226" y="230.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">REJECTED</text><text x="382" y="231.6" font-size="16" fill="#18181b">updateReviewWorkflow</text><text x="868" y="231.6" font-size="16" fill="#18181b" text-anchor="end">admin</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">published</text><rect x="192" y="274" width="111.2" height="32" fill="#f4f4f5"/><rect x="204" y="285" width="10" height="10" fill="#c2680c"/><text x="226" y="294.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">PENDING</text><text x="382" y="295.6" font-size="16" fill="#18181b">updateReviewWorkflow</text><text x="868" y="295.6" font-size="16" fill="#18181b" text-anchor="end">admin</text><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#71717a">null</text><text x="192" y="359.6" font-size="16" fill="#3f3f46">seller_note</text><text x="382" y="359.6" font-size="16" fill="#18181b">respondReviewWorkflow</text><text x="868" y="359.6" font-size="16" fill="#18181b" text-anchor="end">vendor, admin</text><line x1="0" y1="386" x2="900" y2="386" stroke="#ededf0" stroke-width="1"/><text x="32" y="423.6" font-size="16" fill="#71717a">null</text><text x="192" y="423.6" font-size="16" fill="#3f3f46">deleted_at</text><text x="382" y="423.6" font-size="16" fill="#18181b">deleteReviewWorkflow</text><text x="868" y="423.6" font-size="16" fill="#18181b" text-anchor="end">admin, store</text><line x1="0" y1="450" x2="900" y2="450" stroke="#ededf0" stroke-width="1"/></g></g><rect x="40.5" y="196.5" width="899" height="449" fill="none" stroke="#e4e4e7" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/review-overview-dark.svg b/apps/docs/images/figures/review-overview-dark.svg
new file mode 100644
index 000000000..2c19acc02
--- /dev/null
+++ b/apps/docs/images/figures/review-overview-dark.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="600" viewBox="0 0 1040 600" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="Behind, createReviewWorkflow, which writes every review. In front, the review table: order #1001 backs a published seller review of ACME and a pending product review of the linen shirt, beside a rejected review from order #998.">
+<title>Behind, createReviewWorkflow, which writes every review. In front, the review table: order #1001 backs a published seller review of ACME and a pending product review of the linen shirt, beside a rejected review from order #998.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000000" flood-opacity="0.55"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#2c2737"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="330"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="330"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="-88" width="88" height="88" fill="#1d1926"/><rect x="1056" y="-88" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="-88" y="0" width="88" height="88" fill="#1d1926"/><rect x="-88" y="0" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="0.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="352" y="0" width="88" height="88" fill="#1d1926"/><rect x="352" y="0" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="1056.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="-87.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="0.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88" y="176" width="88" height="88" fill="url(#dt)"/><rect x="616" y="176" width="88" height="88" fill="url(#dt)"/><rect x="264" y="264" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="352.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616" y="352" width="88" height="88" fill="url(#dt)"/><rect x="968" y="352" width="88" height="88" fill="#1d1926"/><rect x="968" y="352" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="176" y="440" width="88" height="88" fill="#1d1926"/><rect x="176" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="440.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528" y="440" width="88" height="88" fill="#1d1926"/><rect x="528" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="88" y="528" width="88" height="88" fill="url(#dt)"/><rect x="352" y="528" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056" y="528" width="88" height="88" fill="#1d1926"/><rect x="1056" y="528" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="0.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88" y="616" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968" y="616" width="88" height="88" fill="url(#dt)"/><rect x="100" y="110" width="900" height="330" fill="#15121d" filter="url(#sh)"/><rect x="100" y="110" width="900" height="330" fill="#15121d"/><g transform="translate(100 110)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#a1a1aa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">createReviewWorkflow</text><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">CreateReviewDTO</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">STEP</text><text x="332" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">DOES</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">validate-review</text><text x="332" y="167.6" font-size="16" fill="#a1a1aa">order belongs to customer, no duplicate</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">create-review</text><text x="332" y="231.6" font-size="16" fill="#a1a1aa">review, customer and order links</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">create-remote-links</text><text x="332" y="295.6" font-size="16" fill="#a1a1aa">product or seller link</text><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/></g></g><rect x="100.5" y="110.5" width="899" height="329" fill="none" stroke="#2b2636" stroke-width="1"/><rect x="40" y="196" width="900" height="330" fill="#15121d" filter="url(#sh)"/><rect x="40" y="196" width="900" height="330" fill="#15121d"/><g transform="translate(40 196)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#a78bfa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Reviews</text><line x1="145.6" y1="20" x2="145.6" y2="56" stroke="#2b2636" stroke-width="1"/><text x="177.6" y="44" font-size="17" fill="#f4f4f5">All</text><rect x="159.6" y="73" width="66.6" height="3" fill="#f4f4f5"/><text x="248.2" y="44" font-size="17" fill="#a1a1aa">Product</text><text x="359.6" y="44" font-size="17" fill="#a1a1aa">Seller</text><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">rev_</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">REVIEW</text><text x="142" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">REFERENCE</text><text x="292" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">TARGET</text><text x="452" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">ORDER</text><text x="652" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">RATING</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">STATUS</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#a78bfa"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">#1043</text><text x="142" y="167.6" font-size="16" fill="#f4f4f5">seller</text><text x="292" y="167.6" font-size="16" fill="#f4f4f5">ACME</text><text x="452" y="167.6" font-size="16" fill="#f4f4f5">#1001</text><text x="652" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">5</text><rect x="737.6" y="146" width="130.4" height="32" fill="#1f1b29"/><rect x="749.6" y="157" width="10" height="10" fill="#6fbf68"/><text x="771.6" y="166.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">PUBLISHED</text><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">#1042</text><text x="142" y="231.6" font-size="16" fill="#f4f4f5">product</text><text x="292" y="231.6" font-size="16" fill="#f4f4f5">Linen shirt</text><text x="452" y="231.6" font-size="16" fill="#f4f4f5">#1001</text><text x="652" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">4</text><rect x="756.8" y="210" width="111.2" height="32" fill="#1f1b29"/><rect x="768.8" y="221" width="10" height="10" fill="#f2a14b"/><text x="790.8" y="230.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">PENDING</text><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#a1a1aa">#1041</text><text x="142" y="295.6" font-size="16" fill="#a1a1aa">product</text><text x="292" y="295.6" font-size="16" fill="#a1a1aa">Desk lamp</text><text x="452" y="295.6" font-size="16" fill="#a1a1aa">#998</text><text x="652" y="295.6" font-size="16" fill="#a1a1aa" text-anchor="end">2</text><rect x="747.2" y="274" width="120.8" height="32" fill="#1f1b29"/><rect x="759.2" y="285" width="10" height="10" fill="#f0735a"/><text x="781.2" y="294.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">REJECTED</text><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/></g></g><rect x="40.5" y="196.5" width="899" height="329" fill="none" stroke="#2b2636" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/review-overview-light.svg b/apps/docs/images/figures/review-overview-light.svg
new file mode 100644
index 000000000..6df1de8d4
--- /dev/null
+++ b/apps/docs/images/figures/review-overview-light.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="600" viewBox="0 0 1040 600" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="Behind, createReviewWorkflow, which writes every review. In front, the review table: order #1001 backs a published seller review of ACME and a pending product review of the linen shirt, beside a rejected review from order #998.">
+<title>Behind, createReviewWorkflow, which writes every review. In front, the review table: order #1001 backs a published seller review of ACME and a pending product review of the linen shirt, beside a rejected review from order #998.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#18181b" flood-opacity="0.07"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#d9d9de"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="330"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="330"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="-88" width="88" height="88" fill="#e4e4e7"/><rect x="1056" y="-88" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="-88" y="0" width="88" height="88" fill="#e4e4e7"/><rect x="-88" y="0" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="0.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="352" y="0" width="88" height="88" fill="#e4e4e7"/><rect x="352" y="0" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="1056.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="-87.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="0.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88" y="176" width="88" height="88" fill="url(#dt)"/><rect x="616" y="176" width="88" height="88" fill="url(#dt)"/><rect x="264" y="264" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="352.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616" y="352" width="88" height="88" fill="url(#dt)"/><rect x="968" y="352" width="88" height="88" fill="#e4e4e7"/><rect x="968" y="352" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="176" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="176" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="440.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="528" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="88" y="528" width="88" height="88" fill="url(#dt)"/><rect x="352" y="528" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056" y="528" width="88" height="88" fill="#e4e4e7"/><rect x="1056" y="528" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="0.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88" y="616" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968" y="616" width="88" height="88" fill="url(#dt)"/><rect x="100" y="110" width="900" height="330" fill="#ffffff" filter="url(#sh)"/><rect x="100" y="110" width="900" height="330" fill="#ffffff"/><g transform="translate(100 110)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#71717a"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">createReviewWorkflow</text><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">CreateReviewDTO</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">STEP</text><text x="332" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">DOES</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#18181b">validate-review</text><text x="332" y="167.6" font-size="16" fill="#71717a">order belongs to customer, no duplicate</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">create-review</text><text x="332" y="231.6" font-size="16" fill="#71717a">review, customer and order links</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">create-remote-links</text><text x="332" y="295.6" font-size="16" fill="#71717a">product or seller link</text><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/></g></g><rect x="100.5" y="110.5" width="899" height="329" fill="none" stroke="#e4e4e7" stroke-width="1"/><rect x="40" y="196" width="900" height="330" fill="#ffffff" filter="url(#sh)"/><rect x="40" y="196" width="900" height="330" fill="#ffffff"/><g transform="translate(40 196)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#7c3aed"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Reviews</text><line x1="145.6" y1="20" x2="145.6" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="177.6" y="44" font-size="17" fill="#18181b">All</text><rect x="159.6" y="73" width="66.6" height="3" fill="#18181b"/><text x="248.2" y="44" font-size="17" fill="#71717a">Product</text><text x="359.6" y="44" font-size="17" fill="#71717a">Seller</text><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">rev_</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">REVIEW</text><text x="142" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">REFERENCE</text><text x="292" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">TARGET</text><text x="452" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">ORDER</text><text x="652" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">RATING</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">STATUS</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#7c3aed"/><text x="32" y="167.6" font-size="16" fill="#18181b">#1043</text><text x="142" y="167.6" font-size="16" fill="#18181b">seller</text><text x="292" y="167.6" font-size="16" fill="#18181b">ACME</text><text x="452" y="167.6" font-size="16" fill="#18181b">#1001</text><text x="652" y="167.6" font-size="16" fill="#18181b" text-anchor="end">5</text><rect x="737.6" y="146" width="130.4" height="32" fill="#f4f4f5"/><rect x="749.6" y="157" width="10" height="10" fill="#3f7d3a"/><text x="771.6" y="166.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">PUBLISHED</text><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">#1042</text><text x="142" y="231.6" font-size="16" fill="#18181b">product</text><text x="292" y="231.6" font-size="16" fill="#18181b">Linen shirt</text><text x="452" y="231.6" font-size="16" fill="#18181b">#1001</text><text x="652" y="231.6" font-size="16" fill="#18181b" text-anchor="end">4</text><rect x="756.8" y="210" width="111.2" height="32" fill="#f4f4f5"/><rect x="768.8" y="221" width="10" height="10" fill="#c2680c"/><text x="790.8" y="230.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">PENDING</text><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#71717a">#1041</text><text x="142" y="295.6" font-size="16" fill="#71717a">product</text><text x="292" y="295.6" font-size="16" fill="#71717a">Desk lamp</text><text x="452" y="295.6" font-size="16" fill="#71717a">#998</text><text x="652" y="295.6" font-size="16" fill="#71717a" text-anchor="end">2</text><rect x="747.2" y="274" width="120.8" height="32" fill="#f4f4f5"/><rect x="759.2" y="285" width="10" height="10" fill="#b3361f"/><text x="781.2" y="294.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">REJECTED</text><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/></g></g><rect x="40.5" y="196.5" width="899" height="329" fill="none" stroke="#e4e4e7" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/store-lifecycle-dark.svg b/apps/docs/images/figures/store-lifecycle-dark.svg
new file mode 100644
index 000000000..c1db2afa9
--- /dev/null
+++ b/apps/docs/images/figures/store-lifecycle-dark.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="620" viewBox="0 0 1040 620" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="A Status transitions table for the Seller module listing each lifecycle workflow with the status it starts from, the status it sets, and the event it emits, with the terminate row highlighted because only a suspended or pending store can be terminated.">
+<title>A Status transitions table for the Seller module listing each lifecycle workflow with the status it starts from, the status it sets, and the event it emits, with the terminate row highlighted because only a suspended or pending store can be terminated.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000000" flood-opacity="0.55"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#2c2737"/></pattern><clipPath id="c1"><rect x="0" y="0" width="920" height="451"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="920" height="451"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="616" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="968.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="176.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264" y="0" width="88" height="88" fill="url(#dt)"/><rect x="352.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528" y="0" width="88" height="88" fill="#1d1926"/><rect x="528" y="0" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="792.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="264.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616.5" y="176.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968" y="176" width="88" height="88" fill="url(#dt)"/><rect x="88.5" y="264.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="176" y="264" width="88" height="88" fill="#1d1926"/><rect x="176" y="264" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="880.5" y="264.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="352" y="352" width="88" height="88" fill="url(#dt)"/><rect x="968" y="352" width="88" height="88" fill="#1d1926"/><rect x="968" y="352" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="88" y="440" width="88" height="88" fill="#1d1926"/><rect x="88" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="528" y="440" width="88" height="88" fill="url(#dt)"/><rect x="880.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616" y="528" width="88" height="88" fill="#1d1926"/><rect x="616" y="528" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="704.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968" y="528" width="88" height="88" fill="#1d1926"/><rect x="968" y="528" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="0.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528" y="616" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880" y="616" width="88" height="88" fill="#1d1926"/><rect x="880" y="616" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="-88" y="704" width="88" height="88" fill="#1d1926"/><rect x="-88" y="704" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="0" y="704" width="88" height="88" fill="url(#dt)"/><rect x="616" y="704" width="88" height="88" fill="url(#dt)"/><rect x="704" y="704" width="88" height="88" fill="url(#dt)"/><rect x="968.5" y="704.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="100" y="44" width="920" height="451" fill="#15121d" filter="url(#sh)"/><rect x="100" y="44" width="920" height="451" fill="#15121d"/><g transform="translate(100 44)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#f4f4f5"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">initech</text><line x1="145.6" y1="20" x2="145.6" y2="56" stroke="#2b2636" stroke-width="1"/><text x="177.6" y="44" font-size="17" fill="#a1a1aa">Details</text><text x="289" y="44" font-size="17" fill="#f4f4f5">Status</text><rect x="271" y="73" width="97.2" height="3" fill="#f4f4f5"/><text x="390.2" y="44" font-size="17" fill="#a1a1aa">Team</text><text x="896" y="43.3" font-size="15" fill="#71717a" text-anchor="end">sel_01JD8Q1234567</text><line x1="0" y1="76" x2="920" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">FIELD</text><text x="888" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">VALUE</text><line x1="0" y1="130" x2="920" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">status</text><text x="888" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">suspended</text><line x1="0" y1="194" x2="920" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">status_reason</text><text x="888" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">Chargeback review</text><line x1="0" y1="258" x2="920" y2="258" stroke="#221e2b" stroke-width="1"/></g></g><rect x="100.5" y="44.5" width="919" height="450" fill="none" stroke="#2b2636" stroke-width="1"/><rect x="40" y="130" width="920" height="451" fill="#15121d" filter="url(#sh)"/><rect x="40" y="130" width="920" height="451" fill="#15121d"/><g transform="translate(40 130)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#a78bfa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Status transitions</text><line x1="264.4" y1="20" x2="264.4" y2="56" stroke="#2b2636" stroke-width="1"/><text x="296.4" y="44" font-size="17" fill="#f4f4f5">Workflows</text><rect x="278.4" y="73" width="127.8" height="3" fill="#f4f4f5"/><text x="428.2" y="44" font-size="17" fill="#a1a1aa">Events</text><text x="896" y="43.3" font-size="15" fill="#71717a" text-anchor="end">SellerStatus</text><line x1="0" y1="76" x2="920" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">WORKFLOW</text><text x="302" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">FROM</text><text x="516" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">TO</text><text x="888" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">EVENT</text><line x1="0" y1="130" x2="920" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">approveSellerWorkflow</text><rect x="302" y="146" width="197.6" height="32" fill="#1f1b29"/><rect x="314" y="157" width="10" height="10" fill="#f2a14b"/><text x="336" y="166.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">PENDING APPROVAL</text><rect x="516" y="146" width="82.4" height="32" fill="#1f1b29"/><rect x="528" y="157" width="10" height="10" fill="#6fbf68"/><text x="550" y="166.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">OPEN</text><text x="888" y="167.6" font-size="16" fill="#a1a1aa" text-anchor="end">seller.approved</text><line x1="0" y1="194" x2="920" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">suspendSellerWorkflow</text><rect x="302" y="210" width="82.4" height="32" fill="#1f1b29"/><rect x="314" y="221" width="10" height="10" fill="#6fbf68"/><text x="336" y="230.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">OPEN</text><rect x="516" y="210" width="130.4" height="32" fill="#1f1b29"/><rect x="528" y="221" width="10" height="10" fill="#f0735a"/><text x="550" y="230.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">SUSPENDED</text><text x="888" y="231.6" font-size="16" fill="#a1a1aa" text-anchor="end">seller.suspended</text><line x1="0" y1="258" x2="920" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">unsuspendSellerWorkflow</text><rect x="302" y="274" width="130.4" height="32" fill="#1f1b29"/><rect x="314" y="285" width="10" height="10" fill="#f0735a"/><text x="336" y="294.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">SUSPENDED</text><rect x="516" y="274" width="82.4" height="32" fill="#1f1b29"/><rect x="528" y="285" width="10" height="10" fill="#6fbf68"/><text x="550" y="294.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">OPEN</text><text x="888" y="295.6" font-size="16" fill="#a1a1aa" text-anchor="end">seller.unsuspended</text><line x1="0" y1="322" x2="920" y2="322" stroke="#221e2b" stroke-width="1"/><rect x="0" y="322" width="3" height="64" fill="#a78bfa"/><text x="32" y="359.6" font-size="16" fill="#f4f4f5">terminateSellerWorkflow</text><rect x="302" y="338" width="130.4" height="32" fill="#1f1b29"/><rect x="314" y="349" width="10" height="10" fill="#f0735a"/><text x="336" y="358.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">SUSPENDED</text><rect x="516" y="338" width="140" height="32" fill="#1f1b29"/><rect x="528" y="349" width="10" height="10" fill="#71717a"/><text x="550" y="358.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">TERMINATED</text><text x="888" y="359.6" font-size="16" fill="#a1a1aa" text-anchor="end">seller.terminated</text><line x1="0" y1="386" x2="920" y2="386" stroke="#221e2b" stroke-width="1"/><text x="32" y="423.6" font-size="16" fill="#f4f4f5">unterminateSellerWorkflow</text><rect x="302" y="402" width="140" height="32" fill="#1f1b29"/><rect x="314" y="413" width="10" height="10" fill="#71717a"/><text x="336" y="422.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">TERMINATED</text><rect x="516" y="402" width="130.4" height="32" fill="#1f1b29"/><rect x="528" y="413" width="10" height="10" fill="#f0735a"/><text x="550" y="422.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">SUSPENDED</text><text x="888" y="423.6" font-size="16" fill="#a1a1aa" text-anchor="end">seller.unterminated</text><line x1="0" y1="450" x2="920" y2="450" stroke="#221e2b" stroke-width="1"/></g></g><rect x="40.5" y="130.5" width="919" height="450" fill="none" stroke="#2b2636" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/store-lifecycle-light.svg b/apps/docs/images/figures/store-lifecycle-light.svg
new file mode 100644
index 000000000..0e5b1901c
--- /dev/null
+++ b/apps/docs/images/figures/store-lifecycle-light.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="620" viewBox="0 0 1040 620" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="A Status transitions table for the Seller module listing each lifecycle workflow with the status it starts from, the status it sets, and the event it emits, with the terminate row highlighted because only a suspended or pending store can be terminated.">
+<title>A Status transitions table for the Seller module listing each lifecycle workflow with the status it starts from, the status it sets, and the event it emits, with the terminate row highlighted because only a suspended or pending store can be terminated.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#18181b" flood-opacity="0.07"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#d9d9de"/></pattern><clipPath id="c1"><rect x="0" y="0" width="920" height="451"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="920" height="451"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="616" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="968.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="176.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264" y="0" width="88" height="88" fill="url(#dt)"/><rect x="352.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528" y="0" width="88" height="88" fill="#e4e4e7"/><rect x="528" y="0" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="792.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="264.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616.5" y="176.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968" y="176" width="88" height="88" fill="url(#dt)"/><rect x="88.5" y="264.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="176" y="264" width="88" height="88" fill="#e4e4e7"/><rect x="176" y="264" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="880.5" y="264.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="352" y="352" width="88" height="88" fill="url(#dt)"/><rect x="968" y="352" width="88" height="88" fill="#e4e4e7"/><rect x="968" y="352" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="88" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="88" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="528" y="440" width="88" height="88" fill="url(#dt)"/><rect x="880.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616" y="528" width="88" height="88" fill="#e4e4e7"/><rect x="616" y="528" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="704.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968" y="528" width="88" height="88" fill="#e4e4e7"/><rect x="968" y="528" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="0.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528" y="616" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880" y="616" width="88" height="88" fill="#e4e4e7"/><rect x="880" y="616" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="-88" y="704" width="88" height="88" fill="#e4e4e7"/><rect x="-88" y="704" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="0" y="704" width="88" height="88" fill="url(#dt)"/><rect x="616" y="704" width="88" height="88" fill="url(#dt)"/><rect x="704" y="704" width="88" height="88" fill="url(#dt)"/><rect x="968.5" y="704.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="100" y="44" width="920" height="451" fill="#ffffff" filter="url(#sh)"/><rect x="100" y="44" width="920" height="451" fill="#ffffff"/><g transform="translate(100 44)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#18181b"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">initech</text><line x1="145.6" y1="20" x2="145.6" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="177.6" y="44" font-size="17" fill="#71717a">Details</text><text x="289" y="44" font-size="17" fill="#18181b">Status</text><rect x="271" y="73" width="97.2" height="3" fill="#18181b"/><text x="390.2" y="44" font-size="17" fill="#71717a">Team</text><text x="896" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">sel_01JD8Q1234567</text><line x1="0" y1="76" x2="920" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">FIELD</text><text x="888" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">VALUE</text><line x1="0" y1="130" x2="920" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#18181b">status</text><text x="888" y="167.6" font-size="16" fill="#18181b" text-anchor="end">suspended</text><line x1="0" y1="194" x2="920" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">status_reason</text><text x="888" y="231.6" font-size="16" fill="#18181b" text-anchor="end">Chargeback review</text><line x1="0" y1="258" x2="920" y2="258" stroke="#ededf0" stroke-width="1"/></g></g><rect x="100.5" y="44.5" width="919" height="450" fill="none" stroke="#e4e4e7" stroke-width="1"/><rect x="40" y="130" width="920" height="451" fill="#ffffff" filter="url(#sh)"/><rect x="40" y="130" width="920" height="451" fill="#ffffff"/><g transform="translate(40 130)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#7c3aed"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Status transitions</text><line x1="264.4" y1="20" x2="264.4" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="296.4" y="44" font-size="17" fill="#18181b">Workflows</text><rect x="278.4" y="73" width="127.8" height="3" fill="#18181b"/><text x="428.2" y="44" font-size="17" fill="#71717a">Events</text><text x="896" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">SellerStatus</text><line x1="0" y1="76" x2="920" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">WORKFLOW</text><text x="302" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">FROM</text><text x="516" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">TO</text><text x="888" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">EVENT</text><line x1="0" y1="130" x2="920" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#18181b">approveSellerWorkflow</text><rect x="302" y="146" width="197.6" height="32" fill="#f4f4f5"/><rect x="314" y="157" width="10" height="10" fill="#c2680c"/><text x="336" y="166.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">PENDING APPROVAL</text><rect x="516" y="146" width="82.4" height="32" fill="#f4f4f5"/><rect x="528" y="157" width="10" height="10" fill="#3f7d3a"/><text x="550" y="166.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">OPEN</text><text x="888" y="167.6" font-size="16" fill="#71717a" text-anchor="end">seller.approved</text><line x1="0" y1="194" x2="920" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">suspendSellerWorkflow</text><rect x="302" y="210" width="82.4" height="32" fill="#f4f4f5"/><rect x="314" y="221" width="10" height="10" fill="#3f7d3a"/><text x="336" y="230.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">OPEN</text><rect x="516" y="210" width="130.4" height="32" fill="#f4f4f5"/><rect x="528" y="221" width="10" height="10" fill="#b3361f"/><text x="550" y="230.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">SUSPENDED</text><text x="888" y="231.6" font-size="16" fill="#71717a" text-anchor="end">seller.suspended</text><line x1="0" y1="258" x2="920" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">unsuspendSellerWorkflow</text><rect x="302" y="274" width="130.4" height="32" fill="#f4f4f5"/><rect x="314" y="285" width="10" height="10" fill="#b3361f"/><text x="336" y="294.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">SUSPENDED</text><rect x="516" y="274" width="82.4" height="32" fill="#f4f4f5"/><rect x="528" y="285" width="10" height="10" fill="#3f7d3a"/><text x="550" y="294.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">OPEN</text><text x="888" y="295.6" font-size="16" fill="#71717a" text-anchor="end">seller.unsuspended</text><line x1="0" y1="322" x2="920" y2="322" stroke="#ededf0" stroke-width="1"/><rect x="0" y="322" width="3" height="64" fill="#7c3aed"/><text x="32" y="359.6" font-size="16" fill="#18181b">terminateSellerWorkflow</text><rect x="302" y="338" width="130.4" height="32" fill="#f4f4f5"/><rect x="314" y="349" width="10" height="10" fill="#b3361f"/><text x="336" y="358.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">SUSPENDED</text><rect x="516" y="338" width="140" height="32" fill="#f4f4f5"/><rect x="528" y="349" width="10" height="10" fill="#a1a1aa"/><text x="550" y="358.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">TERMINATED</text><text x="888" y="359.6" font-size="16" fill="#71717a" text-anchor="end">seller.terminated</text><line x1="0" y1="386" x2="920" y2="386" stroke="#ededf0" stroke-width="1"/><text x="32" y="423.6" font-size="16" fill="#18181b">unterminateSellerWorkflow</text><rect x="302" y="402" width="140" height="32" fill="#f4f4f5"/><rect x="314" y="413" width="10" height="10" fill="#a1a1aa"/><text x="336" y="422.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">TERMINATED</text><rect x="516" y="402" width="130.4" height="32" fill="#f4f4f5"/><rect x="528" y="413" width="10" height="10" fill="#b3361f"/><text x="550" y="422.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">SUSPENDED</text><text x="888" y="423.6" font-size="16" fill="#71717a" text-anchor="end">seller.unterminated</text><line x1="0" y1="450" x2="920" y2="450" stroke="#ededf0" stroke-width="1"/></g></g><rect x="40.5" y="130.5" width="919" height="450" fill="none" stroke="#e4e4e7" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/store-overview-dark.svg b/apps/docs/images/figures/store-overview-dark.svg
new file mode 100644
index 000000000..d42ebecf5
--- /dev/null
+++ b/apps/docs/images/figures/store-overview-dark.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="560" viewBox="0 0 1040 560" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="A Stores list from the Seller module showing four stores, each with its status, currency, member count, and premium flag, in front of the Team panel for acme-supplies with three members and their seller roles.">
+<title>A Stores list from the Seller module showing four stores, each with its status, currency, member count, and premium flag, in front of the Team panel for acme-supplies with three members and their seller roles.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000000" flood-opacity="0.55"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#2c2737"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="387"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="387"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="440" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="-87.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="-88" width="88" height="88" fill="#1d1926"/><rect x="1056" y="-88" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="-88" y="0" width="88" height="88" fill="#1d1926"/><rect x="-88" y="0" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="0.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="352" y="0" width="88" height="88" fill="#1d1926"/><rect x="352" y="0" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="1056.5" y="0.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="-87.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="0.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056.5" y="88.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88" y="176" width="88" height="88" fill="url(#dt)"/><rect x="616" y="176" width="88" height="88" fill="url(#dt)"/><rect x="264" y="264" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="352.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="616" y="352" width="88" height="88" fill="url(#dt)"/><rect x="968" y="352" width="88" height="88" fill="#1d1926"/><rect x="968" y="352" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="176" y="440" width="88" height="88" fill="#1d1926"/><rect x="176" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="440.5" y="440.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="528" y="440" width="88" height="88" fill="#1d1926"/><rect x="528" y="440" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="88" y="528" width="88" height="88" fill="url(#dt)"/><rect x="352" y="528" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="880.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="968.5" y="528.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="1056" y="528" width="88" height="88" fill="#1d1926"/><rect x="1056" y="528" width="88" height="88" fill="#a1a1aa" opacity="0.35" filter="url(#gr)"/><rect x="0.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="88" y="616" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="792" y="616" width="88" height="88" fill="url(#dt)"/><rect x="880" y="616" width="88" height="88" fill="url(#dt)"/><rect x="1056.5" y="616.5" width="87" height="87" fill="none" stroke="#1d1926" stroke-width="1"/><rect x="100" y="44" width="900" height="387" fill="#15121d" filter="url(#sh)"/><rect x="100" y="44" width="900" height="387" fill="#15121d"/><g transform="translate(100 44)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#f4f4f5"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Team</text><line x1="113.2" y1="20" x2="113.2" y2="56" stroke="#2b2636" stroke-width="1"/><text x="145.2" y="44" font-size="17" fill="#f4f4f5">Members</text><rect x="127.2" y="73" width="107.4" height="3" fill="#f4f4f5"/><text x="256.6" y="44" font-size="17" fill="#a1a1aa">Invites</text><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">acme-supplies</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">EMAIL</text><text x="332" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">ROLE</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">OWNER</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">[email protected]</text><text x="332" y="167.6" font-size="16" fill="#f4f4f5">role_seller_administration</text><rect x="822" y="151" width="46" height="22" fill="#6fbf68"/><rect x="846" y="154" width="19" height="16" fill="#15121d"/><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">[email protected]</text><text x="332" y="231.6" font-size="16" fill="#f4f4f5">role_seller_order_management</text><rect x="822" y="215" width="46" height="22" fill="#3f3a4b"/><rect x="825" y="218" width="19" height="16" fill="#15121d"/><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">[email protected]</text><text x="332" y="295.6" font-size="16" fill="#f4f4f5">role_seller_accounting</text><rect x="822" y="279" width="46" height="22" fill="#3f3a4b"/><rect x="825" y="282" width="19" height="16" fill="#15121d"/><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/></g></g><rect x="100.5" y="44.5" width="899" height="386" fill="none" stroke="#2b2636" stroke-width="1"/><rect x="40" y="130" width="900" height="387" fill="#15121d" filter="url(#sh)"/><rect x="40" y="130" width="900" height="387" fill="#15121d"/><g transform="translate(40 130)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#a78bfa"/><text x="46" y="44.3" font-size="18" fill="#f4f4f5" font-weight="500">Stores</text><line x1="134.8" y1="20" x2="134.8" y2="56" stroke="#2b2636" stroke-width="1"/><text x="166.8" y="44" font-size="17" fill="#f4f4f5">All</text><rect x="148.8" y="73" width="66.6" height="3" fill="#f4f4f5"/><text x="237.4" y="44" font-size="17" fill="#a1a1aa">Pending</text><text x="348.8" y="44" font-size="17" fill="#a1a1aa">Suspended</text><text x="876" y="43.3" font-size="15" fill="#71717a" text-anchor="end">MercurModules.SELLER</text><line x1="0" y1="76" x2="900" y2="76" stroke="#2b2636" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">HANDLE</text><text x="252" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">STATUS</text><text x="488" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2">CURRENCY</text><text x="738" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">MEMBERS</text><text x="868" y="107.9" font-size="14" fill="#a1a1aa" letter-spacing="1.2" text-anchor="end">PREMIUM</text><line x1="0" y1="130" x2="900" y2="130" stroke="#221e2b" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#a78bfa"/><text x="32" y="167.6" font-size="16" fill="#f4f4f5">acme-supplies</text><rect x="252" y="146" width="82.4" height="32" fill="#1f1b29"/><rect x="264" y="157" width="10" height="10" fill="#6fbf68"/><text x="286" y="166.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">OPEN</text><text x="488" y="167.6" font-size="16" fill="#f4f4f5">usd</text><text x="738" y="167.6" font-size="16" fill="#f4f4f5" text-anchor="end">3</text><rect x="822" y="151" width="46" height="22" fill="#6fbf68"/><rect x="846" y="154" width="19" height="16" fill="#15121d"/><line x1="0" y1="194" x2="900" y2="194" stroke="#221e2b" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#f4f4f5">globex</text><rect x="252" y="210" width="197.6" height="32" fill="#1f1b29"/><rect x="264" y="221" width="10" height="10" fill="#f2a14b"/><text x="286" y="230.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">PENDING APPROVAL</text><text x="488" y="231.6" font-size="16" fill="#f4f4f5">eur</text><text x="738" y="231.6" font-size="16" fill="#f4f4f5" text-anchor="end">1</text><rect x="822" y="215" width="46" height="22" fill="#3f3a4b"/><rect x="825" y="218" width="19" height="16" fill="#15121d"/><line x1="0" y1="258" x2="900" y2="258" stroke="#221e2b" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#f4f4f5">initech</text><rect x="252" y="274" width="130.4" height="32" fill="#1f1b29"/><rect x="264" y="285" width="10" height="10" fill="#f0735a"/><text x="286" y="294.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">SUSPENDED</text><text x="488" y="295.6" font-size="16" fill="#f4f4f5">usd</text><text x="738" y="295.6" font-size="16" fill="#f4f4f5" text-anchor="end">2</text><rect x="822" y="279" width="46" height="22" fill="#3f3a4b"/><rect x="825" y="282" width="19" height="16" fill="#15121d"/><line x1="0" y1="322" x2="900" y2="322" stroke="#221e2b" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#a1a1aa">hooli</text><rect x="252" y="338" width="140" height="32" fill="#1f1b29"/><rect x="264" y="349" width="10" height="10" fill="#71717a"/><text x="286" y="358.9" font-size="14" fill="#d4d4d8" letter-spacing="1.2">TERMINATED</text><text x="488" y="359.6" font-size="16" fill="#a1a1aa">gbp</text><text x="738" y="359.6" font-size="16" fill="#a1a1aa" text-anchor="end">1</text><rect x="822" y="343" width="46" height="22" fill="#3f3a4b"/><rect x="825" y="346" width="19" height="16" fill="#15121d"/><line x1="0" y1="386" x2="900" y2="386" stroke="#221e2b" stroke-width="1"/></g></g><rect x="40.5" y="130.5" width="899" height="386" fill="none" stroke="#2b2636" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/images/figures/store-overview-light.svg b/apps/docs/images/figures/store-overview-light.svg
new file mode 100644
index 000000000..f157274b0
--- /dev/null
+++ b/apps/docs/images/figures/store-overview-light.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="560" viewBox="0 0 1040 560" font-family="JetBrains Mono, SF Mono, SFMono-Regular, Menlo, Consolas, Liberation Mono, monospace" role="img" aria-label="A Stores list from the Seller module showing four stores, each with its status, currency, member count, and premium flag, in front of the Team panel for acme-supplies with three members and their seller roles.">
+<title>A Stores list from the Seller module showing four stores, each with its status, currency, member count, and premium flag, in front of the Team panel for acme-supplies with three members and their seller roles.</title>
+<defs><filter id="sh" x="-30%" y="-30%" width="160%" height="170%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#18181b" flood-opacity="0.07"/></filter><filter id="gr" x="0" y="0" width="100%" height="100%"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" seed="7" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/><feComponentTransfer><feFuncA type="table" tableValues="0 1"/></feComponentTransfer><feComposite in2="SourceGraphic" operator="in"/></filter><pattern id="dt" width="11" height="11" patternUnits="userSpaceOnUse"><rect x="4.5" y="4.5" width="1.6" height="1.6" fill="#d9d9de"/></pattern><clipPath id="c1"><rect x="0" y="0" width="900" height="387"/></clipPath><clipPath id="c2"><rect x="0" y="0" width="900" height="387"/></clipPath></defs>
+<rect x="-87.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="440" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="-87.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968" y="-88" width="88" height="88" fill="url(#dt)"/><rect x="1056" y="-88" width="88" height="88" fill="#e4e4e7"/><rect x="1056" y="-88" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="-88" y="0" width="88" height="88" fill="#e4e4e7"/><rect x="-88" y="0" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="0.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="352" y="0" width="88" height="88" fill="#e4e4e7"/><rect x="352" y="0" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="1056.5" y="0.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="-87.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="0.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056.5" y="88.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88" y="176" width="88" height="88" fill="url(#dt)"/><rect x="616" y="176" width="88" height="88" fill="url(#dt)"/><rect x="264" y="264" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="352.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="616" y="352" width="88" height="88" fill="url(#dt)"/><rect x="968" y="352" width="88" height="88" fill="#e4e4e7"/><rect x="968" y="352" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="176" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="176" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="440.5" y="440.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="528" y="440" width="88" height="88" fill="#e4e4e7"/><rect x="528" y="440" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="88" y="528" width="88" height="88" fill="url(#dt)"/><rect x="352" y="528" width="88" height="88" fill="url(#dt)"/><rect x="616.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="880.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="968.5" y="528.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="1056" y="528" width="88" height="88" fill="#e4e4e7"/><rect x="1056" y="528" width="88" height="88" fill="#71717a" opacity="0.22" filter="url(#gr)"/><rect x="0.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="88" y="616" width="88" height="88" fill="url(#dt)"/><rect x="264.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="792" y="616" width="88" height="88" fill="url(#dt)"/><rect x="880" y="616" width="88" height="88" fill="url(#dt)"/><rect x="1056.5" y="616.5" width="87" height="87" fill="none" stroke="#ececef" stroke-width="1"/><rect x="100" y="44" width="900" height="387" fill="#ffffff" filter="url(#sh)"/><rect x="100" y="44" width="900" height="387" fill="#ffffff"/><g transform="translate(100 44)"><g clip-path="url(#c1)"><rect x="24" y="33" width="10" height="10" fill="#18181b"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Team</text><line x1="113.2" y1="20" x2="113.2" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="145.2" y="44" font-size="17" fill="#18181b">Members</text><rect x="127.2" y="73" width="107.4" height="3" fill="#18181b"/><text x="256.6" y="44" font-size="17" fill="#71717a">Invites</text><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">acme-supplies</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">EMAIL</text><text x="332" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">ROLE</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">OWNER</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><text x="32" y="167.6" font-size="16" fill="#18181b">[email protected]</text><text x="332" y="167.6" font-size="16" fill="#18181b">role_seller_administration</text><rect x="822" y="151" width="46" height="22" fill="#3f7d3a"/><rect x="846" y="154" width="19" height="16" fill="#ffffff"/><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">[email protected]</text><text x="332" y="231.6" font-size="16" fill="#18181b">role_seller_order_management</text><rect x="822" y="215" width="46" height="22" fill="#d4d4d8"/><rect x="825" y="218" width="19" height="16" fill="#ffffff"/><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">[email protected]</text><text x="332" y="295.6" font-size="16" fill="#18181b">role_seller_accounting</text><rect x="822" y="279" width="46" height="22" fill="#d4d4d8"/><rect x="825" y="282" width="19" height="16" fill="#ffffff"/><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/></g></g><rect x="100.5" y="44.5" width="899" height="386" fill="none" stroke="#e4e4e7" stroke-width="1"/><rect x="40" y="130" width="900" height="387" fill="#ffffff" filter="url(#sh)"/><rect x="40" y="130" width="900" height="387" fill="#ffffff"/><g transform="translate(40 130)"><g clip-path="url(#c2)"><rect x="24" y="33" width="10" height="10" fill="#7c3aed"/><text x="46" y="44.3" font-size="18" fill="#18181b" font-weight="500">Stores</text><line x1="134.8" y1="20" x2="134.8" y2="56" stroke="#e4e4e7" stroke-width="1"/><text x="166.8" y="44" font-size="17" fill="#18181b">All</text><rect x="148.8" y="73" width="66.6" height="3" fill="#18181b"/><text x="237.4" y="44" font-size="17" fill="#71717a">Pending</text><text x="348.8" y="44" font-size="17" fill="#71717a">Suspended</text><text x="876" y="43.3" font-size="15" fill="#a1a1aa" text-anchor="end">MercurModules.SELLER</text><line x1="0" y1="76" x2="900" y2="76" stroke="#e4e4e7" stroke-width="1"/><text x="32" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">HANDLE</text><text x="252" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">STATUS</text><text x="488" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2">CURRENCY</text><text x="738" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">MEMBERS</text><text x="868" y="107.9" font-size="14" fill="#71717a" letter-spacing="1.2" text-anchor="end">PREMIUM</text><line x1="0" y1="130" x2="900" y2="130" stroke="#ededf0" stroke-width="1"/><rect x="0" y="130" width="3" height="64" fill="#7c3aed"/><text x="32" y="167.6" font-size="16" fill="#18181b">acme-supplies</text><rect x="252" y="146" width="82.4" height="32" fill="#f4f4f5"/><rect x="264" y="157" width="10" height="10" fill="#3f7d3a"/><text x="286" y="166.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">OPEN</text><text x="488" y="167.6" font-size="16" fill="#18181b">usd</text><text x="738" y="167.6" font-size="16" fill="#18181b" text-anchor="end">3</text><rect x="822" y="151" width="46" height="22" fill="#3f7d3a"/><rect x="846" y="154" width="19" height="16" fill="#ffffff"/><line x1="0" y1="194" x2="900" y2="194" stroke="#ededf0" stroke-width="1"/><text x="32" y="231.6" font-size="16" fill="#18181b">globex</text><rect x="252" y="210" width="197.6" height="32" fill="#f4f4f5"/><rect x="264" y="221" width="10" height="10" fill="#c2680c"/><text x="286" y="230.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">PENDING APPROVAL</text><text x="488" y="231.6" font-size="16" fill="#18181b">eur</text><text x="738" y="231.6" font-size="16" fill="#18181b" text-anchor="end">1</text><rect x="822" y="215" width="46" height="22" fill="#d4d4d8"/><rect x="825" y="218" width="19" height="16" fill="#ffffff"/><line x1="0" y1="258" x2="900" y2="258" stroke="#ededf0" stroke-width="1"/><text x="32" y="295.6" font-size="16" fill="#18181b">initech</text><rect x="252" y="274" width="130.4" height="32" fill="#f4f4f5"/><rect x="264" y="285" width="10" height="10" fill="#b3361f"/><text x="286" y="294.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">SUSPENDED</text><text x="488" y="295.6" font-size="16" fill="#18181b">usd</text><text x="738" y="295.6" font-size="16" fill="#18181b" text-anchor="end">2</text><rect x="822" y="279" width="46" height="22" fill="#d4d4d8"/><rect x="825" y="282" width="19" height="16" fill="#ffffff"/><line x1="0" y1="322" x2="900" y2="322" stroke="#ededf0" stroke-width="1"/><text x="32" y="359.6" font-size="16" fill="#71717a">hooli</text><rect x="252" y="338" width="140" height="32" fill="#f4f4f5"/><rect x="264" y="349" width="10" height="10" fill="#a1a1aa"/><text x="286" y="358.9" font-size="14" fill="#3f3f46" letter-spacing="1.2">TERMINATED</text><text x="488" y="359.6" font-size="16" fill="#71717a">gbp</text><text x="738" y="359.6" font-size="16" fill="#71717a" text-anchor="end">1</text><rect x="822" y="343" width="46" height="22" fill="#d4d4d8"/><rect x="825" y="346" width="19" height="16" fill="#ffffff"/><line x1="0" y1="386" x2="900" y2="386" stroke="#ededf0" stroke-width="1"/></g></g><rect x="40.5" y="130.5" width="899" height="386" fill="none" stroke="#e4e4e7" stroke-width="1"/>
+</svg>
\ No newline at end of file
diff --git a/apps/docs/platform/attribute/concepts/attribute-types.mdx b/apps/docs/platform/attribute/concepts/attribute-types.mdx
index fc61beecc..679fa13b4 100644
--- a/apps/docs/platform/attribute/concepts/attribute-types.mdx
+++ b/apps/docs/platform/attribute/concepts/attribute-types.mdx
@@ -1,59 +1,86 @@
---
-title: "Attribute types"
+title: "Attribute types and values"
sidebarTitle: "Attribute types"
-description: "The five attribute types and the values they hold."
+description: "The five attribute types, how each one stores its values, and the flags every attribute carries."
---
-In this document, you'll learn about the attribute record, its five types, and
-the values attached to it.
-
-## Product attribute
-
-An attribute is a typed field in the shared catalog, represented by the
-`ProductAttribute` data model (table `product_attribute`, id prefix `pattr`).
-Each attribute carries a `name`, an optional `handle`, a `rank` for ordering, and
-a `type` that decides how its values are validated and rendered.
-
-```ts
-const { result } = await createProductAttributesWorkflow(container).run({
- input: {
- attributes: [
- {
- name: "Material",
- type: "single_select",
- values: [{ name: "Cotton" }, { name: "Wool" }],
- },
- ],
- },
-})
+An attribute is a typed field in the shared catalog, and its type decides what a product can hold for it: a choice from a list, free text, a measurement, or a yes/no flag. Picking the right type matters because it fixes how values are stored and linked, and you can’t change it once the attribute exists.
+
+## The attribute record
+
+Every attribute is a `ProductAttribute` record (id prefix `pattr`) with a `name`, a `type`, and a few flags. Its selectable choices are separate `ProductAttributeValue` records (id prefix `pattrval`) that belong to it and are deleted with it.
+
+```ts title="src/scripts/seed-attributes.ts"
+import type { ExecArgs } from "@medusajs/framework/types"
+import { AttributeType } from "@mercurjs/types"
+import { createProductAttributesWorkflow } from "@mercurjs/core/workflows"
+
+export default async function seedAttributes({ container }: ExecArgs) {
+ await createProductAttributesWorkflow(container).run({
+ input: {
+ attributes: [
+ {
+ name: "Material",
+ type: AttributeType.SINGLE_SELECT,
+ values: [{ name: "Cotton" }, { name: "Linen" }],
+ },
+ ],
+ },
+ })
+}
```
-The `type` field is one of the `AttributeType` enum values:
+The script creates one global `single_select` attribute with two values. Because no `handle` is passed, the module derives `material` from the name.
-| Type | Value | Holds |
-| --- | --- | --- |
-| Single select | `single_select` | One choice from a fixed list of values |
-| Multi select | `multi_select` | Several choices from a fixed list of values |
-| Text | `text` | A free-form string |
-| Unit | `unit` | A numeric measurement (e.g. weight, capacity) |
-| Toggle | `toggle` | A boolean, backed by seeded `true` / `false` values |
+## The five types
+
+The `type` field takes one of the `AttributeType` enum values. Each type stores what a product holds in a different way:
+
+| Type | Enum | A product holds | Where the value comes from |
+| --- | --- | --- | --- |
+| Single select | `single_select` | One choice from a fixed list | Values you create on the attribute |
+| Multi select | `multi_select` | Several choices from a fixed list | Values you create on the attribute |
+| Text | `text` | A free-form string | A new value created when you attach it |
+| Unit | `unit` | A measurement, such as `400` | A new value created when you attach it |
+| Toggle | `toggle` | `true` or `false` | The two values seeded when the attribute is created |
+
+Only a `multi_select` attribute can be a [variant axis](/platform/attribute/concepts/variant-axes). The other four types describe a product but never shape its variants.
+
+## How values link to products
-## Product attribute value
+A product doesn’t store attribute data on itself. Instead, each value it holds is linked to it through the product to value pivot link, and the shape of that link depends on the type:
-The choices for select-style attributes are `ProductAttributeValue` records
-(table `product_attribute_value`, id prefix `pattrval`). Each value belongs to
-one attribute (`attribute_id`), has its own `name`, `handle`, and `rank`, and is
-deleted along with its parent attribute.
+- **Select types**: the product links to existing values you pick by id
+- **Text and unit**: attaching creates a new `ProductAttributeValue` named after the entered content, for example `"400"`, and links it
+- **Toggle**: the product links to the seeded `"true"` or `"false"` value, and no new value is ever created
<Note>
- `single_select` and `multi_select` attributes hold a list of predefined
- `ProductAttributeValue` records. `text` and `unit` create a value on the fly
- from the entered content when attached to a product. `toggle` is seeded with
- its `true` / `false` values and never creates new ones.
+ `unit` stores the number as the value’s `name` string. The attribute has no separate unit-of-measure field, so put the unit in the attribute name, for example “Weight (kg)”.
</Note>
-<Tip>
- Use `is_required` to enforce that a product must carry a value for the
- attribute, and `is_active` to retire an attribute from new use without deleting
- its history.
-</Tip>
+## Rules the module enforces
+
+The Product Attribute service adds a few rules on top of the generated CRUD methods:
+
+- **Type is fixed**: `updateProductAttributes` throws when you try to change the `type` of an existing attribute
+- **Handles are derived**: a global attribute without a `handle` gets one from its name, and global select values get one from theirs
+- **Handles are unique**: attribute handles are unique across the catalog, and value handles are unique per attribute
+- **Toggle values are seeded**: creating a `toggle` attribute adds its `true` (rank 0) and `false` (rank 1) values
+
+## Flags on every attribute
+
+Each attribute carries flags that control where it shows up and how it’s treated:
+
+| Field | Default | Effect |
+| --- | --- | --- |
+| `is_required` | `false` | The attachment workflows refuse to remove the attribute from a product |
+| `is_filterable` | `false` | Marks the attribute as a storefront facet |
+| `is_variant_axis` | `false` | Makes a `multi_select` attribute generate a `ProductOption` |
+| `is_active` | `true` | A status flag you can filter attribute lists by |
+| `rank` | `0` | Sort order for attributes and for values within an attribute |
+
+## Related
+
+- [Variant axes and Medusa product options](/platform/attribute/concepts/variant-axes)
+- [Global and inline attributes](/platform/attribute/concepts/global-vs-inline)
+- [Every field on the data models](/platform/attribute/reference/data-models)
diff --git a/apps/docs/platform/attribute/concepts/global-vs-inline.mdx b/apps/docs/platform/attribute/concepts/global-vs-inline.mdx
index 3e8454c26..d598276d9 100644
--- a/apps/docs/platform/attribute/concepts/global-vs-inline.mdx
+++ b/apps/docs/platform/attribute/concepts/global-vs-inline.mdx
@@ -1,50 +1,72 @@
---
-title: "Global vs inline & filtering"
+title: "Global and inline attributes"
sidebarTitle: "Global vs inline"
-description: "Catalog-wide attributes, product-scoped attributes, and storefront filtering."
+description: "Catalog-wide attributes, attributes scoped to one product, category scoping, and storefront filters."
---
-In this document, you'll learn the difference between global and inline
-attributes and how an attribute becomes a storefront filter.
+Every attribute is either global, a catalog entry any product can reuse, or inline, a one-off field created on a single product. Global attributes keep the catalog consistent across stores. Inline attributes cover the odd field one product needs without adding noise to the shared vocabulary.
-## Scope
+## Scope is decided by product_id
-Every `ProductAttribute` is either **global** or **inline**, decided by its
-`product_id` field:
+The `product_id` field on `ProductAttribute` decides the scope. It’s `null` for a global attribute and holds the product’s id for an inline one:
-| Scope | `product_id` | Meaning |
-| --- | --- | --- |
-| Global | `null` | A catalog entry, reusable across any product, listed in the operator's attribute catalog |
-| Inline | set | A one-off attribute scoped to a single product, created from that product's form and hidden from the global catalog |
+| Scope | `product_id` | Created by | Listed in the catalog |
+| --- | --- | --- | --- |
+| Global | `null` | `createProductAttributesWorkflow` | Yes |
+| Inline | `prod_…` | An inline entry in a product’s `add` list | No |
+
+The admin, vendor, and store attribute list routes all filter on `product_id: null`, so inline attributes never appear in the catalog. You read them from the product through the `scoped_attributes` link instead.
```ts
-// Global: reusable across the catalog
-{ name: "Material", type: "single_select", values: [{ name: "Cotton" }] }
+const { data: [product] } = await query.graph({
+ entity: "product",
+ fields: ["id", "scoped_attributes.name", "scoped_attributes.values.name"],
+ filters: { id: "prod_01JD8Q1234567" },
+})
+```
+
+## Create an inline attribute
+
+You create an inline attribute while you attach it. An `add` entry with a `title` instead of an `id` creates a product-scoped attribute, its values, and the links in one step:
-// Inline: scoped to one product, created as it's attached
-{ title: "Gift wrap", type: "toggle", product_id: "prod_123" }
+```ts
+await createAndLinkProductAttributesToProductWorkflow(container).run({
+ input: {
+ product_id: "prod_01JD8Q1234567",
+ add: [{ title: "Gift wrap", value: true }],
+ },
+})
```
-A global attribute is defined once and attached to many products. An inline
-attribute is created in the same step it is attached and only ever describes that
-one product. It is useful for the occasional one-off field that doesn't belong in
-the shared vocabulary.
+When you omit `type`, the workflow infers it: `is_variant_axis: true` makes a `multi_select` axis, a boolean `value` makes a `toggle`, and anything else makes a `text` attribute. Inline attributes get no derived handle, so their names never clash with the catalog.
+
+The two scopes behave differently over their life:
+
+- **Rename**: an `update` entry with a `title` renames an inline attribute and, for an axis, its exclusive option, but it’s ignored for a global attribute
+- **Remove**: removing an inline attribute from its product deletes the attribute and its values, while removing a global one drops the product’s value links and, for an axis, detaches the option
+- **Delete**: `deleteProductAttributesWorkflow` refuses to delete a global attribute while any of its values are linked to a product
-<Note>
- Attributes describe products in the **shared master catalog**. They are never
- owned by a store. A seller sells against a master product through an offer, and
- the product's attributes come from the catalog, not from the seller.
-</Note>
+## Scope global attributes to categories
-## Filtering
+A global attribute can link to product categories through the `categories` link. The admin and vendor attribute lists accept a `product_category_id` filter and return two groups: attributes linked to that category, and attributes linked to no category at all. Category links change where an attribute is offered:
-An attribute with `is_filterable` set to `true` is exposed as a storefront
-filter, letting shoppers narrow the catalog by its values. Leave it `false` for
-descriptive-only attributes that shouldn't appear as facets.
+- **No categories**: the attribute is offered for every product
+- **One or more categories**: the attribute is offered only for products in those categories
+
+Pass `category_ids` to `createProductAttributesWorkflow` to create the links with the attribute.
+
+## Storefront filters
+
+Shoppers filter `GET /store/products` with `attributes[<handle>]=value` query parameters. The store middleware turns each one into a filter on `variants.options.value`, so filtering works on variant axis values. Several values for one attribute are OR’d, and separate attributes are AND’d.
+
+`is_filterable` doesn’t change that query. It’s a flag your storefront reads from the store attribute list to decide which attributes to render as facets.
<Tip>
- Filtering pairs naturally with variant axes: a filterable `multi_select` axis
- like Color both generates variants and lets shoppers filter by them. A
- descriptive `text` attribute like Care instructions is usually left
- non-filterable.
+ Mark axes such as Size and Color as filterable. Descriptive `text` attributes such as care instructions aren’t variant options, so the product filter can’t match them.
</Tip>
+
+## Related
+
+- [Attach attributes to a product](/platform/attribute/guides/attach-attributes-to-a-product)
+- [Variant axes and Medusa product options](/platform/attribute/concepts/variant-axes)
+- [The scoped_attributes and categories links](/platform/attribute/reference/links)
diff --git a/apps/docs/platform/attribute/concepts/variant-axes.mdx b/apps/docs/platform/attribute/concepts/variant-axes.mdx
index eca610346..88625fc99 100644
--- a/apps/docs/platform/attribute/concepts/variant-axes.mdx
+++ b/apps/docs/platform/attribute/concepts/variant-axes.mdx
@@ -1,20 +1,24 @@
---
-title: "Variant axes"
+title: "Variant axes and product options"
sidebarTitle: "Variant axes"
-description: "How is_variant_axis mirrors a native ProductOption and generates variants."
+description: "How a multi_select axis attribute mirrors a native Medusa ProductOption, and how products pick a subset of its values."
---
-In this document, you'll learn how an attribute becomes the axis a product's
-variants are generated from, and the mirror links that keep the two in sync.
+A variant axis is a `multi_select` attribute that a product varies along, such as Size or Color. Mercur doesn’t invent its own variant system: each axis is backed by a native Medusa `ProductOption`, so variants, carts, and orders keep working the way Medusa expects while operators manage sizes and colors as catalog attributes.
-## Variant-axis attribute
+<img className="block dark:hidden" src="/images/figures/attribute-variant-axis-light.svg" alt="The Size axis attribute maps each value to a Medusa option value, S to optval_01JD8Q1 and so on, and the Linen shirt selects only S and M, so its variants behind it are S and M." />
+<img className="hidden dark:block" src="/images/figures/attribute-variant-axis-dark.svg" alt="The Size axis attribute maps each value to a Medusa option value, S to optval_01JD8Q1 and so on, and the Linen shirt selects only S and M, so its variants behind it are S and M." />
-A `multi_select` attribute marked `is_variant_axis` is more than a descriptor.
-It defines a dimension along which a product varies, such as Size or Color. When
-such an attribute is created, the `ProductAttribute` model records the id of a native
-Medusa `ProductOption` in its `product_option_id` field, and each of its
-`ProductAttributeValue`s records the matching `ProductOptionValue` id in
-`product_option_value_id`.
+## The option mirror
+
+When you create a `multi_select` attribute with `is_variant_axis: true`, `createProductAttributesWorkflow` first creates a Medusa `ProductOption` (id prefix `opt`) titled with the attribute’s name. It then stores the option’s id on the attribute and each option value’s id on the matching attribute value.
+
+| Attribute side | Field | Medusa side |
+| --- | --- | --- |
+| `ProductAttribute` | `product_option_id` | `ProductOption` |
+| `ProductAttributeValue` | `product_option_value_id` | `ProductOptionValue` (id prefix `optval`) |
+
+The workflows keep the two sides in step. Renaming the attribute renames the option, and adding, renaming, or deleting values rewrites the option’s value list. Deleting the attribute deletes the option.
```ts
await createProductAttributesWorkflow(container).run({
@@ -22,7 +26,7 @@ await createProductAttributesWorkflow(container).run({
attributes: [
{
name: "Size",
- type: "multi_select",
+ type: AttributeType.MULTI_SELECT,
is_variant_axis: true,
values: [{ name: "S" }, { name: "M" }, { name: "L" }],
},
@@ -31,31 +35,49 @@ await createProductAttributesWorkflow(container).run({
})
```
-Because the attribute mirrors a real `ProductOption`, the values a product
-selects along that axis are exactly what Medusa uses to generate its variants.
+This run creates the `Size` attribute, a global `Size` option with values `S`, `M`, and `L`, and three attribute values pointing at those option values.
-## Mirror links
+## Global options and exclusive options
-The attribute catalog and Medusa's product options are two separate modules, so
-the relationship is kept as a pair of **read-only mirror links**:
+Since Medusa 2.16, a product option can be shared by several products, and products attach to it. Mercur uses both kinds of option Medusa offers:
-| Mirror | FK on the attribute side | Points to |
-| --- | --- | --- |
-| Attribute → option | `ProductAttribute.product_option_id` | `ProductOption` |
-| Value → option value | `ProductAttributeValue.product_option_value_id` | `ProductOptionValue` |
+| Axis | Option created | `is_exclusive` | Shared by |
+| --- | --- | --- | --- |
+| Global axis attribute | When the attribute is created | `false` | Every product that attaches the axis |
+| Inline axis attribute | When it’s added to one product | `true` | Only that product |
+
+Medusa keeps titles of non-exclusive options unique, so two global axis attributes can’t share a name. Inline axes use exclusive options, so two products can each have their own “Cut” axis.
+
+## A product picks a subset of values
+
+A global axis holds every value the marketplace supports, but one product rarely uses all of them. When you attach the axis with `value_ids`, the workflow links the option to the product with only the matching option values, and it also links those attribute values to the product through the pivot link.
+
+```ts
+await createAndLinkProductAttributesToProductWorkflow(container).run({
+ input: {
+ product_id: "prod_01JD8Q1234567",
+ add: [
+ {
+ id: "pattr_01JD8Q1234567",
+ value_ids: ["pattrval_01JD8Q1234567", "pattrval_01JD8Q1234568"],
+ },
+ ],
+ },
+})
+```
+
+The product now has the `Size` option restricted to two values. You change the subset later with an `update` entry. The workflow moves the option values and the pivot links together.
-Both are 1:1 and have no pivot table. The foreign key lives on the attribute
-record itself.
+## Variants bind to the option by title
+
+Attaching an axis doesn’t create variants. You create variants yourself, and each one names its option values by option title, for example `options: { Size: "M" }`. Mercur’s `createProductsWorkflow` takes `attributes` and `variants` together, attaches the axes first, and then creates the variants against them.
<Note>
- The mirror links are **read-only**. They're resolved from the FK on the
- attribute record; you never write the relationship through the link. The
- workflows keep the option and the attribute in step whenever an axis attribute
- or its values change.
+ A product with no axis still needs an option for Medusa to accept variants. `createProductsWorkflow` gives every new product a placeholder `__default__` option and removes it once a real axis is attached.
</Note>
-<Tip>
- Only `multi_select` attributes can be variant axes. The other four types
- (`single_select`, `text`, `unit`, `toggle`) describe a product but never
- generate variants.
-</Tip>
+## Related
+
+- [Create a variant axis and build variants on it](/platform/attribute/guides/create-a-variant-axis)
+- [The read-only mirror links](/platform/attribute/reference/links)
+- [Global and inline attributes](/platform/attribute/concepts/global-vs-inline)
diff --git a/apps/docs/platform/attribute/guides/attach-attributes-to-a-product.mdx b/apps/docs/platform/attribute/guides/attach-attributes-to-a-product.mdx
index ad0aba967..c2d2b6100 100644
--- a/apps/docs/platform/attribute/guides/attach-attributes-to-a-product.mdx
+++ b/apps/docs/platform/attribute/guides/attach-attributes-to-a-product.mdx
@@ -1,69 +1,112 @@
---
title: "Attach attributes to a product"
sidebarTitle: "Attach to a product"
-description: "Attach, detach, and update a product's attributes in one batch call."
+description: "Attach, detach, and update a product's attributes in one run of the batch workflow."
---
-In this guide, you'll learn how to manage all of a product's attributes from
-server code through a single batch workflow.
+Manage every attribute on a product from server code with one workflow, `createAndLinkProductAttributesToProductWorkflow`, the same engine behind the admin attribute batch route.
-Mercur exposes `createAndLinkProductAttributesToProductWorkflow`, the engine
-behind the product attribute batch endpoint. One call can attach new attributes,
-detach existing ones, and update selections, applied in the order
-**remove → add → update** so a same-call remove and re-add of one attribute
-resolves correctly.
+## Before you begin
+
+You need the following:
+
+- **A product**: the id of a product in the shared catalog, such as `prod_01JD8Q1234567`
+- **Global attributes**: the ids of the catalog attributes and values you want to attach, created as in [Create a catalog attribute](/platform/attribute/guides/create-an-attribute)
## Run the batch workflow
-```ts title="src/api/custom/products/[id]/attributes/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { createAndLinkProductAttributesToProductWorkflow } from "@mercurjs/core/workflows"
-
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
- await createAndLinkProductAttributesToProductWorkflow(req.scope).run({
- input: {
- product_id: req.params.id,
- add: [
- // Existing select attribute: link chosen values
- { id: "pattr_material", value_ids: ["pattrval_cotton"] },
- // Existing text / unit / toggle attribute: set a scalar
- { id: "pattr_thread_count", value: 400 },
- // Inline attribute created and attached in one step
- { title: "Gift wrap", type: "toggle", value: true },
+<Steps>
+ <Step title="Send add, remove, and update in one input">
+ The workflow applies `remove`, then `add`, then `update`, so removing and re-adding the same attribute in one run works.
+
+ ```ts title="src/api/admin/catalog-import/products/[id]/route.ts"
+ import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+ import {
+ createAndLinkProductAttributesToProductWorkflow,
+ } from "@mercurjs/core/workflows"
+
+ export async function POST(req: MedusaRequest, res: MedusaResponse) {
+ await createAndLinkProductAttributesToProductWorkflow(req.scope).run({
+ input: {
+ product_id: req.params.id,
+ add: [
+ { id: "pattr_01JD8Q1234561", value_ids: ["pattrval_01JD8Q1234561"] },
+ { id: "pattr_01JD8Q1234562", value: 400 },
+ { title: "Gift wrap", value: true },
+ ],
+ remove: ["pattr_01JD8Q1234563"],
+ },
+ })
+
+ res.sendStatus(200)
+ }
+ ```
+
+ The first entry picks a value of a select attribute, the second sets a `unit` attribute to `400`, and the third creates an inline `toggle` attribute on this product.
+ </Step>
+ <Step title="Read the attributes back">
+ A product holds its selections as linked values. Read them through the `product_attribute_values` link, and read inline attributes through `scoped_attributes`.
+
+ ```ts
+ const query = req.scope.resolve("query")
+
+ const { data: [product] } = await query.graph({
+ entity: "product",
+ fields: [
+ "product_attribute_values.name",
+ "product_attribute_values.attribute.name",
+ "scoped_attributes.name",
],
- remove: ["pattr_legacy_field"],
- update: [{ id: "pattr_color", add: ["pattrval_blue"], remove: ["pattrval_red"] }],
- },
- })
+ filters: { id: req.params.id },
+ })
+ ```
- res.sendStatus(200)
-}
-```
+ Inline attributes also show up under `product_attribute_values`, because their values link to the product the same way.
+ </Step>
+</Steps>
-## The three operations
+## Choose the add form
-Each entry in `add` is one of the `ProductAttributeBatchAdd` forms:
+Each `add` entry is a `ProductAttributeBatchAdd`. The keys you pass decide what the workflow does:
| Form | Shape | Effect |
| --- | --- | --- |
-| Existing select / axis | `{ id, value_ids }` | Links the referenced values to the product |
-| Existing text / unit / toggle | `{ id, value }` | `text`/`unit` create and link a value; `toggle` links the seeded `true`/`false` value |
-| Inline axis | `{ title, values, is_variant_axis: true }` | Creates an exclusive option, a scoped attribute, and the value mirror |
-| Inline non-axis | `{ title, type, value \| values }` | Creates a scoped attribute plus its value(s) and links them |
-
-`remove` takes attribute ids to detach; `update` carries
-`ProductAttributeBatchUpdate` entries adjusting an existing selection.
-
-<Note>
- For a variant-axis attribute, `value_ids` is the per-product **subset** of the
- mirror option's values. The product's variants are generated from exactly that
- subset. See [Variant axes](/platform/attribute/concepts/variant-axes).
-</Note>
-
-<Tip>
- The batch workflow composes the lower-level
- `addProductAttributesToProductWorkflow`,
- `removeProductAttributesFromProductWorkflow`, and
- `updateProductAttributesOnProductWorkflow`. Reach for those directly when you
- only need one of the three operations.
-</Tip>
+| Existing select | `{ id, value_ids }` | Links the chosen values to the product |
+| Existing axis | `{ id, value_ids }` | Attaches the global option with only those values, and links the values |
+| Existing text or unit | `{ id, value }` | Creates a value named `String(value)` and links it |
+| Existing toggle | `{ id, value }` | Links the seeded `"true"` or `"false"` value |
+| Inline attribute | `{ title, type?, value }` or `{ title, type?, values }` | Creates a product-scoped attribute and its values, and links them |
+| Inline axis | `{ title, values, is_variant_axis: true }` | Creates an exclusive option, a scoped `multi_select` attribute, and the mirrored values |
+
+## Change a selection with update
+
+An `update` entry targets one attribute by `id`. What `add` and `remove` mean depends on the attribute:
+
+- **Global select or axis**: `add` and `remove` hold attribute value ids, and an axis also moves the option values
+- **Global select or axis, full set**: `value_ids` is the complete set the product should hold, and the workflow works out the difference
+- **Inline axis**: `add` holds new values such as `{ value: "XL" }`, and `remove` holds attribute value ids to delete
+- **Text, unit, or toggle**: `value` replaces the current value
+- **Inline rename**: `title` renames an inline attribute, and it’s ignored for global ones
+
+```ts
+update: [
+ { id: "pattr_01JD8Q1234561", value_ids: ["pattrval_01JD8Q1234562"] },
+ { id: "pattr_01JD8Q1234564", title: "Fit", add: [{ value: "Relaxed" }] },
+]
+```
+
+The first entry swaps the product to a different value. The second renames an inline axis and adds a value to its exclusive option.
+
+## Handle a required attribute
+
+Removing an attribute with `is_required: true` fails with a `NOT_ALLOWED` error, and nothing in the run is applied. The check skips attributes you remove and re-add in the same run, so you can replace a required attribute’s selection in one call.
+
+## Route vendor edits through review
+
+Running the batch workflow writes to the product immediately. For changes a store makes, run `productEditUpdateAttributesWorkflow` with the same `add`, `remove`, and `update` plus `created_by`. It stages a product change for review, and the change runs the batch workflow when it’s confirmed. See [Product edits](/platform/product-edit/overview).
+
+## Next steps
+
+- [Create a variant axis and build variants on it](/platform/attribute/guides/create-a-variant-axis)
+- [Every attachment workflow and its input](/platform/attribute/reference/workflows)
+- [The links behind product attributes](/platform/attribute/reference/links)
diff --git a/apps/docs/platform/attribute/guides/create-a-variant-axis.mdx b/apps/docs/platform/attribute/guides/create-a-variant-axis.mdx
index 7e58460f1..250404a94 100644
--- a/apps/docs/platform/attribute/guides/create-a-variant-axis.mdx
+++ b/apps/docs/platform/attribute/guides/create-a-variant-axis.mdx
@@ -1,83 +1,132 @@
---
-title: "Create a variant axis"
+title: "Create a variant axis and build variants on it"
sidebarTitle: "Create a variant axis"
-description: "Generate product variants from a multi_select axis attribute."
+description: "Create a multi_select axis attribute, then create a product whose variants bind to it."
---
-In this guide, you'll learn how to create a variant-axis attribute and use it to
-generate a product's variants from server code.
-
-A variant axis is a `multi_select` attribute with `is_variant_axis` set. Creating
-one mirrors a native Medusa `ProductOption`, so the values a product selects along
-the axis become the dimensions Medusa uses to generate variants.
-
-## Create the axis attribute
-
-```ts title="src/api/custom/attributes/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { createProductAttributesWorkflow } from "@mercurjs/core/workflows"
-
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
- const { result } = await createProductAttributesWorkflow(req.scope).run({
- input: {
- attributes: [
- {
- name: "Size",
- type: "multi_select",
- is_variant_axis: true,
- is_filterable: true,
- values: [{ name: "S" }, { name: "M" }, { name: "L" }],
- },
- ],
- },
- })
+Create a variant axis such as Size, then create a product that uses part of it and has one variant per selected value. You need this whenever products in your catalog come in sizes, colors, or any other dimension shoppers pick between.
- res.status(201).json({ attribute: result[0] })
-}
-```
+## Before you begin
-The workflow creates the `ProductAttribute`, a mirror `ProductOption`, and a
-`ProductAttributeValue` for each option value. It wires `product_option_id` and
-`product_option_value_id` behind the scenes.
+You need the following:
-## Attach it to a product
+- **A Mercur server**: an API app with `@mercurjs/core` registered through `withMercur()`
+- **The concept**: read [Variant axes and product options](/platform/attribute/concepts/variant-axes) to see how an axis maps to a Medusa `ProductOption`
-Attach the axis to a product and pass the subset of values that product offers.
-Medusa generates a variant for each selected value.
+## Build the axis and the product
-```ts
-import { createAndLinkProductAttributesToProductWorkflow } from "@mercurjs/core/workflows"
+<Steps>
+ <Step title="Create the axis attribute">
+ An axis is a `multi_select` attribute with `is_variant_axis: true`. The workflow creates a global `ProductOption` titled `Size` with the same three values.
+
+ ```ts title="src/scripts/seed-size-axis.ts"
+ import type { ExecArgs } from "@medusajs/framework/types"
+ import { AttributeType } from "@mercurjs/types"
+ import { createProductAttributesWorkflow } from "@mercurjs/core/workflows"
+ export default async function seedSizeAxis({ container }: ExecArgs) {
+ const { result } = await createProductAttributesWorkflow(container).run({
+ input: {
+ attributes: [
+ {
+ name: "Size",
+ type: AttributeType.MULTI_SELECT,
+ is_variant_axis: true,
+ is_filterable: true,
+ values: [{ name: "S" }, { name: "M" }, { name: "L" }],
+ },
+ ],
+ },
+ })
+
+ container.resolve("logger").info(`Created axis ${result[0].id}`)
+ }
+ ```
+
+ Run it with `npx medusa exec ./src/scripts/seed-size-axis.ts`. Medusa keeps global option titles unique, so a second global axis named `Size` fails.
+ </Step>
+ <Step title="Create a product on the axis">
+ Mercur’s `createProductsWorkflow` takes `attributes` and `variants` together. It attaches the axis with the values you pick, then creates the variants against it.
+
+ ```ts
+ import { createProductsWorkflow } from "@mercurjs/core/workflows"
+
+ const { result } = await createProductsWorkflow(req.scope).run({
+ input: {
+ created_by: req.auth_context.actor_id,
+ products: [
+ {
+ title: "Linen shirt",
+ attributes: [
+ {
+ id: "pattr_01JD8Q1234567",
+ value_ids: ["pattrval_01JD8Q1", "pattrval_01JD8Q2"],
+ },
+ ],
+ variants: [
+ { title: "Linen shirt / S", options: { Size: "S" } },
+ { title: "Linen shirt / M", options: { Size: "M" } },
+ ],
+ },
+ ],
+ },
+ })
+ ```
+
+ Run this inside an authenticated route handler, so `req.auth_context.actor_id` records who created the product. Each variant names its option value by the option title, which is the attribute name. The product only holds `S` and `M`, so those are the variants it can have.
+ </Step>
+</Steps>
+
+## Change the values a product uses
+
+Run `createAndLinkProductAttributesToProductWorkflow` with an `update` entry to grow or shrink the subset. The workflow moves the option values on the product and the pivot links together.
+
+```ts
await createAndLinkProductAttributesToProductWorkflow(req.scope).run({
input: {
- product_id: "prod_shirt",
- add: [{ id: "pattr_size", value_ids: ["pattrval_s", "pattrval_m"] }],
+ product_id: "prod_01JD8Q1234567",
+ update: [
+ {
+ id: "pattr_01JD8Q1234567",
+ add: ["pattrval_01JD8Q3"],
+ remove: ["pattrval_01JD8Q1"],
+ },
+ ],
},
})
```
-<Note>
- Only `multi_select` attributes can be variant axes. The `value_ids` you pass
- are the per-product subset of the axis's values. Only those become variants.
-</Note>
+After the run, the product offers `M` and `L`. Create the `L` variant with Medusa’s `createProductVariantsWorkflow` and `options: { Size: "L" }`.
-## Inline axes
+## Create an axis for one product
-To create a product-scoped axis in the same step it's attached, pass the inline
-form instead of an existing id. This creates an exclusive `ProductOption`, a
-scoped attribute (`product_id` set), and the value mirror in one call:
+When only one product needs a dimension, add an inline axis instead of a global one. It creates an exclusive option (`is_exclusive: true`), a product-scoped `multi_select` attribute, and its values, and attaches them to the product.
```ts
await createAndLinkProductAttributesToProductWorkflow(req.scope).run({
input: {
- product_id: "prod_shirt",
- add: [{ title: "Cut", is_variant_axis: true, values: ["Slim", "Regular"] }],
+ product_id: "prod_01JD8Q1234567",
+ add: [
+ { title: "Cut", is_variant_axis: true, values: ["Slim", "Regular"] },
+ ],
},
})
```
-<Tip>
- Inline axes are ideal for a one-off dimension a single product needs. Reach for
- a global axis attribute when the same dimension, such as Size or Color, recurs
- across the catalog. See [Global vs inline](/platform/attribute/concepts/global-vs-inline).
-</Tip>
+An inline axis holds all of its values, so there’s no subset to pick. You add values to it later with `update` and `add: [{ value: "Relaxed" }]`.
+
+## Add values to a global axis
+
+`createProductAttributeValuesWorkflow` adds values to the attribute and to its global option in one run. Products don’t gain the new value until you add it to their subset.
+
+```ts
+await createProductAttributeValuesWorkflow(req.scope).run({
+ input: { attribute_id: "pattr_01JD8Q1234567", values: [{ name: "XL" }] },
+})
+```
+
+## Next steps
+
+- [Every add and update form for the batch workflow](/platform/attribute/guides/attach-attributes-to-a-product)
+- [Global and inline attributes](/platform/attribute/concepts/global-vs-inline)
+- [The workflows that keep the option in sync](/platform/attribute/reference/workflows)
diff --git a/apps/docs/platform/attribute/guides/create-an-attribute.mdx b/apps/docs/platform/attribute/guides/create-an-attribute.mdx
index 7511ef508..66aaf2d3a 100644
--- a/apps/docs/platform/attribute/guides/create-an-attribute.mdx
+++ b/apps/docs/platform/attribute/guides/create-an-attribute.mdx
@@ -1,81 +1,130 @@
---
-title: "Create an attribute"
+title: "Create a catalog attribute"
sidebarTitle: "Create an attribute"
-description: "Create a typed catalog attribute with createProductAttributesWorkflow."
+description: "Create a global attribute with its values from a route, a seed script, or a catalog import."
---
-In this guide, you'll learn how to create a global catalog attribute from your
-own server code, for example in a seed script, a custom API route, or a catalog
-import.
+Create global catalog attributes from your own server code, for example when you seed a marketplace or import a taxonomy from a product information system.
-Mercur exposes a `createProductAttributesWorkflow` that creates one or more
-`ProductAttribute` records along with their values. Run it from any place that
-has access to the Medusa container.
+## Before you begin
-## Run the workflow
+You need the following:
-```ts title="src/api/custom/attributes/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { createProductAttributesWorkflow } from "@mercurjs/core/workflows"
+- **A Mercur server**: an API app with `@mercurjs/core` registered through `withMercur()`
+- **Workflow imports**: every workflow on this page comes from `@mercurjs/core/workflows`
+
+## Create the attribute
+
+<Steps>
+ <Step title="Run createProductAttributesWorkflow from a route">
+ The workflow takes a list of attributes, each with its values, and returns the created records.
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
- const { result } = await createProductAttributesWorkflow(req.scope).run({
- input: {
- attributes: [
- {
- name: "Material",
- type: "single_select",
- is_filterable: true,
- values: [{ name: "Cotton" }, { name: "Wool" }, { name: "Linen" }],
+ ```ts title="src/api/admin/catalog-import/attributes/route.ts"
+ import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+ import { AttributeType } from "@mercurjs/types"
+ import { createProductAttributesWorkflow } from "@mercurjs/core/workflows"
+
+ export async function POST(req: MedusaRequest, res: MedusaResponse) {
+ const { result } = await createProductAttributesWorkflow(req.scope).run({
+ input: {
+ attributes: [
+ {
+ name: "Material",
+ type: AttributeType.SINGLE_SELECT,
+ is_filterable: true,
+ values: [{ name: "Cotton" }, { name: "Linen" }],
+ },
+ ],
},
- ],
- },
- })
+ })
- res.status(201).json({ attribute: result[0] })
-}
-```
+ res.status(201).json({ product_attributes: result })
+ }
+ ```
-The workflow creates the attribute, its `ProductAttributeValue` records, and,
-for a `multi_select` axis, the mirror `ProductOption`. It also emits the
-`product-attribute.created` event.
+ Leaving out `product_id` makes the attribute global. The service derives the handle `material` and a handle for each value.
+ </Step>
+ <Step title="Scope it to categories">
+ Pass `category_ids` to link the attribute to product categories in the same run. An attribute with no categories is offered for every product.
-<Note>
- Leaving `product_id` unset creates a **global** attribute reusable across the
- catalog. Passing a `product_id` creates an **inline** attribute scoped to a
- single product. See [Global vs inline](/platform/attribute/concepts/global-vs-inline).
-</Note>
+ ```ts
+ await createProductAttributesWorkflow(req.scope).run({
+ input: {
+ attributes: [
+ {
+ name: "Thread count",
+ type: AttributeType.UNIT,
+ category_ids: ["pcat_01JD8Q1234567"],
+ },
+ ],
+ },
+ })
+ ```
-## Associate categories
+ A `unit` attribute has no predefined values. Each product gets its own value when you attach the attribute.
+ </Step>
+ <Step title="Add values later">
+ Run `createProductAttributeValuesWorkflow` to add values to an existing select attribute. It takes one `attribute_id` and the new values.
-Pass `category_ids` on an attribute to associate it with product categories
-through the category link in the same call:
+ ```ts
+ import { createProductAttributeValuesWorkflow } from "@mercurjs/core/workflows"
-```ts
-await createProductAttributesWorkflow(req.scope).run({
- input: {
- attributes: [
- {
- name: "Thread count",
- type: "unit",
- category_ids: ["pcat_bedding"],
+ await createProductAttributeValuesWorkflow(req.scope).run({
+ input: {
+ attribute_id: "pattr_01JD8Q1234567",
+ values: [{ name: "Wool" }, { name: "Silk", rank: 3 }],
},
- ],
- },
-})
+ })
+ ```
+
+ For a variant axis, the workflow also adds the values to the mirror `ProductOption`.
+ </Step>
+</Steps>
+
+## Attach custom data with additional_data
+
+Every catalog workflow accepts `additional_data` and passes it to its completion hook. Register a handler on `productAttributesCreated` to store your own data next to the attribute without forking the workflow.
+
+```ts title="src/workflows/hooks/product-attributes-created.ts"
+import { createProductAttributesWorkflow } from "@mercurjs/core/workflows"
+
+createProductAttributesWorkflow.hooks.productAttributesCreated(
+ async ({ attributes, additional_data }, { container }) => {
+ const logger = container.resolve("logger")
+ const source = additional_data?.imported_from
+
+ for (const attribute of attributes) {
+ logger.info(`Attribute ${attribute.id} imported from ${source}`)
+ }
+ }
+)
```
-## Attach custom data
+Pass the data when you run the workflow, for example `additional_data: { imported_from: "legacy_pim" }`. The workflow also exposes a `validate` hook that runs before anything is written, so you can throw there to reject the input.
+
+## Update or delete an attribute
-The workflow accepts an `additional_data` payload passed to its
-`productAttributesCreated` hook, letting you persist marketplace-specific data
-alongside the attribute without forking the workflow.
+`updateProductAttributesWorkflow` takes a `selector` and an `update`. Keep these rules in mind:
+
+- **Type is fixed**: the service throws if `update.type` differs from the current type
+- **Renames reach the option**: changing `name` on an axis also renames its `ProductOption`
+- **Deletes check usage**: `deleteProductAttributesWorkflow` throws `NOT_ALLOWED` while any value is linked to a product
```ts
-await createProductAttributesWorkflow(req.scope).run({
+import { updateProductAttributesWorkflow } from "@mercurjs/core/workflows"
+
+await updateProductAttributesWorkflow(req.scope).run({
input: {
- attributes: [{ name: "Material", type: "single_select" }],
- additional_data: { imported_from: "legacy-pim" },
+ selector: { id: "pattr_01JD8Q1234567" },
+ update: { name: "Fabric", is_filterable: false },
},
})
```
+
+The run renames the attribute and turns off its facet flag. The handle stays `material`, because handles are derived only on create.
+
+## Next steps
+
+- [Attach the attribute to a product](/platform/attribute/guides/attach-attributes-to-a-product)
+- [Create a variant axis](/platform/attribute/guides/create-a-variant-axis)
+- [Subscribe to attribute events](/platform/attribute/reference/events)
diff --git a/apps/docs/platform/attribute/overview.mdx b/apps/docs/platform/attribute/overview.mdx
index 00243f52f..27eb67ecf 100644
--- a/apps/docs/platform/attribute/overview.mdx
+++ b/apps/docs/platform/attribute/overview.mdx
@@ -1,82 +1,86 @@
---
-title: "Attribute"
+title: "Attributes"
sidebarTitle: "Overview"
-description: "An operator-managed, typed attribute catalog for describing and filtering the shared product catalog."
+description: "Describe the shared catalog with typed attributes, turn them into variant axes, and expose them as storefront filters."
---
-Use Mercur to define a typed vocabulary for your products, such as colors,
-materials, sizes, capacities, or warranty toggles, and reuse it across the whole
-marketplace.
+Use attributes to give every product in your marketplace the same typed vocabulary, from sizes and materials to capacities and yes/no flags.
-The Attribute domain is an operator-managed catalog of typed fields that attach
-to products in the shared master catalog. Attributes describe products
-consistently and drive storefront filters. For variant axes, they generate the
-product variants shoppers pick between. Every attribute is one of five types.
-Each one is either a global catalog entry reused everywhere or an inline field
-scoped to a single product.
+An attribute is a typed field that operators define once and attach to products in the shared master catalog. It describes products the same way across every store, feeds storefront filters, and, when it’s a variant axis, decides which variants a product can have. The Product Attribute module holds the attributes and their values. Links connect them to Medusa’s products, categories, and product options, so a variant axis is a real Medusa `ProductOption` underneath.
+
+<img className="block dark:hidden" src="/images/figures/attribute-overview-light.svg" alt="The global attribute catalog lists Size, Material, Thread count, Gift wrap, and Care with their types, and Size is the one variant axis, backed by the global Medusa product option Size behind it." />
+<img className="hidden dark:block" src="/images/figures/attribute-overview-dark.svg" alt="The global attribute catalog lists Size, Material, Thread count, Gift wrap, and Care with their types, and Size is the one variant axis, backed by the global Medusa product option Size behind it." />
<Note>
- **Attribute = the `ProductAttribute` entity.** The catalog is owned by the
- Product Attribute module (`MercurModules.PRODUCT_ATTRIBUTE`, id prefix
- `pattr`). Products are the shared master catalog. Attributes never belong to a
- store. Sellers list against master products through offers.
+ The data models are `ProductAttribute` (id prefix `pattr`) and `ProductAttributeValue` (id prefix `pattrval`), resolved with `MercurModules.PRODUCT_ATTRIBUTE` from `@mercurjs/types`. Attributes belong to the catalog, never to a store.
</Note>
## Key features
-- **Five typed forms:** `single_select`, `multi_select`, `text`, `unit`, and `toggle`, each with its own validation and UI shape.
-- **Variant axes:** a `multi_select` attribute marked `is_variant_axis` mirrors a native Medusa `ProductOption` and generates product variants.
-- **Global or inline:** reuse a global catalog attribute across products, or attach a one-off attribute scoped to a single product.
-- **Storefront filtering:** an `is_filterable` flag exposes an attribute as a shopper-facing facet.
-- **Batch attach:** attach, detach, and update all of a product's attributes through a single engine workflow.
-- **Ordered and governed:** `rank`, `is_active`, and `is_required` control ordering, availability, and required-field enforcement.
+The Product Attribute module covers the full life of a catalog attribute:
+
+- **Five types**: `single_select`, `multi_select`, `text`, `unit`, and `toggle`, each storing its values differently
+- **Variant axes**: a `multi_select` attribute with `is_variant_axis` creates a Medusa `ProductOption` that variants bind to
+- **Global or inline**: define an attribute once for the whole catalog, or create a one-off attribute on a single product
+- **Category scoping**: link an attribute to product categories so it’s offered only for products in them
+- **Storefront filters**: shoppers filter products by axis values, and `is_filterable` tells your storefront which attributes to show as facets
+- **One batch workflow**: attach, detach, and update all of a product’s attributes in a single run
+- **Hooks and events**: catalog workflows expose hooks and emit `product-attribute.*` and `product-attribute-value.*` events
+
+## How it works
+
+An attribute reaches a product in four steps:
+
+1. An operator runs `createProductAttributesWorkflow`. For a variant axis, it also creates a global `ProductOption` with the same values.
+2. A product is created with Mercur’s `createProductsWorkflow`, or edited with `createAndLinkProductAttributesToProductWorkflow`, and picks the attributes and values it uses.
+3. Selected values link to the product. For an axis, the product also gets the option with only the selected subset of values.
+4. Variants bind to the axis option by its title, for example `{ Size: "M" }`, and the storefront filters products by those option values.
## Get started
-Learn how the domain fits together.
+Learn how attributes, values, and axes fit together.
<CardGroup cols={2}>
<Card title="Attribute types" icon="shapes" href="/platform/attribute/concepts/attribute-types">
- The five attribute types and the values they hold.
+ The five types and how each one stores its values.
</Card>
<Card title="Variant axes" icon="sitemap" href="/platform/attribute/concepts/variant-axes">
- How `is_variant_axis` mirrors a `ProductOption` and generates variants.
+ How an axis attribute mirrors a Medusa `ProductOption`.
</Card>
<Card title="Global vs inline" icon="layer-group" href="/platform/attribute/concepts/global-vs-inline">
- Catalog-wide attributes, product-scoped attributes, and filtering.
+ Catalog attributes, product-scoped attributes, categories, and filters.
</Card>
</CardGroup>
## Examples
-Build against the Attribute domain in your own code.
+Build against attributes in your own server code.
<CardGroup cols={2}>
<Card title="Create an attribute" icon="plus" href="/platform/attribute/guides/create-an-attribute">
Run `createProductAttributesWorkflow` from a route or seed script.
</Card>
<Card title="Attach to a product" icon="link" href="/platform/attribute/guides/attach-attributes-to-a-product">
- Attach, detach, and update attributes in one batch call.
+ Attach, detach, and update a product’s attributes in one run.
</Card>
<Card title="Create a variant axis" icon="sitemap" href="/platform/attribute/guides/create-a-variant-axis">
- Generate variants from a `multi_select` axis attribute.
+ Create an axis and build a product’s variants on it.
</Card>
</CardGroup>
## Resources
-Data models, links, workflows, service methods, and events for the Attribute
-domain.
+The data models, links, workflows, service methods, and events behind attributes.
<CardGroup cols={2}>
<Card title="Data models" icon="table" href="/platform/attribute/reference/data-models">
- The `ProductAttribute` and `ProductAttributeValue` entities.
+ `ProductAttribute` and `ProductAttributeValue`, field by field.
</Card>
<Card title="Links" icon="link" href="/platform/attribute/reference/links">
- How the Attribute domain links to products, categories, and options.
+ Links to products, categories, and product options.
</Card>
<Card title="Workflows" icon="diagram-project" href="/platform/attribute/reference/workflows">
- Catalog and product-attachment workflows.
+ Catalog workflows and product attachment workflows.
</Card>
<Card title="Service" icon="gear" href="/platform/attribute/reference/service">
Module service methods for working with records directly.
diff --git a/apps/docs/platform/attribute/reference/data-models.mdx b/apps/docs/platform/attribute/reference/data-models.mdx
index 0a947eaf3..6d370d8b1 100644
--- a/apps/docs/platform/attribute/reference/data-models.mdx
+++ b/apps/docs/platform/attribute/reference/data-models.mdx
@@ -1,56 +1,71 @@
---
-title: "Data models"
+title: "Attribute data models"
sidebarTitle: "Data models"
-description: "The data models owned by the Attribute (Product Attribute) domain."
+description: "Every field on ProductAttribute and ProductAttributeValue, with defaults, nullability, indexes, and relations."
---
-The Attribute domain is owned by the **Product Attribute module**. This reference
-lists its data models and their fields. For the full module overview, see the
-[Attribute module overview](/platform/attribute/overview).
+The Product Attribute module owns 2 data models: `ProductAttribute` and `ProductAttributeValue`. Both are defined in `packages/core/src/modules/product-attribute/models` and resolved through `MercurModules.PRODUCT_ATTRIBUTE` (`"product_attribute"`). Like every Medusa data model, each also gets `created_at`, `updated_at`, and `deleted_at` timestamps.
## ProductAttribute
-Table `product_attribute`, id prefix `pattr`. A typed catalog attribute.
+A typed attribute in the shared catalog, either global or scoped to one product. Id prefix `pattr`.
-| Field | Type | Notes |
+| Field | Type | Description |
| --- | --- | --- |
-| `id` | text | Primary key |
-| `name` | text | Searchable |
-| `handle` | text | Nullable; unique when set |
-| `description` | text | Nullable |
-| `type` | enum | `AttributeType`: `single_select`, `multi_select`, `text`, `unit`, `toggle` |
-| `is_required` | boolean | Default `false` |
-| `is_filterable` | boolean | Default `false`; exposes the attribute as a storefront filter |
-| `is_variant_axis` | boolean | Default `false`; `multi_select` axis that generates variants |
-| `rank` | number | Default `0`; ordering |
-| `is_active` | boolean | Default `true` |
-| `created_by` | text | Nullable |
-| `product_id` | text | Nullable; non-null = product-scoped (inline), null = global |
-| `product_option_id` | text | Nullable; FK to the mirror `ProductOption` (axis attributes) |
-| `metadata` | json | Nullable |
-
-Relations: `values` (one-to-many `ProductAttributeValue`, deleted with the
-attribute).
+| `id` | `string` | Primary key, prefixed `pattr` |
+| `handle` | `string \| null` | Unique among non-deleted attributes when set. Derived from `name` on create for global attributes |
+| `name` | `string` | Display name. Searchable. For an axis, also the title of its `ProductOption` |
+| `description` | `string \| null` | Free-form description |
+| `type` | `AttributeType` | One of `single_select`, `multi_select`, `unit`, `toggle`, `text`. Can’t change after create |
+| `is_required` | `boolean` | Default `false`. The remove workflows refuse to detach a required attribute |
+| `is_filterable` | `boolean` | Default `false`. Marks the attribute as a storefront facet |
+| `is_variant_axis` | `boolean` | Default `false`. With `multi_select`, backs the attribute with a `ProductOption` |
+| `rank` | `number` | Default `0`. Sort order |
+| `is_active` | `boolean` | Default `true` |
+| `created_by` | `string \| null` | Id of whoever created the attribute. The built-in routes leave it unset |
+| `product_id` | `string \| null` | `null` for a global attribute, the product’s id for an inline one |
+| `product_option_id` | `string \| null` | Id of the mirror `ProductOption` for an axis attribute |
+| `metadata` | `Record<string, unknown> \| null` | Custom key-value data |
+
+Relations and constraints:
+
+- **`values`**: has many `ProductAttributeValue`, deleted with the attribute
+- **`IDX_product_attribute_handle_unique`**: unique `handle` where `deleted_at IS NULL AND handle IS NOT NULL`
+- **`IDX_product_attribute_type`**: index on `type`
+- **`IDX_product_attribute_product_id`**: index on `product_id` where it’s not null
## ProductAttributeValue
-Table `product_attribute_value`, id prefix `pattrval`. A selectable value that
-belongs to one attribute.
+One selectable value of an attribute, or the stored value of a `text`, `unit`, or `toggle` attribute on a product. Id prefix `pattrval`.
-| Field | Type | Notes |
+| Field | Type | Description |
| --- | --- | --- |
-| `id` | text | Primary key |
-| `name` | text | The value label |
-| `handle` | text | Nullable; unique per attribute when set |
-| `rank` | number | Default `0`; ordering |
-| `is_active` | boolean | Default `true` |
-| `product_option_value_id` | text | Nullable; FK to the mirror `ProductOptionValue` (axis values) |
-| `metadata` | json | Nullable |
+| `id` | `string` | Primary key, prefixed `pattrval` |
+| `attribute_id` | `string` | Id of the parent `ProductAttribute` |
+| `handle` | `string \| null` | Unique per attribute when set. Derived from `name` on create for values of global select attributes |
+| `name` | `string` | The value label, or the stored content for `text` and `unit` |
+| `rank` | `number` | Default `0`. Sort order within the attribute |
+| `is_active` | `boolean` | Default `true` |
+| `product_option_value_id` | `string \| null` | Id of the mirror `ProductOptionValue` for an axis value |
+| `metadata` | `Record<string, unknown> \| null` | Custom key-value data |
+
+Relations and constraints:
+
+- **`attribute`**: belongs to `ProductAttribute` through `attribute_id`
+- **`IDX_product_attribute_value_handle_unique`**: unique `(attribute_id, handle)` where `deleted_at IS NULL AND handle IS NOT NULL`
+
+## AttributeType enum
+
+`AttributeType` is exported from `@mercurjs/types`:
-Relations: `attribute` (belongs to `ProductAttribute` via `attribute_id`).
+| Member | Value |
+| --- | --- |
+| `SINGLE_SELECT` | `"single_select"` |
+| `MULTI_SELECT` | `"multi_select"` |
+| `UNIT` | `"unit"` |
+| `TOGGLE` | `"toggle"` |
+| `TEXT` | `"text"` |
<Note>
- `product_option_id` on the attribute and `product_option_value_id` on the value
- are the foreign keys behind the read-only mirror links to Medusa's product
- options. See [Links](/platform/attribute/reference/links).
+ Neither model stores which products hold a value. That lives in the `product_attribute_value_link` pivot table, described in [Links](/platform/attribute/reference/links).
</Note>
diff --git a/apps/docs/platform/attribute/reference/events.mdx b/apps/docs/platform/attribute/reference/events.mdx
index b38e336f3..62a40084a 100644
--- a/apps/docs/platform/attribute/reference/events.mdx
+++ b/apps/docs/platform/attribute/reference/events.mdx
@@ -1,22 +1,59 @@
---
-title: "Event reference"
+title: "Attribute events"
sidebarTitle: "Events"
-description: "Events emitted by the Attribute domain, for subscribers and side effects."
+description: "Events the Product Attribute workflows emit, when they fire, and their payloads."
---
-The Attribute domain emits events as attributes and their values change.
-Subscribe to them to run side effects, such as reindexing storefront filters,
-syncing an external PIM, or kicking off follow-up workflows, instead of polling.
+The catalog workflows emit 6 events as attributes and values change. Subscribe to them to reindex storefront facets, sync an external product information system, or start your own workflows. The event names are exported as `ProductAttributeWorkflowEvents` and `ProductAttributeValueWorkflowEvents` from `@mercurjs/core/workflows`.
-```ts title="src/subscribers/attribute-created.ts"
+## Attribute events
+
+Each event fires once per attribute, with that attribute’s id as the payload.
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `product-attribute.created` | `createProductAttributesWorkflow` creates attributes | `{ id }` |
+| `product-attribute.updated` | `updateProductAttributesWorkflow` updates attributes, including an inline rename from the batch workflow | `{ id }` |
+| `product-attribute.deleted` | `deleteProductAttributesWorkflow` deletes attributes, including inline attributes removed from their product | `{ id }` |
+
+## Value events
+
+Each event fires once per value, with that value’s id as the payload.
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `product-attribute-value.created` | `createProductAttributeValuesWorkflow` creates values, including new values added to an inline axis | `{ id }` |
+| `product-attribute-value.updated` | `updateProductAttributeValuesWorkflow` updates values | `{ id }` |
+| `product-attribute-value.deleted` | `deleteProductAttributeValuesWorkflow` deletes values, including values removed from an inline axis | `{ id }` |
+
+## What doesn’t emit
+
+Some writes create or change records without a matching event:
+
+- **Values created with an attribute**: `createProductAttributesWorkflow` emits only `product-attribute.created`, not a value event per value
+- **Upserts**: `upsertProductAttributeValuesWorkflow` emits nothing
+- **Attaching and detaching**: linking values to a product, `text` and `unit` values created on attach, and option changes on a product emit no attribute events
+
+## Subscribe to an event
+
+A subscriber receives one event per attribute. Resolve `query` to load the record by id.
+
+```ts title="src/subscribers/product-attribute-created.ts"
import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
-export default async function attributeCreatedHandler({
+export default async function productAttributeCreated({
event,
container,
}: SubscriberArgs<{ id: string }>) {
- const attributeId = event.data.id
- // ...reindex filters, sync to an external system, etc.
+ const query = container.resolve(ContainerRegistrationKeys.QUERY)
+ const { data: [attribute] } = await query.graph({
+ entity: "product_attribute",
+ fields: ["id", "name", "type", "is_filterable", "values.name"],
+ filters: { id: event.data.id },
+ })
+
+ container.resolve("logger").info(`Index facet ${attribute.name}`)
}
export const config: SubscriberConfig = {
@@ -24,18 +61,4 @@ export const config: SubscriberConfig = {
}
```
-## Attribute events
-
-| Event | Emitted when | Payload |
-| --- | --- | --- |
-| `product-attribute.created` | An attribute is created | `{ id }` |
-| `product-attribute.updated` | An attribute changes | `{ id }` |
-| `product-attribute.deleted` | An attribute is deleted | `{ id }` |
-
-## Value events
-
-| Event | Emitted when | Payload |
-| --- | --- | --- |
-| `product-attribute-value.created` | A value is created | `{ id }` |
-| `product-attribute-value.updated` | A value changes | `{ id }` |
-| `product-attribute-value.deleted` | A value is deleted | `{ id }` |
+The subscriber loads the new attribute with its values. Swap the log line for a call to your search index.
diff --git a/apps/docs/platform/attribute/reference/links.mdx b/apps/docs/platform/attribute/reference/links.mdx
index 17f5acbcf..e2a8fd37c 100644
--- a/apps/docs/platform/attribute/reference/links.mdx
+++ b/apps/docs/platform/attribute/reference/links.mdx
@@ -1,45 +1,116 @@
---
-title: "Links to other modules"
+title: "Attribute links"
sidebarTitle: "Links"
-description: "How the Attribute (Product Attribute) domain links to products, categories, and options."
+description: "The five module links between the Product Attribute module and Medusa's Product module."
---
-Modules in Mercur never reference each other directly. They're connected through
-**module links**. The Product Attribute module links into Medusa's product module
-in several ways: to products, to categories, and, for variant axes, to product
-options through mirror links. Once a link is defined, you retrieve related records
-with `query.graph` using the link alias.
+The Product Attribute module never references Medusa’s Product module directly. Five module links in `packages/core/src/links` connect them: two that store data in pivot tables and three read-only links resolved from a foreign key on one side. Resolve `query` from the container to read across them.
```ts
-const { data: products } = await query.graph({
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
+
+const query = container.resolve(ContainerRegistrationKeys.QUERY)
+```
+
+## Product to attribute value
+
+The values a product holds, for every attribute type. This is the link the attachment workflows write.
+
+| Property | Value |
+| --- | --- |
+| Sides | `Product` ↔ `ProductAttributeValue` |
+| Cardinality | Many-to-many |
+| Storage | Pivot table `product_attribute_value_link` |
+| Aliases | `product_attribute_values` on product, `products` on value |
+| Defined in | `product-attribute-value-pivot-link.ts` |
+
+```ts
+const { data: [product] } = await query.graph({
entity: "product",
- fields: ["id", "title", "scoped_attributes.*"],
+ fields: [
+ "product_attribute_values.name",
+ "product_attribute_values.attribute.name",
+ ],
+ filters: { id: "prod_01JD8Q1234567" },
})
```
-## Products
+The query returns each linked value with its parent attribute, which is how you read a product’s full attribute selection.
-| Link | Table | Relationship |
-| --- | --- | --- |
-| **Product → attribute** (`scoped_attributes`) | None | Read-only; a product's inline (product-scoped) attributes, resolved from `ProductAttribute.product_id` |
-| **Product ↔ attribute value** | `product_attribute_value_link` | Many-to-many pivot; the values selected on a product |
+## Product to scoped attributes
-## Categories
+The inline attributes created on a product. The link is read-only and resolves `ProductAttribute.product_id` against `product.id`.
-| Link | Table | Relationship |
-| --- | --- | --- |
-| **Attribute ↔ category** (`categories`) | `product_category_attribute` | Many-to-many; the product categories an attribute is associated with |
+| Property | Value |
+| --- | --- |
+| Sides | `Product` → `ProductAttribute` |
+| Cardinality | One-to-many |
+| Storage | None, read-only |
+| Alias | `scoped_attributes` on product |
+| Defined in | `product-attribute-product-link.ts` |
-## Product options (mirror links)
+```ts
+const { data: [product] } = await query.graph({
+ entity: "product",
+ fields: ["scoped_attributes.name", "scoped_attributes.values.name"],
+ filters: { id: "prod_01JD8Q1234567" },
+})
+```
+
+## Attribute to category
-| Link | FK | Relationship |
-| --- | --- | --- |
-| **Attribute → option** | `ProductAttribute.product_option_id` | Read-only 1:1; the mirror `ProductOption` for a variant-axis attribute |
-| **Value → option value** | `ProductAttributeValue.product_option_value_id` | Read-only 1:1; the mirror `ProductOptionValue` for an axis value |
+The product categories a global attribute is offered for. An attribute with no category links is offered for every product.
+
+| Property | Value |
+| --- | --- |
+| Sides | `ProductAttribute` ↔ `ProductCategory` |
+| Cardinality | Many-to-many |
+| Storage | Pivot table `product_category_attribute` |
+| Aliases | `categories` on attribute, `product_attributes` on category |
+| Defined in | `product-attribute-category-link.ts` |
+
+```ts
+const { data: attributes } = await query.graph({
+ entity: "product_attribute",
+ fields: ["id", "name", "categories.id", "categories.name"],
+ filters: { product_id: null },
+})
+```
+
+`createProductAttributesWorkflow` writes these links from `category_ids`. Write more yourself with the link service, using the keys `product_attribute_id` and `product_category_id`.
+
+## Attribute to product option
+
+The Medusa `ProductOption` that backs a variant axis. The link is read-only and keyed on `ProductAttribute.product_option_id`.
+
+| Property | Value |
+| --- | --- |
+| Sides | `ProductAttribute` → `ProductOption` |
+| Cardinality | One-to-one |
+| Storage | None, read-only |
+| Defined in | `product-attribute-option-mirror-link.ts` |
+
+## Attribute value to option value
+
+The Medusa `ProductOptionValue` that backs one value of a variant axis. The link is read-only and keyed on `ProductAttributeValue.product_option_value_id`.
+
+| Property | Value |
+| --- | --- |
+| Sides | `ProductAttributeValue` → `ProductOptionValue` |
+| Cardinality | One-to-one |
+| Storage | None, read-only |
+| Defined in | `product-attribute-value-option-value-mirror-link.ts` |
+
+Core code reads the mirror through the foreign keys, not through these links. Do the same: read the ids from the attribute, then query the option.
+
+```ts
+const { data: [option] } = await query.graph({
+ entity: "product_option",
+ fields: ["id", "title", "is_exclusive", "values.id", "values.value"],
+ filters: { id: attribute.product_option_id },
+})
+```
<Note>
- The mirror links (Attribute → option, Value → option value) and the product
- scope link (`scoped_attributes`) are **read-only**. They're resolved from the
- FK on the owning record and can't be written through the link itself. The
- workflows keep the mirror in sync when axis attributes and values change.
+ The workflows keep the mirror in step. Never write `product_option_id` or `product_option_value_id` yourself, or the attribute and its option will drift apart.
</Note>
diff --git a/apps/docs/platform/attribute/reference/service.mdx b/apps/docs/platform/attribute/reference/service.mdx
index 27422e58d..c57f75b12 100644
--- a/apps/docs/platform/attribute/reference/service.mdx
+++ b/apps/docs/platform/attribute/reference/service.mdx
@@ -1,49 +1,88 @@
---
-title: "Service reference"
+title: "Product Attribute module service"
sidebarTitle: "Service"
-description: "The Product Attribute module service, with methods for working with records directly."
+description: "Resolve the Product Attribute module service, and the generated and overridden methods it exposes."
---
-The Product Attribute module exposes a service you can resolve from the Medusa
-container to read and write records directly, without going through a workflow.
-Use it inside custom services, subscribers, or scheduled jobs.
+The Product Attribute module service reads and writes `ProductAttribute` and `ProductAttributeValue` records directly. Use it for reads in routes, subscribers, and scheduled jobs. For writes, prefer the [workflows](/platform/attribute/reference/workflows), because the service doesn’t emit events, update the mirror `ProductOption`, or link values to products.
-```ts
-import { MercurModules } from "@mercurjs/types"
+## Resolve the service
+
+Resolve the service from the container with `MercurModules.PRODUCT_ATTRIBUTE`, whose value is `"product_attribute"`.
+
+```ts title="src/api/admin/catalog-import/facets/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { AttributeType, MercurModules } from "@mercurjs/types"
+
+export async function GET(req: MedusaRequest, res: MedusaResponse) {
+ const attributeService = req.scope.resolve(MercurModules.PRODUCT_ATTRIBUTE)
-const attributeModuleService = container.resolve(
- MercurModules.PRODUCT_ATTRIBUTE,
-)
+ const [attributes, count] =
+ await attributeService.listAndCountProductAttributes(
+ { is_filterable: true, product_id: null },
+ { relations: ["values"], order: { rank: "ASC" } }
+ )
-const [attributes, count] =
- await attributeModuleService.listAndCountProductAttributes({
- type: "single_select",
- })
+ res.json({ attributes, count })
+}
```
+The route lists filterable global attributes in rank order, each with its values.
+
## Generated methods
-Each data model gets a standard set of auto-generated methods. For
-`ProductAttribute`:
+The service extends `MedusaService`, so each data model gets the standard methods. For `ProductAttribute`:
| Method | Description |
| --- | --- |
-| `createProductAttributes(data)` | Create one or more attributes |
-| `retrieveProductAttribute(id, config?)` | Retrieve an attribute by id |
-| `listProductAttributes(filters?, config?)` | List attributes matching filters |
-| `listAndCountProductAttributes(filters?, config?)` | List attributes with a total count |
-| `updateProductAttributes(data)` | Update one or more attributes |
-| `deleteProductAttributes(ids)` | Delete one or more attributes |
-
-The same set exists for `ProductAttributeValue`: `createProductAttributeValues`,
-`retrieveProductAttributeValue`, `listProductAttributeValues`,
-`listAndCountProductAttributeValues`, `updateProductAttributeValues`, and
-`deleteProductAttributeValues`.
+| `retrieveProductAttribute(id, config?)` | Retrieve one attribute by id |
+| `listProductAttributes(filters?, config?)` | List attributes. Overridden, see below |
+| `listAndCountProductAttributes(filters?, config?)` | List attributes with a total count. Overridden, see below |
+| `createProductAttributes(data)` | Create one or more attributes. Overridden, see below |
+| `updateProductAttributes(data)` | Update one or more attributes by id. Overridden, see below |
+| `deleteProductAttributes(ids)` | Hard-delete attributes and their values |
+| `softDeleteProductAttributes(ids)` | Soft-delete attributes and their values |
+| `restoreProductAttributes(ids)` | Restore soft-deleted attributes |
+
+`ProductAttributeValue` gets the same set: `retrieveProductAttributeValue`, `listProductAttributeValues`, `listAndCountProductAttributeValues`, `createProductAttributeValues`, `updateProductAttributeValues`, `deleteProductAttributeValues`, `softDeleteProductAttributeValues`, and `restoreProductAttributeValues`.
+
+## Overridden methods
+
+Five methods add behavior on top of the generated ones.
+
+### createProductAttributes
+
+```ts
+createProductAttributes(data: object | object[], sharedContext?: Context)
+```
+
+Derives a `handle` from `name` for any global attribute created without one. After creating, it seeds a `"true"` value (rank 0) and a `"false"` value (rank 1) for every `toggle` attribute. It doesn’t create any other values, so add them with `createProductAttributeValues`.
+
+### updateProductAttributes
+
+```ts
+updateProductAttributes(data: object | object[], sharedContext?: Context)
+```
+
+Throws `INVALID_DATA` when an update sets a `type` that differs from the attribute’s current type. Every other field passes through.
+
+### listProductAttributes and listAndCountProductAttributes
+
+```ts
+listProductAttributes(filters?, config?: FindConfig, sharedContext?: Context)
+listAndCountProductAttributes(filters?, config?, sharedContext?)
+```
+
+When `config.relations` or `config.select` asks for `values`, the service loads them in a separate query. Only `single_select`, `multi_select`, and `toggle` attributes get their values. `text` and `unit` attributes come back with `values: []`, because their values belong to individual products.
+
+### createProductAttributeValues
+
+```ts
+createProductAttributeValues(data: object | object[], sharedContext?: Context)
+```
+
+Derives a `handle` from `name` for values of global `single_select` and `multi_select` attributes. Values of inline attributes and of `text`, `unit`, and `toggle` attributes keep a `null` handle.
<Warning>
- Prefer [workflows](/platform/attribute/reference/workflows) for anything with
- side effects, such as creating an axis attribute, attaching attributes to a
- product, or keeping the mirror `ProductOption` in sync. The service writes records
- directly and does **not** emit events, maintain the option mirror, or run
- compensation.
+ Writing `product_option_id` or `product_option_value_id` through the service doesn’t create or change any Medusa option. Use `createProductAttributesWorkflow` and the value workflows so the mirror stays correct.
</Warning>
diff --git a/apps/docs/platform/attribute/reference/workflows.mdx b/apps/docs/platform/attribute/reference/workflows.mdx
index b910e4780..a5ce3b0d1 100644
--- a/apps/docs/platform/attribute/reference/workflows.mdx
+++ b/apps/docs/platform/attribute/reference/workflows.mdx
@@ -1,45 +1,175 @@
---
-title: "Workflows"
+title: "Attribute workflows"
sidebarTitle: "Workflows"
-description: "Attribute catalog and product-attachment workflows."
+description: "Every catalog and product attachment workflow in the Product Attribute domain, with inputs, hooks, and events."
---
-This reference lists the workflows for the Attribute domain. Import them from
-`@mercurjs/core/workflows` and run them against the Medusa container.
+The Product Attribute domain exports 11 workflows from `@mercurjs/core/workflows`: 7 that manage the catalog and 4 that attach attributes to products. Run each one with `workflow(container).run({ input })`. When a step fails, the steps that already ran undo their work through their compensation functions.
## Catalog workflows
-Manage the attribute catalog and its values.
+These workflows create, change, and delete attributes and values. They keep the mirror `ProductOption` of a variant axis in step.
-| Workflow | Input | Purpose |
+### createProductAttributesWorkflow
+
+Creates attributes and their values. For each `multi_select` attribute with `is_variant_axis`, it first creates a global `ProductOption` (`is_exclusive: false`) titled with the attribute name, then links the values to its option values. Id `create-product-attributes`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `attributes` | `(CreateProductAttributeDTO & { category_ids?: string[] })[]` | Attributes to create, each with optional `values` |
+| `additional_data` | `Record<string, unknown>` | Passed to the `productAttributesCreated` hook |
+
+- **Returns**: `ProductAttributeDTO[]`
+- **Hooks**: `validate` with `{ input }`, `productAttributesCreated` with `{ attributes, additional_data }`
+- **Events**: `product-attribute.created` per attribute
+
+### updateProductAttributesWorkflow
+
+Updates every attribute matching `selector`. When `update.name` is set, it also renames the mirror option of each axis attribute. Id `update-product-attributes`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `selector` | `Record<string, unknown>` | Filters for the attributes to update, such as `{ id }` |
+| `update` | `UpdateProductAttributeDTO` | Fields to set. Changing `type` throws |
+| `additional_data` | `Record<string, unknown>` | Passed to the `productAttributesUpdated` hook |
+
+- **Returns**: `ProductAttributeDTO[]`
+- **Hooks**: `validate` with `{ input }`, `productAttributesUpdated` with `{ attributes, additional_data }`
+- **Events**: `product-attribute.updated` per attribute
+
+### deleteProductAttributesWorkflow
+
+Soft-deletes attributes and their values, then deletes the mirror options of axis attributes. It throws `NOT_ALLOWED` if any value of an attribute is linked to a product. Id `delete-product-attributes`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `ids` | `string[]` | Attribute ids |
+| `additional_data` | `Record<string, unknown>` | Passed to the `productAttributesDeleted` hook |
+
+- **Returns**: nothing
+- **Hooks**: `validate` with `{ input }`, `productAttributesDeleted` with `{ ids, additional_data }`
+- **Events**: `product-attribute.deleted` per id
+
+### createProductAttributeValuesWorkflow
+
+Adds values to one attribute. For an axis, it first adds the names to the mirror option and stores each new option value’s id. Id `create-product-attribute-values`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `attribute_id` | `string` | The parent attribute |
+| `values` | `CreateProductAttributeValueDTO[]` | Values to create, each with at least a `name` |
+| `additional_data` | `Record<string, unknown>` | Passed to the `productAttributeValuesCreated` hook |
+
+- **Returns**: `ProductAttributeValueDTO[]`
+- **Hooks**: `validate` with `{ input }`, `productAttributeValuesCreated` with `{ values, additional_data }`
+- **Events**: `product-attribute-value.created` per value
+
+### updateProductAttributeValuesWorkflow
+
+Updates every value matching `selector`. When the values belong to exactly one axis attribute, it rewrites that option’s values from the attribute’s value names. Id `update-product-attribute-values`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `selector` | `Record<string, unknown>` | Filters for the values to update |
+| `update` | `UpdateProductAttributeValueDTO` | Fields to set |
+| `additional_data` | `Record<string, unknown>` | Passed to the `productAttributeValuesUpdated` hook |
+
+- **Returns**: `ProductAttributeValueDTO[]`
+- **Hooks**: `validate` with `{ input }`, `productAttributeValuesUpdated` with `{ values, additional_data }`
+- **Events**: `product-attribute-value.updated` per value
+
+### deleteProductAttributeValuesWorkflow
+
+Soft-deletes values. When they belong to exactly one axis attribute, it rewrites that option’s values from the remaining value names. Id `delete-product-attribute-values`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `ids` | `string[]` | Value ids |
+| `additional_data` | `Record<string, unknown>` | Passed to the `productAttributeValuesDeleted` hook |
+
+- **Returns**: nothing
+- **Hooks**: `validate` with `{ input }`, `productAttributeValuesDeleted` with `{ ids, additional_data }`
+- **Events**: `product-attribute-value.deleted` per id
+
+### upsertProductAttributeValuesWorkflow
+
+Creates values without an `id` and updates values with one, for a single attribute. For an axis, it adds any new names to the mirror option first. Id `upsert-product-attribute-values`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `attribute_id` | `string` | The parent attribute |
+| `values` | `UpsertProductAttributeValueDTO[]` | Values to create or update, matched by `id` |
+
+- **Returns**: `ProductAttributeValueDTO[]`, created values first
+- **Hooks**: none
+- **Events**: none
+
+## Product attachment workflows
+
+These workflows attach attributes to products, write the `product_attribute_value_link` pivot, and attach or detach axis options on the product. Their input types are `ProductAttributeBatchAdd` and `ProductAttributeBatchUpdate` from `@mercurjs/types`.
+
+### createAndLinkProductAttributesToProductWorkflow
+
+The batch engine. It runs the remove, add, and update workflows below in that order, skipping any list that’s empty. Id `create-and-link-product-attributes-to-product`.
+
+| Input | Type | Description |
| --- | --- | --- |
-| `createProductAttributesWorkflow` | `{ attributes[], additional_data? }` | Create attributes (+ values, + mirror option for axes) |
-| `updateProductAttributesWorkflow` | `{ selector, update }` | Update attribute fields |
-| `deleteProductAttributesWorkflow` | `{ ids[] }` | Delete attributes (fails if still linked) |
-| `createProductAttributeValuesWorkflow` | `{ values[], additional_data? }` | Add values to attributes |
-| `updateProductAttributeValuesWorkflow` | `{ selector, update }` | Update values |
-| `deleteProductAttributeValuesWorkflow` | `{ ids[] }` | Delete values |
-| `upsertProductAttributeValuesWorkflow` | `{ attribute_id, values[] }` | Create or update an attribute's values in one call |
+| `product_id` | `string` | The product to change |
+| `add` | `ProductAttributeBatchAdd[]` | Attributes to attach, existing or inline |
+| `remove` | `string[]` | Attribute ids to detach |
+| `update` | `ProductAttributeBatchUpdate[]` | Selections to change |
+| `additional_data` | `Record<string, unknown>` | Passed to the `productAttributesLinked` hook |
-## Product-attachment workflows
+- **Returns**: nothing
+- **Hooks**: `validate` with `{ input }`, `productAttributesLinked` with `{ product_id, additional_data }`
+- **Events**: none of its own. Nested catalog workflows emit theirs
-Attach attributes to products in the shared master catalog.
+### addProductAttributesToProductWorkflow
-| Workflow | Input | Purpose |
+Attaches attributes. It creates inline attributes and their exclusive options, creates `text` and `unit` values, attaches axis options with the selected subset, and links every value to the product. Id `add-product-attributes-to-product`.
+
+| Input | Type | Description |
| --- | --- | --- |
-| `createAndLinkProductAttributesToProductWorkflow` | `{ product_id, add?, remove?, update? }` | Batch engine: attach, detach, and update, applied remove → add → update |
-| `addProductAttributesToProductWorkflow` | `{ product_id, add[] }` | Attach attributes (existing or inline) to a product |
-| `removeProductAttributesFromProductWorkflow` | `{ product_id, ... }` | Detach attributes from a product |
-| `updateProductAttributesOnProductWorkflow` | `{ product_id, ... }` | Update a product's attribute selections |
+| `product_id` | `string` | The product to change |
+| `add` | `ProductAttributeBatchAdd[]` | Attributes to attach |
+
+The input can also be an array of `{ product_id, add }` objects to attach to several products in one run. It has no hooks and emits no events.
+
+### removeProductAttributesFromProductWorkflow
+
+Detaches attributes. It throws `NOT_ALLOWED` for a required attribute unless the id is also in `readd`. It then detaches global axis options, drops the value links, and deletes inline attributes through `deleteProductAttributesWorkflow`. Id `remove-product-attributes-from-product`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `product_id` | `string` | The product to change |
+| `remove` | `string[]` | Attribute ids to detach |
+| `readd` | `string[]` | Ids removed and re-added in the same batch, skipped by the required check |
+
+### updateProductAttributesOnProductWorkflow
+
+Changes selections. It resolves `value_ids` into an add and remove delta, moves global axis option values, swaps `text`, `unit`, and `toggle` values, adds or deletes values of an inline axis, and renames inline attributes from `title`. Id `update-product-attributes-on-product`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `product_id` | `string` | The product to change |
+| `update` | `ProductAttributeBatchUpdate[]` | Selections to change |
<Note>
- `createAndLinkProductAttributesToProductWorkflow` is the engine behind the
- product attribute batch endpoint; it composes the three single-purpose
- attachment workflows. See
- [Attach attributes to a product](/platform/attribute/guides/attach-attributes-to-a-product).
+ Changes made by these workflows land on the product right away. To route a store’s attribute edits through review, run `productEditUpdateAttributesWorkflow` from the [Product edits](/platform/product-edit/overview) domain, which applies the batch engine once the change is confirmed.
</Note>
-To work with records directly instead of through a workflow, see the
-[Service reference](/platform/attribute/reference/service). To run side effects
-when an attribute changes, see the
-[Event reference](/platform/attribute/reference/events).
+## Steps
+
+The domain also exports its steps for use in your own workflows:
+
+| Step | Id | Compensation |
+| --- | --- | --- |
+| `createProductAttributesStep` | `pa-create-product-attributes` | Deletes the created attributes |
+| `updateProductAttributesStep` | `pa-update-product-attributes` | Restores previous field values |
+| `deleteProductAttributesStep` | `pa-delete-product-attributes` | Restores the soft-deleted attributes |
+| `createProductAttributeValuesStep` | `pa-create-product-attribute-values` | Deletes the created values |
+| `updateProductAttributeValuesStep` | `pa-update-product-attribute-values` | Restores previous field values |
+| `deleteProductAttributeValuesStep` | `pa-delete-product-attribute-values` | Restores the soft-deleted values |
+| `detachProductOptionValuesFromProductStep` | `pa-detach-product-option-values-from-product` | Re-attaches the option values |
+| `validateProductAttributesNotLinkedStep` | `pa-validate-attributes-not-linked` | None |
+| `validateProductAttributesNotRequiredStep` | `pa-validate-attributes-not-required` | None |
diff --git a/apps/docs/platform/catalog/concepts/master-products.mdx b/apps/docs/platform/catalog/concepts/master-products.mdx
index aadeb5192..2d418215a 100644
--- a/apps/docs/platform/catalog/concepts/master-products.mdx
+++ b/apps/docs/platform/catalog/concepts/master-products.mdx
@@ -1,54 +1,56 @@
---
-title: "Master products"
+title: "Master products in a shared catalog"
sidebarTitle: "Master products"
-description: "The shared catalog, why products aren't seller-owned, and submission attribution."
+description: "Why products belong to the marketplace catalog instead of a store, and how Mercur records who submitted each one."
---
-In this document, you'll learn how Mercur models products as a single shared
-catalog rather than per-seller listings.
+A master product is the one catalog record for an item that any number of stores can sell. Mercur keeps products out of store ownership so that two stores selling the same chair share one title, one set of variants, and one product page, and compete on their offers instead.
-## Product
+## One product, sold through offers
-A product is a **master product** in a catalog shared by the whole marketplace,
-represented by Medusa's native `Product` data model (table `product`, id prefix
-`prod`). Products carry the usual commerce fields such as `title`, `handle`,
-`description`, `status`, variants, options, and images, and are **not owned by
-any store**. Creating a product adds it to the shared catalog. Multiple stores
-can then sell the same master product.
+A master product is Medusa's native `Product` model (table `product`, id prefix `prod`). It holds the shared catalog data: `title`, `handle`, `description`, `status`, images, options, variants, and categories. It has no seller column. Creating a product adds it to the catalog, and stores then sell it by creating [offers](/platform/offer/overview) against its variants.
+
+The split between the two records works like this:
+
+- **Master product**: what the item is, shared by every store that sells it
+- **Offer**: how one store sells it, with the store's own SKU, price, stock, and shipping profile
+
+A store's stock and price never live on the variant. Offer inventory links to the offer, so a variant's `inventory_items` stay empty for marketplace sales.
+
+## Attribution instead of ownership
+
+Mercur records who submitted a product without making them its owner. `createProductsWorkflow` takes a required `created_by` and writes a confirmed `ProductChange` with that value as `created_by`, holding one `PRODUCT_ADD` action. The action's `details` store the starting `status` and the ids of the attributes the product began with.
+
+The vendor API passes the store's seller id as `created_by`, and the admin API passes the operator's user id. Mercur reads that record back to decide which products a store submitted:
```ts
-const { result } = await createProductsWorkflow(container).run({
- input: {
- products: [
- {
- title: "Aeron Chair",
- status: "proposed",
- seller_ids: ["sel_123"],
- },
- ],
- created_by: "usr_123",
+const { data: actions } = await query.graph({
+ entity: "product_change_action",
+ fields: ["product_id"],
+ filters: {
+ action: "PRODUCT_ADD",
+ product_change: { created_by: "sel_01JD8Q1234567" },
},
})
```
+The query returns the ids of every product the store submitted. Mercur runs the same lookup to let a store see its own `draft` and `proposed` submissions, which other stores never see.
+
<Note>
- A store never sells a bare master product directly. It sells against one by
- creating an [offer](/platform/offer/overview). The offer carries the store's
- own SKU, price, inventory, and shipping profile, while the master product
- holds the shared catalog data everyone shares.
+ Attribution grants visibility, not control of the catalog entry. Every edit a store makes through the vendor API, to its own submission or to a published product, goes through the [product edit pipeline](/platform/product-edit/overview).
</Note>
-## Attribution, not ownership
+## What a store sees
+
+The vendor API filters product reads by status, attribution, and the [allowlist](/platform/catalog/concepts/product-seller-allowlist). A store's product list contains:
+
+- **Its own submissions**: products it created that are `draft` or `proposed`
+- **Published products open to it**: `published` products whose allowlist is empty or includes the store
+
+A store can still read one of its own `rejected` products by id, but rejected products drop out of its list. The Store API returns `published` products only.
-Because the catalog is shared, the creator of a product does **not** own it.
-When a store submits a new product, Mercur records the submission as an immutable
-audit entry (a `PRODUCT_ADD` action in the product-change pipeline) so you know
-who proposed it. That attribution is for review and history only. Once
-published, the product belongs to the shared catalog like any other.
+## Related
-<Tip>
- Attribution is recorded automatically by `createProductsWorkflow` through its
- `created_by` input. You don't manage it by hand. See the
- [status lifecycle](/platform/catalog/concepts/status-lifecycle) for how a
- submission becomes a published catalog product.
-</Tip>
+- [Status lifecycle](/platform/catalog/concepts/status-lifecycle) for how a submission becomes a published product
+- [Create a master product](/platform/catalog/guides/create-a-master-product) to run the create workflow from your code
+- [Offers](/platform/offer/overview) for how stores sell a master product
diff --git a/apps/docs/platform/catalog/concepts/product-seller-allowlist.mdx b/apps/docs/platform/catalog/concepts/product-seller-allowlist.mdx
index 61f1c4a0c..4f311d117 100644
--- a/apps/docs/platform/catalog/concepts/product-seller-allowlist.mdx
+++ b/apps/docs/platform/catalog/concepts/product-seller-allowlist.mdx
@@ -1,48 +1,69 @@
---
-title: "The store allowlist"
+title: "Restrict a product to chosen stores"
sidebarTitle: "The allowlist"
-description: "The product_seller link that controls which stores may sell a master product."
+description: "How the product_seller link opens a product to every store or restricts it to the stores on its list."
---
-In this document, you'll learn how Mercur controls which stores are allowed to
-sell a shared master product.
+The store allowlist decides which stores can see and sell a published master product. It's a many-to-many link between Medusa's `Product` and Mercur's `Seller`, stored in the `product_seller` table. Use it for exclusive ranges, brand-authorized resellers, or products only certain stores may carry.
-## Product seller
+## Open by default, restricted by rows
-Since the catalog is shared, Mercur needs a way to say *which* stores may sell a
-given master product. That's the **product–seller allowlist**: a many-to-many
-link between Medusa's `Product` and Mercur's `Seller`, stored in the
-`product_seller` table.
+A product's allowlist has two states, and the number of `product_seller` rows decides which one applies. An empty allowlist doesn't block anyone: it means every store can sell the product.
+
+| `product_seller` rows | Who can see and sell the published product |
+| --- | --- |
+| None | Every store |
+| One or more | Only the stores on the list |
+
+Adding the first store to a product's allowlist closes it to every other store. Removing the last store opens it to all stores again.
+
+## Read a product's allowlist
+
+The link exposes the stores under the `sellers` alias on a product. Read it with `query.graph`:
```ts
-const { data: products } = await query.graph({
+const { data: [product] } = await query.graph({
entity: "product",
fields: ["id", "title", "sellers.id", "sellers.name"],
- filters: { id: "prod_123" },
+ filters: { id: "prod_01JD8Q1234567" },
})
+
+const isOpen = (product.sellers ?? []).length === 0
```
-A store appears in a product's `sellers` list only if it has been allowlisted.
-Being on the allowlist is what lets a store create an
-[offer](/platform/offer/overview) against the master product. Without it, the
-store cannot list that product for sale.
-
-<Note>
- The allowlist link is created automatically for the submitting store when a
- product is created with `seller_ids`, and managed afterwards with
- `linkSellersToProductWorkflow`. See
- [Allowlist stores](/platform/catalog/guides/allowlist-stores).
-</Note>
-
-## Category allowlist
-
-Product categories carry the same pattern through the `category_seller` link. It
-is a many-to-many association between `ProductCategory` and `Seller` that scopes
-which categories a store is associated with. Manage it with
-`linkSellersToProductCategoryWorkflow`.
-
-<Tip>
- The allowlist governs the **right to sell**, not the sale itself. A store on
- the allowlist still has to create an offer to actually list the product.
- Allowlisting alone doesn't put anything on the storefront.
-</Tip>
+An empty `sellers` array means the product is open to every store. You can also query the link table directly as the `product_seller` entity, with `product_id` and `seller_id` fields.
+
+## Where Mercur enforces it
+
+Mercur applies the allowlist when it scopes a store's view of the catalog. These vendor reads hide a published product restricted to other stores:
+
+- **Product list and detail**: the product returns `404` for a store not on its list
+- **Variant list**: variants of restricted products are filtered out
+- **Product variants under a product**: blocked with the product itself
+
+A store always sees its own `draft` and `proposed` submissions, whatever their allowlist. The admin API and the Store API don't filter by allowlist.
+
+<Warning>
+ `createOffersWorkflow` doesn't check the allowlist. If you create offers from your own server code, check the product's `sellers` first, or a store can sell a product it isn't allowed to.
+</Warning>
+
+## How stores get on the list
+
+Mercur writes `product_seller` rows in two places:
+
+- **On create**: `createProductsWorkflow` links every id in a product's `seller_ids` input
+- **Afterwards**: `linkSellersToProductWorkflow` adds and removes stores in one run
+
+The vendor API never passes `seller_ids`, so a store's own submission starts open to every store. An operator restricts it with `linkSellersToProductWorkflow`. Removing a store from the list doesn't touch the offers it already created.
+
+## The category_seller link
+
+Categories have a second link to stores, `category_seller`, between `ProductCategory` and `Seller` with the `sellers` alias on a category. `linkSellersToProductCategoryWorkflow` writes it.
+
+No shipped route or workflow reads the link to filter products. Mercur exports `validateSellerProductPermissionsStep`, which throws `Seller is restricted from categories` when the seller is linked to any of the category ids you pass. Add that step to your own workflow if you treat the link as a category block list.
+
+## Related
+
+- [Allowlist stores](/platform/catalog/guides/allowlist-stores) to manage the list from your code
+- [Master products](/platform/catalog/concepts/master-products) for what a store sees by default
+- [Links reference](/platform/catalog/reference/links) for every link on products and categories
diff --git a/apps/docs/platform/catalog/concepts/status-lifecycle.mdx b/apps/docs/platform/catalog/concepts/status-lifecycle.mdx
index 82cffcc6a..ed5ef5a24 100644
--- a/apps/docs/platform/catalog/concepts/status-lifecycle.mdx
+++ b/apps/docs/platform/catalog/concepts/status-lifecycle.mdx
@@ -1,58 +1,64 @@
---
-title: "Status lifecycle"
+title: "Product status lifecycle"
sidebarTitle: "Status lifecycle"
-description: "How a master product moves from draft to proposed, published, or rejected."
+description: "How a master product moves from draft or proposed to published or rejected, and which workflow runs each step."
---
-In this document, you'll learn about the product status lifecycle and how a
-submission becomes a live catalog product.
+Every master product has a `status` that decides who can see it and whether it's for sale. Mercur uses that status as a review gate: stores submit products as `proposed`, and an operator decides whether each one joins the published catalog.
-## Status
+## The four statuses
-A product's state is held in the `status` field of the `Product` model, typed by
-Medusa's `ProductStatus` enum. A master product moves through four statuses:
+The status lives in the `status` field of Medusa's `Product` model. Mercur re-exports the values as `ProductStatus` from `@mercurjs/types`. The model default is `draft`.
+| Status | Meaning | Who sees it |
+| --- | --- | --- |
+| `draft` | Work in progress, not submitted | Operators and the submitting store |
+| `proposed` | Submitted and waiting for review | Operators and the submitting store |
+| `published` | Live in the shared catalog | Everyone the [allowlist](/platform/catalog/concepts/product-seller-allowlist) permits, and the Store API |
+| `rejected` | Turned down in review | Operators, and the submitting store by id |
+
+## Review transitions
+
+Mercur ships one workflow per review step. Each one reads the product, checks its status with `validateProductsStatusStep`, records a confirmed `ProductChange`, and emits an event.
+
+<img className="block dark:hidden" src="/images/figures/catalog-status-lifecycle-light.svg" alt="A Status transitions table: createProductsWorkflow creates a product as proposed, then confirmProductsWorkflow, rejectProductWorkflow, and requestProductChangeWorkflow move it to published, to rejected, or keep it proposed, with a product_change audit table behind." />
+<img className="hidden dark:block" src="/images/figures/catalog-status-lifecycle-dark.svg" alt="A Status transitions table: createProductsWorkflow creates a product as proposed, then confirmProductsWorkflow, rejectProductWorkflow, and requestProductChangeWorkflow move it to published, to rejected, or keep it proposed, with a product_change audit table behind." />
+
+| Workflow | From | To | Audit action | Event |
+| --- | --- | --- | --- | --- |
+| `createProductsWorkflow` | none | input `status` | `PRODUCT_ADD` | `product.created` |
+| `confirmProductsWorkflow` | `proposed` | `published` | `STATUS_CHANGE` | `product.published` |
+| `rejectProductWorkflow` | `proposed` | `rejected` | `STATUS_CHANGE` | `product.rejected` |
+| `requestProductChangeWorkflow` | `proposed` | `proposed` | `CHANGE_REQUESTED` | `product.change-requested` |
+
+The three review workflows run only on `proposed` products. A product in any other status fails with a `NOT_ALLOWED` error that lists each product id and its current status.
+
+## Starting status
+
+The status a product starts in depends on who creates it. `createProductsWorkflow` passes the `status` you give it to Medusa, which falls back to `draft`.
+
+- **Vendor API**: defaults to `proposed`; a store may also send `draft`
+- **Admin API**: uses the request's `status`, or `draft` when it has none
+- **Your own code**: whatever you pass, or `draft`
+
+The vendor rule comes from the `product_request` feature flag, which is on by default. Turn it off with `MEDUSA_FF_PRODUCT_REQUEST=false` and stores can create products in any status, including `published`.
+
+```bash title=".env"
+MEDUSA_FF_PRODUCT_REQUEST=false
```
- ┌────────┐ submit ┌──────────┐ approve ┌────────────┐
- │ draft │ ──────────►│ proposed │ ──────────►│ published │
- └────────┘ └────┬─────┘ └────────────┘
- │ reject
- ▼
- ┌────────────┐
- │ rejected │
- └────────────┘
-```
-| Status | Meaning |
-| --- | --- |
-| `draft` | Work in progress, not yet submitted for review |
-| `proposed` | Submitted, awaiting operator review |
-| `published` | Approved and live in the shared catalog, sellable via offers |
-| `rejected` | Turned down during review |
-
-<Note>
- Vendor-created products default to **`proposed`**. A store submits a product
- for review rather than publishing it directly. An operator (or a low-risk
- auto-confirm rule) is what promotes it to `published`.
-</Note>
-
-## Transitions
-
-Each review transition has a dedicated Mercur workflow so the audit trail,
-events, and side effects run consistently:
-
-| Workflow | Transition |
-| --- | --- |
-| `confirmProductsWorkflow` | `proposed` → `published` |
-| `rejectProductWorkflow` | `proposed` → `rejected` |
-| `requestProductChangeWorkflow` | stays `proposed`, asks the submitter for a revision |
-
-Every transition validates that the product is currently `proposed` before it
-runs, and records an immutable `STATUS_CHANGE` (or `CHANGE_REQUESTED`) action in
-the product-change pipeline for a full history of who reviewed what.
-
-<Tip>
- Reviewing a product doesn't touch offers. Publishing makes the master product
- sellable, but each store still lists it independently through its own
- [offer](/platform/offer/overview).
-</Tip>
+The same flag controls whether store edits to existing products wait for review. See [status and auto-confirm](/platform/product-edit/concepts/status-and-auto-confirm).
+
+## Changes outside the review workflows
+
+Mercur ships no workflow that moves a `draft` to `proposed`, or a `published` product back. Those changes go through a regular product update. The admin API runs Medusa's `updateProductsWorkflow` for that, which accepts any status.
+
+<Warning>
+ A direct status update skips the `proposed` check, writes no `STATUS_CHANGE` record, and emits none of Mercur's product events. Use the review workflows when you need the audit trail.
+</Warning>
+
+## Related
+
+- [Publish or reject a product](/platform/catalog/guides/publish-or-reject-a-product) to run the review workflows
+- [Workflows reference](/platform/catalog/reference/workflows) for inputs and hooks
+- [Change pipeline](/platform/product-edit/concepts/change-pipeline) for how edits to existing products are reviewed
diff --git a/apps/docs/platform/catalog/concepts/variants-categories-collections.mdx b/apps/docs/platform/catalog/concepts/variants-categories-collections.mdx
index 828f17667..cf0c64c3c 100644
--- a/apps/docs/platform/catalog/concepts/variants-categories-collections.mdx
+++ b/apps/docs/platform/catalog/concepts/variants-categories-collections.mdx
@@ -1,49 +1,69 @@
---
-title: "Variants, categories & collections"
+title: "Variants, categories, and collections"
sidebarTitle: "Variants & categories"
-description: "The native Medusa Product structure the shared catalog is built on."
+description: "The Medusa Product module models that structure the shared catalog, and the places Mercur extends them."
---
-In this document, you'll learn about the structural models that organize the
-shared catalog, all of them native to Medusa's Product module.
+The shared catalog is built from Medusa's Product module models. Variants describe what a customer can buy, and categories, collections, tags, and types organize products for browsing. Mercur keeps these models as they are and changes how variants get their options and where a variant's price and stock come from.
-## Product variant
+## Variants come from attributes
-A variant is a purchasable configuration of a master product, represented by the
-`ProductVariant` data model (table `product_variant`, id prefix `variant`).
-Variants are generated from a product's options, including Mercur attributes
-marked as variant axes, and hold the SKU-level structure of the catalog entry.
+A variant is one purchasable configuration of a master product: Medusa's `ProductVariant` model (id prefix `variant`). Each variant binds to one value of every product option, such as Size `M`.
+
+When you create a product through Mercur's `createProductsWorkflow`, you don't pass native `options`. You pass Mercur `attributes`, and every `multi_select` attribute marked `is_variant_axis` becomes a native `ProductOption`. Each variant then names its option values by title:
```ts
-const { data: products } = await query.graph({
- entity: "product",
- fields: ["id", "title", "variants.id", "variants.title", "options.*"],
- filters: { id: "prod_123" },
-})
+const product = {
+ title: "Linen shirt",
+ attributes: [
+ { title: "Size", is_variant_axis: true, values: ["S", "M"] },
+ ],
+ variants: [
+ { title: "S", options: { Size: "S" } },
+ { title: "M", options: { Size: "M" } },
+ ],
+}
```
-<Note>
- Offer-based inventory and pricing live on the [offer](/platform/offer/overview),
- not the variant. The variant defines the shared catalog structure. Each store's
- stock and price come from its own offer.
-</Note>
+Medusa requires every product to have at least one option. Mercur creates each product with an internal `__default__` option and removes it once a variant-axis attribute attaches a real one. Products without an axis keep it.
+
+## Price and stock live on offers
+
+A variant holds catalog data such as `title`, `sku`, `ean`, and dimensions. It doesn't hold a store's price or stock. Mercur's create workflow sets `manage_inventory` to `false` on new variants unless you pass it, because each store's stock lives on its [offer](/platform/offer/overview).
-## Categories & collections
+- **Price**: an offer-scoped price on the variant's price set, matched by an `offer_id` rule
+- **Stock**: inventory items linked to the offer, not the variant
+- **SKU**: the store's own SKU on the offer, unique per store
+
+## Grouping models
Products are organized with Medusa's native grouping models:
-| Model | Purpose |
-| --- | --- |
-| `ProductCategory` | Hierarchical, nestable classification (id prefix `pcat`) |
-| `ProductCollection` | Flat, curated grouping (id prefix `pcol`) |
-| `ProductTag` | Free-form labels for filtering |
-| `ProductType` | A single type classification per product |
-
-Assign products to a category with `assignProductsToCategoryWorkflow`, which
-keeps each product in exactly one category at a time.
-
-<Tip>
- Categories participate in the marketplace layer too: the `category_seller`
- link scopes which stores a category is associated with, mirroring the product
- [allowlist](/platform/catalog/concepts/product-seller-allowlist).
-</Tip>
+| Model | Id prefix | Shape | Mercur extension |
+| --- | --- | --- | --- |
+| `ProductCategory` | `pcat` | Nested tree through `parent_category` | `media_images`, `sellers`, attribute link |
+| `ProductCollection` | `pcol` | Flat group, one per product | `media_images` |
+| `ProductTag` | `ptag` | Free-form labels, many per product | None |
+| `ProductType` | `ptyp` | One type per product | None |
+
+Categories and collections link to Mercur's media module through `media_images` for gallery and icon images. A category also links to stores through `category_seller` and to product attributes through `product_category_attribute`. See the [links reference](/platform/catalog/reference/links).
+
+## One category per product
+
+Medusa lets a product belong to several categories. Mercur's `assignProductsToCategoryWorkflow` keeps one category per product: adding a product to a category replaces the categories it had.
+
+```ts
+import { assignProductsToCategoryWorkflow } from "@mercurjs/core/workflows"
+
+await assignProductsToCategoryWorkflow(container).run({
+ input: { id: "pcat_01JD8Q1234567", add: ["prod_01JD8Q1234567"] },
+})
+```
+
+The product now belongs only to `pcat_01JD8Q1234567`. Passing a product id in `remove` clears all its categories, not only this one.
+
+## Related
+
+- [Attributes](/platform/attribute/overview) for attribute types and variant axes
+- [Data models](/platform/catalog/reference/data-models) for every field on these models
+- [Offers](/platform/offer/overview) for price and stock per store
diff --git a/apps/docs/platform/catalog/guides/allowlist-stores.mdx b/apps/docs/platform/catalog/guides/allowlist-stores.mdx
index c294d6716..5e9415845 100644
--- a/apps/docs/platform/catalog/guides/allowlist-stores.mdx
+++ b/apps/docs/platform/catalog/guides/allowlist-stores.mdx
@@ -1,59 +1,122 @@
---
-title: "Allowlist stores"
+title: "Restrict a product to chosen stores"
sidebarTitle: "Allowlist stores"
-description: "Grant and revoke a store's right to sell a master product from server code."
+description: "Add stores to a product's allowlist, remove them, and open a product to every store again from server code."
---
-In this guide, you'll learn how to control which stores may sell a shared master
-product by managing the `product_seller` allowlist from your own server code.
+Run `linkSellersToProductWorkflow` to change which stores can see and sell a master product. Use it for exclusive ranges, authorized resellers, or to restrict a store's own submission after review.
-A store can only create an [offer](/platform/offer/overview) against a master
-product if it's on that product's allowlist. Mercur exposes
-`linkSellersToProductWorkflow` to add and remove stores in a single call.
+## Before you begin
-## Add and remove stores
+Know how the list behaves before you change it:
-```ts title="src/api/custom/allowlist/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { linkSellersToProductWorkflow } from "@mercurjs/core/workflows"
+- **Empty list**: every store can sell the product
+- **One or more stores**: only those stores can sell it
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
- await linkSellersToProductWorkflow(req.scope).run({
- input: {
- id: req.params.id, // product id
- add: ["sel_123", "sel_456"],
- remove: ["sel_789"],
- },
- })
+Read [the store allowlist](/platform/catalog/concepts/product-seller-allowlist) for where Mercur enforces it.
- res.sendStatus(200)
+## Change a product's allowlist
+
+<Steps>
+ <Step title="Add a route that runs the workflow">
+ The workflow takes the product `id` and optional `add` and `remove` arrays of seller ids. It writes and deletes `product_seller` rows in one run.
+
+ ```ts title="src/api/admin/exclusive-products/[id]/route.ts"
+ import type {
+ MedusaRequest,
+ MedusaResponse,
+ } from "@medusajs/framework/http"
+ import { linkSellersToProductWorkflow } from "@mercurjs/core/workflows"
+
+ type Body = { add?: string[]; remove?: string[] }
+
+ export async function POST(
+ req: MedusaRequest<Body>,
+ res: MedusaResponse
+ ) {
+ await linkSellersToProductWorkflow(req.scope).run({
+ input: { id: req.params.id, ...req.body },
+ })
+
+ res.json({ id: req.params.id })
+ }
+ ```
+
+ If a step fails, the workflow undoes the rows it already changed.
+ </Step>
+ <Step title="Check the result">
+ Read the product's `sellers` to confirm the new list.
+
+ ```ts
+ const { data: [product] } = await query.graph({
+ entity: "product",
+ fields: ["id", "sellers.id"],
+ filters: { id: "prod_01JD8Q1234567" },
+ })
+ ```
+
+ `product.sellers` holds every store on the list. An empty array means the product is open to all stores.
+ </Step>
+</Steps>
+
+## Open a product to every store again
+
+Remove every store on the list. Read the current stores first, then pass all of them in `remove`.
+
+```ts
+const { data: [product] } = await query.graph({
+ entity: "product",
+ fields: ["sellers.id"],
+ filters: { id: "prod_01JD8Q1234567" },
+})
+
+await linkSellersToProductWorkflow(container).run({
+ input: {
+ id: "prod_01JD8Q1234567",
+ remove: (product.sellers ?? []).map((seller) => seller.id),
+ },
+})
+```
+
+The product now has no `product_seller` rows, so every store can see and sell it once it's published.
+
+## Check the allowlist before creating offers
+
+`createOffersWorkflow` doesn't read the allowlist. If your code creates offers for stores, read the product's `sellers` as shown above and check that the store may sell it first.
+
+```ts
+import { MedusaError } from "@medusajs/framework/utils"
+
+const sellerIds = (product.sellers ?? []).map((seller) => seller.id)
+const allowed =
+ sellerIds.length === 0 || sellerIds.includes("sel_01JD8Q1234567")
+
+if (!allowed) {
+ throw new MedusaError(
+ MedusaError.Types.NOT_ALLOWED,
+ "This store can't sell the product"
+ )
}
```
-<Note>
- `add` and `remove` are both optional. Pass either or both. Adding a store
- that's already allowlisted is idempotent. Removing a store revokes its right
- to sell the product going forward.
-</Note>
+`allowed` is true when the list is empty or names the store. Removing a store from the list later doesn't delete the offers it already has.
-## Allowlist a category
+## Link stores to a category
-Categories use the same shape through `linkSellersToProductCategoryWorkflow`,
-scoping which stores a category is associated with:
+`linkSellersToProductCategoryWorkflow` writes the `category_seller` link with the same input shape.
```ts
import { linkSellersToProductCategoryWorkflow } from "@mercurjs/core/workflows"
await linkSellersToProductCategoryWorkflow(container).run({
- input: {
- id: "pcat_123",
- add: ["sel_123"],
- },
+ input: { id: "pcat_01JD8Q1234567", add: ["sel_01JD8Q1234567"] },
})
```
-<Tip>
- Allowlisting grants the **right to sell**, not the listing itself. After a
- store is allowlisted, it still has to create an offer for the product to
- appear on its storefront.
-</Tip>
+Mercur doesn't filter products by this link. Run `validateSellerProductPermissionsStep` in your own workflow if you want linked stores blocked from a category.
+
+## Next steps
+
+- [Create a master product](/platform/catalog/guides/create-a-master-product) with `seller_ids` set from the start
+- [Create an offer](/platform/offer/guides/create-an-offer) for an allowed store
+- [Links reference](/platform/catalog/reference/links) for the `product_seller` and `category_seller` definitions
diff --git a/apps/docs/platform/catalog/guides/create-a-master-product.mdx b/apps/docs/platform/catalog/guides/create-a-master-product.mdx
index 0315fa8c5..b1f05ed5f 100644
--- a/apps/docs/platform/catalog/guides/create-a-master-product.mdx
+++ b/apps/docs/platform/catalog/guides/create-a-master-product.mdx
@@ -1,70 +1,146 @@
---
-title: "Create a master product"
+title: "Create a master product from server code"
sidebarTitle: "Create a master product"
-description: "Create a master product programmatically with createProductsWorkflow."
+description: "Add a product to the shared catalog with Mercur's createProductsWorkflow, including attributes, variants, and an allowlist."
---
-In this guide, you'll learn how to add a product to the shared catalog from your
-own server code, for example in a seed script, a custom API route, or an import
-flow.
+Run `createProductsWorkflow` to add a product to the shared catalog from a custom route, a seed script, or an import job. It creates the product and its variants, attaches attributes, links any stores you name, and records the submission.
-Mercur exposes a `createProductsWorkflow` that creates the `Product` record,
-attaches attributes and variants, records the submission for audit, and
-optionally allowlists the submitting store. Run it from any place that has access
-to the Medusa container.
+## Before you begin
-## Run the workflow
+You need the following in place:
-```ts title="src/api/custom/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { createProductsWorkflow } from "@mercurjs/core/workflows"
+- A Mercur server with `@mercurjs/core` installed
+- The ids of any [attributes](/platform/attribute/overview) and stores you want to reference
+
+<Warning>
+ Import `createProductsWorkflow` from `@mercurjs/core/workflows`, not `@medusajs/medusa/core-flows`. Medusa's workflow has the same name but skips attributes, the allowlist, and the audit record.
+</Warning>
+
+## Create the product
+
+<Steps>
+ <Step title="Add a route that runs the workflow">
+ Create an admin route. The workflow returns the created `ProductDTO` objects in input order.
+
+ ```ts title="src/api/admin/supplier-products/route.ts"
+ import type {
+ AuthenticatedMedusaRequest,
+ MedusaResponse,
+ } from "@medusajs/framework/http"
+ import { createProductsWorkflow } from "@mercurjs/core/workflows"
+
+ export async function POST(
+ req: AuthenticatedMedusaRequest,
+ res: MedusaResponse
+ ) {
+ const { result } = await createProductsWorkflow(req.scope).run({
+ input: {
+ products: [{ title: "Aeron Chair", status: "proposed" }],
+ created_by: req.auth_context.actor_id,
+ },
+ })
+
+ res.status(201).json({ product: result[0] })
+ }
+ ```
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
- const { result } = await createProductsWorkflow(req.scope).run({
- input: {
- products: [
+ `created_by` is required. Mercur stores it on the `PRODUCT_ADD` change as the submitter. Without a `status`, the product starts as `draft`.
+ </Step>
+ <Step title="Add attributes and variants">
+ Pass `attributes` instead of native `options`. A `multi_select` attribute with `is_variant_axis` becomes the option that variants bind to by title.
+
+ ```ts
+ const product = {
+ title: "Aeron Chair",
+ status: "proposed" as const,
+ attributes: [
{
- title: "Aeron Chair",
- status: "proposed",
- seller_ids: ["sel_123"],
+ id: "pattr_01JD8Q1234567",
+ value_ids: ["pattrval_01JD8Q1234567"],
},
+ { title: "Size", is_variant_axis: true, values: ["B", "C"] },
],
- created_by: req.auth_context.actor_id,
- },
- })
-
- res.status(201).json({ product: result[0] })
-}
-```
+ variants: [
+ { title: "Size B", options: { Size: "B" } },
+ { title: "Size C", options: { Size: "C" } },
+ ],
+ }
+ ```
-<Note>
- Passing `seller_ids` allowlists those stores for the product as it's created,
- so the submitting store can immediately create an
- [offer](/platform/offer/overview) against it. `created_by` records who
- submitted the product for the audit trail.
-</Note>
+ The first entry attaches a global attribute with a chosen value. The second creates a product-scoped axis. New variants get `manage_inventory: false` unless you set it, since stock lives on [offers](/platform/offer/overview).
+ </Step>
+ <Step title="Restrict the product to stores">
+ Add `seller_ids` to a product to put those stores on its [allowlist](/platform/catalog/concepts/product-seller-allowlist).
-## Default status
+ ```ts
+ const product = {
+ title: "Aeron Chair",
+ seller_ids: ["sel_01JD8Q1234567", "sel_01JD8Q1234568"],
+ }
+ ```
-A product created without an explicit `status` follows the marketplace's review
-flow. Vendor-created products default to **`proposed`**, submitted for operator
-review rather than published outright. Set `status: "draft"` to keep a product
-private until it's ready, or `status: "published"` from a trusted operator flow
-to skip review. See the
-[status lifecycle](/platform/catalog/concepts/status-lifecycle).
+ Only these 2 stores can see and sell the product once it's published. Leave `seller_ids` out to open it to every store.
+ </Step>
+</Steps>
-## Attach custom data
+## Submit on behalf of a store
-The workflow accepts an `additional_data` payload passed to its hooks, letting
-you persist marketplace-specific data alongside the product without forking the
-workflow.
+Pass the store's seller id as `created_by` to make the product a submission from that store. That's what the vendor API does, and it's how Mercur lets a store see its own `draft` and `proposed` products.
```ts
-await createProductsWorkflow(req.scope).run({
+await createProductsWorkflow(container).run({
input: {
- products: [{ title: "Aeron Chair", seller_ids: ["sel_123"] }],
- created_by: "usr_123",
- additional_data: { source: "supplier-feed" },
+ products: [{ title: "Desk lamp", status: "proposed" }],
+ created_by: "sel_01JD8Q1234567",
},
})
```
+
+The product appears in that store's product list as a proposed submission, and stays hidden from other stores until it's published.
+
+## Validate input with the validate hook
+
+The workflow runs a `validate` hook before it creates anything. Throw from the handler to stop the run.
+
+```ts title="src/workflows/hooks/validate-products.ts"
+import { createProductsWorkflow } from "@mercurjs/core/workflows"
+import { MedusaError } from "@medusajs/framework/utils"
+
+createProductsWorkflow.hooks.validate(async ({ products }) => {
+ const missing = products.find((p) => !p.description)
+ if (missing) {
+ throw new MedusaError(
+ MedusaError.Types.INVALID_DATA,
+ `Product "${missing.title}" needs a description`
+ )
+ }
+})
+```
+
+The hook receives the raw `input` and its `products` array, so you can check any field before Medusa writes rows.
+
+## Attach custom data with additional_data
+
+Pass `additional_data` to carry extra values through the run. Mercur forwards it to Medusa's product and variant workflows and to the `productsCreated` hook.
+
+```ts title="src/workflows/hooks/products-created.ts"
+import { createProductsWorkflow } from "@mercurjs/core/workflows"
+
+createProductsWorkflow.hooks.productsCreated(
+ async ({ products, additional_data }, { container }) => {
+ const logger = container.resolve("logger")
+ const source = additional_data?.source
+
+ logger.info(`Imported ${products.length} products from ${source}`)
+ }
+)
+```
+
+Call the workflow with `additional_data: { source: "supplier_feed" }` and the handler receives it next to the created products.
+
+## Next steps
+
+- [Publish or reject a product](/platform/catalog/guides/publish-or-reject-a-product) to review what you created
+- [Allowlist stores](/platform/catalog/guides/allowlist-stores) to change the store list later
+- [Create an offer](/platform/offer/guides/create-an-offer) so a store can sell the product
diff --git a/apps/docs/platform/catalog/guides/publish-or-reject-a-product.mdx b/apps/docs/platform/catalog/guides/publish-or-reject-a-product.mdx
index e07101836..4ec4b9c11 100644
--- a/apps/docs/platform/catalog/guides/publish-or-reject-a-product.mdx
+++ b/apps/docs/platform/catalog/guides/publish-or-reject-a-product.mdx
@@ -1,79 +1,144 @@
---
-title: "Publish or reject a product"
+title: "Publish or reject a proposed product"
sidebarTitle: "Publish or reject"
-description: "Move a proposed master product to published or rejected from server code."
+description: "Review a store's product submission from server code: publish it, reject it, or ask for a revision."
---
-In this guide, you'll learn how to review a submitted product from your own
-server code. Each transition has a dedicated workflow so the audit trail, events,
-and side effects run consistently.
+Run Mercur's review workflows to decide on a `proposed` product from a custom route, a subscriber, or a scheduled job. Each one checks the status, records who reviewed the product, and emits an event.
-A product enters review as `proposed`. From there you can publish it, reject it,
-or ask the submitter for a revision. Every workflow validates that the product is
-currently `proposed` before it runs.
+## Before you begin
-## Publish a product
+You need the following in place:
-Move one or more `proposed` products to `published` with
-`confirmProductsWorkflow`:
+- A product in `proposed` status, such as a store submission
+- The id of the operator or system acting, for the audit record
-```ts title="src/api/custom/publish/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+The workflows fail with a `NOT_ALLOWED` error for any product that isn't `proposed`.
+
+## Review a product
+
+<Steps>
+ <Step title="Publish it">
+ `confirmProductsWorkflow` publishes one or more products in a single run. `internal_note` is stored on each audit record for operators.
+
+ ```ts title="src/api/admin/reviews/publish/route.ts"
+ import type {
+ AuthenticatedMedusaRequest,
+ MedusaResponse,
+ } from "@medusajs/framework/http"
+ import { confirmProductsWorkflow } from "@mercurjs/core/workflows"
+
+ type Body = { product_ids: string[] }
+
+ export async function POST(
+ req: AuthenticatedMedusaRequest<Body>,
+ res: MedusaResponse
+ ) {
+ await confirmProductsWorkflow(req.scope).run({
+ input: {
+ product_ids: req.body.product_ids,
+ actor_id: req.auth_context.actor_id,
+ internal_note: "Checked against the supplier sheet",
+ },
+ })
+
+ res.json({ published: req.body.product_ids })
+ }
+ ```
+
+ If any product isn't `proposed`, the run fails and none of them change.
+ </Step>
+ <Step title="Or reject it">
+ `rejectProductWorkflow` handles one product. `message` is stored as the change's `external_note`, the note the store can read.
+
+ ```ts
+ import { rejectProductWorkflow } from "@mercurjs/core/workflows"
+
+ await rejectProductWorkflow(container).run({
+ input: {
+ product_id: "prod_01JD8Q1234567",
+ message: "Images don't match the description",
+ actor_id: "user_01JD8Q1234567",
+ },
+ })
+ ```
+
+ The product moves to `rejected` and leaves the store's product list.
+ </Step>
+ <Step title="Or ask for a revision">
+ `requestProductChangeWorkflow` keeps the product `proposed` and records a `CHANGE_REQUESTED` action with your message.
+
+ ```ts
+ import { requestProductChangeWorkflow } from "@mercurjs/core/workflows"
+
+ await requestProductChangeWorkflow(container).run({
+ input: {
+ product_id: "prod_01JD8Q1234567",
+ message: "Add a size B variant",
+ actor_id: "user_01JD8Q1234567",
+ },
+ })
+ ```
+
+ The product stays in the review queue, and your message is stored as the change's `external_note`.
+ </Step>
+</Steps>
+
+## Run a review from a subscriber
+
+Review products automatically by running a workflow when they're created. This subscriber publishes products from one trusted store.
+
+```ts title="src/subscribers/auto-publish-trusted.ts"
+import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
import { confirmProductsWorkflow } from "@mercurjs/core/workflows"
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
- await confirmProductsWorkflow(req.scope).run({
- input: {
- product_ids: [req.params.id],
- actor_id: req.auth_context.actor_id,
- internal_note: "Looks good",
- },
+export default async function autoPublish({
+ event,
+ container,
+}: SubscriberArgs<{ id: string }>) {
+ const query = container.resolve("query")
+ const { data: [action] } = await query.graph({
+ entity: "product_change_action",
+ fields: ["product_change.created_by"],
+ filters: { product_id: event.data.id, action: "PRODUCT_ADD" },
})
+ if (action?.product_change?.created_by !== "sel_01JD8Q1234567") return
- res.sendStatus(200)
+ await confirmProductsWorkflow(container).run({
+ input: { product_ids: [event.data.id], actor_id: "system" },
+ })
}
+
+export const config: SubscriberConfig = { event: "product.created" }
```
-## Reject a product
+The handler reads the `PRODUCT_ADD` record to find the submitter, then publishes. `product.created` fires twice for each product created through Mercur's workflow, so the second run fails the `proposed` check. Catch that error, or check the status first.
-```ts
-import { rejectProductWorkflow } from "@mercurjs/core/workflows"
+## React to the outcome with hooks
-await rejectProductWorkflow(container).run({
- input: {
- product_id: "prod_123",
- message: "Images don't match the description",
- actor_id: "usr_123",
- },
-})
-```
+Each review workflow exposes a hook that runs after the status change. Use it for side effects that must happen inside the same run.
-## Request a revision
+| Workflow | Hook | Hook input |
+| --- | --- | --- |
+| `confirmProductsWorkflow` | `productsConfirmed` | `product_ids`, `internal_note`, `additional_data` |
+| `rejectProductWorkflow` | `productRejected` | `product_id`, `message`, `additional_data` |
+| `requestProductChangeWorkflow` | `productChangeRequested` | `product_id`, `message`, `additional_data` |
-To send the submission back for changes without rejecting it, use
-`requestProductChangeWorkflow`. The product stays `proposed` and a
-`CHANGE_REQUESTED` action is recorded for the submitter to act on:
-
-```ts
-import { requestProductChangeWorkflow } from "@mercurjs/core/workflows"
+```ts title="src/workflows/hooks/product-rejected.ts"
+import { rejectProductWorkflow } from "@mercurjs/core/workflows"
-await requestProductChangeWorkflow(container).run({
- input: {
- product_id: "prod_123",
- message: "Please add a size variant",
- actor_id: "usr_123",
- },
-})
+rejectProductWorkflow.hooks.productRejected(
+ async ({ product_id, message }, { container }) => {
+ const logger = container.resolve("logger")
+ logger.info(`Rejected ${product_id}: ${message ?? "no reason"}`)
+ }
+)
```
-<Warning>
- These workflows require the product to be `proposed`. Running them against a
- `draft`, `published`, or `rejected` product fails validation rather than
- forcing the transition.
-</Warning>
+For work that can run later, subscribe to `product.published`, `product.rejected`, or `product.change-requested` instead.
-## React to review outcomes
+## Next steps
-To run your own side effects when a product is published or rejected, subscribe
-to the events these workflows emit rather than polling. See the
-[Event reference](/platform/catalog/reference/events) for the event names.
+- [Event reference](/platform/catalog/reference/events) for payloads
+- [Status lifecycle](/platform/catalog/concepts/status-lifecycle) for every transition
+- [Request a revision](/platform/product-edit/guides/request-a-revision) for edits to published products
diff --git a/apps/docs/platform/catalog/overview.mdx b/apps/docs/platform/catalog/overview.mdx
index d7eb292c9..72cb2ea78 100644
--- a/apps/docs/platform/catalog/overview.mdx
+++ b/apps/docs/platform/catalog/overview.mdx
@@ -1,90 +1,94 @@
---
title: "Catalog"
sidebarTitle: "Overview"
-description: "Master products, variants, categories, and the store allowlist that governs who may sell what."
+description: "Keep one shared product catalog, decide which stores may sell each product, and review what stores submit."
---
-Use Mercur to govern one shared product catalog and control which stores are
-allowed to sell what.
+Use Mercur to keep one product catalog for the whole marketplace and control which stores can sell each product.
-Master-data governance lives here. The Catalog domain keeps products as a single
-shared source of truth, controls access to it through an allowlist over who may
-sell each product, and holds every submission to an approval lifecycle before it
-goes live. On top of that governance layer it holds master products, variants,
-categories, collections, tags, and types. A store never owns a product. It sells
-against a shared master product through an [offer](/platform/offer/overview).
+The catalog is Medusa's Product module (`Modules.PRODUCT`) with a marketplace layer on top. Products, variants, categories, collections, tags, and types are native Medusa models. Mercur adds the `product_seller` allowlist, a review flow over the product `status`, an audit record for every submission, and its own product workflows. No store owns a product: a store sells a master product through an [offer](/platform/offer/overview) that carries its own SKU, price, and stock.
+
+<img className="block dark:hidden" src="/images/figures/catalog-overview-light.svg" alt="A product_seller link table behind a Products list of the shared catalog: each master product shows its status, the stores on its allowlist, and its offer count, with the Linen shirt restricted to ACME highlighted." />
+<img className="hidden dark:block" src="/images/figures/catalog-overview-dark.svg" alt="A product_seller link table behind a Products list of the shared catalog: each master product shows its status, the stores on its allowlist, and its offer count, with the Linen shirt restricted to ACME highlighted." />
<Note>
- **Catalog = Medusa's Product module + Mercur's marketplace layer.** Products,
- variants, categories, and collections are Medusa's native `Product` module.
- Mercur adds the `product_seller` allowlist (which stores may sell a product),
- the `draft` → `proposed` → `published` / `rejected` status lifecycle, and its
- own product workflows. Products are **shared master products**, not
- seller-owned, and a store sells one via an [offer](/platform/offer/overview).
+ There's no Mercur catalog module. Resolve the service with `Modules.PRODUCT` from `@medusajs/framework/utils`, and run Mercur's product workflows from `@mercurjs/core/workflows`. Mercur's `createProductsWorkflow` has the same name as Medusa's, so check the import path.
</Note>
## Key features
-- **Shared master data:** products live in one catalog, not owned by any store. Creating a product adds it to the shared catalog.
-- **Allowlist access control:** the `product_seller` link governs which stores may sell a given master product.
-- **Approval governance:** a `draft` → `proposed` → `published` / `rejected` lifecycle, with vendor-created products defaulting to `proposed`.
-- **Attribution, not ownership:** the creator of an unreviewed submission is recorded for audit, but the product still belongs to the shared catalog.
-- **Native Medusa structure:** variants, categories, collections, tags, and types come straight from Medusa's Product module.
-- **Sold via offers:** a store lists a master product by creating an offer that carries its SKU, price, and inventory.
+The catalog layer covers how products enter the marketplace and who can sell them:
+
+- **Shared master products**: one `Product` record per item, sold by any number of stores through offers
+- **Store allowlist**: the `product_seller` link restricts a product to the stores on it; a product with no rows is open to every store
+- **Review flow**: vendor submissions start as `proposed` and an operator publishes or rejects them
+- **Submission audit**: every create and review step writes a confirmed `ProductChange` record with the actor who did it
+- **Attribute-driven variants**: products take Mercur attributes on create, and variant-axis attributes become the options variants bind to
+- **Native structure**: variants, categories, collections, tags, and types come straight from Medusa's Product module
+
+## How it works
+
+A product moves through the catalog in a fixed order:
+
+1. A store or an operator runs `createProductsWorkflow`. Vendor submissions default to `proposed`.
+2. The workflow records a `PRODUCT_ADD` change with the creator as `created_by`, and links any `seller_ids` to the product.
+3. An operator runs `confirmProductsWorkflow`, `rejectProductWorkflow`, or `requestProductChangeWorkflow` on the proposed product.
+4. Once `published`, the product shows in the Store API and to every store its allowlist permits.
+5. Each store that sells it creates an offer against one of its variants.
## Get started
-Learn how the domain fits together.
+Learn how master products, the allowlist, and statuses fit together.
<CardGroup cols={2}>
<Card title="Master products" icon="box" href="/platform/catalog/concepts/master-products">
- The shared catalog, why products aren't seller-owned, and submission attribution.
+ Why products belong to the catalog and how Mercur records who submitted them.
</Card>
<Card title="The store allowlist" icon="user-lock" href="/platform/catalog/concepts/product-seller-allowlist">
- The `product_seller` link that controls who may sell a product.
+ How the `product_seller` link decides which stores see and sell a product.
</Card>
<Card title="Status lifecycle" icon="arrows-rotate" href="/platform/catalog/concepts/status-lifecycle">
- Draft, proposed, published, and rejected, plus how products move between them.
+ The four statuses and the workflow behind each transition.
</Card>
<Card title="Variants & categories" icon="sitemap" href="/platform/catalog/concepts/variants-categories-collections">
- Variants, categories, collections, tags, and types from Medusa's Product module.
+ The Medusa models that structure the catalog, and where Mercur extends them.
</Card>
</CardGroup>
## Examples
-Build against the Catalog domain in your own code.
+Build against the catalog in your own server code.
<CardGroup cols={2}>
<Card title="Create a master product" icon="plus" href="/platform/catalog/guides/create-a-master-product">
- Run `createProductsWorkflow` from a route or seed script.
+ Run `createProductsWorkflow` with attributes, variants, and an allowlist.
</Card>
<Card title="Allowlist stores" icon="user-plus" href="/platform/catalog/guides/allowlist-stores">
- Grant and revoke a store's right to sell a product in code.
+ Restrict a product to chosen stores, or open it to all of them again.
</Card>
<Card title="Publish or reject" icon="gavel" href="/platform/catalog/guides/publish-or-reject-a-product">
- Move a proposed product to published or rejected.
+ Review a proposed product from a route or a subscriber.
</Card>
</CardGroup>
## Resources
-Data models, workflows, service methods, and events for the Catalog domain.
+The data models, links, workflows, service methods, and events behind the catalog.
<CardGroup cols={2}>
<Card title="Data models" icon="table" href="/platform/catalog/reference/data-models">
- The `Product`, `ProductVariant`, `ProductCategory`, and the `product_seller` table.
+ `Product`, `ProductVariant`, `ProductCategory`, and the other Product module models.
</Card>
<Card title="Links" icon="link" href="/platform/catalog/reference/links">
- How the catalog links to sellers, offers, attributes, and media.
+ How products and categories link to stores, offers, attributes, changes, and media.
</Card>
<Card title="Workflows" icon="diagram-project" href="/platform/catalog/reference/workflows">
- Mercur's product create, review, and allowlist workflows.
+ Mercur's create, review, allowlist, and category workflows with their hooks.
</Card>
<Card title="Service" icon="gear" href="/platform/catalog/reference/service">
Medusa's Product module service, resolved with `Modules.PRODUCT`.
</Card>
<Card title="Events" icon="bell" href="/platform/catalog/reference/events">
- Events emitted as products are created and reviewed.
+ The events Mercur emits when products are created and reviewed.
</Card>
</CardGroup>
diff --git a/apps/docs/platform/catalog/reference/data-models.mdx b/apps/docs/platform/catalog/reference/data-models.mdx
index cc192aa5c..1dd1b825d 100644
--- a/apps/docs/platform/catalog/reference/data-models.mdx
+++ b/apps/docs/platform/catalog/reference/data-models.mdx
@@ -1,66 +1,177 @@
---
-title: "Data models"
+title: "Catalog data models"
sidebarTitle: "Data models"
-description: "The Medusa Product models the catalog is built on, plus Mercur's marketplace layer."
+description: "Every field on the Medusa Product module models the shared catalog is built on, and the relations Mercur adds."
---
-The Catalog domain is owned by **Medusa's Product module**, with a marketplace
-layer added by Mercur. This reference lists the models at the Mercur-relevant
-level. It doesn't restate every Medusa product field. For the full module, see
-the [Medusa Product module](https://docs.medusajs.com/resources/commerce-modules/product).
+The catalog's data models belong to Medusa's Product module, version 2.21. Mercur adds no columns to them. It adds relations through [module links](/platform/catalog/reference/links), listed under each model. Every model also has `created_at`, `updated_at`, and `deleted_at` timestamps that Medusa manages.
## Product
-Table `product`, id prefix `prod`. The shared master product, not owned by any
-store. The marketplace-relevant fields:
+The shared master product. Table `product`, id prefix `prod`.
-| Field | Type | Notes |
+| Field | Type | Description |
| --- | --- | --- |
-| `id` | text | Primary key |
-| `title` | text | Searchable |
-| `handle` | text | Unique |
-| `subtitle` / `description` | text | Nullable |
-| `status` | enum | `ProductStatus`: `draft` / `proposed` / `published` / `rejected`, default `draft` |
-| `thumbnail` | text | Nullable |
-| `metadata` | json | Nullable |
+| `id` | `text` | Primary key |
+| `title` | `text` | Display title, searchable and translatable |
+| `handle` | `text` | URL handle, unique among non-deleted products |
+| `subtitle` | `text`, nullable | Subtitle, searchable and translatable |
+| `description` | `text`, nullable | Description, searchable and translatable |
+| `is_giftcard` | `boolean` | Whether the product is a gift card. Default `false` |
+| `status` | `enum` | `draft`, `proposed`, `published`, or `rejected`. Default `draft` |
+| `thumbnail` | `text`, nullable | Thumbnail image URL |
+| `weight` | `float`, nullable | Weight |
+| `length` | `float`, nullable | Length |
+| `height` | `float`, nullable | Height |
+| `width` | `float`, nullable | Width |
+| `origin_country` | `text`, nullable | Country of origin |
+| `hs_code` | `text`, nullable | Harmonized System code |
+| `mid_code` | `text`, nullable | Manufacturer identification code |
+| `material` | `text`, nullable | Material, translatable |
+| `discountable` | `boolean` | Whether promotions can apply. Default `true` |
+| `external_id` | `text`, nullable | Id in an external system |
+| `metadata` | `json`, nullable | Custom key-value data |
+
+Native relations:
+
+- **`variants`**: `ProductVariant[]`, deleted with the product
+- **`options`**: `ProductOption[]` through the `ProductProductOption` pivot
+- **`images`**: `ProductImage[]`, deleted with the product
+- **`categories`**: `ProductCategory[]` through `product_category_product`
+- **`collection`**: `ProductCollection`, nullable
+- **`type`**: `ProductType`, nullable
+- **`tags`**: `ProductTag[]` through `product_tags`
+
+Mercur relations:
+
+- **`sellers`**: `Seller[]`, the store allowlist in `product_seller`
+- **`product_attribute_values`**: attribute values attached to the product
+- **`scoped_attributes`**: product-scoped attributes, read-only
+- **`changes`**: `ProductChange[]`, the audit and edit history, read-only
+- **`reviews`**: `Review[]`
-Relations used by the marketplace: `variants`, `options`, `categories`,
-`collection`, `tags`, `type`, `images` (native Medusa), plus Mercur's `sellers`
-(the allowlist), `offers`, `scoped_attributes`, and `changes` (audit history).
+## ProductVariant
-## product_seller
+One purchasable configuration of a product. Table `product_variant`, id prefix `variant`.
-The **allowlist**: a many-to-many link table between `Product` and `Seller`
-controlling which stores may sell a master product.
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `text` | Primary key |
+| `title` | `text` | Display title, searchable and translatable |
+| `sku` | `text`, nullable | Catalog SKU, unique among non-deleted variants |
+| `barcode` | `text`, nullable | Barcode, unique |
+| `ean` | `text`, nullable | EAN, unique |
+| `upc` | `text`, nullable | UPC, unique |
+| `allow_backorder` | `boolean` | Default `false` |
+| `manage_inventory` | `boolean` | Model default `true`; Mercur's create workflow sends `false` |
+| `hs_code` | `text`, nullable | Harmonized System code |
+| `origin_country` | `text`, nullable | Country of origin |
+| `mid_code` | `text`, nullable | Manufacturer identification code |
+| `material` | `text`, nullable | Material, translatable |
+| `weight` | `float`, nullable | Weight |
+| `length` | `float`, nullable | Length |
+| `height` | `float`, nullable | Height |
+| `width` | `float`, nullable | Width |
+| `thumbnail` | `text`, nullable | Variant thumbnail URL |
+| `variant_rank` | `number`, nullable | Sort order. Default `0` |
+| `metadata` | `json`, nullable | Custom key-value data |
+
+Relations: `product` (nullable), `options` (`ProductOptionValue[]` through `product_variant_option`), and `images` (`ProductImage[]`). Mercur links offers to variants through `offer.variant_id`. Each store's price and stock live on the [offer](/platform/offer/reference/data-models), not here.
+
+## ProductOption
+
+An axis that variants vary on. Table `product_option`, id prefix `opt`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `text` | Primary key |
+| `title` | `text` | Option name, such as `Size` |
+| `is_exclusive` | `boolean` | `true` when the option belongs to one product. Default `false` |
+| `metadata` | `json`, nullable | Custom key-value data |
-| Column | References |
-| --- | --- |
-| `product_id` | `product.id` |
-| `seller_id` | `seller.id` |
+Relations: `products` and `values` (`ProductOptionValue[]`). A variant-axis attribute mirrors one option through `product_attribute.product_option_id`.
-A store on this table can create an [offer](/platform/offer/overview) against the
-product; a store not on it cannot.
+## ProductOptionValue
-## ProductVariant
+One value of an option. Table `product_option_value`, id prefix `optval`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `text` | Primary key |
+| `value` | `text` | The value, such as `M` |
+| `rank` | `number`, nullable | Sort order |
+| `metadata` | `json`, nullable | Custom key-value data |
+
+Relations: `option` (nullable), `variants`, and `product_options`.
-Table `product_variant`, id prefix `variant`. A purchasable configuration of a
-master product, generated from its options and variant-axis attributes. Holds the
-SKU-level catalog structure. Offer-scoped price and inventory live on the offer,
-not here.
+## ProductImage
+
+A product image. Table `image`, id prefix `img`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `text` | Primary key |
+| `url` | `text` | Image URL |
+| `rank` | `number` | Sort order. Default `0` |
+| `metadata` | `json`, nullable | Custom key-value data |
+
+Relations: `product` and `variants`.
## ProductCategory
-Table `product_category`, id prefix `pcat`. Hierarchical, nestable
-classification. Participates in the marketplace layer through the
-`category_seller` allowlist and the `media_images` link.
+A node in the category tree. Table `product_category`, id prefix `pcat`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `text` | Primary key |
+| `name` | `text` | Display name, searchable and translatable |
+| `description` | `text` | Description. Default `""` |
+| `handle` | `text` | URL handle, unique |
+| `mpath` | `text` | Materialized path of ancestor ids |
+| `is_active` | `boolean` | Whether the category is live. Default `false` |
+| `is_internal` | `boolean` | Hidden from the storefront. Default `false` |
+| `rank` | `number` | Sort order among siblings. Default `0` |
+| `external_id` | `text`, nullable | Id in an external system |
+| `metadata` | `json`, nullable | Custom key-value data |
+
+Relations: `parent_category` (nullable), `category_children` (deleted with the parent), and `products`. Mercur adds `sellers`, `media_images`, and the product attribute link.
## ProductCollection
-Table `product_collection`, id prefix `pcol`. Flat, curated grouping of products,
-with a `media_images` link for collection artwork.
+A flat group of products. Table `product_collection`, id prefix `pcol`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `text` | Primary key |
+| `title` | `text` | Display title, searchable and translatable |
+| `handle` | `text` | URL handle, unique |
+| `external_id` | `text`, nullable | Id in an external system |
+| `metadata` | `json`, nullable | Custom key-value data |
+
+Relations: `products`. Mercur adds `media_images`.
+
+## ProductTag
+
+A free-form label. Table `product_tag`, id prefix `ptag`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `text` | Primary key |
+| `value` | `text` | The label, unique |
+| `external_id` | `text`, nullable | Id in an external system |
+| `metadata` | `json`, nullable | Custom key-value data |
+
+Relations: `products`.
+
+## ProductType
+
+A single classification per product. Table `product_type`, id prefix `ptyp`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `text` | Primary key |
+| `value` | `text` | The type name, unique |
+| `external_id` | `text`, nullable | Id in an external system |
+| `metadata` | `json`, nullable | Custom key-value data |
-<Note>
- `ProductTag` and `ProductType` round out the native grouping models: free-form
- labels and a single type classification per product, respectively. They carry
- no Mercur-specific columns.
-</Note>
+Relations: `products`.
diff --git a/apps/docs/platform/catalog/reference/events.mdx b/apps/docs/platform/catalog/reference/events.mdx
index 6c95e7308..79008c239 100644
--- a/apps/docs/platform/catalog/reference/events.mdx
+++ b/apps/docs/platform/catalog/reference/events.mdx
@@ -1,41 +1,57 @@
---
-title: "Event reference"
+title: "Catalog events"
sidebarTitle: "Events"
-description: "Events emitted by the Catalog domain, for subscribers and side effects."
+description: "The events Mercur's product workflows emit, their payloads, and how to subscribe to them."
---
-The Catalog domain emits events as products are created and reviewed. Subscribe
-to them to run side effects instead of polling, such as sending notifications,
-syncing external systems, or reindexing search.
+Mercur's product workflows emit 4 events as products are created and reviewed. The names are exported as `ProductWorkflowEvents` from `@mercurjs/core/workflows`. Subscribe to them to notify stores, sync external systems, or reindex search.
-```ts title="src/subscribers/product-published.ts"
+## Product events
+
+Each event is emitted once per product. Payloads come from the `emitEventStep` calls in `packages/core/src/workflows/product/workflows`.
+
+| Event | Constant | Emitted when | Payload |
+| --- | --- | --- | --- |
+| `product.created` | `CREATED` | `createProductsWorkflow` creates a product | `{ id }` |
+| `product.published` | `PUBLISHED` | `confirmProductsWorkflow` publishes a product | `{ id, internal_note? }` |
+| `product.rejected` | `REJECTED` | `rejectProductWorkflow` rejects a product | `{ id, message? }` |
+| `product.change-requested` | `CHANGE_REQUESTED` | `requestProductChangeWorkflow` asks for a revision | `{ id, message?, actor_id? }` |
+
+<Warning>
+ Mercur's `createProductsWorkflow` runs Medusa's `createProductsWorkflow` as a step, which also emits `product.created` with `{ id }`. Expect 2 `product.created` events per product and make handlers idempotent.
+</Warning>
+
+## Subscribe to an event
+
+Write a subscriber that listens for one of the events. This one logs the rejection reason for each rejected product.
+
+```ts title="src/subscribers/product-rejected.ts"
import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+import { ProductWorkflowEvents } from "@mercurjs/core/workflows"
-export default async function productPublishedHandler({
+export default async function productRejected({
event,
container,
-}: SubscriberArgs<{ id: string }>) {
- const productId = event.data.id
- // ...reindex search, notify the seller, etc.
+}: SubscriberArgs<{ id: string; message?: string }>) {
+ const logger = container.resolve("logger")
+ const reason = event.data.message ?? "no reason given"
+
+ logger.info(`Product ${event.data.id} rejected: ${reason}`)
}
export const config: SubscriberConfig = {
- event: "product.published",
+ event: ProductWorkflowEvents.REJECTED,
}
```
-## Product events
+Medusa calls the handler once per rejected product with the payload above.
+
+## Events from Medusa
+
+Medusa's own product workflows emit their events alongside Mercur's. These matter for the catalog:
+
+- **`product.updated`**: from Medusa's `updateProductsWorkflow`, which `assignProductsToCategoryWorkflow` and the admin product update both run
+- **`product.deleted`**: from Medusa's `deleteProductsWorkflow`
+- **`product-variant.created`**: from `createProductVariantsWorkflow`, which Mercur's create workflow runs for `variants`
-| Event | Emitted when | Payload |
-| --- | --- | --- |
-| `product.created` | A master product is created | `{ id }` |
-| `product.published` | A proposed product is approved (`→ published`) | `{ id, internal_note? }` |
-| `product.rejected` | A proposed product is rejected | `{ id, message? }` |
-| `product.change-requested` | A revision is requested on a proposed product | `{ id, message?, actor_id? }` |
-
-<Note>
- These are the marketplace lifecycle events emitted by Mercur's product
- workflows. Medusa's Product module also emits its own native events (e.g.
- `product.updated`, `product-variant.created`) for lower-level changes. See the
- [Medusa events reference](https://docs.medusajs.com/resources/events-reference).
-</Note>
+See the [Medusa events reference](https://docs.medusajs.com/resources/references/events) for the full list. Edits that stores submit through the product edit pipeline emit `product-change.*` events, listed in the [product edit events](/platform/product-edit/reference/events).
diff --git a/apps/docs/platform/catalog/reference/links.mdx b/apps/docs/platform/catalog/reference/links.mdx
index 9519735e9..a828c1a45 100644
--- a/apps/docs/platform/catalog/reference/links.mdx
+++ b/apps/docs/platform/catalog/reference/links.mdx
@@ -1,44 +1,212 @@
---
-title: "Links to other modules"
+title: "Catalog module links"
sidebarTitle: "Links"
-description: "How the catalog links to sellers, offers, attributes, and media."
+description: "Every Mercur link on Product module models: both sides, cardinality, source file, and how to query it."
---
-Modules in Mercur never reference each other directly. They connect through
-**module links**. The Catalog (Medusa's `Product` module) is wired into the
-marketplace layer with a set of links defined in Mercur core. Once a link is
-defined, you retrieve related records with `query.graph` using the link alias.
+Mercur connects Medusa's Product module to its own modules through module links defined in `packages/core/src/links`. Read across a link with `query.graph` and the link's alias. Read-only links have no pivot table: they resolve from a foreign key column on one side, and you change them by updating that column.
+
+Resolve `query` from the container before you run the examples:
+
+```ts
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
+
+const query = container.resolve(ContainerRegistrationKeys.QUERY)
+```
+
+## Product and Seller
+
+The store allowlist. A product with no rows is open to every store.
+
+- **Sides**: `Product` (many) and `Seller` (many)
+- **Storage**: pivot table `product_seller` with `product_id` and `seller_id`
+- **Alias on product**: `sellers`
+- **File**: `product-seller-link.ts`
+
+```ts
+const { data } = await query.graph({
+ entity: "product",
+ fields: ["id", "sellers.id", "sellers.name"],
+ filters: { id: "prod_01JD8Q1234567" },
+})
+```
+
+Write it with `linkSellersToProductWorkflow` or the `seller_ids` input of `createProductsWorkflow`.
+
+## ProductCategory and Seller
+
+Links stores to categories. No shipped route filters products by it.
+
+- **Sides**: `ProductCategory` (many) and `Seller` (many)
+- **Storage**: pivot table generated by Medusa
+- **Alias on category**: `sellers`
+- **File**: `category-seller-link.ts`
+
+```ts
+const { data } = await query.graph({
+ entity: "product_category",
+ fields: ["id", "sellers.id"],
+ filters: { id: "pcat_01JD8Q1234567" },
+})
+```
+
+Write it with `linkSellersToProductCategoryWorkflow`.
+
+## Offer and Product
+
+Each offer points at the master product it sells.
+
+- **Sides**: `Offer` (one) to `Product` (one)
+- **Storage**: read-only, through `offer.product_id`
+- **Alias on offer**: `product`
+- **File**: `offer-product-link.ts`
+
+```ts
+const { data } = await query.graph({
+ entity: "offer",
+ fields: ["id", "product.id", "product.title"],
+ filters: { product_id: "prod_01JD8Q1234567" },
+})
+```
+
+To list a product's offers, query `offer` filtered by `product_id`, as above.
+
+## Offer and ProductVariant
+
+Each offer sells exactly one variant.
+
+- **Sides**: `Offer` (one) to `ProductVariant` (one)
+- **Storage**: read-only, through `offer.variant_id`
+- **Alias on offer**: `product_variant`
+- **File**: `offer-variant-link.ts`
+
+```ts
+const { data } = await query.graph({
+ entity: "offer",
+ fields: ["id", "product_variant.title", "product_variant.sku"],
+ filters: { variant_id: "variant_01JD8Q1234567" },
+})
+```
+
+## Product and ProductChange
+
+The audit and edit history of a product, including every `PRODUCT_ADD` and `STATUS_CHANGE` record.
+
+- **Sides**: `Product` (one) to `ProductChange` (many)
+- **Storage**: read-only, through `product_change.product_id`
+- **Alias on product**: `changes`
+- **File**: `product-change-link.ts`
```ts
-const { data: products } = await query.graph({
+const { data } = await query.graph({
entity: "product",
- fields: ["id", "title", "sellers.*", "offers.*", "changes.*"],
+ fields: ["id", "changes.status", "changes.created_by"],
+ filters: { id: "prod_01JD8Q1234567" },
})
```
-## Marketplace
+## Product and ProductAttributeValue
-| Linked module | Relationship |
-| --- | --- |
-| **Seller** | Many-to-many allowlist (`product_seller`) that controls which stores may sell a master product. Categories carry the same via `category_seller`. |
-| **Offer** | A product has many offers (`offer.product_id`, read-only). Offers are how a store sells against the master product. |
-| **Product change** | A product has many change records (`product.changes`, read-only): the immutable submission and review audit trail. |
+The attribute values attached to a product.
-## Attributes
+- **Sides**: `Product` (many) and `ProductAttributeValue` (many)
+- **Storage**: pivot table `product_attribute_value_link`
+- **Alias on product**: `product_attribute_values`
+- **File**: `product-attribute-value-pivot-link.ts`
-| Linked module | Relationship |
-| --- | --- |
-| **Product attribute** | Product-scoped attributes resolve under `product.scoped_attributes` (read-only). Categories link attributes through `product_category_attribute`. |
+```ts
+const { data } = await query.graph({
+ entity: "product",
+ fields: [
+ "product_attribute_values.name",
+ "product_attribute_values.attribute.handle",
+ ],
+ filters: { id: "prod_01JD8Q1234567" },
+})
+```
+
+## Product and scoped ProductAttribute
+
+Attributes created inline for one product.
+
+- **Sides**: `Product` (one) to `ProductAttribute` (many)
+- **Storage**: read-only, through `product_attribute.product_id`
+- **Alias on product**: `scoped_attributes`
+- **File**: `product-attribute-product-link.ts`
+
+```ts
+const { data } = await query.graph({
+ entity: "product",
+ fields: ["scoped_attributes.name", "scoped_attributes.values.name"],
+ filters: { id: "prod_01JD8Q1234567" },
+})
+```
+
+## ProductAttribute and ProductCategory
+
+Assigns attributes to categories.
+
+- **Sides**: `ProductAttribute` (many) and `ProductCategory` (many)
+- **Storage**: pivot table `product_category_attribute`
+- **Alias on attribute**: `categories`
+- **File**: `product-attribute-category-link.ts`
+
+```ts
+const { data } = await query.graph({
+ entity: "product_attribute",
+ fields: ["id", "categories.id", "categories.name"],
+})
+```
+
+## Attribute option mirrors
-## Media
+A variant-axis attribute mirrors a native option, and each of its values mirrors an option value. Both links are one-to-one and read-only:
-| Linked module | Relationship |
-| --- | --- |
-| **Media** | Categories and collections link their artwork through the `media_images` alias (a `MediaImage` list). |
+- **`ProductAttribute` to `ProductOption`**: through `product_attribute.product_option_id`, in `product-attribute-option-mirror-link.ts`
+- **`ProductAttributeValue` to `ProductOptionValue`**: through `product_attribute_value.product_option_value_id`, in `product-attribute-value-option-value-mirror-link.ts`
+
+Read the ids from the attribute side:
+
+```ts
+const { data } = await query.graph({
+ entity: "product_attribute",
+ fields: ["id", "product_option_id", "values.product_option_value_id"],
+ filters: { is_variant_axis: true },
+})
+```
+
+## Product and Review
+
+Customer reviews of a product.
+
+- **Sides**: `Product` (one) to `Review` (many)
+- **Storage**: pivot table generated by Medusa
+- **Alias on product**: `reviews`
+- **File**: `product-review.ts`
+
+```ts
+const { data } = await query.graph({
+ entity: "product",
+ fields: ["id", "reviews.id"],
+ filters: { id: "prod_01JD8Q1234567" },
+})
+```
+
+## ProductCategory and ProductCollection images
+
+Categories and collections own gallery and icon images from Mercur's media module.
+
+- **Sides**: `ProductCategory` (one) to `MediaImage` (many), and `ProductCollection` (one) to `MediaImage` (many)
+- **Alias**: `media_images` on both
+- **Files**: `media-product-category-link.ts` and `media-product-collection-link.ts`
+
+```ts
+const { data } = await query.graph({
+ entity: "product_category",
+ fields: ["id", "media_images.url", "media_images.is_thumbnail"],
+})
+```
-<Note>
- Read-only links (Offer, Product change, scoped attributes) are resolved from
- the field on the owning record and can't be written through the link itself.
- The `media_images` alias is deliberately **not** the bare `images` alias. That
- would shadow the native `Product.images` relation and break product queries.
-</Note>
+<Warning>
+ Don't define a link with the alias `images` on a category or collection. Both models live in the Product module, and that alias shadows `Product.images`, which breaks every product query.
+</Warning>
diff --git a/apps/docs/platform/catalog/reference/service.mdx b/apps/docs/platform/catalog/reference/service.mdx
index f48a80925..f8a27f3b6 100644
--- a/apps/docs/platform/catalog/reference/service.mdx
+++ b/apps/docs/platform/catalog/reference/service.mdx
@@ -1,52 +1,74 @@
---
-title: "Service reference"
+title: "Product module service"
sidebarTitle: "Service"
-description: "Medusa's Product module service: methods for working with records directly."
+description: "Resolve Medusa's Product module service with Modules.PRODUCT and call its methods for catalog records."
---
-The catalog is backed by **Medusa's Product module**, not a Mercur-specific one.
-Resolve its service from the container with the `Modules.PRODUCT` key to read and
-write products, variants, categories, and collections directly, without going
-through a workflow. Use it inside custom services, subscribers, or scheduled jobs.
+The catalog uses Medusa's Product module service. Mercur adds no catalog service of its own. Resolve it with `Modules.PRODUCT` to read and write products, variants, options, categories, collections, tags, and types from a subscriber, a scheduled job, or a custom step.
+
+## Resolve the service
+
+The service key comes from `@medusajs/framework/utils`, not `MercurModules`:
```ts
import { Modules } from "@medusajs/framework/utils"
-const productModuleService = container.resolve(Modules.PRODUCT)
+const productService = container.resolve(Modules.PRODUCT)
-const [products, count] = await productModuleService.listAndCountProducts({
- status: "published",
-})
+const [products, count] = await productService.listAndCountProducts(
+ { status: "published" },
+ { take: 20, select: ["id", "title"] }
+)
```
-<Note>
- Because this is Medusa's own module, the service key is `Modules.PRODUCT` from
- `@medusajs/framework/utils`, **not** a `MercurModules` key. Mercur adds its
- marketplace behavior (allowlist, review lifecycle, audit trail) as
- [workflows](/platform/catalog/reference/workflows) layered on top of this
- service.
-</Note>
+`listAndCountProducts` returns a page of products and the total count.
+
+<Warning>
+ The service writes rows directly. It doesn't link stores, record `ProductChange` entries, or emit Mercur's `product.*` events. Use the [catalog workflows](/platform/catalog/reference/workflows) for creates and reviews, and `query.graph` to read linked data such as `sellers`.
+</Warning>
-## Generated methods
+## Product methods
-Each data model gets a standard set of auto-generated methods. For `Product`:
+These methods act on `Product`:
-| Method | Description |
+| Method | Signature |
| --- | --- |
-| `createProducts(data)` | Create one or more products |
-| `retrieveProduct(id, config?)` | Retrieve a product by id |
-| `listProducts(filters?, config?)` | List products matching filters |
-| `listAndCountProducts(filters?, config?)` | List products with a total count |
-| `updateProducts(data)` | Update one or more products |
-| `deleteProducts(ids)` | Delete one or more products |
+| `retrieveProduct` | `(productId: string, config?) => Promise<ProductDTO>` |
+| `listProducts` | `(filters?, config?) => Promise<ProductDTO[]>` |
+| `listAndCountProducts` | `(filters?, config?) => Promise<[ProductDTO[], number]>` |
+| `createProducts` | `(data: CreateProductDTO \| CreateProductDTO[]) => Promise<ProductDTO \| ProductDTO[]>` |
+| `upsertProducts` | `(data: UpsertProductDTO \| UpsertProductDTO[]) => Promise<ProductDTO \| ProductDTO[]>` |
+| `updateProducts` | `(id: string, data) => Promise<ProductDTO>` or `(selector, data) => Promise<ProductDTO[]>` |
+| `deleteProducts` | `(productIds: string[]) => Promise<void>` |
+| `softDeleteProducts` | `(productIds: string[], config?) => Promise<Record<string, string[]> \| void>` |
+| `restoreProducts` | `(productIds: string[], config?) => Promise<Record<string, string[]> \| void>` |
-The same set exists for every model in the module, such as `ProductVariant`,
-`ProductCategory`, `ProductCollection`, `ProductTag`, and `ProductType` (e.g.
-`createProductVariants`, `listProductCategories`, `updateProductCollections`).
+`filters` takes `FilterableProductProps`, such as `id`, `status`, `handle`, or `q`. `config` takes `select`, `relations`, `skip`, `take`, and `order`.
-<Warning>
- Prefer [workflows](/platform/catalog/reference/workflows) for anything with
- side effects, such as submissions, review transitions, and allowlist changes. The
- service writes records directly and does **not** run the marketplace layer,
- emit Mercur's product events, or record the audit trail.
-</Warning>
+## Methods for the other models
+
+The same method set exists for each model in the module, named after it:
+
+| Model | Example methods |
+| --- | --- |
+| `ProductVariant` | `retrieveProductVariant`, `listProductVariants`, `createProductVariants`, `updateProductVariants` |
+| `ProductOption` | `listProductOptions`, `createProductOptions`, `upsertProductOptions`, `deleteProductOptions` |
+| `ProductOptionValue` | `listProductOptionValues`, `createProductOptionValues`, `updateProductOptionValues` |
+| `ProductCategory` | `retrieveProductCategory`, `listProductCategories`, `createProductCategories` |
+| `ProductCollection` | `retrieveProductCollection`, `listProductCollections`, `updateProductCollections` |
+| `ProductTag` | `listProductTags`, `createProductTags`, `upsertProductTags`, `deleteProductTags` |
+| `ProductType` | `listProductTypes`, `createProductTypes`, `upsertProductTypes`, `deleteProductTypes` |
+
+## Option and image methods
+
+The service also has methods that manage shared options and variant images:
+
+| Method | Does |
+| --- | --- |
+| `addProductOptionToProduct` | Attaches an existing option to a product, from `{ product_id, product_option_id }` or an array |
+| `removeProductOptionFromProduct` | Detaches an option from a product |
+| `updateProductOptionValuesOnProduct` | Changes which values of an option a product uses |
+| `addImageToVariant` | Links a product image to a variant |
+| `removeImageFromVariant` | Unlinks a product image from a variant |
+
+Mercur's attribute workflows create and attach the options behind variant-axis attributes. Prefer those workflows over the option methods, so each attribute stays in sync with the option it mirrors.
diff --git a/apps/docs/platform/catalog/reference/workflows.mdx b/apps/docs/platform/catalog/reference/workflows.mdx
index 34d74224c..b9ff114ca 100644
--- a/apps/docs/platform/catalog/reference/workflows.mdx
+++ b/apps/docs/platform/catalog/reference/workflows.mdx
@@ -1,40 +1,134 @@
---
-title: "Workflows"
+title: "Catalog workflows"
sidebarTitle: "Workflows"
-description: "Mercur's product create, review, and allowlist workflows."
+description: "Mercur's product create, review, allowlist, and category workflows: inputs, hooks, and events."
---
-This reference lists the Mercur workflows for the Catalog domain. Import them
-from `@mercurjs/core/workflows` and run them against the Medusa container. They
-wrap Medusa's native product flows to add the marketplace layer: the store
-allowlist, the review lifecycle, and the audit trail.
+Mercur ships 7 catalog workflows in `packages/core/src/workflows/product`. Import them from `@mercurjs/core/workflows` and run them with the Medusa container. For plain updates and deletes of products, variants, and categories, use Medusa's core flows, such as `updateProductsWorkflow`.
-## Product workflows
+```ts
+import { confirmProductsWorkflow } from "@mercurjs/core/workflows"
-| Workflow | Input | Purpose |
+await confirmProductsWorkflow(container).run({
+ input: { product_ids: ["prod_01JD8Q1234567"] },
+})
+```
+
+## createProductsWorkflow
+
+Creates master products with attributes and variants, links stores to them, and records each submission. Workflow id `mercur-create-products`. Returns the created `ProductDTO[]` in input order.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `products` | `(CreateProductDTO & { seller_ids?: string[] })[]` | Products to create. `CreateProductDTO` from `@mercurjs/types` replaces `options` with `attributes` |
+| `products[].seller_ids` | `string[]`, optional | Stores to put on the product's allowlist |
+| `created_by` | `string` | Submitter id, a seller id or a user id, stored on the audit record |
+| `additional_data` | `Record<string, unknown>`, optional | Forwarded to Medusa's product and variant workflows and the `productsCreated` hook |
+
+The workflow runs these steps in order:
+
+1. Runs the `validate` hook with `input` and `products`
+2. Creates the products with Medusa's `createProductsWorkflow`, each with an internal `__default__` option
+3. Attaches `attributes` with `addProductAttributesToProductWorkflow`
+4. Removes the `__default__` option from products that gained a variant axis
+5. Creates `variants` with `createProductVariantsWorkflow`, defaulting `manage_inventory` to `false`
+6. Links `seller_ids` with `associateSellersWithProductStep`
+7. Records a `PRODUCT_ADD` change per product with `recordProductAuditChangeWorkflow`
+8. Runs the `productsCreated` hook with `products` and `additional_data`
+9. Emits `product.created`
+
+It exposes the `validate` and `productsCreated` hooks. It emits `product.created` with `{ id }` for each product.
+
+## confirmProductsWorkflow
+
+Publishes `proposed` products. Workflow id `mercur-confirm-products`.
+
+| Input | Type | Description |
| --- | --- | --- |
-| `createProductsWorkflow` | `{ products[], created_by, additional_data? }` | Create master products, attach attributes/variants, record the submission, allowlist `seller_ids` |
-| `confirmProductsWorkflow` | `{ product_ids[], actor_id?, internal_note? }` | `proposed` → `published` |
-| `rejectProductWorkflow` | `{ product_id, message?, actor_id? }` | `proposed` → `rejected` |
-| `requestProductChangeWorkflow` | `{ product_id, message?, actor_id? }` | Ask the submitter for a revision (stays `proposed`) |
+| `product_ids` | `string[]` | Products to publish. All must be `proposed` |
+| `actor_id` | `string`, optional | Reviewer, stored as `created_by` and `confirmed_by` |
+| `internal_note` | `string`, optional | Operator note on each audit record |
+| `additional_data` | `Record<string, unknown>`, optional | Passed to the hook |
-## Allowlist & organization workflows
+Records a `STATUS_CHANGE` action with `{ status: "published" }` per product, then sets the status.
-| Workflow | Input | Purpose |
+It exposes the `productsConfirmed` hook with `product_ids`, `internal_note`, and `additional_data`. It emits `product.published` with `{ id, internal_note }` for each product.
+
+## rejectProductWorkflow
+
+Rejects one `proposed` product. Workflow id `mercur-reject-product`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `product_id` | `string` | Product to reject |
+| `message` | `string`, optional | Reason, stored as the change's `external_note` |
+| `actor_id` | `string`, optional | Reviewer |
+| `additional_data` | `Record<string, unknown>`, optional | Passed to the hook |
+
+Records a `STATUS_CHANGE` action with `{ status: "rejected" }`, then sets the status.
+
+It exposes the `productRejected` hook with `product_id`, `message`, and `additional_data`. It emits `product.rejected` with `{ id, message }`.
+
+## requestProductChangeWorkflow
+
+Asks the submitter to revise a `proposed` product without changing its status. Workflow id `mercur-request-product-change`.
+
+| Input | Type | Description |
| --- | --- | --- |
-| `linkSellersToProductWorkflow` | `{ id, add?, remove? }` | Add/remove stores on a product's allowlist |
-| `linkSellersToProductCategoryWorkflow` | `{ id, add?, remove? }` | Add/remove stores on a category's allowlist |
-| `assignProductsToCategoryWorkflow` | `{ id, add?, remove? }` | Assign products to a single category |
-
-<Note>
- For plain create/update/delete of products, variants, and categories, Mercur
- reuses Medusa's native core-flows (`createProductsWorkflow`,
- `updateProductsWorkflow`, `createProductVariantsWorkflow`, and so on) under the
- hood. The workflows above are the Mercur-specific entry points that add the
- allowlist, review lifecycle, and audit history.
-</Note>
-
-To work with records directly instead of through a workflow, see the
-[Service reference](/platform/catalog/reference/service). To run side effects
-when a product changes, see the
-[Event reference](/platform/catalog/reference/events).
+| `product_id` | `string` | Product to send back |
+| `message` | `string`, optional | Requested changes, stored as `external_note` |
+| `actor_id` | `string`, optional | Reviewer |
+| `additional_data` | `Record<string, unknown>`, optional | Passed to the hook |
+
+Records a `CHANGE_REQUESTED` action with `{ message }`.
+
+It exposes the `productChangeRequested` hook with `product_id`, `message`, and `additional_data`. It emits `product.change-requested` with `{ id, message, actor_id }`.
+
+## linkSellersToProductWorkflow
+
+Adds stores to and removes stores from a product's allowlist. Workflow id `mercur-link-sellers-to-product`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Product id |
+| `add` | `string[]`, optional | Seller ids to link |
+| `remove` | `string[]`, optional | Seller ids to unlink |
+
+Runs `associateSellersWithProductStep` and `detachSellersFromProductStep`, which undo their changes if the run fails. No hooks or events.
+
+## linkSellersToProductCategoryWorkflow
+
+Adds and removes `category_seller` rows for a category. Workflow id `mercur-link-sellers-to-product-category`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Category id |
+| `add` | `string[]`, optional | Seller ids to link |
+| `remove` | `string[]`, optional | Seller ids to unlink |
+
+Runs `associateSellersWithProductCategoryStep` and `detachSellersFromProductCategoryStep`. No hooks or events.
+
+## assignProductsToCategoryWorkflow
+
+Moves products into one category. Workflow id `mercur-assign-products-to-category`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Category id |
+| `add` | `string[]`, optional | Product ids. Each product's categories become `[id]` |
+| `remove` | `string[]`, optional | Product ids. Each product's categories become empty |
+
+Runs Medusa's `updateProductsWorkflow` with `category_ids`, so Medusa's product update events fire. No hooks of its own.
+
+## Exported steps
+
+These steps are exported for use in your own workflows:
+
+| Step | Does |
+| --- | --- |
+| `associateSellersWithProductStep` | Creates `product_seller` rows from `{ links: { product_id, seller_id }[] }` |
+| `detachSellersFromProductStep` | Dismisses `product_seller` rows with the same input |
+| `associateSellersWithProductCategoryStep` | Creates `category_seller` rows from `{ links: { category_id, seller_id }[] }` |
+| `detachSellersFromProductCategoryStep` | Dismisses `category_seller` rows with the same input |
+| `validateProductsStatusStep` | Throws `NOT_ALLOWED` unless every product in `products` has the `expected_status` |
+| `validateSellerProductPermissionsStep` | Throws `NOT_ALLOWED` when `seller_id` is linked to any of `category_ids` |
diff --git a/apps/docs/platform/commission/concepts/order-commission-lines.mdx b/apps/docs/platform/commission/concepts/order-commission-lines.mdx
index 726f1e722..514b8141a 100644
--- a/apps/docs/platform/commission/concepts/order-commission-lines.mdx
+++ b/apps/docs/platform/commission/concepts/order-commission-lines.mdx
@@ -1,65 +1,67 @@
---
-title: "Order commission lines"
+title: "Commission lines on orders"
sidebarTitle: "Order commission lines"
-description: "Per-order commission lines, how they're computed, and BigNumber precision."
+description: "What a commission line records, when Mercur writes and rewrites it, and how payouts read it."
---
-This page covers how commission is recorded on an order and kept in sync as the
-order changes.
+A commission line is the resolved commission for one line item or one shipping method of an order. It’s derived data: Mercur computes it from the current rates and the order’s contents, writes it at checkout, and rewrites it whenever the order changes. Payouts read these lines to work out what the seller receives.
-## Commission line
+## What a line records
-A commission line is the resolved commission for a single order line. It's
-represented by the `CommissionLine` data model (table `commission_line`, id
-prefix `comline`). Each line anchors to either an item (`item_id`) or a shipping
-method (`shipping_method_id`). It records the rate that matched
-(`commission_rate_id`, `code`), the applied `rate`, and the computed `amount`.
+A line is a `CommissionLine` record (id prefix `comline`). It points at exactly one of `item_id` or `shipping_method_id`, and it stores the rate it came from and the amount.
```ts
-// A commission line, as written by the refresh workflow
-{
- item_id: "ordli_123",
+const line = {
+ id: "comline_01JD8Q1234567",
+ item_id: "ordli_01JD8Q1234567",
shipping_method_id: null,
- commission_rate_id: "comrate_123",
- code: "standard-a1b2c3",
- rate: 10,
- amount: 250, // 10% of a 2500 subtotal
+ commission_rate_id: "comrate_01JD8Q1234567",
+ provider_id: "system",
+ code: "acme-apparel-k3x9qa",
+ rate: 12,
+ amount: 5.64,
description: null,
+ data: null,
}
```
-Lines are generated automatically during checkout. When the cart is split into
-per-seller orders, `refreshOrderCommissionLinesWorkflow` runs against each new
-order. Shipping lines carry a `"Shipping Commission"` description. Item lines
-carry none.
-
-## Recomputed on change
-
-Commission lines are **derived** data, not a one-time snapshot. The lines are
-recomputed whenever an order's composition changes, such as when an order edit
-is confirmed, a return is received, or a claim or exchange is created. That
-keeps the seller's commission tracking what the customer actually kept.
-
-The refresh is **idempotent**: it deletes any existing lines for the affected
-items and shipping methods, then inserts the freshly computed set. Re-running it
-never duplicates lines.
-
-<Note>
- Computed lines carry no `id`. The module's `upsertCommissionLines` deletes by
- anchor (`item_id` / `shipping_method_id`) before inserting, which is what
- makes repeated refreshes safe.
-</Note>
-
-## BigNumber precision
-
-All commission arithmetic uses Medusa's `MathBN` (BigNumber). It's arbitrary
-precision, so percentages and per-currency amounts never accumulate
-floating-point error. A percentage amount is `subtotal × value ÷ 100`. A fixed
-amount is the per-currency value (or the fallback `value`). Each is computed in
-BigNumber before being stored.
-
-<Tip>
- Commission lines feed the payout pipeline: when a seller's payout is
- calculated, the order's commission lines are read straight from the commission
- module and deducted from the amount transferred to the seller.
-</Tip>
+The fields carry these values from the `system` provider:
+
+- **`code`**: the code of the winning rate, kept so the line stays readable if the rate is renamed or deleted
+- **`rate`**: the percent for a percentage rate, or the fixed amount for a fixed rate
+- **`amount`**: the commission for the line, computed with `MathBN`
+- **`description`**: `Shipping Commission` on shipping lines, empty on item lines
+- **`provider_id`**: the provider that computed the line, `system` by default
+- **`data`**: free JSON a custom provider can fill
+
+## When lines are written
+
+Mercur writes lines at checkout and rewrites them when the order’s contents change. Both paths run `refreshOrderCommissionLinesWorkflow`:
+
+| Trigger | Where it runs |
+| --- | --- |
+| Cart completed | A nested step of `completeCartWithSplitOrdersWorkflow`, for every seller order in the group |
+| `order-edit.confirmed` | The `order-commission-refresh-handler` subscriber |
+| `order.return_received` | The same subscriber |
+| `order.claim_created` | The same subscriber |
+| `order.exchange_created` | The same subscriber |
+
+A refresh resolves against the rates that exist when it runs. Changing a rate doesn’t touch existing lines until the order is refreshed again.
+
+## A refresh replaces, it doesn’t append
+
+Computed lines carry no `id`. The module’s `upsertCommissionLines` first deletes every existing line whose `item_id` or `shipping_method_id` is in the new set, then inserts the new lines in the same transaction. Running a refresh twice leaves one line per item and shipping method.
+
+<Warning>
+ Deletion is keyed on the anchors in the new set. If an item no longer gets a line, for example because you disabled the only rate that matched it, its old line stays in place.
+</Warning>
+
+## How payouts use the lines
+
+`createPayoutWorkflow` reads every commission line whose `item_id` or `shipping_method_id` belongs to the order. It sums their `amount` and transfers the order `total` minus that sum to the seller’s payout account. With the lines from the [overview figure](/platform/commission/overview), an order total of € 92.00 and commission of € 10.14 pays the seller € 81.86.
+
+## Related
+
+- [Refresh an order’s lines from your own code](/platform/commission/guides/refresh-order-commission-lines)
+- [The order events that trigger a refresh](/platform/commission/reference/events)
+- [All `CommissionLine` fields](/platform/commission/reference/data-models)
diff --git a/apps/docs/platform/commission/concepts/rule-matching.mdx b/apps/docs/platform/commission/concepts/rule-matching.mdx
index 75f109725..db5cba77c 100644
--- a/apps/docs/platform/commission/concepts/rule-matching.mdx
+++ b/apps/docs/platform/commission/concepts/rule-matching.mdx
@@ -1,86 +1,76 @@
---
-title: "Rule matching"
+title: "How Mercur picks a commission rate"
sidebarTitle: "Rule matching"
-description: "The five dimensions, most-specific-wins resolution, tie-breaks, and shipping."
+description: "The five rule dimensions, AND and OR matching, most-specific-wins, the oldest-rate tie-break, and shipping."
---
-This page covers how Mercur decides which commission rate applies to a given
-order line.
+Rule matching decides which single rate commissions each order line. Mercur finds every enabled rate whose rules fit the line’s product and seller, then keeps the one scoped on the most dimensions. Knowing the algorithm lets you predict a seller’s commission before an order exists.
-## Commission rule
+<img className="block dark:hidden" src="/images/figures/commission-rule-matching-light.svg" alt="Resolving the rate for a Linen shirt sold by ACME in the Shirts category: four enabled rates match, the acme-shirts rate scopes on two dimensions and wins, lighting does not match, and the default rate ranks last." />
+<img className="hidden dark:block" src="/images/figures/commission-rule-matching-dark.svg" alt="Resolving the rate for a Linen shirt sold by ACME in the Shirts category: four enabled rates match, the acme-shirts rate scopes on two dimensions and wins, lighting does not match, and the default rate ranks last." />
-A commission rule scopes a rate to part of the catalog. It's represented by the
-`CommissionRule` data model (table `commission_rule`, id prefix `comrule`). A
-rule is a `reference` / `reference_id` pair that belongs to one rate. The
-`reference` names the dimension, and the `reference_id` names the specific
-record.
+## Each dimension checks one product field
+
+A rule compares its `reference_id` with one field of the line’s product. The product comes from the order line, and the seller comes from the offer the customer bought.
+
+| `reference` | Matches when |
+| --- | --- |
+| `product` | `product.id` equals `reference_id` |
+| `product_type` | `product.type_id` equals `reference_id` |
+| `product_collection` | `product.collection_id` equals `reference_id` |
+| `product_category` | Any of `product.categories` has the id `reference_id` |
+| `seller` | The offer’s `seller_id` equals `reference_id` |
+
+Products are a shared catalog that no seller owns, which is why the `seller` dimension reads the offer on the line and not the product.
+
+<Warning>
+ The module stores `reference` as free text and doesn’t validate it. A rule with any other `reference`, such as a typo, never matches, so the whole rate never matches.
+</Warning>
+
+## AND across dimensions, OR within one
+
+Mercur groups a rate’s rules by `reference`. The rate matches a line when every group has at least one rule that matches. Rules in the same group are alternatives, and groups narrow each other.
```ts
-await batchCommissionRulesWorkflow(container).run({
- input: {
- commission_rate_id: "comrate_123",
- create: [
- { reference: "seller", reference_id: "sel_123" },
- { reference: "product_category", reference_id: "pcat_shoes" },
- ],
- },
-})
+const rules = [
+ { reference: "seller", reference_id: "sel_01JD8Q1234567" },
+ { reference: "product_category", reference_id: "pcat_01JD8Q1234567" },
+ { reference: "product_category", reference_id: "pcat_01JD8Q1234568" },
+]
```
-A rate with **no** rules is a catch-all that matches every line. A rate with
-rules only matches lines that satisfy them.
+A rate with these rules matches lines sold by that seller in either category. It doesn’t match the seller’s lines in other categories, or other sellers’ lines in those categories.
-## The five dimensions
+## The most specific rate wins
-A rule's `reference` is one of five dimensions, each resolved against the order
-line's product:
+When several rates match, Mercur sorts them by specificity and keeps the first. Specificity is the number of distinct dimensions a rate’s rules use, not the number of rules. The rules above give a specificity of 2.
-| `reference` | Matches when |
-| --- | --- |
-| `product` | The line's product id equals `reference_id` |
-| `product_type` | The product's type id equals `reference_id` |
-| `product_collection` | The product's collection id equals `reference_id` |
-| `product_category` | One of the product's categories equals `reference_id` |
-| `seller` | The seller behind the line's offer equals `reference_id` |
+Mercur resolves each line in this order:
-<Note>
- Products are the shared master catalog. The `seller` dimension resolves
- through the **offer** on the order line (`item.offer.seller_id`), not through
- product ownership.
-</Note>
+1. Drop disabled rates and rates whose `currency_code` is set to another currency.
+2. Keep the rates that match the line. A rate without rules always matches.
+3. Sort by specificity, highest first.
+4. Break ties by `created_at`, oldest first.
+5. Apply the first rate to the line’s base amount.
-## Most-specific-wins
+The global rate has no rules, so its specificity is 0 and any matching scoped rate beats it. If no enabled rate matches, the line gets no commission line.
-When several rates match a line, resolution is **AND across dimensions, OR
-within a dimension**. Rules are grouped by `reference`. A rate matches only when
-**every** group it defines has at least one matching rule. Among the matching
-rates, the one scoped on the **most distinct dimensions** wins.
+<Warning>
+ The tie-break also applies between rule-less rates. If you create a second rate without rules, it competes with the global rate at specificity 0, and the older of the two wins.
+</Warning>
-```
-Rate A: seller = sel_123 (specificity 1)
-Rate B: seller = sel_123 AND category = pcat_shoes (specificity 2) ← wins
-```
+## Shipping uses the global rate only
-<Tip>
- Specificity is the count of **distinct dimensions** a rate scopes on, not the
- number of rules. Two `product_category` rules on one rate still count as a
- single dimension (they OR together).
-</Tip>
+Shipping methods aren’t matched against rules. If the global rate has `include_shipping` set, every shipping method on the order gets a line from it, with the description `Shipping Commission`. Otherwise shipping isn’t commissioned.
-## Tie-break
+The global rate’s `include_tax` flag applies to shipping too, adding the method’s `tax_total` to its `subtotal`. For a fixed global rate, each shipping method gets the fixed amount.
-When two matching rates have equal specificity, the **oldest** rate wins. Rates
-are evaluated `created_at` ascending, so the earliest-created rate is the
-deterministic winner.
+## Rates load once per batch
-## Shipping commission
+The `system` provider loads all enabled rates with their rules and values in one query per batch of orders. It then resolves every line of every order in memory. Adding rates doesn’t add queries per line.
-Item commission is resolved per line as above. Shipping is different: a
-shipping method is commissioned **only** by the global rate, and only when its
-`include_shipping` flag is on. No scoped rate can commission shipping.
+## Related
-<Note>
- `include_tax` is a separate, per-rate toggle. When on, the line's `tax_total`
- is added to the base amount before the rate is applied. This holds for both
- item and shipping commission.
-</Note>
+- [Rate types, per-currency values, and the global commission](/platform/commission/concepts/rules-and-rates)
+- [Scope a rate with batchCommissionRulesWorkflow](/platform/commission/guides/batch-update-rules)
+- [Write your own provider to replace this algorithm](/platform/commission/reference/service)
diff --git a/apps/docs/platform/commission/concepts/rules-and-rates.mdx b/apps/docs/platform/commission/concepts/rules-and-rates.mdx
index 3b234c8aa..b6fc72d38 100644
--- a/apps/docs/platform/commission/concepts/rules-and-rates.mdx
+++ b/apps/docs/platform/commission/concepts/rules-and-rates.mdx
@@ -1,84 +1,86 @@
---
-title: "Rules & rates"
+title: "Commission rates and rules"
sidebarTitle: "Rules & rates"
-description: "The commission rate, its fixed and percentage forms, and per-currency amounts."
+description: "How a commission rate expresses the marketplace's cut, how rules scope it, and what the global commission does."
---
-This page covers how a commission rate is modeled and the two ways it can
-express the marketplace's cut.
+A commission rate is the cut the marketplace takes from a sale, and rules decide which lines it applies to. Every marketplace has one global rate that covers everything, and you add scoped rates on top of it for specific sellers or parts of the catalog. Getting this model right decides what every seller is paid.
-## Commission rate
+## A rate is a type and a value
-A commission rate is the number the marketplace takes from a sale. It's
-represented by the `CommissionRate` data model (table `commission_rate`, id
-prefix `comrate`). A rate has a `name`, a unique `code`, a `type`, and a
-`value`, plus the `include_tax` and `include_shipping` toggles.
+A rate is a `CommissionRate` record (id prefix `comrate`). Its `type` says how to read its `value`, and two flags change the base amount the value applies to.
-```ts
-const { result } = await createCommissionRatesWorkflow(container).run({
- input: [
- {
- name: "Standard",
- type: CommissionRateType.PERCENTAGE,
- value: 10,
- },
- ],
-})
-```
+| `type` | How `value` is read | Line `amount` |
+| --- | --- | --- |
+| `percentage` | A percent, so `10` means 10% | `base × value ÷ 100` |
+| `fixed` | A flat amount per line item | The per-currency amount, or `value` |
-A rate is either **percentage** or **fixed**, set by `type`
-(`CommissionRateType`):
+The base amount is the line’s `subtotal`. A rate changes it with these flags:
-| Type | How `value` is read |
-| --- | --- |
-| `percentage` | A percent of the line's base amount (e.g. `10` → 10%) |
-| `fixed` | A flat amount deducted per line |
+- **`include_tax`**: adds the line’s `tax_total` to the base before the rate applies
+- **`include_shipping`**: lets the rate commission shipping methods, and only takes effect on the global rate
+- **`is_enabled`**: disabled rates are skipped during resolution
-<Note>
- A rate's `code` is unique. When you create a rate without one, the module
- auto-generates a URL-safe code from the `name` (e.g. `"Standard"` →
- `standard-a1b2c3`).
-</Note>
-
-## Per-currency amounts
+<Warning>
+ A fixed rate applies once per line item, not once per unit. A line with a quantity of 3 still gets one fixed amount. The `system` provider doesn’t cap a fixed amount at the line total.
+</Warning>
-A fixed rate can carry a different amount for each currency. This is
-represented by the `CommissionRateValue` data model (table
-`commission_rate_value`, id prefix `comval`). Each value pairs a `currency_code`
-with an `amount`, and the calculation picks the value matching the order's
-currency.
+Each rate also has a `name` and a unique `code`. When you create a rate without a `code`, the module builds one from the name plus a random suffix, so `"Standard"` becomes something like `standard-k3x9qa`.
```ts
+import { CommissionRateType } from "@mercurjs/types"
+import { createCommissionRatesWorkflow } from "@mercurjs/core/workflows"
+
await createCommissionRatesWorkflow(container).run({
input: [
- {
- name: "Flat fee",
- type: CommissionRateType.FIXED,
- value: 5, // fallback when no per-currency value matches
- values: [
- { currency_code: "usd", amount: 5 },
- { currency_code: "eur", amount: 4 },
- ],
- },
+ { name: "Standard", type: CommissionRateType.PERCENTAGE, value: 10 },
],
})
```
-<Tip>
- When no `values` entry matches the order's currency, a fixed rate falls back
- to its scalar `value`. Percentage rates ignore `values` entirely. A percent
- is currency-independent.
-</Tip>
+The example creates a 10% rate with no rules, which matches every line until a more specific rate wins.
+
+## Per-currency amounts for fixed rates
+
+A fixed rate holds one amount per currency in `CommissionRateValue` records (id prefix `comval`). During resolution, Mercur picks the value whose `currency_code` equals the order’s currency. When none matches, it uses the rate’s own `value`.
+
+Percentage rates ignore `values`, because a percent is the same in every currency. A rate’s own `currency_code` field is separate: when it’s set, the rate only applies to orders in that currency.
+
+| Rate | `values` | Order in `usd` | Order in `gbp` |
+| --- | --- | --- | --- |
+| fixed, `value: 3` | `usd: 2.5`, `eur: 2` | 2.5 per line | 3 per line |
+| percentage, `value: 10` | ignored | 10% of base | 10% of base |
+
+## Rules scope a rate
+
+A rule is a `CommissionRule` record (id prefix `comrule`) that belongs to one rate. It’s a `reference` naming a dimension and a `reference_id` naming the record, for example `seller` and `sel_01JD8Q1234567`. A rate without rules matches every line. A rate with rules matches only the lines that satisfy them.
+
+The five dimensions are:
+
+- **`product`**: a master product id
+- **`product_type`**: a product type id
+- **`product_collection`**: a collection id
+- **`product_category`**: a category id
+- **`seller`**: the seller of the offer on the order line
+
+[Rule matching](/platform/commission/concepts/rule-matching) explains how rules combine and which rate wins when several match.
## The global commission
-Every marketplace has exactly one **Global Commission**. This is the rate with
-`is_default` set to `true`. Mercur seeds it at boot (a `0%` percentage rate
-named `Default`) so a rate always exists, and it applies whenever no
-more-specific rate matches a line.
+The global commission is the rate with `is_default: true`. The module seeds it on boot when none exists, as a 0% percentage rate named `Default` with the code `default`. You raise it to set the marketplace’s baseline cut.
+
+The global rate has rules that set it apart:
+
+- **Always present**: `deleteCommissionRatesWorkflow` throws `NOT_ALLOWED` if you try to delete it
+- **Fallback for items**: it has no rules, so it matches every line and loses to any scoped rate that also matches
+- **Only shipping rate**: its `include_shipping` flag is the only one that produces shipping commission lines
<Note>
- The global rate is also the **only** rate that can commission shipping. See
- [Rule matching](/platform/commission/concepts/rule-matching) for how
- specificity and shipping are resolved.
+ Nothing stops you from setting `include_shipping` on a scoped rate, but the flag has no effect there. Shipping is resolved from the global rate alone.
</Note>
+
+## Related
+
+- [How Mercur picks one rate for each line](/platform/commission/concepts/rule-matching)
+- [Create a rate from your server code](/platform/commission/guides/create-a-rate)
+- [All `CommissionRate` fields](/platform/commission/reference/data-models)
diff --git a/apps/docs/platform/commission/guides/batch-update-rules.mdx b/apps/docs/platform/commission/guides/batch-update-rules.mdx
index e689fcda5..d9aaaa80a 100644
--- a/apps/docs/platform/commission/guides/batch-update-rules.mdx
+++ b/apps/docs/platform/commission/guides/batch-update-rules.mdx
@@ -1,58 +1,86 @@
---
title: "Batch-update commission rules"
sidebarTitle: "Batch-update rules"
-description: "Create, update, and delete a rate's rules in a single call."
+description: "Add, change, and remove a commission rate's rules in one workflow run with batchCommissionRulesWorkflow."
---
-In this guide, you'll learn how to manage the rules that scope a commission rate
-from your own server code, adding, changing, and removing them in one atomic
-operation.
+Change the rules that scope a commission rate in one run, for example to move a seller onto a negotiated rate or to retarget a rate at a new category.
-## Run the workflow
+## Before you begin
-`batchCommissionRulesWorkflow` applies creates, updates, and deletes to a single
-rate's rules in parallel. Pass the target `commission_rate_id` and any of the
-`create`, `update`, and `delete` arrays.
+You need the following:
-```ts title="src/api/custom/rules/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { batchCommissionRulesWorkflow } from "@mercurjs/core/workflows"
+- The id of the rate to change, such as `comrate_01JD8Q1234567`
+- The ids of the rules to update or delete, from the rate’s `rules` relation
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
- const { result } = await batchCommissionRulesWorkflow(req.scope).run({
- input: {
- commission_rate_id: "comrate_123",
- create: [
- { reference: "seller", reference_id: "sel_123" },
- { reference: "product_category", reference_id: "pcat_shoes" },
- ],
- update: [{ id: "comrule_456", reference_id: "pcat_boots" }],
- delete: ["comrule_789"],
- },
- })
+<Steps>
+ <Step title="Look up the rate's rules">
+ List the rate’s current rules through the module service.
- res.json(result)
-}
-```
+ ```ts
+ import { MercurModules } from "@mercurjs/types"
-The result groups the affected rules as `{ created, updated, deleted }`.
+ const commission = container.resolve(MercurModules.COMMISSION)
+
+ const rules = await commission.listCommissionRules({
+ commission_rate_id: "comrate_01JD8Q1234567",
+ })
+ ```
+
+ Each rule has an `id`, a `reference`, and a `reference_id`. You need the `id` to update or delete a rule.
+
+ </Step>
+ <Step title="Run the batch">
+ Call `batchCommissionRulesWorkflow` from an API route. This route adds a seller rule, retargets a category rule, and removes a product rule.
+
+ ```ts title="src/api/admin/commission-scopes/route.ts"
+ import type {
+ MedusaRequest,
+ MedusaResponse,
+ } from "@medusajs/framework/http"
+ import { batchCommissionRulesWorkflow } from "@mercurjs/core/workflows"
+
+ export async function POST(req: MedusaRequest, res: MedusaResponse) {
+ const { result } = await batchCommissionRulesWorkflow(req.scope).run({
+ input: {
+ commission_rate_id: "comrate_01JD8Q1234567",
+ create: [{ reference: "seller", reference_id: "sel_01JD8Q1234567" }],
+ update: [
+ { id: "comrule_01JD8Q1234567", reference_id: "pcat_01JD8Q1234568" },
+ ],
+ delete: ["comrule_01JD8Q1234569"],
+ },
+ })
+
+ res.json(result)
+ }
+ ```
+
+ The result is `{ created, updated, deleted }`: the created and updated rules, and the deleted ids.
+
+ </Step>
+</Steps>
+
+## How the three operations run
+
+The workflow runs `createCommissionRulesStep`, `updateCommissionRulesStep`, and `deleteCommissionRulesStep` in parallel. Each array is optional, and an empty or missing one is a no-op. If any step fails, the others roll back: created rules are deleted, updated rules get their old values, and deleted rules are created again.
<Note>
- Every rule's `reference` must be one of the five dimensions: `product`,
- `product_type`, `product_collection`, `product_category`, or `seller`. The
- `reference_id` is the id of the specific record in that dimension.
+ A rolled-back delete creates new rule records with the same `reference` and `reference_id`. The rules keep their meaning, but their ids change.
</Note>
-## How scoping changes matching
+## How the new rules change matching
+
+Adding rules narrows a rate. Rules on the same dimension are alternatives, and rules on different dimensions must all match. Adding the `seller` rule above to a rate that already had a `product_category` rule raises its specificity from 1 to 2, so it now beats single-dimension rates on that seller’s lines in that category.
+
+Use only the five supported references: `product`, `product_type`, `product_collection`, `product_category`, and `seller`. The module stores any string, and a rule with an unknown reference makes the rate match nothing.
+
+## Recompute existing orders
+
+Rule changes affect orders placed or refreshed after the change. To apply new rules to existing orders, run `refreshOrderCommissionLinesWorkflow` for them.
-Adding rules **narrows** a rate. Rules on the same dimension OR together. Rules
-across dimensions AND together. The two `create` rules above make the rate match
-only lines that are both from seller `sel_123` **and** in category `pcat_shoes`,
-raising the rate's specificity to `2`.
+## Next steps
-<Tip>
- Increasing a rate's specificity makes it win over less-specific rates on the
- lines it matches. See
- [Rule matching](/platform/commission/concepts/rule-matching) for how
- most-specific-wins and tie-breaks resolve.
-</Tip>
+- [Refresh order commission lines after a rule change](/platform/commission/guides/refresh-order-commission-lines)
+- [See how specificity and tie-breaks pick a rate](/platform/commission/concepts/rule-matching)
+- [Input and output of batchCommissionRulesWorkflow](/platform/commission/reference/workflows)
diff --git a/apps/docs/platform/commission/guides/create-a-rate.mdx b/apps/docs/platform/commission/guides/create-a-rate.mdx
index 8cea38894..a89ca2d46 100644
--- a/apps/docs/platform/commission/guides/create-a-rate.mdx
+++ b/apps/docs/platform/commission/guides/create-a-rate.mdx
@@ -1,72 +1,120 @@
---
title: "Create a commission rate"
sidebarTitle: "Create a rate"
-description: "Create a commission rate programmatically with createCommissionRatesWorkflow."
+description: "Create percentage and fixed commission rates from a seed script or API route with createCommissionRatesWorkflow."
---
-In this guide, you'll learn how to create a commission rate from your own server
-code. This is useful in a seed script, a custom API route, or an onboarding flow.
+Create commission rates from your own server code, for example to seed a new marketplace or to set a seller’s rate during onboarding.
-Mercur exposes a `createCommissionRatesWorkflow` that creates one or more
-`CommissionRate` records. Run it from any place that has access to the Medusa
-container.
+## Before you begin
-## Run the workflow
+You need the following:
-```ts title="src/api/custom/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { createCommissionRatesWorkflow } from "@mercurjs/core/workflows"
-import { CommissionRateType } from "@mercurjs/types"
+- A Mercur project with `@mercurjs/core` registered through `withMercur()`
+- The id of any seller, product, or category you want to scope a rate to
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
- const { result } = await createCommissionRatesWorkflow(req.scope).run({
- input: [
- {
- name: "Standard",
- type: CommissionRateType.PERCENTAGE,
- value: 10,
+<Steps>
+ <Step title="Create a percentage rate">
+ Run `createCommissionRatesWorkflow` with an array of rates. This seed script creates a 12% rate for apparel.
+
+ ```ts title="src/scripts/seed-commission.ts"
+ import type { ExecArgs } from "@medusajs/framework/types"
+ import { CommissionRateType } from "@mercurjs/types"
+ import { createCommissionRatesWorkflow } from "@mercurjs/core/workflows"
+
+ export default async function seedCommission({ container }: ExecArgs) {
+ const { result } = await createCommissionRatesWorkflow(container).run({
+ input: [
+ {
+ name: "Apparel",
+ code: "apparel",
+ type: CommissionRateType.PERCENTAGE,
+ value: 12,
+ },
+ ],
+ })
+
+ console.log(result.map((rate) => rate.id))
+ }
+ ```
+
+ The workflow returns the created rates in input order. If you leave out `code`, the module generates one from `name` with a random suffix, so set it when other code needs to find the rate by code.
+
+ </Step>
+ <Step title="Run the script">
+ Run the script with the Medusa CLI from your API app.
+
+ ```bash
+ npx medusa exec ./src/scripts/seed-commission.ts
+ ```
+
+ A rate without rules matches every line, so it competes with the global rate until you scope it.
+
+ </Step>
+ <Step title="Scope the rate">
+ Attach rules with `batchCommissionRulesWorkflow`, passing the id of the rate you created.
+
+ ```ts title="src/scripts/seed-commission.ts"
+ import { batchCommissionRulesWorkflow } from "@mercurjs/core/workflows"
+
+ await batchCommissionRulesWorkflow(container).run({
+ input: {
+ commission_rate_id: result[0].id,
+ create: [
+ { reference: "product_type", reference_id: "ptyp_01JD8Q1234567" },
+ ],
},
- ],
- })
+ })
+ ```
+
+ The rate now matches only lines whose product has that type. See [Batch-update commission rules](/platform/commission/guides/batch-update-rules) for updates and deletes.
+
+ </Step>
+</Steps>
- res.status(201).json({ commission_rate: result[0] })
+## Create a fixed rate with per-currency amounts
+
+A fixed rate takes an amount per currency in `values`, and `value` is the fallback. `CreateCommissionRateDTO` doesn’t declare `values` or `rules`, but the module creates both as nested records.
+
+```ts title="src/scripts/seed-commission.ts"
+const flatFee = {
+ name: "Flat fee",
+ type: CommissionRateType.FIXED,
+ value: 3,
+ values: [
+ { currency_code: "usd", amount: 2.5 },
+ { currency_code: "eur", amount: 2 },
+ ],
+ rules: [{ reference: "seller", reference_id: "sel_01JD8Q1234567" }],
}
+
+await createCommissionRatesWorkflow(container).run({ input: [flatFee] })
```
-<Note>
- The workflow takes an **array** of rates and returns the created records. When
- you omit `code`, the module generates a unique one from `name`.
-</Note>
-
-## Create a fixed, per-currency rate
-
-For a flat fee, use `CommissionRateType.FIXED` and pass per-currency `values`.
-The scalar `value` is the fallback when no currency matches.
-
-```ts
-await createCommissionRatesWorkflow(req.scope).run({
- input: [
- {
- name: "Flat fee",
- type: CommissionRateType.FIXED,
- value: 5,
- values: [
- { currency_code: "usd", amount: 5 },
- { currency_code: "eur", amount: 4 },
- ],
- },
- ],
+Declaring the rate as a variable keeps TypeScript from rejecting the extra `values` and `rules` keys. The result is a flat fee per line item for one seller: 2.5 in USD, 2 in EUR, and 3 in any other currency.
+
+## Change the global commission
+
+The global rate is the one with `is_default: true`. Look it up, then update it with `updateCommissionRatesWorkflow`.
+
+```ts title="src/scripts/seed-commission.ts"
+import { MercurModules } from "@mercurjs/types"
+import { updateCommissionRatesWorkflow } from "@mercurjs/core/workflows"
+
+const commission = container.resolve(MercurModules.COMMISSION)
+const [globalRate] = await commission.listCommissionRates({
+ is_default: true,
+})
+
+await updateCommissionRatesWorkflow(container).run({
+ input: [{ id: globalRate.id, value: 10, include_shipping: true }],
})
```
-## Scope the rate
+This raises the baseline to 10% and turns on shipping commission. Only the global rate’s `include_shipping` produces shipping lines.
-A rate created without rules is a catch-all. To scope it to part of the catalog,
-attach rules with
-[`batchCommissionRulesWorkflow`](/platform/commission/guides/batch-update-rules).
+## Next steps
-<Tip>
- Only the global rate (`is_default`) may commission shipping. To let the global
- rate take a cut of shipping, update it with `include_shipping: true` via
- `updateCommissionRatesWorkflow`.
-</Tip>
+- [Scope rates with batchCommissionRulesWorkflow](/platform/commission/guides/batch-update-rules)
+- [Recompute existing orders after changing rates](/platform/commission/guides/refresh-order-commission-lines)
+- [See how the winning rate is picked](/platform/commission/concepts/rule-matching)
diff --git a/apps/docs/platform/commission/guides/refresh-order-commission-lines.mdx b/apps/docs/platform/commission/guides/refresh-order-commission-lines.mdx
index b3dfcfe8b..4c7d4f598 100644
--- a/apps/docs/platform/commission/guides/refresh-order-commission-lines.mdx
+++ b/apps/docs/platform/commission/guides/refresh-order-commission-lines.mdx
@@ -1,55 +1,124 @@
---
title: "Refresh order commission lines"
sidebarTitle: "Refresh order lines"
-description: "Recompute an order's commission lines after it changes."
+description: "Recompute commission lines for existing orders, and pass extra data to the commission provider with workflow hooks."
---
-In this guide, you'll learn how to recompute the commission lines for an order
-from your own server code. Mercur already refreshes lines automatically at
-checkout and on order changes. Reach for this workflow when you change an order
-outside those paths, or when backfilling.
+Recompute the commission lines of existing orders, for example after you change rates or when you change an order outside Mercur’s own workflows. Mercur already refreshes lines at checkout and on order edits, returns, claims, and exchanges.
-## Run the workflow
+<Steps>
+ <Step title="Run the workflow">
+ Pass the ids of the orders to `refreshOrderCommissionLinesWorkflow`. This route refreshes one order.
-`refreshOrderCommissionLinesWorkflow` reads each order, resolves the matching
-rate for every item and shipping method, and writes the resulting
-`CommissionLine` records.
+ ```ts title="src/api/admin/orders/[id]/recompute-commission/route.ts"
+ import type {
+ MedusaRequest,
+ MedusaResponse,
+ } from "@medusajs/framework/http"
+ import { refreshOrderCommissionLinesWorkflow } from "@mercurjs/core/workflows"
-```ts title="src/api/custom/refresh/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+ export async function POST(req: MedusaRequest, res: MedusaResponse) {
+ const { result } = await refreshOrderCommissionLinesWorkflow(
+ req.scope
+ ).run({
+ input: { order_ids: [req.params.id] },
+ })
+
+ res.json({ commission_lines: result })
+ }
+ ```
+
+ The workflow returns the lines it wrote for all the orders. It throws if any id doesn’t belong to an order.
+
+ </Step>
+ <Step title="Check the result">
+ Read the lines back through `query.graph`, filtering by the order’s item ids.
+
+ ```ts
+ const { data: lines } = await query.graph({
+ entity: "commission_line",
+ fields: ["item_id", "shipping_method_id", "code", "rate", "amount"],
+ filters: { item_id: ["ordli_01JD8Q1234567"] },
+ })
+ ```
+
+ Item lines carry `item_id`. Shipping lines carry `shipping_method_id` and the description `Shipping Commission`.
+
+ </Step>
+</Steps>
+
+## Backfill existing orders
+
+The workflow takes any number of order ids and resolves them in one batch, so the rates load once per run. For a backfill, page through orders and refresh each page.
+
+```ts title="src/scripts/backfill-commission.ts"
+import type { ExecArgs } from "@medusajs/framework/types"
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
import { refreshOrderCommissionLinesWorkflow } from "@mercurjs/core/workflows"
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
- const { result } = await refreshOrderCommissionLinesWorkflow(req.scope).run({
- input: { order_ids: [req.params.id] },
- })
+export default async function backfill({ container }: ExecArgs) {
+ const query = container.resolve(ContainerRegistrationKeys.QUERY)
+ const take = 100
+
+ for (let skip = 0; ; skip += take) {
+ const { data } = await query.graph({
+ entity: "order",
+ fields: ["id"],
+ pagination: { skip, take },
+ })
+ if (!data.length) break
- res.json({ commission_lines: result })
+ await refreshOrderCommissionLinesWorkflow(container).run({
+ input: { order_ids: data.map((order) => order.id) },
+ })
+ }
}
```
-<Note>
- The workflow takes an array of `order_ids`, so you can refresh many orders in
- one run. This is useful for backfilling after you change your commission
- configuration.
-</Note>
+Each page is one workflow run. A refresh replaces lines by item and shipping method, so you can re-run the script safely.
-## Idempotency
+## Pass extra data with setCommissionContext
-The refresh is a **delete-then-insert** for each affected item and shipping
-method, so re-running it never duplicates lines. You can call it as often as you
-need without cleaning up first.
+The `setCommissionContext` hook receives the calculation contexts before they reach the provider. Return a `StepResponse` with new contexts to fill `additional_context` for a custom provider, or return nothing to keep them.
-## When it runs automatically
+```ts title="src/workflows/hooks/commission-context.ts"
+import { StepResponse } from "@medusajs/framework/workflows-sdk"
+import { refreshOrderCommissionLinesWorkflow } from "@mercurjs/core/workflows"
+
+refreshOrderCommissionLinesWorkflow.hooks.setCommissionContext(
+ ({ contexts }) =>
+ new StepResponse(
+ contexts.map((context) => ({
+ ...context,
+ additional_context: { tier: "gold" },
+ }))
+ )
+)
+```
+
+Each context already has `order_id`, `seller_id`, `currency_code`, `items`, and `shipping_methods`. Items carry the product’s `tags` and `attribute_value_ids`, which the `system` provider ignores but your own provider can use.
+
+## React with commissionLinesUpserted
+
+The `commissionLinesUpserted` hook runs after the lines are written, as part of the same workflow run. If your handler throws, the run fails, and at checkout that fails the cart completion too.
+
+```ts title="src/workflows/hooks/commission-written.ts"
+import { refreshOrderCommissionLinesWorkflow } from "@mercurjs/core/workflows"
+
+refreshOrderCommissionLinesWorkflow.hooks.commissionLinesUpserted(
+ async ({ order_ids, commission_lines }, { container }) => {
+ const logger = container.resolve("logger")
+ logger.info(
+ `${commission_lines.length} lines for ${order_ids.join(", ")}`
+ )
+ }
+)
+```
-You rarely need to call this by hand. Mercur runs it for you:
+Use this hook to sync commission to an external ledger. Use the [order events](/platform/commission/reference/events) instead when your side effect shouldn’t be able to block the refresh.
-- **At checkout:** as each per-seller order is created from the split cart.
-- **On order changes:** a subscriber re-runs it when an order edit is
- confirmed, or a return, claim, or exchange is created.
+## Next steps
-<Tip>
- To hook your own logic into these moments, subscribe to the same order events
- rather than re-running this workflow. See the
- [Events reference](/platform/commission/reference/events).
-</Tip>
+- [What a commission line records](/platform/commission/concepts/order-commission-lines)
+- [Write a custom commission provider](/platform/commission/reference/service)
+- [Hooks of every commission workflow](/platform/commission/reference/workflows)
diff --git a/apps/docs/platform/commission/overview.mdx b/apps/docs/platform/commission/overview.mdx
index aa5833c3c..ff8b14e32 100644
--- a/apps/docs/platform/commission/overview.mdx
+++ b/apps/docs/platform/commission/overview.mdx
@@ -1,86 +1,94 @@
---
-title: "Commission"
+title: "Commissions"
sidebarTitle: "Overview"
-description: "Configure how the marketplace takes its cut of every seller order."
+description: "Set the share of each sale the marketplace keeps, scope it to sellers and parts of the catalog, and record it per order line."
---
-Use Mercur to keep financial control over what share of each sale the
-marketplace keeps and each seller earns.
+Use Mercur to decide what share of each sale the marketplace keeps and what each seller earns.
-Financial control over the marketplace runs through commission. You set
-policy-based **rates** (fixed or percentage) and scope them to parts of your
-catalog with **rules**. Mercur resolves the right rate for every order line by
-most-specific-wins and writes an auditable **commission line**. That line is the
-exact amount deducted before the seller is paid out, computed in arbitrary
-precision so the numbers reconcile.
+Commission is the marketplace’s cut of a seller order. You define rates as a percentage or a fixed amount and scope them with rules to sellers, products, types, collections, or categories. When an order is placed, Mercur picks the most specific matching rate for every line item and writes a commission line with the amount. The payout for that order is the order total minus the sum of its commission lines.
+
+<img className="block dark:hidden" src="/images/figures/commission-overview-light.svg" alt="Commission rates behind the commission lines of order #100: the Linen shirt line matches the 12% acme-apparel rate for € 5.64, while the Desk lamp line and the shipping method fall back to the 10% default rate." />
+<img className="hidden dark:block" src="/images/figures/commission-overview-dark.svg" alt="Commission rates behind the commission lines of order #100: the Linen shirt line matches the 12% acme-apparel rate for € 5.64, while the Desk lamp line and the shipping method fall back to the 10% default rate." />
<Note>
- **Commission = the `CommissionRate` + `CommissionRule` entities.** A rate is
- the number, either a percentage or a fixed amount. Rules scope that rate to a
- slice of the catalog. Every marketplace has one **Global Commission**. This is
- the `is_default` rate that applies when nothing more specific matches.
+ The Commission module owns four data models: `CommissionRate` (`comrate`), `CommissionRule` (`comrule`), `CommissionRateValue` (`comval`), and `CommissionLine` (`comline`). Resolve its service with `MercurModules.COMMISSION` from `@mercurjs/types`.
</Note>
## Key features
-- **Fixed or percentage:** a percentage of the line, or a flat per-currency amount.
-- **Per-currency amounts:** fixed rates carry an amount per currency, falling back to a default `value`.
-- **Five scoping dimensions:** match on `product`, `product_type`, `product_collection`, `product_category`, and `seller`.
-- **Most-specific-wins:** the rate scoped on the most dimensions wins, and ties break to the oldest rate.
-- **Shipping commission:** only the global rate may commission shipping (`include_shipping`).
-- **Automatic order lines:** a commission line is generated per item and recomputed when an order changes.
-- **BigNumber arithmetic:** all commission math uses arbitrary precision for financial accuracy.
+The Commission module covers configuration, resolution, and the per-order record:
+
+- **Percentage or fixed rates**: a percent of the line subtotal, or a flat amount per line
+- **Per-currency amounts**: a fixed rate holds one amount per currency and falls back to its `value`
+- **Five scoping dimensions**: rules match on `product`, `product_type`, `product_collection`, `product_category`, and `seller`
+- **Most specific wins**: the matching rate scoped on the most dimensions wins, and ties go to the oldest rate
+- **Global commission**: a seeded `is_default` rate that can’t be deleted and is the only rate that commissions shipping
+- **Lines that follow the order**: lines are written at checkout and recomputed on order edits, returns, claims, and exchanges
+- **Exact arithmetic**: amounts are computed with Medusa’s `MathBN` and stored as big numbers
+- **Pluggable calculation**: swap the built-in `system` provider for your own `ICommissionProvider`
+
+## How it works
+
+Commission runs as part of checkout and again whenever the order changes:
+
+1. `completeCartWithSplitOrdersWorkflow` splits the cart into one order per seller.
+2. It runs `refreshOrderCommissionLinesWorkflow` for the new orders as a nested step.
+3. The workflow builds one calculation context per order and passes them to the active provider in one batch.
+4. The `system` provider loads the enabled rates once and picks the winning rate for each item.
+5. The module replaces the order’s commission lines with the new set.
+6. When a payout is created, Mercur subtracts the sum of the order’s commission lines from the order total.
## Get started
-Learn how the domain fits together.
+Learn how rates, rules, and commission lines fit together.
<CardGroup cols={2}>
<Card title="Rules & rates" icon="percent" href="/platform/commission/concepts/rules-and-rates">
- Fixed vs. percentage rates, per-currency amounts, and the global rate.
+ Percentage and fixed rates, per-currency amounts, and the global commission.
</Card>
<Card title="Rule matching" icon="sliders" href="/platform/commission/concepts/rule-matching">
- The five dimensions, most-specific-wins, tie-breaks, and shipping.
+ How Mercur picks one rate for each line, and how shipping is handled.
</Card>
<Card title="Order commission lines" icon="receipt" href="/platform/commission/concepts/order-commission-lines">
- How per-order lines are computed and kept in sync.
+ What a commission line records and when it’s recomputed.
</Card>
</CardGroup>
## Examples
-Build against the Commission domain in your own code.
+Build against commission in your own server code.
<CardGroup cols={2}>
<Card title="Create a rate" icon="plus" href="/platform/commission/guides/create-a-rate">
- Run `createCommissionRatesWorkflow` from a route or seed script.
+ Create percentage and fixed rates with `createCommissionRatesWorkflow`.
</Card>
<Card title="Batch-update rules" icon="list-check" href="/platform/commission/guides/batch-update-rules">
- Create, update, and delete a rate's rules in one call.
+ Add, change, and remove a rate’s rules in one workflow run.
</Card>
<Card title="Refresh order lines" icon="arrows-rotate" href="/platform/commission/guides/refresh-order-commission-lines">
- Recompute commission for an order after it changes.
+ Recompute commission for orders and extend the calculation context.
</Card>
</CardGroup>
## Resources
-Data models, workflows, service methods, and events for the Commission domain.
+The data models, links, workflows, service methods, and events behind commission.
<CardGroup cols={2}>
<Card title="Data models" icon="table" href="/platform/commission/reference/data-models">
- `CommissionRate`, `CommissionRule`, and related entities.
+ Every field of the four commission models.
</Card>
<Card title="Links" icon="link" href="/platform/commission/reference/links">
- How Commission connects to catalog, sellers, and orders.
+ How commission records point at the catalog, sellers, and orders.
</Card>
<Card title="Workflows" icon="diagram-project" href="/platform/commission/reference/workflows">
- Rate, rule, and order-line workflows.
+ Rate, rule, and order-line workflows with their inputs and hooks.
</Card>
<Card title="Service" icon="gear" href="/platform/commission/reference/service">
- Module service methods for working with records directly.
+ Generated and custom service methods, and commission providers.
</Card>
<Card title="Events" icon="bell" href="/platform/commission/reference/events">
- How commission stays in sync with order changes.
+ The order events that trigger a recompute.
</Card>
</CardGroup>
diff --git a/apps/docs/platform/commission/reference/data-models.mdx b/apps/docs/platform/commission/reference/data-models.mdx
index 2e1ce8f30..f884957ff 100644
--- a/apps/docs/platform/commission/reference/data-models.mdx
+++ b/apps/docs/platform/commission/reference/data-models.mdx
@@ -1,75 +1,89 @@
---
-title: "Data models"
+title: "Commission data models"
sidebarTitle: "Data models"
-description: "The data models owned by the Commission domain."
+description: "Every field of CommissionRate, CommissionRule, CommissionRateValue, and CommissionLine."
---
-The Commission domain is owned by the **Commission module**. This reference
-lists its data models and their fields. For the full module overview, see the
-[Commission overview](/platform/commission/overview).
+The Commission module owns four data models, defined in `packages/core/src/modules/commission/models`. Every model also has `created_at`, `updated_at`, and a nullable `deleted_at`, which Medusa adds and the tables below leave out.
## CommissionRate
-Table `commission_rate`, id prefix `comrate`. The rate the marketplace takes
-from a sale.
+The rate the marketplace takes from a sale. Table `commission_rate`, id prefix `comrate`.
-| Field | Type | Notes |
+| Field | Type | Description |
| --- | --- | --- |
| `id` | text | Primary key |
-| `name` | text | Searchable |
-| `code` | text | Unique, searchable; auto-generated from `name` when omitted |
-| `type` | enum | `CommissionRateType`, `fixed` or `percentage` |
-| `value` | bigNumber | Percent (for `percentage`) or fallback amount (for `fixed`) |
-| `currency_code` | text | Nullable; when set, the rate applies only to that currency |
-| `include_tax` | boolean | Default `false`; add `tax_total` to the base amount |
-| `include_shipping` | boolean | Default `false`; only meaningful on the global rate |
-| `is_enabled` | boolean | Default `true`; only enabled rates are evaluated |
-| `is_default` | boolean | Default `false`; the single Global Commission |
-
-Relations: `rules` (one-to-many `CommissionRule`), `values` (one-to-many
-`CommissionRateValue`).
+| `name` | text | Display name, searchable |
+| `code` | text | Unique among non-deleted rates and searchable. Generated from `name` when omitted on create |
+| `type` | enum | `CommissionRateType`: `fixed` or `percentage` |
+| `value` | bigNumber | The percent for `percentage`, the fallback amount for `fixed` |
+| `currency_code` | text, nullable | When set, the rate applies only to orders in this currency |
+| `include_tax` | boolean | Default `false`. Adds the line’s `tax_total` to the base amount |
+| `include_shipping` | boolean | Default `false`. Produces shipping lines, on the `is_default` rate only |
+| `is_enabled` | boolean | Default `true`. Disabled rates are skipped |
+| `is_default` | boolean | Default `false`. Marks the global commission, which can’t be deleted |
+
+Relations:
+
+- **`rules`**: has many `CommissionRule`
+- **`values`**: has many `CommissionRateValue`
## CommissionRule
-Table `commission_rule`, id prefix `comrule`. Scopes a rate to a slice of the
-catalog.
+Scopes a rate to one record in one dimension. Table `commission_rule`, id prefix `comrule`.
-| Field | Type | Notes |
+| Field | Type | Description |
| --- | --- | --- |
| `id` | text | Primary key |
| `reference` | text | The dimension: `product`, `product_type`, `product_collection`, `product_category`, or `seller` |
| `reference_id` | text | The id of the record in that dimension |
-| `commission_rate` | relation | The rate this rule belongs to (`belongsTo`) |
+| `commission_rate_id` | text | Foreign key to the owning rate |
+
+Relations:
+
+- **`commission_rate`**: belongs to `CommissionRate`
+
+The table has an index on `(reference, reference_id)` for non-deleted rows.
## CommissionRateValue
-Table `commission_rate_value`, id prefix `comval`. A per-currency amount for a
-fixed rate.
+A per-currency amount for a fixed rate. Table `commission_rate_value`, id prefix `comval`.
-| Field | Type | Notes |
+| Field | Type | Description |
| --- | --- | --- |
| `id` | text | Primary key |
-| `currency_code` | text | The currency this amount applies to |
-| `amount` | bigNumber | The flat commission for that currency |
-| `commission_rate` | relation | The rate this value belongs to (`belongsTo`) |
+| `currency_code` | text | The currency this amount applies to, such as `usd` |
+| `amount` | bigNumber | The fixed commission per line item in that currency |
+| `commission_rate_id` | text | Foreign key to the owning rate |
+
+Relations:
+
+- **`commission_rate`**: belongs to `CommissionRate`
## CommissionLine
-Table `commission_line`, id prefix `comline`. The resolved commission for one
-order line.
+The resolved commission for one order line item or shipping method. Table `commission_line`, id prefix `comline`.
-| Field | Type | Notes |
+| Field | Type | Description |
| --- | --- | --- |
| `id` | text | Primary key |
-| `item_id` | text | Nullable; the order line item this line commissions |
-| `shipping_method_id` | text | Nullable; the shipping method this line commissions |
-| `commission_rate_id` | text | Nullable; the rate that matched |
-| `code` | text | The matched rate's code |
-| `rate` | float | The applied rate |
-| `amount` | bigNumber | The computed commission amount |
-| `description` | text | Nullable; `"Shipping Commission"` on shipping lines |
-
-<Note>
- A commission line anchors to **either** `item_id` **or** `shipping_method_id`.
- It references those records by id, not through a module link.
-</Note>
+| `item_id` | text, nullable | The order line item this line commissions |
+| `shipping_method_id` | text, nullable | The order shipping method this line commissions |
+| `commission_rate_id` | text, nullable | The rate that produced the line. Plain text, not a relation |
+| `provider_id` | text | Default `system`. The provider that computed the line |
+| `code` | text | The code of the rate that produced the line |
+| `rate` | float | The percent, or the fixed amount, that was applied |
+| `amount` | bigNumber | The commission amount |
+| `description` | text, nullable | `Shipping Commission` on shipping lines from the `system` provider |
+| `data` | json, nullable | Free data from the provider |
+
+The table has indexes on `item_id` and on `shipping_method_id` for non-deleted rows. A line sets one of the two anchors and leaves the other `null`.
+
+## Enums
+
+`CommissionRateType` is exported from `@mercurjs/types`.
+
+| Member | Value |
+| --- | --- |
+| `CommissionRateType.FIXED` | `fixed` |
+| `CommissionRateType.PERCENTAGE` | `percentage` |
diff --git a/apps/docs/platform/commission/reference/events.mdx b/apps/docs/platform/commission/reference/events.mdx
index da2b09b38..d13a51be5 100644
--- a/apps/docs/platform/commission/reference/events.mdx
+++ b/apps/docs/platform/commission/reference/events.mdx
@@ -1,58 +1,52 @@
---
-title: "Event reference"
+title: "Commission events"
sidebarTitle: "Events"
-description: "How the Commission domain stays in sync with order changes."
+description: "Commission emits no domain events of its own. It listens to four order events and recomputes commission lines."
---
-The Commission domain does **not** emit its own domain events. Commission lines
-are derived data, so instead of broadcasting changes, the module **subscribes**
-to order lifecycle events and recomputes lines whenever an order's composition
-changes.
+The Commission module doesn’t define or emit domain events. Commission lines are derived from the order, so the module listens to order events instead and recomputes the lines when the order’s contents change.
-## Events it reacts to
+## Events that trigger a recompute
-Mercur ships a subscriber (`order-commission-refresh-handler`) that re-runs
-`refreshOrderCommissionLinesWorkflow` for the affected order on each of these
-events:
+The `order-commission-refresh-handler` subscriber, in `packages/core/src/subscribers/order-edit-confirmed.ts`, runs `refreshOrderCommissionLinesWorkflow` for the order on each of these events.
-| Event | Emitted when |
-| --- | --- |
-| `OrderEditWorkflowEvents.CONFIRMED` | An order edit is confirmed |
-| `OrderWorkflowEvents.RETURN_RECEIVED` | A return is received |
-| `OrderWorkflowEvents.CLAIM_CREATED` | A claim is created |
-| `OrderWorkflowEvents.EXCHANGE_CREATED` | An exchange is created |
+| Event | Emitted when | Payload the subscriber reads |
+| --- | --- | --- |
+| `order-edit.confirmed` | An order edit is confirmed | `order_id` |
+| `order.return_received` | A return is received | `order_id` |
+| `order.claim_created` | A claim is created | `order_id` |
+| `order.exchange_created` | An exchange is created | `order_id` |
-Because the refresh is idempotent (delete-then-insert), reacting to several
-events for the same order never duplicates lines.
+The subscriber reads `order_id` and falls back to `id`. It does nothing when the payload has neither. The events come from Medusa as `OrderEditWorkflowEvents.CONFIRMED`, `OrderWorkflowEvents.RETURN_RECEIVED`, `OrderWorkflowEvents.CLAIM_CREATED`, and `OrderWorkflowEvents.EXCHANGE_CREATED`.
-## Run your own side effects
+Checkout doesn’t go through an event. `completeCartWithSplitOrdersWorkflow` runs the refresh as a nested step for every seller order it creates.
-To run logic when an order's commission changes, subscribe to the same order
-events the module listens to, then read the refreshed lines from the commission
-module.
+## Run your own logic after a recompute
-```ts title="src/subscribers/commission-changed.ts"
+Subscribe to the same order events to run your own logic when an order’s commission may change.
+
+```ts title="src/subscribers/commission-audit.ts"
import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
import { OrderWorkflowEvents } from "@medusajs/framework/utils"
-export default async function commissionChangedHandler({
+export default async function commissionAudit({
event,
container,
-}: SubscriberArgs<{ order_id?: string; id?: string }>) {
- const orderId = event.data.order_id ?? event.data.id
- if (!orderId) {
- return
- }
- // ...read commission lines for the order, notify, sync an external ledger, etc.
+}: SubscriberArgs<{ order_id: string }>) {
+ const logger = container.resolve("logger")
+ logger.info(`Commission may have changed on ${event.data.order_id}`)
}
export const config: SubscriberConfig = {
- event: OrderWorkflowEvents.RETURN_RECEIVED,
+ event: [
+ OrderWorkflowEvents.RETURN_RECEIVED,
+ OrderWorkflowEvents.CLAIM_CREATED,
+ ],
}
```
+Subscribers run independently, so this one can run before the refresh finishes. When you need the new lines, use the `commissionLinesUpserted` hook of `refreshOrderCommissionLinesWorkflow`, which runs after they’re written. See [Refresh order commission lines](/platform/commission/guides/refresh-order-commission-lines).
+
<Note>
- Commission is also refreshed at checkout, as each per-seller order is created
- from the split cart. That refresh happens as a **step inside** the checkout
- workflow rather than via a separate event.
+ Like every `MedusaService` module, the Commission service also emits Medusa’s internal data-mutation events when records are created, updated, or deleted. Mercur doesn’t subscribe to them, and this reference doesn’t treat them as a stable contract.
</Note>
diff --git a/apps/docs/platform/commission/reference/links.mdx b/apps/docs/platform/commission/reference/links.mdx
index bf8c13a80..e5f5a7ca0 100644
--- a/apps/docs/platform/commission/reference/links.mdx
+++ b/apps/docs/platform/commission/reference/links.mdx
@@ -1,45 +1,54 @@
---
-title: "Links to other modules"
+title: "Commission links to other modules"
sidebarTitle: "Links"
-description: "How the Commission domain connects to the catalog, sellers, and orders."
+description: "Commission defines no module links. Rules and lines reference the catalog, sellers, and orders by plain id."
---
-Most Mercur modules connect to each other through **module links** (`defineLink`)
-resolved with `query.graph`. The Commission module is deliberately different: it
-defines **no** module links. Instead it connects to the rest of the marketplace
-through **soft references**. These are plain id fields resolved at calculation
-time. This keeps commission configuration independent of the catalog and order
-modules it scopes against.
+The Commission module defines no module links. None of the files in `packages/core/src/links` has a commission side. Rules and lines point at records in other modules through plain id fields, which Mercur resolves at calculation time or which you filter on directly.
-## Rules → catalog & sellers
+## Rules point at the catalog and sellers
-A `CommissionRule` points at a record in another domain through its
-`reference` / `reference_id` pair, resolved against the order line's product when
-commission is calculated:
+A `CommissionRule` names its target with `reference` and `reference_id`. The `refreshOrderCommissionLinesWorkflow` reads the target’s fields from the order with `query.graph`, so the commission records never need a link.
-| `reference` | Points at | Resolved from |
+| `reference` | Points at | Read from the order line |
| --- | --- | --- |
-| `product` | A master product | `item.product.id` |
-| `product_type` | A product type | `item.product.type_id` |
-| `product_collection` | A collection | `item.product.collection_id` |
-| `product_category` | A category | `item.product.categories[].id` |
-| `seller` | A store | `item.offer.seller_id` |
+| `product` | A master product | `items.product.id` |
+| `product_type` | A product type | `items.product.type_id` |
+| `product_collection` | A product collection | `items.product.collection_id` |
+| `product_category` | A product category | `items.product.categories.id` |
+| `seller` | A seller | `items.offer.seller_id` |
-<Note>
- Products are the shared master catalog, not seller-owned. The `seller`
- dimension resolves through the **offer** on the order line, which carries the
- selling store.
-</Note>
+The `seller` row goes through the `order-line-item-offer-link` from the Offer module. Products belong to the shared catalog, so the seller of a line is the seller of the offer the customer bought.
+
+## Lines point at order items and shipping methods
+
+A `CommissionLine` stores `item_id` or `shipping_method_id` as plain text. To get an order’s lines, collect the ids from the order, then filter `commission_line` by them.
+
+```ts
+const { data: [order] } = await query.graph({
+ entity: "order",
+ fields: ["items.id", "shipping_methods.id"],
+ filters: { id: "order_01JD8Q1234567" },
+})
-## Lines → orders
+const { data: lines } = await query.graph({
+ entity: "commission_line",
+ fields: ["item_id", "shipping_method_id", "code", "amount"],
+ filters: {
+ $or: [
+ { item_id: order.items.map((item) => item.id) },
+ { shipping_method_id: order.shipping_methods.map((m) => m.id) },
+ ],
+ },
+})
+```
-A `CommissionLine` records which order line it commissions through its
-`item_id` (an order line item) or `shipping_method_id` (a shipping method).
-These are stored as plain ids, so the payout pipeline reads an order's lines by
-querying the commission module directly rather than traversing a link.
+`createPayoutWorkflow` and the order commission-lines routes read lines the same way.
-<Tip>
- Because these are soft references, deleting a product, category, or order does
- not cascade to commission records. Rules and lines simply stop matching or are
- refreshed on the next order change.
-</Tip>
+## Lines point at their rate
+
+`commission_rate_id` on a line is also plain text, not a relation. Query the rate separately if you need more than the `code` the line already stores.
+
+<Note>
+ Plain ids don’t cascade. Deleting a product, category, or seller leaves its rules in place, where they stop matching. Deleting a rate soft-deletes it and leaves existing lines untouched.
+</Note>
diff --git a/apps/docs/platform/commission/reference/service.mdx b/apps/docs/platform/commission/reference/service.mdx
index 1882d017e..1a9b53589 100644
--- a/apps/docs/platform/commission/reference/service.mdx
+++ b/apps/docs/platform/commission/reference/service.mdx
@@ -1,51 +1,126 @@
---
-title: "Service reference"
+title: "Commission module service"
sidebarTitle: "Service"
-description: "The Commission module service and its methods for working with records directly."
+description: "Resolve the Commission module service, its generated and custom methods, and the commission provider interface."
---
-The Commission module exposes a service you can resolve from the Medusa
-container to read and write records directly, without going through a workflow.
-Use it inside custom services, subscribers, or scheduled jobs.
+The Commission module service reads and writes commission records without a workflow. Use it in steps, subscribers, and scheduled jobs, and use the [workflows](/platform/commission/reference/workflows) when you need rollback or the global-rate delete guard.
+
+## Resolve the service
+
+Resolve the service from the container with `MercurModules.COMMISSION`.
```ts
import { MercurModules } from "@mercurjs/types"
-const commissionModuleService = container.resolve(MercurModules.COMMISSION)
+const commission = container.resolve(MercurModules.COMMISSION)
-const [rates, count] = await commissionModuleService.listAndCountCommissionRates(
- { is_enabled: true }
+const [rates, count] = await commission.listAndCountCommissionRates(
+ { is_enabled: true },
+ { relations: ["rules", "values"] }
)
```
+The call returns enabled rates with their rules and per-currency values, plus the total count.
+
## Generated methods
-Each data model gets a standard set of auto-generated methods. For
-`CommissionRate`:
+The service extends `MedusaService`, so every model gets the standard methods. For `CommissionRate` they are:
| Method | Description |
| --- | --- |
-| `createCommissionRates(data)` | Create one or more rates (auto-generates `code`) |
-| `retrieveCommissionRate(id, config?)` | Retrieve a rate by id |
-| `listCommissionRates(filters?, config?)` | List rates matching filters |
-| `listAndCountCommissionRates(filters?, config?)` | List rates with a total count |
-| `updateCommissionRates(data)` | Update one or more rates |
-| `deleteCommissionRates(ids)` | Delete one or more rates |
+| `retrieveCommissionRate(id, config?)` | Retrieve one rate |
+| `listCommissionRates(filters?, config?)` | List rates |
+| `listAndCountCommissionRates(filters?, config?)` | List rates with a count |
+| `createCommissionRates(data)` | Create one rate or an array of rates |
+| `updateCommissionRates(data)` | Update rates |
+| `deleteCommissionRates(ids)` | Hard-delete rates |
+| `softDeleteCommissionRates(ids)` | Soft-delete rates |
+| `restoreCommissionRates(ids)` | Restore soft-deleted rates |
+
+The same set exists for `CommissionRule`, `CommissionRateValue`, and `CommissionLine`, for example `listCommissionRules`, `createCommissionRateValues`, and `retrieveCommissionLine`.
-The same set exists for every model in the module: `CommissionRule`,
-`CommissionRateValue`, and `CommissionLine` (e.g. `createCommissionRules`,
-`listCommissionRateValues`, `deleteCommissionLines`).
+<Warning>
+ `deleteCommissionRates` doesn’t check for the global rate. Use `deleteCommissionRatesWorkflow` to keep the `is_default` rate safe.
+</Warning>
-## Calculation & line methods
+## Custom methods
+
+The service overrides or adds these methods:
| Method | Description |
| --- | --- |
-| `getCommissionLines(context)` | Resolve the commission lines for a calculation context (items + shipping in a currency), most-specific-wins, without persisting |
-| `upsertCommissionLines(lines)` | Replace lines by anchor (`item_id` / `shipping_method_id`), making refreshes idempotent |
+| `createCommissionRates(data)` | Fills a missing `code` from `name` plus a random suffix, then creates. Returns one rate for one input, an array for an array |
+| `listCommissionRates(filters?, config?)` | Accepts a virtual `scope_type` filter |
+| `listAndCountCommissionRates(filters?, config?)` | Accepts the same `scope_type` filter |
+| `getCommissionLines(context)` | Computes lines for one context with the default provider. Doesn’t persist |
+| `getCommissionLinesBatch(contexts)` | Computes lines for several contexts, one array per context in order. Doesn’t persist |
+| `upsertCommissionLines(lines)` | Deletes existing lines with the same `item_id` or `shipping_method_id`, then inserts `lines` |
-<Warning>
- Prefer [workflows](/platform/commission/reference/workflows) for order-line
- refreshes and rate deletion. `refreshOrderCommissionLinesWorkflow` builds the
- calculation context from the order and calls these methods for you;
- `deleteCommissionRatesWorkflow` validates that a rate is safe to delete first.
-</Warning>
+`getCommissionLines` and `getCommissionLinesBatch` stamp the default provider’s id on any line without a `provider_id`. `getCommissionLinesBatch` falls back to one `getCommissionLines` call per context when the provider has no batch method.
+
+## Filter rates by scope type
+
+`scope_type` filters rates by the dimensions their rules use, computed in the database. Pass one value, an array, or a comma-separated string. Several values are combined with OR, and an unknown value matches nothing.
+
+| `scope_type` | Rates whose rules use |
+| --- | --- |
+| `store` | `seller` only, without `product_type` or `product_category` |
+| `product_type` | `product_type`, without `seller` or `product_category` |
+| `category` | `product_category`, without `seller` or `product_type` |
+| `store_product_type` | `seller` and `product_type` |
+| `store_category` | `seller` and `product_category`, without `product_type` |
+
+## Commission providers
+
+A provider computes the lines from a calculation context. The module always registers the built-in `system` provider, which implements the [rule matching](/platform/commission/concepts/rule-matching) algorithm, and uses it unless you configure another one.
+
+```ts title="src/modules/tiered-commission/service.ts"
+import { MathBN } from "@medusajs/framework/utils"
+import type {
+ CommissionCalculationContext,
+ CreateCommissionLineDTO,
+ ICommissionProvider,
+} from "@mercurjs/types"
+
+export default class TieredCommissionProvider
+ implements ICommissionProvider
+{
+ static identifier = "tiered"
+
+ async getCommissionLines(
+ context: CommissionCalculationContext
+ ): Promise<CreateCommissionLineDTO[]> {
+ const percent = context.additional_context?.tier === "gold" ? 8 : 12
+ return (context.items ?? []).map((item) => ({
+ item_id: item.id,
+ code: "tiered",
+ rate: percent,
+ amount: MathBN.div(MathBN.mult(item.subtotal, percent), 100).toNumber(),
+ }))
+ }
+}
+```
+
+A provider class needs a static `identifier` and `getCommissionLines`. It can add `getCommissionLinesBatch(contexts)` to load its data once per batch. The module doesn’t cap `amount`, so keep it within the item’s `total` yourself.
+
+Export the class as a module provider so the commission module can register it.
+
+```ts title="src/modules/tiered-commission/index.ts"
+import { ModuleProvider } from "@medusajs/framework/utils"
+import { MercurModules } from "@mercurjs/types"
+import TieredCommissionProvider from "./service"
+
+export default ModuleProvider(MercurModules.COMMISSION, {
+ services: [TieredCommissionProvider],
+})
+```
+
+The module takes these options, typed as `CommissionModuleOptions`:
+
+| Option | Description |
+| --- | --- |
+| `providers` | Array of `{ resolve, id, options?, is_default? }` registered next to `system` |
+| `default_provider` | Provider id used for every calculation. Overrides `is_default` |
+
+A single configured provider becomes the default without `is_default`.
diff --git a/apps/docs/platform/commission/reference/workflows.mdx b/apps/docs/platform/commission/reference/workflows.mdx
index f9fd5461b..9dc4b252e 100644
--- a/apps/docs/platform/commission/reference/workflows.mdx
+++ b/apps/docs/platform/commission/reference/workflows.mdx
@@ -1,40 +1,114 @@
---
-title: "Workflows"
+title: "Commission workflows"
sidebarTitle: "Workflows"
-description: "Commission rate, rule, and order-line workflows."
+description: "Inputs, outputs, steps, and hooks of the rate, rule, and order-line commission workflows."
---
-This reference lists the workflows for the Commission domain. Import them from
-`@mercurjs/core/workflows` and run them against the Medusa container.
+The Commission module ships five workflows, exported from `@mercurjs/core/workflows`. They run against the Medusa container, and each step compensates on failure unless noted. None of them emits an event.
-## Rate workflows
+## createCommissionRatesWorkflow
-| Workflow | Input | Purpose |
+Creates one or more commission rates. Workflow id `create-commission-rates`.
+
+| Input | Type |
+| --- | --- |
+| (root) | `CreateCommissionRateDTO[]` |
+
+`CreateCommissionRateDTO` takes `name`, `type`, and `value`, and optionally `code`, `currency_code`, `include_tax`, `include_shipping`, `is_enabled`, and `is_default`. The module also accepts nested `rules` and `values` arrays, which the DTO doesn’t declare. A missing `code` is generated from `name`.
+
+- **Output**: the created rates, in input order
+- **Steps**: `createCommissionRatesStep`, compensated by deleting the created rates
+- **Hooks**: none
+
+## updateCommissionRatesWorkflow
+
+Updates fields on one or more rates. Workflow id `update-commission-rates`.
+
+| Input | Type |
+| --- | --- |
+| (root) | `UpdateCommissionRateDTO[]` |
+
+Each item needs an `id` and takes any `CreateCommissionRateDTO` field as optional.
+
+- **Output**: the updated rates
+- **Steps**: `updateCommissionRatesStep`
+- **Hooks**: none
+
+<Warning>
+ The compensation of `updateCommissionRatesStep` re-applies the step’s input, not the previous values. If a later step in a parent workflow fails, the rate keeps the new values.
+</Warning>
+
+## deleteCommissionRatesWorkflow
+
+Soft-deletes rates after checking that none of them is the global rate. Workflow id `delete-commission-rates`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `ids` | `string[]` | Ids of the rates to delete |
+
+- **Output**: none
+- **Steps**: `validateCommissionRatesDeletableStep`, which throws `NOT_ALLOWED` for an `is_default` rate, then `deleteCommissionRatesStep`, compensated by restoring the rates
+- **Hooks**: `commissionRatesDeleted`, with `{ ids }`
+
+## batchCommissionRulesWorkflow
+
+Creates, updates, and deletes the rules of one rate. Workflow id `batch-commission-rules`.
+
+| Input | Type | Description |
| --- | --- | --- |
-| `createCommissionRatesWorkflow` | `CreateCommissionRateDTO[]` | Create rates (auto-generates `code`) |
-| `updateCommissionRatesWorkflow` | `UpdateCommissionRateDTO[]` | Update rate fields |
-| `deleteCommissionRatesWorkflow` | `{ ids[] }` | Delete rates (validates deletability first) |
+| `commission_rate_id` | `string` | The rate that new rules attach to |
+| `create` | `CreateCommissionRuleDTO[]`, optional | `{ reference, reference_id }` |
+| `update` | `UpdateCommissionRuleDTO[]`, optional | `{ id, reference?, reference_id? }` |
+| `delete` | `string[]`, optional | Ids of rules to delete |
+
+- **Output**: `{ created, updated, deleted }`, where `deleted` holds the ids
+- **Steps**: `createCommissionRulesStep`, `updateCommissionRulesStep`, and `deleteCommissionRulesStep`, run in parallel
+- **Hooks**: none
+
+Only `create` uses `commission_rate_id`. The ids in `update` and `delete` aren’t checked against it.
+
+## refreshOrderCommissionLinesWorkflow
-## Rule workflows
+Recomputes and replaces the commission lines of one or more orders. Workflow id `refresh-order-commission-lines`.
-| Workflow | Input | Purpose |
+| Input | Type | Description |
| --- | --- | --- |
-| `batchCommissionRulesWorkflow` | `{ commission_rate_id, create?, update?, delete? }` | Create, update, and delete a rate's rules in one call |
+| `order_ids` | `string[]` | Orders to refresh. An unknown id throws |
-## Order-line workflows
+- **Output**: `CommissionLineDTO[]`, the lines written for all the orders
+- **Steps**: `fetch-orders` (`useQueryGraphStep`), `getCommissionLinesStep`, `upsertCommissionLinesStep`
+- **Called by**: `completeCartWithSplitOrdersWorkflow` and the `order-commission-refresh-handler` subscriber
-| Workflow | Input | Purpose |
+The workflow exposes two hooks:
+
+| Hook | Input | Return |
| --- | --- | --- |
-| `refreshOrderCommissionLinesWorkflow` | `{ order_ids[] }` | Recompute and upsert an order's commission lines (idempotent) |
-
-<Note>
- `deleteCommissionRatesWorkflow` exposes a `commissionRatesDeleted` hook, and
- `batchCommissionRulesWorkflow` runs its create / update / delete steps in
- parallel. `refreshOrderCommissionLinesWorkflow` also runs as a step inside the
- cart-split checkout workflow.
-</Note>
-
-To work with records directly instead of through a workflow, see the
-[Service reference](/platform/commission/reference/service). To run side effects
-when an order changes, see the
-[Event reference](/platform/commission/reference/events).
+| `setCommissionContext` | `{ contexts: CommissionCalculationContext[] }` | `StepResponse` of new contexts, or nothing |
+| `commissionLinesUpserted` | `{ order_ids, commission_lines }` | Ignored |
+
+```ts
+refreshOrderCommissionLinesWorkflow.hooks.setCommissionContext(
+ ({ contexts }) =>
+ new StepResponse(
+ contexts.map((c) => ({ ...c, additional_context: { tier: "gold" } }))
+ )
+)
+```
+
+The handler above adds data to every context before the provider sees it. Neither `getCommissionLinesStep` nor `upsertCommissionLinesStep` defines a compensation.
+
+## Exported steps
+
+`@mercurjs/core/workflows` also exports each step, with its id, for use in your own workflows:
+
+| Step | Id |
+| --- | --- |
+| `createCommissionRatesStep` | `create-commission-rates-step` |
+| `updateCommissionRatesStep` | `update-commission-rates-step` |
+| `deleteCommissionRatesStep` | `delete-commission-rates-step` |
+| `validateCommissionRatesDeletableStep` | `validate-commission-rates-deletable-step` |
+| `createCommissionRulesStep` | `create-commission-rules-step` |
+| `updateCommissionRulesStep` | `update-commission-rules-step` |
+| `deleteCommissionRulesStep` | `delete-commission-rules-step` |
+| `getCommissionLinesStep` | `get-commission-lines` |
+| `upsertCommissionLinesStep` | `upsert-commission-lines` |
diff --git a/apps/docs/platform/offer/concepts/pricing-and-inventory.mdx b/apps/docs/platform/offer/concepts/pricing-and-inventory.mdx
index 84433ee08..0992aa812 100644
--- a/apps/docs/platform/offer/concepts/pricing-and-inventory.mdx
+++ b/apps/docs/platform/offer/concepts/pricing-and-inventory.mdx
@@ -1,72 +1,86 @@
---
-title: "Pricing & inventory"
+title: "How offer prices and stock work"
sidebarTitle: "Pricing & inventory"
-description: "Offer-scoped prices on the shared price set, and inventory linked to the offer."
+description: "Offer prices live on the variant's shared price set behind an offer_id rule, and offer stock lives in inventory items linked to the offer."
---
-In this document, you'll learn how an offer carries its own price and inventory
-without owning the master variant.
+Several stores sell the same master variant, so prices and stock can’t live on the variant alone. Mercur keeps one price set per variant and tags each price row with the offer that owns it. Stock goes the other way: each offer gets its own inventory items, linked to the offer and never to the variant.
-## Offer-scoped pricing
+<img className="block dark:hidden" src="/images/figures/offer-price-rules-light.svg" alt="The shared price set of the Linen shirt M variant holds price rows for three offers; each row carries an offer_id rule, and the two rows for offer_01JD8QA form a quantity tier. Behind it, that offer links to its own inventory items." />
+<img className="hidden dark:block" src="/images/figures/offer-price-rules-dark.svg" alt="The shared price set of the Linen shirt M variant holds price rows for three offers; each row carries an offer_id rule, and the two rows for offer_01JD8QA form a quantity tier. Behind it, that offer links to its own inventory items." />
-An offer's prices don't live on a private price set. They live on the **master
-variant's shared `PriceSet`**, with each offer-owned row scoped by a
-`PriceRule` on the `offer_id` attribute. That's how many stores price the same
-variant independently: every price row Mercur writes for an offer is stamped with
-that offer's id, and reads filter the set back down to just that offer's rows.
+## Prices on the shared price set
+
+An offer has no price set of its own. Its prices are rows on the master variant’s `PriceSet`, and each row carries a price rule with the attribute `offer_id` set to the offer’s id.
+
+When an offer is created, `ensureVariantPriceSetsStep` gives the variant a price set if it has none. The workflow then adds each price with the `offer_id` rule merged into any rules you pass, and links every new price to the offer through the `offer ↔ price` link. That link is what `offer.prices` reads.
```ts
-// Every offer price row is written with an offer_id rule on the shared price set
prices: [
- {
- amount: 2500,
- currency_code: "usd",
- rules: { offer_id: "offer_123" },
- },
+ { amount: 4700, currency_code: "eur" },
+ { amount: 4200, currency_code: "eur", min_quantity: 10 },
]
```
-The offer side reads its price ladder through the writable `offer ↔ price`
-list-link, so `offer.prices` resolves in a single query traversal. Each row is a
-standard Medusa money amount and supports `min_quantity` / `max_quantity` for
-quantity-break pricing.
+These two rows give the offer a quantity tier. Each price accepts `min_quantity`, `max_quantity`, and extra `rules`. You never write the `offer_id` rule yourself: the workflow adds it.
+
+## How the right price is picked
+
+Carts resolve offer prices through Medusa’s pricing context. Mercur hooks into `setPricingContext` on `addToCartWorkflow`, `updateLineItemInCartWorkflow`, and `refreshCartItemsWorkflow` and adds `offer_id` with the ids of the offers in the cart.
+
+The pricing module then matches only the rows whose `offer_id` rule fits. If none of the items being added resolves to an offer, `addToCartWorkflow` fails with `Every cart line item must resolve to an offer_id`.
-<Note>
- Because prices sit on the shared price set scoped by `offer_id`, the master
- variant is never mutated per store. The variant keeps a single price set, and
- the `offer_id` rule partitions it per offer.
-</Note>
+## Replacing an offer’s prices
-## Offer-scoped inventory
+Updating prices replaces the offer’s own rows and leaves every other offer on the variant alone. `upsertOfferPricesWorkflow` does the work, and `updateOffersWorkflow` runs it when an entry has a `prices` array.
-An offer's stock is held in Medusa `InventoryItem` records that link to the
-**offer**, not to the variant. The `offer ↔ inventory_item` link is a list-link
-whose pivot table (`offer_inventory_item`) carries a `required_quantity` column,
-so one offer can draw on several inventory items, each with its own required
-quantity.
+The incoming array is the full new list:
+
+- **Row with an `id`**: updates that price in place
+- **Row without an `id`**: adds a new price with the `offer_id` rule
+- **Owned price left out**: removes the price and its link
+- **`id` owned by another offer**: the run fails with `Price … does not belong to offer …`
<Warning>
- Offer inventory links to the **offer**, not the variant. `variant.inventory_items`
- is empty for offer-based orders. Always resolve stock through
- `offer.inventory_items`, never through the variant.
+ Removed prices are deleted, not soft-deleted. The `offerPricesUpserted` hook payload carries `previous_prices`, which is the only place the old values can still be read.
</Warning>
-When you create an offer, its `inventory_items` entries each create a brand-new
-`InventoryItem` (with optional starting `stock_levels`) and link it to the offer
-in the same workflow run. An offer must have at least one inventory item.
+## Inventory linked to the offer
+
+Offer stock lives in Medusa `InventoryItem` records linked to the offer. The `offer ↔ inventory_item` link is many-to-many and its table, `offer_inventory_item`, has a `required_quantity` column (default `1`).
+
+One offer can draw on several inventory items, which makes it a kit. Ordering 1 unit of the offer reserves `required_quantity` units of each linked item.
+
+<Warning>
+ `variant.inventory_items` is empty for offers. Read stock through the offer, never through the variant.
+</Warning>
+
+The link has two read paths in `query.graph`:
+
+- **`inventory_items`**: the `InventoryItem` rows themselves, without the pivot columns
+- **`inventory_item_link`**: the pivot rows, with `required_quantity` and a nested `inventory_item`
```ts
-inventory_items: [
- {
- sku: "ACME-WIDGET-01",
- required_quantity: 1,
- stock_levels: [{ location_id: "sloc_1", stocked_quantity: 50 }],
- },
-]
+const { data: [offer] } = await query.graph({
+ entity: "offer",
+ fields: [
+ "inventory_item_link.required_quantity",
+ "inventory_item_link.inventory_item.location_levels.*",
+ ],
+ filters: { id: "offer_01JD8Q1234567" },
+})
```
-<Tip>
- The inventory items an offer creates are also linked to the store, so they show
- up under the store's inventory. To change the set of items on an existing
- offer, use the [batch inventory workflow](/platform/offer/guides/manage-offer-inventory).
-</Tip>
+## Inventory created with the offer
+
+`createOffersWorkflow` creates fresh inventory items for every offer. Each `inventory_items` entry becomes one new item with optional starting `stock_levels`, linked to the offer and to the store.
+
+Every offer needs at least one entry. The new item takes the variant’s title, and when the offer has a single item with `required_quantity` 1, it also copies the variant’s weight, dimensions, `hs_code`, `mid_code`, `origin_country`, and `material`.
+
+The offer row’s `manage_inventory` and `allow_backorder` flags drive the stock check. When `manage_inventory` is `true` and `allow_backorder` is `false`, adding the offer to a cart confirms `required_quantity` × quantity for each linked item. To change which items back an existing offer, use `batchOfferInventoryItemsWorkflow`.
+
+## Related
+
+- [Manage offer inventory](/platform/offer/guides/manage-offer-inventory)
+- [Price and inventory links](/platform/offer/reference/links)
+- [upsertOfferPricesWorkflow and its hook](/platform/offer/reference/workflows)
diff --git a/apps/docs/platform/offer/concepts/shipping.mdx b/apps/docs/platform/offer/concepts/shipping.mdx
index 5cc62a53b..8ea871970 100644
--- a/apps/docs/platform/offer/concepts/shipping.mdx
+++ b/apps/docs/platform/offer/concepts/shipping.mdx
@@ -1,48 +1,47 @@
---
-title: "Shipping"
+title: "How an offer ships"
sidebarTitle: "Shipping"
-description: "How an offer carries its own shipping profile."
+description: "Each offer names its store's shipping profile, and Mercur links the master product to a profile so multi-store carts keep their shipping methods."
---
-In this document, you'll learn how an offer determines how its items ship.
+Every offer ships with a shipping profile that belongs to its store. The profile ties the offer’s items to that store’s shipping options, so in a cart with items from several stores, each store ships its own items at its own rates.
-## Shipping profile
+## The offer’s shipping profile
-Every offer points at a store's own **shipping profile** through its
-`shipping_profile_id` field, joined via the read-only `offer ↔ shipping_profile`
-link. The profile is what ties the offer's items to the store's shipping options
-at checkout, so each store fulfills its slice of a multi-seller cart with its own
-rates.
+An offer stores its profile in `shipping_profile_id`, a required field on the `Offer` row. A read-only link on that field exposes the profile as `offer.shipping_profile` in `query.graph`.
+
+You set the profile when you create the offer and can change it with `updateOffersWorkflow`:
```ts
-await createOffersWorkflow(container).run({
+await updateOffersWorkflow(container).run({
input: {
offers: [
- {
- seller_id: "sel_123",
- created_by: "mem_123",
- variant_id: "variant_123",
- shipping_profile_id: "sp_123",
- sku: "ACME-WIDGET-01",
- prices: [{ amount: 2500, currency_code: "usd" }],
- inventory_items: [{ stock_levels: [{ location_id: "sloc_1", stocked_quantity: 50 }] }],
- },
+ { id: "offer_01JD8Q1234567", shipping_profile_id: "sp_01JD8Q1234567" },
],
},
})
```
-## Master products carry no profile
+This run moves one offer to a different profile and emits `offer.updated`. The offer workflows don’t check that the profile belongs to the offer’s store, so validate that in your route when the input comes from a seller.
+
+## Shipping profiles on master products
+
+Master products don’t carry a shipping profile of their own, but Medusa’s cart refresh keeps a shipping method only when a product in the cart matches the option’s profile. Without a profile on the product, multi-store carts would lose their shipping methods on every refresh.
+
+`createOffersWorkflow` closes that gap. For each master product in the run, it links the product to the offer’s shipping profile when the product has no profile yet:
-Master products live in the shared catalog and have no shipping profile of their
-own. To keep multi-seller carts from losing their shipping methods on refresh,
-`createOffersWorkflow` links the offer's **master product** to the offer's
-shipping profile. The product↔profile link is one-to-one, so the first offer's
-profile wins for a given master product. Later offers (including other stores'
-offers on the same product) skip the link if a profile is already attached.
+- **Product without a profile**: the first offer in the run sets it
+- **Product that already has a profile**: the link is skipped, even when another store’s offer names a different profile
+- **Several offers on one product in one run**: only the first offer’s profile is linked
<Note>
- The one-to-one product↔profile link is a checkout-refresh accommodation, not
- the source of truth for how a store ships. Each offer still carries its own
- `shipping_profile_id`, which is what drives that store's fulfillment.
+ The product to profile link is one-to-one and exists only for the cart refresh. Each offer’s own `shipping_profile_id` is still what decides how that store ships.
</Note>
+
+`updateOffersWorkflow` doesn’t touch the product link, so changing an offer’s profile later leaves the product’s profile as it was.
+
+## Related
+
+- [What is an offer](/platform/offer/concepts/what-is-an-offer)
+- [The offer to shipping profile link](/platform/offer/reference/links)
+- [Create an offer](/platform/offer/guides/create-an-offer)
diff --git a/apps/docs/platform/offer/concepts/what-is-an-offer.mdx b/apps/docs/platform/offer/concepts/what-is-an-offer.mdx
index 46c21a5e9..457cfa467 100644
--- a/apps/docs/platform/offer/concepts/what-is-an-offer.mdx
+++ b/apps/docs/platform/offer/concepts/what-is-an-offer.mdx
@@ -1,65 +1,68 @@
---
title: "What is an offer"
sidebarTitle: "What is an offer"
-description: "The offer record, how it points at a master product variant, and its SKU."
+description: "The offer record, how it points at a master variant, its SKU rules, and the conditions a store can list under."
---
-In this document, you'll learn what an offer is and how it relates to the shared
-master catalog.
+An offer is a store’s listing of one master product variant. The catalog product belongs to the marketplace, and the offer holds the store’s commercial terms on top of it: SKU, barcodes, condition, shipping profile, prices, and stock. You need this split in mind before you build anything that sells, because carts, orders, commissions, and payouts all follow the offer, not the product.
-## Offer
+## The offer record
-An offer is a store's listing against a master product variant, represented by
-the `Offer` data model (table `offer`, id prefix `offer`). It's a thin
-marketplace-side record: it holds the store (`seller_id`), the master variant it
-points at (`variant_id`), the master product (`product_id`), the store's own
-`sku`, optional `ean` / `upc` barcodes, and the shipping profile it ships with.
-Price and inventory are attached through links rather than stored on the row.
+The `Offer` data model (table `offer`, id prefix `offer`) is a thin row that points at catalog records by id. Prices and inventory aren’t columns on it: they attach through module links.
+
+The row carries these groups of fields:
+
+- **Ownership**: `seller_id` is the store, and `created_by` is the member who created the offer
+- **Catalog pointers**: `variant_id` and `product_id`, where `product_id` is read from the variant when the offer is created
+- **Identity**: `sku`, plus optional `ean` and `upc` barcodes copied from the variant when you leave them out
+- **Selling terms**: `shipping_profile_id`, `manage_inventory` (default `true`), `allow_backorder` (default `false`), and `leadtime_to_ship`
+- **Condition**: an optional `condition_id` that points at an `OfferCondition`
```ts
-const { result } = await createOffersWorkflow(container).run({
- input: {
- offers: [
- {
- seller_id: "sel_123",
- created_by: "mem_123",
- variant_id: "variant_123",
- shipping_profile_id: "sp_123",
- sku: "ACME-WIDGET-01",
- prices: [{ amount: 2500, currency_code: "usd" }],
- inventory_items: [{ stock_levels: [{ location_id: "sloc_1", stocked_quantity: 50 }] }],
- },
- ],
- },
+const { data: [offer] } = await query.graph({
+ entity: "offer",
+ fields: ["id", "sku", "seller.name", "product_variant.title"],
+ filters: { id: "offer_01JD8Q1234567" },
})
```
-<Note>
- **Products are not seller-owned.** The master product and its variants live in
- the shared catalog. An offer never modifies the product. It points at a
- variant and layers the store's own commercial terms on top.
-</Note>
+This query reads one offer with its store and master variant. `seller` and `product_variant` resolve through read-only links on `seller_id` and `variant_id`.
-## Offer vs. master product
+## Offers and master products
-A single master variant can back many offers, one per store that sells it. The
-`Offer` carries the identity of that particular listing:
+A master variant can back any number of offers. Each store that sells the variant holds its own offer, and the variant itself never changes when a store lists, prices, or stocks it.
-- `product_id` / `variant_id`: the master records the offer points at (joined through read-only links).
-- `seller_id`: the store that owns the offer (read-only link to the store).
-- `sku`: the store's own stock-keeping unit for this listing.
-- `ean` / `upc`: barcodes, snapshotted off the linked variant when not supplied.
+The same store can also list a variant more than once, for example a new and a refurbished copy. The module doesn’t limit offers per variant. The only uniqueness rule is the SKU.
<Tip>
- A store's `sku` is **unique within that store** (`(seller_id, sku)`, enforced
- while `deleted_at IS NULL`). Two different stores may reuse the same SKU string
- for their own offers.
+ A SKU is unique within a store: the index on `(seller_id, sku)` applies while `deleted_at` is null. Two stores can use the same SKU string, and a soft-deleted offer frees its SKU.
</Tip>
-## One offer per variant
+## Offer conditions
+
+An offer condition describes the physical state an offer is sold in. Operators manage conditions, and stores pick one when they create or update an offer.
+
+The `OfferCondition` model (id prefix `ofcond`) has a unique `code`, a display `label`, an `is_active` flag, and a `rank` that orders the list. The create and update workflows check every `condition_id` they receive:
+
+- **Unknown id**: the run fails with a not found error
+- **Inactive condition**: the run fails, so a deactivated condition can’t be assigned to new or edited offers
+- **Condition in use**: `deleteOfferConditionsWorkflow` refuses to delete a condition while any offer still uses it
+
+Deactivating a condition leaves the offers already listed under it unchanged.
+
+## Grouping offers by store
+
+A store’s offers on one product usually mirror that product’s variants. The service can collapse them into one row per product and store.
+
+When you pass `group_by_seller: true` to `listOffers` or `listAndCountOffers`, the service returns the newest offer of each `(product_id, seller_id)` group and sets two computed fields on it:
+
+- **`variant_count`**: how many offers the store has on that product
+- **`offer_ids`**: the ids of all offers in the group
+
+Only `product_id` and `seller_id` filters apply in grouped mode.
+
+## Related
-Each offer points at exactly one variant, so a store's offers on a product mirror
-that product's variants. When offers are grouped by store
-(`group_by_seller`), the service computes a `variant_count` and an `offer_ids`
-list for the grouped `(product, seller)` row. The dashboards use it to act on
-all of a store's offers on a product at once.
+- [How offer prices and stock work](/platform/offer/concepts/pricing-and-inventory)
+- [How an offer ships](/platform/offer/concepts/shipping)
+- [Offer and OfferCondition fields](/platform/offer/reference/data-models)
diff --git a/apps/docs/platform/offer/guides/bulk-create-offers.mdx b/apps/docs/platform/offer/guides/bulk-create-offers.mdx
index 184128f3c..fca24f595 100644
--- a/apps/docs/platform/offer/guides/bulk-create-offers.mdx
+++ b/apps/docs/platform/offer/guides/bulk-create-offers.mdx
@@ -1,65 +1,84 @@
---
-title: "Bulk-create offers"
+title: "Create and update offers in bulk"
sidebarTitle: "Bulk-create offers"
-description: "List many offers against the master catalog in a single workflow run."
+description: "List a store’s master variants in a single createOffersWorkflow run, then update or delete them in bulk."
---
-In this guide, you'll learn how to create many offers at once, for example when
-onboarding a store's catalog or running a CSV import.
-
-`createOffersWorkflow` accepts an array of offers, so a single run can list a
-store against many master variants at once. Each entry is independent and carries
-its own SKU, prices, inventory, and shipping profile.
-
-## Run the workflow with many offers
-
-```ts title="src/api/custom/bulk/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { createOffersWorkflow } from "@mercurjs/core/workflows"
-
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
- const { result } = await createOffersWorkflow(req.scope).run({
- input: {
- offers: [
- {
- seller_id: "sel_123",
- created_by: "mem_123",
- variant_id: "variant_a",
- shipping_profile_id: "sp_123",
- sku: "ACME-A-01",
- prices: [{ amount: 2500, currency_code: "usd" }],
- inventory_items: [{ stock_levels: [{ location_id: "sloc_1", stocked_quantity: 50 }] }],
- },
- {
- seller_id: "sel_123",
- created_by: "mem_123",
- variant_id: "variant_b",
- shipping_profile_id: "sp_123",
- sku: "ACME-B-01",
- prices: [{ amount: 4000, currency_code: "usd" }],
- inventory_items: [{ stock_levels: [{ location_id: "sloc_1", stocked_quantity: 20 }] }],
- },
- ],
- },
- })
-
- res.status(201).json({ offers: result })
-}
-```
+Pass a list of entries to `createOffersWorkflow` when you onboard a store’s catalog or run an import. One run creates every offer or none of them.
+
+## Before you begin
+
+You need these records in place:
+
+- **A store and a member**: the `seller_id` and the `created_by` member id for every entry
+- **Master variants**: one `variant_id` per row you import
+- **A shipping profile and a stock location**: both owned by the store
<Warning>
- The batch is validated as a whole: if any entry references a missing variant,
- omits its inventory items, or reuses an existing `(seller_id, sku)` pair, the
- run fails and its steps are compensated, so no partial offers are left behind.
+ Keep each run to one store. The workflow links all new inventory items to the store of the first entry, so mixing stores in one run assigns the other stores’ stock to the wrong store.
</Warning>
-## Update many offers
+## Import a store’s rows
+
+<Steps>
+ <Step title="Map your rows to offer entries">
+ Turn each source row into a `CreateOfferDTO` from `@mercurjs/types`.
+
+ ```ts title="src/lib/to-offers.ts"
+ import type { CreateOfferDTO } from "@mercurjs/types"
+
+ type Row = { variant_id: string; sku: string; price: number; qty: number }
+
+ export const toOffers = (rows: Row[]): CreateOfferDTO[] =>
+ rows.map((row) => ({
+ seller_id: "sel_01JD8Q1234567",
+ created_by: "mem_01JD8Q1234567",
+ shipping_profile_id: "sp_01JD8Q1234567",
+ variant_id: row.variant_id,
+ sku: row.sku,
+ prices: [{ amount: row.price, currency_code: "eur" }],
+ inventory_items: [
+ {
+ stock_levels: [
+ { location_id: "sloc_01JD8Q1234567", stocked_quantity: row.qty },
+ ],
+ },
+ ],
+ }))
+ ```
+
+ Each entry is independent and carries its own SKU, price, and starting stock.
+ </Step>
+ <Step title="Run the workflow once for the batch">
+ Call the workflow with the mapped entries.
+
+ ```ts title="src/api/admin/custom/offers/import/route.ts"
+ import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+ import { createOffersWorkflow } from "@mercurjs/core/workflows"
+ import { toOffers } from "../../../../../lib/to-offers"
+
+ export async function POST(req: MedusaRequest, res: MedusaResponse) {
+ const { rows } = req.body as { rows: Parameters<typeof toOffers>[0] }
+
+ const { result } = await createOffersWorkflow(req.scope).run({
+ input: { offers: toOffers(rows) },
+ })
+
+ res.status(201).json({ count: result.length })
+ }
+ ```
-`updateOffersWorkflow` mirrors the same array shape for edits. Each entry is
-keyed by the offer `id`; supplying a `prices` array **replaces** the offer's
-price ladder (rows with an `id` are updated in place, rows without one are added,
-and omitted rows are removed), while leaving `prices` out keeps the ladder
-untouched.
+ The run emits one `offer.created` event per offer.
+ </Step>
+</Steps>
+
+<Note>
+ The batch is all or nothing. A missing variant, an entry without inventory items, or a SKU the store already uses fails the run, and compensation removes everything it created.
+</Note>
+
+## Update offers in bulk
+
+`updateOffersWorkflow` takes the same array shape, keyed by offer `id`. Every field except `id` is optional.
```ts
import { updateOffersWorkflow } from "@mercurjs/core/workflows"
@@ -67,18 +86,35 @@ import { updateOffersWorkflow } from "@mercurjs/core/workflows"
await updateOffersWorkflow(req.scope).run({
input: {
offers: [
- { id: "offer_a", sku: "ACME-A-02" },
+ { id: "offer_01JD8Q1234567", sku: "ACME-LS-M-2" },
{
- id: "offer_b",
- prices: [{ amount: 3500, currency_code: "usd" }],
+ id: "offer_01JD8Q1234568",
+ prices: [{ amount: 3900, currency_code: "eur" }],
},
],
+ updated_by: "mem_01JD8Q1234567",
},
})
```
-<Tip>
- Both workflows emit one event per affected offer (`offer.created` /
- `offer.updated`). Subscribe to those events to run downstream side effects like
- re-indexing search. See the [Event reference](/platform/offer/reference/events).
-</Tip>
+The first entry renames a SKU and keeps its prices. The second replaces that offer’s prices: send an existing price `id` to update a row in place, since rows left out are deleted. `updated_by` reaches the `offersUpdated` and `offerPricesUpserted` hooks.
+
+## Delete offers in bulk
+
+`deleteOffersWorkflow` takes a list of ids and soft-deletes the offer rows.
+
+```ts
+import { deleteOffersWorkflow } from "@mercurjs/core/workflows"
+
+await deleteOffersWorkflow(req.scope).run({
+ input: { ids: ["offer_01JD8Q1234567", "offer_01JD8Q1234568"] },
+})
+```
+
+The run emits `offer.deleted` per offer. Its `offersDeleted` hook gets a snapshot of each offer and its prices taken before the delete. The workflow has no step that removes the offer’s prices or inventory items.
+
+## Next steps
+
+- [Manage offer inventory](/platform/offer/guides/manage-offer-inventory)
+- [How offer prices are replaced](/platform/offer/concepts/pricing-and-inventory)
+- [Offer events](/platform/offer/reference/events)
diff --git a/apps/docs/platform/offer/guides/create-an-offer.mdx b/apps/docs/platform/offer/guides/create-an-offer.mdx
index 2f933e5d6..fde7aa366 100644
--- a/apps/docs/platform/offer/guides/create-an-offer.mdx
+++ b/apps/docs/platform/offer/guides/create-an-offer.mdx
@@ -1,83 +1,135 @@
---
-title: "Create an offer"
+title: "Create an offer from your server code"
sidebarTitle: "Create an offer"
-description: "Create a single offer programmatically with createOffersWorkflow."
+description: "Run createOffersWorkflow to list a master variant for a store with a SKU, price, stock, and shipping profile."
---
-In this guide, you'll learn how to create an offer from your own server code,
-for example in a custom API route, a seed script, or an import flow.
+Create an offer with `createOffersWorkflow` when you list products for a store outside the Vendor panel, for example in a custom route, a seed script, or an import job.
-Mercur exposes a `createOffersWorkflow` that creates the `Offer` record, its
-inventory items, and its price rows, and wires up every link in one run. Run it
-from any place that has access to the Medusa container.
+## Before you begin
-## Run the workflow
+You need these records in place:
-```ts title="src/api/custom/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { createOffersWorkflow } from "@mercurjs/core/workflows"
+- **A store**: its `seller_id` and the id of a member to record as `created_by`
+- **A master variant**: the `variant_id` the store will sell
+- **A shipping profile**: one that belongs to the store
+- **A stock location**: where the starting stock is held
+
+## Create the offer
+
+<Steps>
+ <Step title="Add a route that runs the workflow">
+ Create an API route that runs `createOffersWorkflow` with one offer.
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
- const { result } = await createOffersWorkflow(req.scope).run({
- input: {
- offers: [
- {
- seller_id: "sel_123",
- created_by: "mem_123",
- variant_id: "variant_123",
- shipping_profile_id: "sp_123",
- sku: "ACME-WIDGET-01",
- prices: [{ amount: 2500, currency_code: "usd" }],
- inventory_items: [
+ ```ts title="src/api/admin/custom/offers/route.ts"
+ import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+ import { createOffersWorkflow } from "@mercurjs/core/workflows"
+
+ const stock = [{ location_id: "sloc_01JD8Q1234567", stocked_quantity: 50 }]
+
+ export async function POST(req: MedusaRequest, res: MedusaResponse) {
+ const { result } = await createOffersWorkflow(req.scope).run({
+ input: {
+ offers: [
{
- stock_levels: [{ location_id: "sloc_1", stocked_quantity: 50 }],
+ seller_id: "sel_01JD8Q1234567",
+ created_by: "mem_01JD8Q1234567",
+ variant_id: "variant_01JD8Q1234567",
+ shipping_profile_id: "sp_01JD8Q1234567",
+ sku: "ACME-LS-M",
+ prices: [{ amount: 4700, currency_code: "eur" }],
+ inventory_items: [{ stock_levels: stock }],
},
],
},
+ })
+
+ res.status(201).json({ offer: result[0] })
+ }
+ ```
+
+ The workflow returns the created `Offer` rows. The one `inventory_items` entry becomes a new inventory item with 50 units at the location.
+ </Step>
+ <Step title="Know what the run wires up">
+ One run does more than insert the row:
+
+ - **Inventory**: creates an `InventoryItem` per entry, links it to the offer with its `required_quantity`, and links it to the store
+ - **Prices**: adds each price to the variant’s price set with an `offer_id` rule and links it to the offer
+ - **Barcodes**: copies `ean` and `upc` from the variant when you leave them out
+ - **Shipping**: links the master product to the shipping profile if the product has none
+ - **Event**: emits `offer.created` with `{ id, product_id }`
+ </Step>
+ <Step title="Read the offer back with its links">
+ Query the offer with its prices and stock to confirm the result.
+
+ ```ts
+ const { data: [offer] } = await query.graph({
+ entity: "offer",
+ fields: [
+ "id",
+ "sku",
+ "prices.amount",
+ "prices.currency_code",
+ "inventory_item_link.required_quantity",
+ "inventory_item_link.inventory_item.location_levels.*",
],
- },
- })
+ filters: { id: result[0].id },
+ })
+ ```
+
+ `prices` reads the offer’s own rows on the shared price set. `inventory_item_link` returns the pivot rows, so you get `required_quantity` with each item.
+ </Step>
+</Steps>
+
+## Set selling terms and a condition
- res.status(201).json({ offer: result[0] })
+The offer accepts optional fields beyond the required ones. Add them to the same entry:
+
+```ts
+{
+ sku: "ACME-LS-M-RF",
+ condition_id: "ofcond_01JD8Q1234567",
+ manage_inventory: true,
+ allow_backorder: false,
+ leadtime_to_ship: 3,
+ metadata: { source: "erp" },
}
```
-<Note>
- Each offer must reference an existing master `variant_id` and include at least
- one `inventory_items` entry. The SKU must be unique within the store.
- Reusing an existing `(seller_id, sku)` pair is rejected.
-</Note>
+`condition_id` must point at an active offer condition. `manage_inventory` defaults to `true`, `allow_backorder` to `false`, and `leadtime_to_ship` to `null`.
-## What the workflow wires up
+## Attach custom data with additional_data
-A single run does more than insert a row:
+Pass `additional_data` to the run to hand extra values to the `offersCreated` hook. Use it to store data from your own module next to the offer.
-- Creates a new `InventoryItem` per `inventory_items` entry (with any `stock_levels`) and links each to the offer. Remember, inventory links to the **offer**, not the variant.
-- Writes each price onto the master variant's shared price set, stamped with an `offer_id` rule, and links the price rows to the offer.
-- Links the offer to its store, product, variant, and shipping profile.
-- Emits `offer.created`.
+```ts title="src/workflows/hooks/offers-created.ts"
+import { createOffersWorkflow } from "@mercurjs/core/workflows"
-## Attach custom data
+createOffersWorkflow.hooks.offersCreated(
+ async ({ offers, additional_data }, { container }) => {
+ const logger = container.resolve("logger")
+ for (const offer of offers) {
+ logger.info(`${offer.sku}: ${additional_data?.source ?? "api"}`)
+ }
+ }
+)
+```
-The workflow accepts an `additional_data` payload that is passed to its
-`offersCreated` hook, letting you persist marketplace-specific data alongside the
-offer without forking the workflow.
+The hook receives the created offers with their `prices` loaded. Run the workflow with `additional_data: { source: "erp" }` to see the value in the handler.
-```ts
-await createOffersWorkflow(req.scope).run({
- input: {
- offers: [
- {
- seller_id: "sel_123",
- created_by: "mem_123",
- variant_id: "variant_123",
- shipping_profile_id: "sp_123",
- sku: "ACME-WIDGET-01",
- prices: [{ amount: 2500, currency_code: "usd" }],
- inventory_items: [{ stock_levels: [{ location_id: "sloc_1", stocked_quantity: 50 }] }],
- },
- ],
- additional_data: { source: "csv-import" },
- },
-})
-```
+## Handle a failed run
+
+The workflow validates the whole input and rolls back on failure. Compensation removes the inventory items, prices, and links it already created.
+
+A run fails when:
+
+- **A variant doesn’t exist**: `Variant with id … was not found`
+- **An offer has no inventory items**: `Offer must have at least one inventory item`
+- **A condition is unknown or inactive**: `Offer condition … is not active` or not found
+- **A SKU is taken in the store**: the `(seller_id, sku)` unique index rejects the insert
+
+## Next steps
+
+- [Bulk-create offers](/platform/offer/guides/bulk-create-offers)
+- [Manage offer inventory](/platform/offer/guides/manage-offer-inventory)
+- [createOffersWorkflow reference](/platform/offer/reference/workflows)
diff --git a/apps/docs/platform/offer/guides/manage-offer-inventory.mdx b/apps/docs/platform/offer/guides/manage-offer-inventory.mdx
index 6419053e7..c727de992 100644
--- a/apps/docs/platform/offer/guides/manage-offer-inventory.mdx
+++ b/apps/docs/platform/offer/guides/manage-offer-inventory.mdx
@@ -1,53 +1,93 @@
---
-title: "Manage offer inventory"
+title: "Change the inventory items behind an offer"
sidebarTitle: "Manage offer inventory"
-description: "Attach, update, and detach inventory items on an existing offer."
+description: "Use batchOfferInventoryItemsWorkflow to link, relink, and unlink existing inventory items on an offer."
---
-In this guide, you'll learn how to change the inventory items linked to an
-existing offer from your own server code.
+Run `batchOfferInventoryItemsWorkflow` when an existing offer needs different stock behind it, for example to turn it into a kit or to swap a component. The workflow changes the `offer ↔ inventory_item` links and their `required_quantity` in one run.
-Because inventory links to the **offer** (not the variant), the set of inventory
-items backing an offer is managed through the `offer ↔ inventory_item` link.
-`batchOfferInventoryItemsWorkflow` applies creates, updates, and deletes to that
-link in a single run.
+## Before you begin
-## Run the batch workflow
+You need these records in place:
-```ts title="src/api/custom/offer-inventory/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { batchOfferInventoryItemsWorkflow } from "@mercurjs/core/workflows"
+- **An offer**: the `offer_id` whose stock you change
+- **Existing inventory items**: the workflow links items that already exist and doesn’t create new ones
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
- const { result } = await batchOfferInventoryItemsWorkflow(req.scope).run({
- input: {
- offer_id: "offer_123",
- create: [{ inventory_item_id: "iitem_new", required_quantity: 2 }],
- update: [{ inventory_item_id: "iitem_existing", required_quantity: 5 }],
- delete: ["iitem_stale"],
- },
- })
-
- res.json(result)
-}
-```
+## Change the links
+
+<Steps>
+ <Step title="Add a route that runs the batch">
+ Pass the offer and the three optional lists: `create`, `update`, and `delete`.
+
+ ```ts title="src/api/admin/custom/offers/[id]/inventory/route.ts"
+ import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+ import { batchOfferInventoryItemsWorkflow } from "@mercurjs/core/workflows"
+
+ export async function POST(req: MedusaRequest, res: MedusaResponse) {
+ const { result } = await batchOfferInventoryItemsWorkflow(req.scope).run({
+ input: {
+ offer_id: req.params.id,
+ create: [
+ { inventory_item_id: "iitem_01JD8Q1234567", required_quantity: 2 },
+ ],
+ update: [
+ { inventory_item_id: "iitem_01JD8Q1234568", required_quantity: 1 },
+ ],
+ delete: ["iitem_01JD8Q1234569"],
+ },
+ })
+
+ res.json(result)
+ }
+ ```
+
+ `create` links a new item, `update` changes the `required_quantity` of a linked item, and `delete` unlinks an item. The inventory item itself stays in place after an unlink.
+ </Step>
+ <Step title="Read the result">
+ The workflow returns what changed:
+
+ - **`created`**: the link definitions it added
+ - **`updated`**: the link definitions it rewrote
+ - **`deleted`**: the inventory item ids it unlinked
+
+ It also emits `offer.updated` with `{ id }` for the offer.
+ </Step>
+</Steps>
-The result reports the links that were `created`, `updated`, and `deleted`.
+## Rules the batch enforces
-## Rules the workflow enforces
+The workflow checks the whole payload before it writes anything. Any broken rule fails the run:
-- Items in `create` must **not** already be linked to the offer; items in `update` and `delete` **must** already be linked.
-- An `inventory_item_id` can't appear in more than one section, and can't be duplicated within a section.
-- `create` items must reference existing `InventoryItem` records; `required_quantity` defaults to `1`.
-- Deleting an item that isn't linked to the offer surfaces a 404 rather than silently no-op'ing.
+- **Unknown offer**: `Offer with id: … was not found`
+- **Unknown item in `create`**: the inventory item must exist
+- **Item not linked, in `delete`**: fails with not found instead of a silent no-op
+- **Same id twice**: an id can appear once per list and in only one of the three lists
+
+`required_quantity` defaults to `1` in `create` and is required in `update`.
<Note>
- This workflow manages the **links** between an offer and existing inventory
- items and their `required_quantity`. To create brand-new inventory items with
- starting stock as part of listing an offer, pass `inventory_items` to
- [`createOffersWorkflow`](/platform/offer/guides/create-an-offer) instead.
+ The workflow doesn’t check that an item in `create` is already linked or that an item in `update` is linked, and it doesn’t check which store owns an item. Read the offer’s `inventory_item_link` and the item’s store first when your input comes from a seller.
</Note>
-The workflow emits `offer.updated` and exposes an `offerInventoryItemsBatched`
-hook carrying the `offer_id`, the batch result, and any `additional_data` you
-passed in.
+## Run code after the batch
+
+The workflow exposes an `offerInventoryItemsBatched` hook. It receives the `offer_id`, the `result`, and any `additional_data` you passed.
+
+```ts title="src/workflows/hooks/offer-inventory-batched.ts"
+import { batchOfferInventoryItemsWorkflow } from "@mercurjs/core/workflows"
+
+batchOfferInventoryItemsWorkflow.hooks.offerInventoryItemsBatched(
+ async ({ offer_id, result }, { container }) => {
+ const logger = container.resolve("logger")
+ logger.info(`${offer_id}: ${result.deleted.length} items unlinked`)
+ }
+)
+```
+
+A `validate` hook runs first with the raw `input`, so you can reject a batch with your own rules before any link changes.
+
+## Next steps
+
+- [How offer stock works](/platform/offer/concepts/pricing-and-inventory)
+- [The offer to inventory item link](/platform/offer/reference/links)
+- [batchOfferInventoryItemsWorkflow reference](/platform/offer/reference/workflows)
diff --git a/apps/docs/platform/offer/overview.mdx b/apps/docs/platform/offer/overview.mdx
index d2f0b29bc..21418741e 100644
--- a/apps/docs/platform/offer/overview.mdx
+++ b/apps/docs/platform/offer/overview.mdx
@@ -1,60 +1,67 @@
---
-title: "Offer"
+title: "Offers"
sidebarTitle: "Overview"
-description: "How a store sells against the shared master catalog, with its own SKU, price, inventory, and shipping."
+description: "Let every store sell a shared catalog product with its own SKU, price, stock, condition, and shipping profile."
---
-Use offers to let each store sell against Mercur's shared master catalog on its
-own terms.
+Use offers to let several stores sell the same catalog product, each on its own terms.
-The offer is the central concept of the marketplace. Products live in a single
-**master catalog** that no store owns; an offer is the record that connects a
-store to a master product variant. It carries everything that makes that listing
-the store's own: its SKU, its price, its inventory, and its shipping profile.
-Cart and order line items link back to the exact offer that was purchased, so the
-whole order lifecycle knows which store fulfills and gets paid.
+Products in Mercur live in one shared master catalog that no store owns. An offer is the record that connects a store to one master variant. It carries everything that makes the listing the store’s own: its SKU, price, inventory, condition, and shipping profile. The Offer module holds the offer and its conditions, and links reach out to the store, the catalog, pricing, inventory, fulfillment, and the cart and order line items that buy it.
+
+<img className="block dark:hidden" src="/images/figures/offer-overview-light.svg" alt="The Linen shirt master product sits behind an Offers list for its M variant: ACME, GLOBEX, and INITECH each list the same variant with their own SKU, condition, price, and stock." />
+<img className="hidden dark:block" src="/images/figures/offer-overview-dark.svg" alt="The Linen shirt master product sits behind an Offers list for its M variant: ACME, GLOBEX, and INITECH each list the same variant with their own SKU, condition, price, and stock." />
<Note>
- **Products are shared; offers are owned.** A store never owns a product. It
- publishes an offer against a master product variant. Two stores selling the
- same product each have their own offer, with their own SKU, price, and stock.
+ The data model is `Offer` (id prefix `offer`), resolved with `MercurModules.OFFER` from `@mercurjs/types`. A store never owns a product. Two stores selling the same variant each hold their own offer.
</Note>
## Key features
-- **Per-store listings:** one offer per store per variant, each with its own SKU (unique within a store).
-- **Offer-scoped pricing:** prices live on the master variant's shared price set, scoped by an `offer_id` rule so every store prices independently.
-- **Offer-scoped inventory:** inventory items link to the **offer**, not the variant, so stock never leaks between stores.
-- **Per-offer shipping:** each offer points at the store's own shipping profile.
-- **Order attribution:** cart and order line items link to the purchased offer, driving fulfillment, commission, and payouts.
-- **Bulk operations:** create and update many offers, and batch an offer's inventory links, in a single workflow run.
+The Offer module covers everything a store needs to sell a catalog variant:
+
+- **Per-store listings**: an offer points at one master variant, with a SKU that’s unique within its store
+- **Offer-scoped pricing**: price rows sit on the variant’s shared price set, each tagged with an `offer_id` price rule
+- **Offer-scoped inventory**: inventory items link to the offer, not the variant, so stock never mixes between stores
+- **Conditions**: operators define conditions such as `new` or `refurbished`, and stores list offers under the active ones
+- **Per-offer shipping**: each offer names the store’s own shipping profile
+- **Order attribution**: cart and order line items link to the offer that was bought
+- **Hooks and events**: every workflow exposes hooks and emits `offer.*` events for your own side effects
+
+## How it works
+
+An offer moves through the marketplace in four steps:
+
+1. A store runs `createOffersWorkflow` against a master variant, with a SKU, prices, inventory items, and a shipping profile.
+2. The workflow writes the prices onto the variant’s price set with an `offer_id` rule and creates inventory items linked to the offer.
+3. When a shopper adds the offer to a cart, the line item links to the offer and pricing resolves the offer’s own rows.
+4. At checkout the order line item keeps the offer link, so the right store fulfills the item and gets paid.
## Get started
-Learn how the domain fits together:
+Learn how offers, prices, stock, and shipping fit together.
<CardGroup cols={2}>
<Card title="What is an offer" icon="tag" href="/platform/offer/concepts/what-is-an-offer">
- The offer record, how it points at a master variant, and its SKU.
+ The offer record, its SKU rules, and offer conditions.
</Card>
<Card title="Pricing & inventory" icon="coins" href="/platform/offer/concepts/pricing-and-inventory">
- Offer-scoped prices on the shared price set and offer-linked inventory.
+ Prices on the shared price set and stock linked to the offer.
</Card>
<Card title="Shipping" icon="truck" href="/platform/offer/concepts/shipping">
- How an offer carries its own shipping profile.
+ How an offer ships with its store’s shipping profile.
</Card>
</CardGroup>
## Examples
-Build against the Offer domain in your own code:
+Build against offers in your own server code.
<CardGroup cols={2}>
<Card title="Create an offer" icon="plus" href="/platform/offer/guides/create-an-offer">
- Run `createOffersWorkflow` with a price and inventory.
+ Run `createOffersWorkflow` from an API route.
</Card>
<Card title="Bulk-create offers" icon="layer-group" href="/platform/offer/guides/bulk-create-offers">
- List many offers against the catalog in one run.
+ List a store’s catalog in a single run.
</Card>
<Card title="Manage offer inventory" icon="boxes-stacked" href="/platform/offer/guides/manage-offer-inventory">
Attach, update, and detach inventory items on an offer.
@@ -63,22 +70,22 @@ Build against the Offer domain in your own code:
## Resources
-Data models, workflows, service methods, and events for the Offer domain:
+The data models, links, workflows, service methods, and events behind offers.
<CardGroup cols={2}>
<Card title="Data models" icon="table" href="/platform/offer/reference/data-models">
- The `Offer` entity and its fields.
+ `Offer` and `OfferCondition`, field by field.
</Card>
<Card title="Links" icon="link" href="/platform/offer/reference/links">
- How the Offer domain links to other modules.
+ How offers link to stores, catalog, pricing, inventory, and orders.
</Card>
<Card title="Workflows" icon="diagram-project" href="/platform/offer/reference/workflows">
- Create, update, delete, and inventory-batch workflows.
+ Offer, price, inventory, and condition workflows with their hooks.
</Card>
<Card title="Service" icon="gear" href="/platform/offer/reference/service">
- Module service methods for working with records directly.
+ Module service methods for reading and writing records directly.
</Card>
<Card title="Events" icon="bell" href="/platform/offer/reference/events">
- Events emitted as offers change.
+ Events emitted as offers and conditions change.
</Card>
</CardGroup>
diff --git a/apps/docs/platform/offer/reference/data-models.mdx b/apps/docs/platform/offer/reference/data-models.mdx
index 4c4435a51..d22e19fc4 100644
--- a/apps/docs/platform/offer/reference/data-models.mdx
+++ b/apps/docs/platform/offer/reference/data-models.mdx
@@ -1,56 +1,86 @@
---
-title: "Data models"
+title: "Offer data models"
sidebarTitle: "Data models"
-description: "The data models owned by the Offer domain."
+description: "Every field of the Offer and OfferCondition data models in the Offer module."
---
-The Offer domain is owned by the **Offer module**. This reference lists its data
-model and fields. For the full module overview, see the
-[Offer overview](/platform/offer/overview).
+The Offer module owns two data models: `Offer` and `OfferCondition`. Prices, inventory, the store, and catalog records aren’t columns on these models. They attach through [module links](/platform/offer/reference/links).
## Offer
-Table `offer`, id prefix `offer`. A store's listing against a master product
-variant. Price and inventory are attached through links rather than stored on the
-row.
+A store’s listing of one master product variant. Table `offer`, id prefix `offer`.
-| Field | Type | Notes |
+| Field | Type | Description |
| --- | --- | --- |
-| `id` | text | Primary key |
-| `seller_id` | text | The store that owns the offer (read-only link) |
-| `variant_id` | text | The master `ProductVariant` the offer points at |
-| `product_id` | text | The master `Product` the variant belongs to |
-| `shipping_profile_id` | text | The store's shipping profile for this offer |
-| `sku` | text | Searchable; unique within a store (see below) |
-| `ean` | text | Nullable, searchable; snapshotted off the variant when omitted |
-| `upc` | text | Nullable, searchable; snapshotted off the variant when omitted |
-| `created_by` | text | The member that created the offer |
-| `variant_count` | number | Computed; only set when grouping by store |
-| `metadata` | json | Nullable |
-
-Uniqueness: `(seller_id, sku)` is unique while `deleted_at IS NULL`, so a store
-can't reuse a SKU across its live offers, but different stores may share SKU
-strings. Indexes also cover `variant_id`, `product_id`, `seller_id`,
-`shipping_profile_id`, `ean`, and `upc`.
-
-## Linked data
-
-The offer's price ladder, inventory, and related records aren't columns on the
-`offer` table. They're joined through links and only present when requested:
-
-| Relation | Source |
-| --- | --- |
-| `prices` | Offer-owned rows on the master variant's shared price set (`offer ↔ price` list-link) |
-| `inventory_items` | `offer ↔ inventory_item` list-link; each row carries `required_quantity` |
-| `seller` | Read-only `offer ↔ seller` link |
-| `product` / `product_variant` | Read-only `offer ↔ product` / `offer ↔ variant` links |
-| `shipping_profile` | Read-only `offer ↔ shipping_profile` link |
-
-<Note>
- `variant_count` (and the companion `offer_ids` list) are computed only when
- offers are listed grouped by store (`group_by_seller`). On ungrouped reads they
- are absent.
-</Note>
-
-See the [Links reference](/platform/offer/reference/links) for the full set of
-module links.
+| `id` | `text` | Primary key, prefixed `offer_` |
+| `seller_id` | `text` | The store that owns the offer |
+| `variant_id` | `text` | The master `ProductVariant` the offer sells |
+| `product_id` | `text` | The master `Product`, read from the variant on create |
+| `shipping_profile_id` | `text` | The store’s shipping profile for this offer |
+| `sku` | `text` | Searchable. Unique per store among live offers |
+| `ean` | `text \| null` | Searchable. Copied from the variant when omitted on create |
+| `upc` | `text \| null` | Searchable. Copied from the variant when omitted on create |
+| `manage_inventory` | `boolean` | Default `true`. Whether stock is checked for the offer |
+| `allow_backorder` | `boolean` | Default `false`. Whether the offer sells past its stock |
+| `leadtime_to_ship` | `number \| null` | Lead time before the offer ships |
+| `created_by` | `text` | The member who created the offer |
+| `condition_id` | `text \| null` | Foreign key to `OfferCondition` |
+| `variant_count` | `number` | Computed, not stored. Set only by `group_by_seller` reads |
+| `metadata` | `json \| null` | Custom key-value data |
+| `created_at` | `timestamp` | Set on create |
+| `updated_at` | `timestamp` | Set on every write |
+| `deleted_at` | `timestamp \| null` | Set when the offer is soft-deleted |
+
+`OfferDTO` also has `offer_ids`, the list of offer ids in a `group_by_seller` group. It isn’t a model field.
+
+### Offer relations
+
+The offer has one relation inside the module:
+
+- **`condition`**: belongs to one `OfferCondition`, nullable
+
+### Offer indexes
+
+Every index applies only to rows where `deleted_at IS NULL`:
+
+| Index | Columns | Notes |
+| --- | --- | --- |
+| `IDX_offer_seller_sku_unique` | `seller_id`, `sku` | Unique |
+| `IDX_offer_variant_id` | `variant_id` | |
+| `IDX_offer_product_id` | `product_id` | |
+| `IDX_offer_seller_id` | `seller_id` | |
+| `IDX_offer_shipping_profile_id` | `shipping_profile_id` | |
+| `IDX_offer_ean` | `ean` | Only where `ean IS NOT NULL` |
+| `IDX_offer_upc` | `upc` | Only where `upc IS NOT NULL` |
+| `IDX_offer_condition_id` | `condition_id` | Only where `condition_id IS NOT NULL` |
+| `IDX_offer_seller_id_created_at` | `seller_id`, `created_at` | |
+| `IDX_offer_product_id_seller_id_created_at` | `product_id`, `seller_id`, `created_at` | |
+
+## OfferCondition
+
+A physical condition an offer can be listed under, such as `new` or `refurbished`. Operators manage the list. Id prefix `ofcond`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `text` | Primary key, prefixed `ofcond_` |
+| `code` | `text` | Searchable. Unique among live conditions |
+| `label` | `text` | Searchable. Display name |
+| `is_active` | `boolean` | Default `true`. Inactive conditions can’t be assigned |
+| `rank` | `number` | Default `0`. Sort order of the list |
+| `metadata` | `json \| null` | Custom key-value data |
+| `created_at` | `timestamp` | Set on create |
+| `updated_at` | `timestamp` | Set on every write |
+| `deleted_at` | `timestamp \| null` | Set when the condition is soft-deleted |
+
+### OfferCondition relations
+
+The condition has one relation inside the module:
+
+- **`offers`**: has many `Offer` records, mapped by `condition`
+
+The index `IDX_offer_condition_code_unique` keeps `code` unique while `deleted_at IS NULL`.
+
+## Related
+
+- [Links to other modules](/platform/offer/reference/links)
+- [What is an offer](/platform/offer/concepts/what-is-an-offer)
diff --git a/apps/docs/platform/offer/reference/events.mdx b/apps/docs/platform/offer/reference/events.mdx
index aca5a2235..b3cdbae33 100644
--- a/apps/docs/platform/offer/reference/events.mdx
+++ b/apps/docs/platform/offer/reference/events.mdx
@@ -1,22 +1,55 @@
---
-title: "Event reference"
+title: "Offer events"
sidebarTitle: "Events"
-description: "Events emitted by the Offer domain, for subscribers and side effects."
+description: "Events the offer workflows emit, with their payloads, for subscribers and side effects."
---
-The Offer domain emits events as offers change. Subscribe to them to run side
-effects instead of polling, such as re-indexing search, syncing external
-systems, or kicking off follow-up workflows.
+The offer and offer condition workflows emit events after they write. Subscribe to them to reindex search, sync an external system, or start a follow-up workflow instead of polling.
+
+## Offer events
+
+The offer workflows emit one event per affected offer. The names come from `OfferWorkflowEvents`.
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `offer.created` | `createOffersWorkflow` creates an offer | `{ id, product_id }` |
+| `offer.updated` | `updateOffersWorkflow` updates an offer | `{ id, product_id }` |
+| `offer.updated` | `batchOfferInventoryItemsWorkflow` changes an offer’s inventory links | `{ id }` |
+| `offer.deleted` | `deleteOffersWorkflow` soft-deletes an offer | `{ id, product_id }` |
+
+<Note>
+ `upsertOfferPricesWorkflow` emits no event of its own. When `updateOffersWorkflow` runs it, `offer.updated` covers the change. When you run it directly, use its `offerPricesUpserted` hook.
+</Note>
+
+## Offer condition events
+
+The condition workflows emit one event per condition. The names come from `OfferConditionWorkflowEvents`.
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `offer_condition.created` | `createOfferConditionsWorkflow` creates a condition | `{ id }` |
+| `offer_condition.updated` | `updateOfferConditionsWorkflow` updates a condition | `{ id }` |
+| `offer_condition.deleted` | `deleteOfferConditionsWorkflow` deletes a condition | `{ id }` |
+
+## Subscribe to an offer event
+
+A subscriber receives the payload and the container. This one reads the new offer with its store.
```ts title="src/subscribers/offer-created.ts"
import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
export default async function offerCreatedHandler({
event,
container,
}: SubscriberArgs<{ id: string; product_id: string }>) {
- const offerId = event.data.id
- // ...re-index the offer, notify the store, etc.
+ const query = container.resolve(ContainerRegistrationKeys.QUERY)
+ const { data: [offer] } = await query.graph({
+ entity: "offer",
+ fields: ["id", "sku", "seller.name"],
+ filters: { id: event.data.id },
+ })
+ container.resolve("logger").info(`${offer.seller.name} listed ${offer.sku}`)
}
export const config: SubscriberConfig = {
@@ -24,16 +57,9 @@ export const config: SubscriberConfig = {
}
```
-## Offer events
+Payloads carry ids only, so query the offer for the fields you need. For an `offer.deleted` subscriber, read values from the `offersDeleted` hook instead, since the row is already soft-deleted.
-| Event | Emitted when | Payload |
-| --- | --- | --- |
-| `offer.created` | An offer is created | `{ id, product_id }` |
-| `offer.updated` | An offer's row, prices, or inventory links change | `{ id, product_id }` |
-| `offer.deleted` | An offer is deleted | `{ id, product_id }` |
+## Related
-<Note>
- `createOffersWorkflow` and `updateOffersWorkflow` emit one event per affected
- offer. `batchOfferInventoryItemsWorkflow` emits `offer.updated` with a single
- `{ id }` payload for the batched offer.
-</Note>
+- [Offer workflows](/platform/offer/reference/workflows)
+- [Offer module links](/platform/offer/reference/links)
diff --git a/apps/docs/platform/offer/reference/links.mdx b/apps/docs/platform/offer/reference/links.mdx
index 4e5b7ed66..6cfbd6319 100644
--- a/apps/docs/platform/offer/reference/links.mdx
+++ b/apps/docs/platform/offer/reference/links.mdx
@@ -1,60 +1,112 @@
---
-title: "Links to other modules"
+title: "Offer module links"
sidebarTitle: "Links"
-description: "How the Offer domain links to other modules across the marketplace."
+description: "Every module link that connects offers to stores, the catalog, pricing, inventory, fulfillment, carts, and orders."
---
-Modules in Mercur never reference each other directly. They connect through
-**module links**. The offer sits at the center of the marketplace, so it links
-out to the store, the master catalog, pricing, inventory, fulfillment, and the
-cart and order line items that reference it. Once a link is defined, you retrieve
-related records with `query.graph` using the link alias.
+The Offer module never references another module directly. Eight module links in `packages/core/src/links/` connect the offer to the rest of the marketplace, and `query.graph` follows them by alias.
+
+| Link | Other side | Kind | File |
+| --- | --- | --- | --- |
+| Offer to store | `Seller` | Read-only, on `seller_id` | `offer-seller-link.ts` |
+| Offer to product | `Product` | Read-only, on `product_id` | `offer-product-link.ts` |
+| Offer to variant | `ProductVariant` | Read-only, on `variant_id` | `offer-variant-link.ts` |
+| Offer to shipping profile | `ShippingProfile` | Read-only, on `shipping_profile_id` | `offer-shipping-profile-link.ts` |
+| Offer to price | `Price` | Writable, one offer to many prices | `offer-price-link.ts` |
+| Offer to inventory item | `InventoryItem` | Writable, many to many | `offer-inventory-item-link.ts` |
+| Cart line item to offer | Cart `LineItem` | Writable, many items to one offer | `cart-line-item-offer-link.ts` |
+| Order line item to offer | `OrderLineItem` | Writable, many items to one offer | `order-line-item-offer-link.ts` |
+
+## Offer to store
+
+Each offer belongs to one store. The link reads `offer.seller_id`, so you write the store by setting that field, not through the link.
+
+```ts
+const { data: offers } = await query.graph({
+ entity: "offer",
+ fields: ["id", "sku", "seller.name"],
+ filters: { seller_id: "sel_01JD8Q1234567" },
+})
+```
+
+## Offer to product and variant
+
+Each offer points at one master product and one master variant. Both links are read-only and read `offer.product_id` and `offer.variant_id`.
+
+```ts
+const { data: offers } = await query.graph({
+ entity: "offer",
+ fields: ["id", "product.title", "product_variant.title"],
+ filters: { product_id: "prod_01JD8Q1234567" },
+})
+```
+
+The variant alias is `product_variant`. Use `product_variant.price_set.id` to reach the shared price set that holds the offer’s prices.
+
+## Offer to shipping profile
+
+Each offer ships with one profile, read from `offer.shipping_profile_id`.
```ts
const { data: offers } = await query.graph({
entity: "offer",
- fields: ["id", "sku", "prices.*", "inventory_items.*", "seller.name"],
+ fields: ["id", "shipping_profile.id", "shipping_profile.name"],
})
```
-## Catalog & store
+## Offer to price
+
+One offer has many prices. The link records which rows on the variant’s shared price set belong to the offer. The offer workflows create and dismiss these links, so don’t write them yourself.
+
+```ts
+const { data: offers } = await query.graph({
+ entity: "offer",
+ fields: [
+ "prices.amount",
+ "prices.currency_code",
+ "prices.min_quantity",
+ "prices.price_rules.attribute",
+ "prices.price_rules.value",
+ ],
+})
+```
-| Linked module | Relationship |
-| --- | --- |
-| **Product** | An offer points at one master product (`offer.product_id`, read-only). |
-| **Product variant** | An offer points at one master variant (`offer.variant_id`, read-only). |
-| **Seller** | An offer belongs to one store (`offer.seller_id`, read-only). |
+Every row returned also carries an `offer_id` price rule with the offer’s id.
-## Pricing & inventory
+## Offer to inventory item
-| Linked module | Relationship |
-| --- | --- |
-| **Price** | An offer has many prices: a writable list-link to the offer-owned rows on the master variant's shared price set. |
-| **Inventory item** | An offer has many inventory items: a writable list-link (`offer_inventory_item`) whose pivot carries a `required_quantity` column. |
+Offers and inventory items link many to many. The link table is `offer_inventory_item`, with an extra `required_quantity` integer column that defaults to `1`.
-## Fulfillment
+The link has three aliases:
-| Linked module | Relationship |
-| --- | --- |
-| **Shipping profile** | An offer ships with one shipping profile (`offer.shipping_profile_id`, read-only). |
+- **`offer.inventory_items`**: the linked `InventoryItem` rows, without pivot columns
+- **`offer.inventory_item_link`**: the pivot rows, with `required_quantity` and a nested `inventory_item`
+- **`inventory_item.offers`**: the offers that draw on an inventory item
-## Cart & order
+```ts
+const { data: offers } = await query.graph({
+ entity: "offer",
+ fields: [
+ "inventory_item_link.required_quantity",
+ "inventory_item_link.inventory_item.sku",
+ ],
+})
+```
+
+## Cart and order line items to offer
+
+Line items link to the offer that was bought. Both links set `isList: true` on the line item side, so one offer can back line items in any number of carts and orders.
+
+```ts
+const { data: [cart] } = await query.graph({
+ entity: "cart",
+ fields: ["items.id", "items.offer.id", "items.offer.seller_id"],
+ filters: { id: "cart_01JD8Q1234567" },
+})
+```
-| Linked module | Relationship |
-| --- | --- |
-| **Cart line item** | A cart line item links to the offer it added; one offer can back many cart line items (list-link on the line-item side). |
-| **Order line item** | An order line item links to the purchased offer; one offer can back many order line items across child orders (list-link on the line-item side). |
+The alias is `offer` on both cart and order line items. At checkout, `mirrorLineItemOfferLinksToOrderStep` copies each cart line item’s link to the new order line item. A subscriber does the same for line items added later by order edits, exchanges, and claims.
-<Note>
- Read-only links (Product, Variant, Seller, Shipping profile) resolve from a
- field on the `offer` row and can't be written through the link itself. The
- Price and Inventory-item links are writable and are managed by the offer
- workflows.
-</Note>
+## Product to shipping profile
-<Tip>
- The cart- and order-line-item links are list-links **on the line-item side** so
- the same offer can be added to many carts and placed on many orders. Without
- that, Medusa would enforce a 1:1 line-item ↔ offer relationship and block
- re-use.
-</Tip>
+`createOffersWorkflow` also writes Medusa’s own product to shipping profile link when the product has none. That link is Medusa’s, not Mercur’s. See [How an offer ships](/platform/offer/concepts/shipping).
diff --git a/apps/docs/platform/offer/reference/service.mdx b/apps/docs/platform/offer/reference/service.mdx
index c11480de0..44a3ad1e5 100644
--- a/apps/docs/platform/offer/reference/service.mdx
+++ b/apps/docs/platform/offer/reference/service.mdx
@@ -1,53 +1,88 @@
---
-title: "Service reference"
+title: "Offer module service"
sidebarTitle: "Service"
-description: "The Offer module service and its methods for working with records directly."
+description: "Resolve the Offer module service and use its generated and custom methods."
---
-The Offer module exposes a service you can resolve from the Medusa container to
-read and write records directly, without going through a workflow. Use it inside
-custom services, subscribers, or scheduled jobs.
+The Offer module service reads and writes `Offer` and `OfferCondition` rows directly. Use it in subscribers, scheduled jobs, and your own steps when you don’t need what the workflows add on top.
+
+## Resolve the service
+
+Resolve the service from the container with `MercurModules.OFFER`.
```ts
import { MercurModules } from "@mercurjs/types"
const offerModuleService = container.resolve(MercurModules.OFFER)
-const [offers, count] = await offerModuleService.listAndCountOffers({
- seller_id: "sel_123",
-})
+const [offers, count] = await offerModuleService.listAndCountOffers(
+ { seller_id: "sel_01JD8Q1234567" },
+ { take: 20 }
+)
```
+<Warning>
+ The service writes rows only. It doesn’t create prices, inventory items, or links, emit events, or roll back on failure. Use the [workflows](/platform/offer/reference/workflows) for anything that touches pricing, stock, or links.
+</Warning>
+
## Generated methods
-The `Offer` model gets a standard set of auto-generated methods:
+The service extends `MedusaService({ Offer, OfferCondition })`, which generates these methods for each model:
-| Method | Description |
+| Offer | OfferCondition |
| --- | --- |
-| `createOffers(data)` | Create one or more offers |
-| `retrieveOffer(id, config?)` | Retrieve an offer by id |
-| `listOffers(filters?, config?)` | List offers matching filters |
-| `listAndCountOffers(filters?, config?)` | List offers with a total count |
-| `updateOffers(data)` | Update one or more offers |
-| `deleteOffers(ids)` | Delete one or more offers |
+| `retrieveOffer(id, config?)` | `retrieveOfferCondition(id, config?)` |
+| `listOffers(filters?, config?)` | `listOfferConditions(filters?, config?)` |
+| `listAndCountOffers(filters?, config?)` | `listAndCountOfferConditions(filters?, config?)` |
+| `createOffers(data)` | `createOfferConditions(data)` |
+| `updateOffers(data)` | `updateOfferConditions(data)` |
+| `deleteOffers(ids)` | `deleteOfferConditions(ids)` |
+| `softDeleteOffers(ids)` | `softDeleteOfferConditions(ids)` |
+| `restoreOffers(ids)` | `restoreOfferConditions(ids)` |
-## Group by seller
+## listOffers and listAndCountOffers with group_by_seller
-`listOffers` and `listAndCountOffers` accept a `group_by_seller` filter. When
-set, the service collapses offers to one row per `(product, seller)` group and
-populates `variant_count` and `offer_ids` on each returned offer.
+Both offer list methods accept an extra `group_by_seller` filter. Without it they behave like the generated methods.
```ts
-const [grouped] = await offerModuleService.listAndCountOffers({
- product_id: "prod_123",
- group_by_seller: true,
-})
+listOffers(
+ filters?: Record<string, unknown> & { group_by_seller?: boolean },
+ config?: FindConfig<OfferDTO>,
+ sharedContext?: Context
+): Promise<OfferDTO[]>
+
+listAndCountOffers(
+ filters?: Record<string, unknown> & { group_by_seller?: boolean },
+ config?: FindConfig<OfferDTO>,
+ sharedContext?: Context
+): Promise<[OfferDTO[], number]>
```
-<Warning>
- The service writes the `offer` row and its computed fields directly. It does
- **not** create the offer's prices, inventory items, or module links, and it
- does **not** emit events or run compensation. Prefer the
- [workflows](/platform/offer/reference/workflows) for anything that must wire up
- pricing, inventory, or links.
-</Warning>
+With `group_by_seller: true`, the service returns one offer per `(product_id, seller_id)` group, the newest by `created_at`. Each returned offer gets `variant_count` and `offer_ids` for its group, and the count is the number of groups.
+
+Grouped mode reads only the `product_id` and `seller_id` filters. Pagination uses `config.skip` and `config.take`, with `take` defaulting to 20.
+
+## getStatistics
+
+Counts offers, and the distinct stores and products behind them, as they stood at a point in time.
+
+```ts
+getStatistics(
+ input?: OfferStatisticsInput,
+ sharedContext?: Context
+): Promise<OfferStatisticsOutput>
+```
+
+`input.at` defaults to now. `input.filters.seller_id` takes one id or a list. An offer counts when it was created at or before `at` and wasn’t deleted by then.
+
+```ts
+const { offers, sellers, products } =
+ await offerModuleService.getStatistics({ at: new Date("2026-10-01") })
+```
+
+The result is `{ offers, sellers, products }`, each a number.
+
+## Related
+
+- [Offer data models](/platform/offer/reference/data-models)
+- [Offer workflows](/platform/offer/reference/workflows)
diff --git a/apps/docs/platform/offer/reference/workflows.mdx b/apps/docs/platform/offer/reference/workflows.mdx
index b0bbdf81a..5bd6815b9 100644
--- a/apps/docs/platform/offer/reference/workflows.mdx
+++ b/apps/docs/platform/offer/reference/workflows.mdx
@@ -1,66 +1,175 @@
---
-title: "Workflows"
+title: "Offer workflows"
sidebarTitle: "Workflows"
-description: "Offer workflows for creating, updating, deleting, and batching inventory."
+description: "Every offer and offer condition workflow, with its input, hooks, and events."
---
-This reference lists the workflows for the Offer domain. Import them from
-`@mercurjs/core/workflows` and run them against the Medusa container.
+The Offer module ships eight workflows: five for offers and their prices and stock, and three for offer conditions. Import them from `@mercurjs/core/workflows` and run them with the Medusa container.
-## Offer workflows
+| Workflow | Id | Emits |
+| --- | --- | --- |
+| `createOffersWorkflow` | `create-offers` | `offer.created` |
+| `updateOffersWorkflow` | `update-offers` | `offer.updated` |
+| `upsertOfferPricesWorkflow` | `upsert-offer-prices` | None |
+| `deleteOffersWorkflow` | `delete-offers` | `offer.deleted` |
+| `batchOfferInventoryItemsWorkflow` | `batch-offer-inventory-items` | `offer.updated` |
+| `createOfferConditionsWorkflow` | `create-offer-conditions` | `offer_condition.created` |
+| `updateOfferConditionsWorkflow` | `update-offer-conditions` | `offer_condition.updated` |
+| `deleteOfferConditionsWorkflow` | `delete-offer-conditions` | `offer_condition.deleted` |
+
+## createOffersWorkflow
-| Workflow | Input | Purpose |
+Creates offers with their inventory items, prices, and links. Returns the created `OfferDTO[]`.
+
+| Input | Type | Description |
| --- | --- | --- |
-| `createOffersWorkflow` | `{ offers[], additional_data? }` | Create offers with prices, inventory, and links |
-| `updateOffersWorkflow` | `{ offers[], updated_by?, additional_data? }` | Update offer rows and rewrite their price ladders |
-| `deleteOffersWorkflow` | `{ ids[], additional_data? }` | Delete offers |
-| `batchOfferInventoryItemsWorkflow` | `{ offer_id, create?, update?, delete?, additional_data? }` | Add, update, and detach an offer's inventory-item links |
+| `offers` | `CreateOfferDTO[]` | One entry per offer |
+| `additional_data` | `Record<string, unknown>` | Optional. Passed to `offersCreated` |
+
+Each `CreateOfferDTO` requires `seller_id`, `created_by`, `sku`, `variant_id`, `shipping_profile_id`, `prices`, and at least one `inventory_items` entry. Optional fields are `ean`, `upc`, `manage_inventory`, `allow_backorder`, `leadtime_to_ship`, `condition_id`, and `metadata`.
+
+An `inventory_items` entry takes `required_quantity` (default `1`), `sku`, `title`, and `stock_levels` (`location_id`, `stocked_quantity`). A price takes `amount`, `currency_code`, and optional `min_quantity`, `max_quantity`, and `rules`.
+
+The run creates the inventory items and links them to the offer and to the store of the first entry. It adds prices to each variant’s price set with an `offer_id` rule, creating the price set first if the variant has none. It also links each master product to its first offer’s shipping profile when the product has no profile.
+
+| Hook | Payload |
+| --- | --- |
+| `validate` | `{ input }` |
+| `offersCreated` | `{ offers: OfferDTO[], additional_data }`, each offer with `prices` |
-## Hooks
+## updateOffersWorkflow
-Each workflow exposes hooks so you can extend it without forking:
+Updates offer rows and, for entries with a `prices` array, replaces that offer’s prices through `upsertOfferPricesWorkflow`. Returns the updated `OfferDTO[]`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `offers` | `UpdateOfferDTO[]` | Keyed by `id`. Every other field is optional |
+| `updated_by` | `string` | Optional. The actor id, passed to both hooks |
+| `additional_data` | `Record<string, unknown>` | Optional. Passed to `offersUpdated` |
-| Workflow | Hooks |
+`UpdateOfferDTO` accepts `sku`, `shipping_profile_id`, `manage_inventory`, `allow_backorder`, `leadtime_to_ship`, `condition_id`, `metadata`, and `prices`. Leave out `prices` to keep the current rows. A `condition_id` must point at an active condition.
+
+| Hook | Payload |
| --- | --- |
-| `createOffersWorkflow` | `validate`, `offersCreated` |
-| `updateOffersWorkflow` | `validate`, `offersUpdated` |
-| `upsertOfferPricesWorkflow` | `offerPricesUpserted` |
-| `deleteOffersWorkflow` | `offersDeleted` |
-| `batchOfferInventoryItemsWorkflow` | `validate`, `offerInventoryItemsBatched` |
+| `validate` | `{ input }` |
+| `offersUpdated` | `{ offers, previous_offers, updated_by, additional_data }` |
+
+`previous_offers` holds the offer rows as they were before the write.
-### Hook payloads
+## upsertOfferPricesWorkflow
+
+Replaces each listed offer’s prices without touching other offers on the same variant. Returns `{ offer_id, price_ids }[]` for the prices it created.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `offers` | `{ id, prices: UpsertOfferPriceDTO[] }[]` | The full new price list per offer |
+| `updated_by` | `string` | Optional. Passed to the hook |
+
+A price with an `id` updates that row, a price without one is added, and owned prices left out are deleted with their links. An `id` that belongs to another offer fails the run with `Price … does not belong to offer …`.
| Hook | Payload |
| --- | --- |
-| `offersCreated` | `{ offers: OfferDTO[], additional_data? }` — each offer carries `created_by` and its `prices` |
-| `offersUpdated` | `{ offers: OfferDTO[], previous_offers: OfferDTO[], updated_by?, additional_data? }` — `previous_offers` is the row state before the write |
-| `offerPricesUpserted` | `{ offers: Array<{ offer_id, previous_prices: OfferPriceDTO[], prices: OfferPriceDTO[], created: string[], updated: string[], deleted: string[] }>, updated_by: string \| null }` |
-| `offersDeleted` | `{ ids: string[], offers: OfferDTO[], additional_data? }` — `offers` is a snapshot taken before deletion, including `prices` |
+| `offerPricesUpserted` | `{ offers, updated_by }`, where `updated_by` is `string \| null` |
-`updated_by` is the authenticated actor id. Vendor routes fill it from the session; pass it yourself when running `updateOffersWorkflow` or `upsertOfferPricesWorkflow` directly.
+Each entry in `offers` has these fields:
-In `offerPricesUpserted`, `previous_prices` and `prices` are the offer's ladder before and after the write (`amount`, `currency_code`, `min_quantity`, `max_quantity`, `price_rules`). `created` and `deleted` hold the price ids added and removed; `updated` holds the ids rewritten in place whose amount, quantity bounds, or rules actually changed — an unchanged row resent with its id is not listed. The hook also fires when `updateOffersWorkflow` runs the price upsert for you, so a single handler on `upsertOfferPricesWorkflow` covers both entry points. Prices are hard-deleted and Medusa's pricing events carry ids only, so these payloads (and the `offersDeleted` snapshot) are the only place the previous values can be read.
+- **`offer_id`**: the offer
+- **`previous_prices`**: the offer’s prices before the write
+- **`prices`**: the offer’s prices after the write
+- **`created`**: ids of new prices
+- **`updated`**: ids whose amount, currency, quantity bounds, or rules changed; an unchanged row resent with its `id` isn’t listed
+- **`deleted`**: ids of removed prices
-```ts
+The hook also fires when `updateOffersWorkflow` runs the upsert, so one handler covers both entry points:
+
+```ts title="src/workflows/hooks/offer-prices-upserted.ts"
import { upsertOfferPricesWorkflow } from "@mercurjs/core/workflows"
-import { StepResponse } from "@medusajs/framework/workflows-sdk"
upsertOfferPricesWorkflow.hooks.offerPricesUpserted(
async ({ offers, updated_by }, { container }) => {
- for (const { offer_id, previous_prices, prices, updated } of offers) {
- // record a price-history entry for every id in `updated`
+ const logger = container.resolve("logger")
+ for (const { offer_id, updated, deleted } of offers) {
+ logger.info(`${offer_id} by ${updated_by}: ${updated.length} changed`)
+ logger.info(`${offer_id}: ${deleted.length} removed`)
}
- return new StepResponse(undefined)
}
)
```
-## Behavior notes
+Deleted prices are gone for good, so this payload is the only place to read their old values.
+
+## deleteOffersWorkflow
+
+Soft-deletes offers. It has no step that removes their prices or inventory items.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `ids` | `string[]` | The offers to delete |
+| `additional_data` | `Record<string, unknown>` | Optional. Passed to `offersDeleted` |
+
+| Hook | Payload |
+| --- | --- |
+| `offersDeleted` | `{ ids, offers, additional_data }` |
+
+`offers` is a snapshot taken before the delete, with each offer’s `prices`.
+
+## batchOfferInventoryItemsWorkflow
+
+Creates, updates, and removes `offer ↔ inventory_item` links on one offer. Returns `{ created, updated, deleted }`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `offer_id` | `string` | The offer to change |
+| `create` | `{ inventory_item_id, required_quantity? }[]` | Optional. Items to link, `required_quantity` defaults to `1` |
+| `update` | `{ inventory_item_id, required_quantity }[]` | Optional. New quantities for linked items |
+| `delete` | `string[]` | Optional. Inventory item ids to unlink |
+| `additional_data` | `Record<string, unknown>` | Optional. Passed to `offerInventoryItemsBatched` |
+
+The run fails when the offer doesn’t exist, an item in `create` doesn’t exist, an item in `delete` isn’t linked, or an id repeats within or across the lists.
+
+| Hook | Payload |
+| --- | --- |
+| `validate` | `{ input }` |
+| `offerInventoryItemsBatched` | `{ offer_id, result, additional_data }` |
+
+## createOfferConditionsWorkflow
+
+Creates offer conditions. Returns `OfferConditionDTO[]`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `offer_conditions` | `CreateOfferConditionDTO[]` | `code` and `label`, plus optional `is_active`, `rank`, and `metadata` |
+
+| Hook | Payload |
+| --- | --- |
+| `offerConditionsCreated` | `{ offer_conditions }` |
+
+## updateOfferConditionsWorkflow
+
+Updates offer conditions by `id`. Returns `OfferConditionDTO[]`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `offer_conditions` | `UpdateOfferConditionDTO[]` | `id`, plus any of `code`, `label`, `is_active`, `rank`, and `metadata` |
+
+| Hook | Payload |
+| --- | --- |
+| `offerConditionsUpdated` | `{ offer_conditions }` |
+
+## deleteOfferConditionsWorkflow
+
+Soft-deletes offer conditions. The run fails when an id doesn’t exist or when any offer still uses one of the conditions.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `ids` | `string[]` | The conditions to delete |
+
+| Hook | Payload |
+| --- | --- |
+| `offerConditionsDeleted` | `{ ids }` |
-- **Prices** are written on the master variant's shared price set, each row scoped by an `offer_id` `PriceRule`. On update, supplying `prices` replaces the ladder with the given rows; omitting it leaves prices untouched.
-- **Inventory** items passed to `createOffersWorkflow` are created and linked to the offer (and the store) in the same run. Every offer needs at least one.
-- Workflows run with compensation, so a failed create rolls back the inventory items, prices, and links it had already created.
+## Related
-To work with records directly instead of through a workflow, see the
-[Service reference](/platform/offer/reference/service). To run side effects when
-an offer changes, see the [Event reference](/platform/offer/reference/events).
+- [Offer events](/platform/offer/reference/events)
+- [Offer service methods](/platform/offer/reference/service)
+- [Create an offer](/platform/offer/guides/create-an-offer)
diff --git a/apps/docs/platform/order-group/concepts/computed-totals.mdx b/apps/docs/platform/order-group/concepts/computed-totals.mdx
index f03def9f6..07eb0f130 100644
--- a/apps/docs/platform/order-group/concepts/computed-totals.mdx
+++ b/apps/docs/platform/order-group/concepts/computed-totals.mdx
@@ -1,59 +1,62 @@
---
-title: "Computed totals"
+title: "How order group totals are computed"
sidebarTitle: "Computed totals"
-description: "Why an order group's seller count and total are derived at query time, not stored."
+description: "Why seller_count and total are summed from the child orders at read time, and how child order statuses are derived."
---
-This page covers how an order group's `seller_count` and `total` are calculated
-and why they aren't persisted.
+An order group never stores its own total. The `seller_count` and `total` fields are computed from the child orders each time you read the group, and the read workflows derive each child order’s payment and fulfillment status the same way. This keeps the group in step with its orders after edits, returns, and refunds, with no denormalized column to keep in sync.
-## Computed, not stored
+## Computed fields hold no value
-Two fields on the `OrderGroup` model are marked `computed()`. They never hold a
-value in the `order_group` row.
+Both fields are declared with `.computed()` on the model, so the `order_group` table has no column for them:
```ts
-const OrderGroup = model.define("order_group", {
- // ...
- seller_count: model.number().computed(),
- total: model.bigNumber().computed(),
-})
+seller_count: model.number().computed(),
+total: model.bigNumber().computed(),
```
-`seller_count` is the number of distinct sellers with a child order in the group.
-`total` is the sum of those child orders' current totals. Both are resolved
-by aggregating across the group's linked orders each time the group is read,
-rather than being written once at creation.
+You can’t write them through `createOrderGroups` or `updateOrderGroups`. They only exist on the records the Seller module reads back.
-<Note>
- Storing these values would immediately go stale: child orders can be refunded,
- returned, or canceled after the group is created, changing both the total and,
- effectively, the active seller set.
-</Note>
+## How the Seller module fills them
-## How they're aggregated
+The Seller module reads groups through a custom `OrderGroupRepository`. Its query joins each group to its child orders and sums them:
-When you read a group, the Seller module's order-group repository joins the group
-to its child orders (and each order to its seller and order summary) and folds
-them up:
+- **`seller_count`**: the number of distinct sellers linked to the group’s orders through `order_order_seller_seller`
+- **`total`**: the sum of `current_order_total` from each order’s summary at its current version, or `0` for a group with no orders
-- `seller_count`: a distinct count of the linked sellers
-- `total`: the sum of each child order's current order total
+Every list, count, and retrieve call on order groups runs through this repository, including `query.graph` on the `order_group` entity. Deleted orders and deleted links are left out.
```ts
-const orderGroup = await sellerModuleService.retrieveOrderGroup("og_123")
-// orderGroup.seller_count -> e.g. 3
-// orderGroup.total -> e.g. 24900 (sum across child orders)
+const sellerModuleService = container.resolve(MercurModules.SELLER)
+
+const group = await sellerModuleService.retrieveOrderGroup(
+ "og_01JD8Q1234567"
+)
```
+For a group with a 47.00 order from ACME and a 40.00 order from GLOBEX, `group.seller_count` is `2` and `group.total` is `87`. The repository converts `total` to a JavaScript `number`, which matches the `OrderGroupDTO` type.
+
+## Filters pick groups, not orders
+
+Order-level filters such as `seller_id`, `status`, `payment_status`, and `sales_channel_id` decide which groups match. They don’t trim the sums. A group that matches `seller_id: "sel_01JD8Q1234567"` still reports the `seller_count` and `total` of every order in it.
+
<Tip>
- Because `total` is a `bigNumber`, group totals stay precise no matter how many
- child orders and currencies contribute to the aggregate.
+ To show one seller’s share of a group, read the group’s `orders` and sum the ones that belong to that seller. The list workflow’s `sellerId` input trims `orders` for you.
</Tip>
-## Aggregated child statuses
+## Child order statuses
+
+`getOrderGroupDetailWorkflow` and `getOrderGroupsListWorkflow` set `payment_status` and `fulfillment_status` on every child order they return. Medusa’s `Order` model doesn’t store these, so the workflows compute them from the order’s data:
+
+| Status | Derived from | Possible values |
+| --- | --- | --- |
+| `payment_status` | The order’s payment collections: its own once the payment is split, the cart’s shared one before | `not_paid`, `awaiting`, `authorized`, `partially_authorized`, `captured`, `partially_captured`, `refunded`, `partially_refunded`, `canceled`, `requires_action` |
+| `fulfillment_status` | The `packed_at`, `shipped_at`, `delivered_at`, and `canceled_at` timestamps of its fulfillments, plus unfulfilled item quantities | `not_fulfilled`, `fulfilled`, `partially_fulfilled`, `shipped`, `partially_shipped`, `delivered`, `partially_delivered`, `canceled` |
+
+The group has no status of its own. Read the child statuses to show where each seller’s part of the purchase stands.
+
+## Related
-The retrieve and list workflows layer the same idea onto child orders. They
-derive each order's `payment_status` and `fulfillment_status` from its payment
-collections and fulfillments at read time, so the group reflects the live state
-of every seller's slice without any denormalized status column.
+- [Retrieve a group with its child order statuses](/platform/order-group/guides/retrieve-an-order-group)
+- [Filters the repository understands](/platform/order-group/reference/service#filters-and-sorting)
+- [The `OrderGroup` fields](/platform/order-group/reference/data-models)
diff --git a/apps/docs/platform/order-group/concepts/order-splitting.mdx b/apps/docs/platform/order-group/concepts/order-splitting.mdx
index 768bcc537..d8544fbfe 100644
--- a/apps/docs/platform/order-group/concepts/order-splitting.mdx
+++ b/apps/docs/platform/order-group/concepts/order-splitting.mdx
@@ -1,61 +1,63 @@
---
-title: "Order splitting"
+title: "How checkout splits a cart into orders"
sidebarTitle: "Order splitting"
-description: "How a multi-seller cart becomes a group of independent per-seller orders."
+description: "How completeCartWithSplitOrdersWorkflow turns one multi-seller cart into one order per seller under a group."
---
-This page covers how a single cart spanning multiple sellers is split into
-per-seller orders at checkout.
+Order splitting is what happens when a shopper completes a cart that holds offers from several sellers. Mercur replaces Medusa’s single-order checkout with `completeCartWithSplitOrdersWorkflow`, which creates one order per seller and wraps them in an order group. Understanding the split tells you where each seller’s items, shipping, promotions, and payment end up.
-## Why carts are split
+## Items follow the offer’s seller
-A marketplace cart can hold offers from many different sellers. Each seller
-fulfills, ships, and settles independently, so a single combined order would be
-impossible to operate. Instead, on completion the cart is divided along seller
-boundaries. Every seller with items in the cart gets its own `Order`, and all of
-those orders are attached to one parent `OrderGroup`.
+The workflow groups line items by `item.offer.seller_id`. Sellers sell against a shared master catalog through offers, so the offer, not the product, ties a line item to a seller. Every seller with at least one item gets one child order.
-The split is driven by the `completeCartWithSplitOrdersWorkflow`. It groups the
-cart's line items by the seller behind each offer, and builds one order per
-seller from that seller's items and shipping methods.
+The split enforces two rules before it creates anything:
+
+- **Every item has a seller**: `validateSellerCartItemsStep` throws `INVALID_DATA` when any line item has no offer with a `seller_id`
+- **Every seller’s shipping is covered**: `validateSellerCartShippingStep` throws when items that require shipping have no matching shipping method
+
+Each child order gets the seller’s line items plus the shipping methods whose shipping option belongs to that seller. Addresses, email, currency, locale, region, and sales channel are copied from the cart.
+
+## Promotions stay with their seller
+
+Promotion adjustments are split by scope. A promotion linked to a seller only keeps its adjustments on that seller’s items and shipping, and the workflow links the promotion to that seller’s child order. A marketplace promotion with no seller keeps its adjustments on every order it touched, and the workflow links it to no order.
+
+## What the split creates
+
+The workflow creates everything for the group in one run:
+
+1. Create the `OrderGroup` with the cart’s `customer_id` and `cart_id`.
+2. Create one `Order` per seller, with status `pending` unless the `setOrderStatus` hook says otherwise.
+3. Link each order to the group, its seller, and the cart, and link new customers to the sellers they bought from.
+4. Mirror each cart line item’s offer link onto the new order line item.
+5. Reserve inventory for offers that manage inventory, and register promotion usage.
+6. Set `completed_at` on the cart and emit `order.placed` and `order_group.created`.
+7. Authorize the payment session, split a captured payment, and refresh commission lines per order.
```ts
import { completeCartWithSplitOrdersWorkflow } from "@mercurjs/core/workflows"
const { result } = await completeCartWithSplitOrdersWorkflow(container).run({
- input: { cart_id: "cart_123" },
+ input: { cart_id: "cart_01JD8Q1234567" },
})
-// result.order_group_id -> the parent group
```
-<Note>
- Items are grouped by `item.offer.seller_id`. Sellers list against the shared
- master catalog through **offers**, so the offer, not the product, is what
- ties a line item to a seller.
-</Note>
+The run returns `{ order_group_id }`. Mercur’s cart completion route and its `processPaymentWorkflow` both run this workflow, so a webhook-driven checkout also produces a group.
-## What the split produces
+## Payment stays on the cart until capture
-For each seller in the cart the workflow, in one transaction:
+The child orders share the cart’s payment collection until the payment is captured. Medusa allows a payment collection to belong to one order only, so the split doesn’t link the orders to it. Once the payment is captured, `splitCapturedCartPaymentWorkflow` gives each order a payment collection of its own for its share. It runs inside checkout for providers that capture on authorization, and from the `payment.captured` subscriber for the rest.
-- creates a child `Order` with that seller's line items and shipping methods
-- links each order to the group (`order_group_order`) and to its seller (`order_order_seller_seller`)
-- mirrors the line-item → offer links onto the new order lines
-- splits payment captures proportionally across the child orders
-- reserves offer-scoped inventory and refreshes commission lines per order
+## One group per cart
-Once every child order is created, the workflow emits `order.placed` for the
-orders and `order_group.created` for the group.
+The split runs at most once per cart. The workflow takes a lock on the cart id, then looks for an existing group with the same `cart_id`. If it finds one, it skips the split and returns that group’s id, so a retried request or a duplicate webhook can’t create a second set of orders.
-<Tip>
- Promotions are attributed per seller: a seller-scoped promotion links only to
- that seller's child order, while marketplace-wide promotions are applied as
- cart adjustments and belong to no single order.
-</Tip>
+<Warning>
+ Child orders don’t carry the cart’s credit lines yet. The split creates every order with an empty `credit_lines` list.
+</Warning>
-## Independent child orders
+## Related
-After the split, each child order lives its own life. Fulfillment, returns, and
-refunds are handled per order, so one seller can ship while another is still
-preparing, without affecting the rest of the group. The group remains the
-single reference the shopper uses to see the purchase as a whole.
+- [Run the split from your own code](/platform/order-group/guides/split-a-cart)
+- [The workflow’s input, hooks, and events](/platform/order-group/reference/workflows#completecartwithsplitordersworkflow)
+- [How offers tie items to sellers](/platform/offer/concepts/what-is-an-offer)
+- [Commission lines per order](/platform/commission/concepts/order-commission-lines)
diff --git a/apps/docs/platform/order-group/concepts/the-order-group.mdx b/apps/docs/platform/order-group/concepts/the-order-group.mdx
index 1e359d3e5..419385f46 100644
--- a/apps/docs/platform/order-group/concepts/the-order-group.mdx
+++ b/apps/docs/platform/order-group/concepts/the-order-group.mdx
@@ -1,21 +1,16 @@
---
-title: "The order group"
+title: "What an order group is"
sidebarTitle: "The order group"
-description: "The aggregate record over a multi-seller purchase, its display id, and cart link."
+description: "The record that ties a multi-seller purchase together: its display id, its customer, its cart, and its child orders."
---
-This page covers the order group record and how it aggregates the per-seller
-orders created from a single cart.
+An order group is the record that represents one checkout across several sellers. Sellers can’t share an order, because each one ships, refunds, and gets paid on their own, so Mercur gives every seller a child order and keeps the purchase together in a group. You use the group whenever you need the shopper’s view of a purchase: an order history page, a confirmation email, or an operator’s order list.
-## Order group
+## The OrderGroup record
-An order group is the shopper-facing wrapper over a multi-seller purchase. It is
-represented by the `OrderGroup` data model (table `order_group`, id prefix
-`og`). When a cart containing offers from more than one seller is completed, the
-cart is split into one child order per seller. All of those orders are attached
-to a single group.
+The group is the `OrderGroup` data model in the Seller module, stored in the `order_group` table with the id prefix `og`. It holds four stored fields and two computed ones:
-```ts
+```ts title="packages/core/src/modules/seller/models/order-group.ts"
const OrderGroup = model.define("order_group", {
id: model.id({ prefix: "og" }).primaryKey(),
display_id: model.autoincrement(),
@@ -26,39 +21,51 @@ const OrderGroup = model.define("order_group", {
})
```
-The group carries a human-readable `display_id`, an auto-incrementing integer,
-so shoppers and operators can reference the purchase without exposing the
-internal id. `customer_id` records who placed it. `seller_count` and `total`
-are computed at read time. See [Computed totals](/platform/order-group/concepts/computed-totals).
+Each field has one job:
+
+- **`display_id`**: an auto-incrementing integer, so people can quote a purchase without the internal id
+- **`customer_id`**: the customer who completed the cart, or `null` when the cart has no customer
+- **`cart_id`**: the cart the group was created from
+- **`seller_count` and `total`**: summed from the child orders when you read the group, covered in [Computed totals](/platform/order-group/concepts/computed-totals)
<Note>
- A group is created even for a single-seller cart, so every completed
- marketplace order has exactly one parent group regardless of how many sellers
- it spans.
+ Checkout creates a group for every completed cart, even when the cart has items from one seller. Every marketplace order therefore has exactly one parent group.
</Note>
## The cart link
-Each group holds a `cart_id` pointing back to the cart it was created from. This
-is exposed as a **read-only** link to the Cart module. The cart is frozen
-(`completed_at` is set) the moment the split runs, so the reference is a
-historical record, not something you write through.
+The `cart_id` field backs a read-only link to Medusa’s Cart module, so you can expand `cart.*` from a group. Checkout sets `completed_at` on the cart in the same run that creates the group, and the cart doesn’t change after that. Treat `cart_id` as a stable pointer to the basket the shopper paid for.
```ts
-const { data: groups } = await query.graph({
+const { data: [group] } = await query.graph({
entity: "order_group",
- fields: ["id", "display_id", "cart.id", "orders.id"],
+ fields: ["id", "display_id", "cart.id", "cart.email"],
+ filters: { id: "og_01JD8Q1234567" },
})
```
-<Tip>
- Because the cart is immutable after checkout, the `cart_id` is safe to treat as
- a stable audit pointer to the exact basket the shopper paid for.
-</Tip>
+The query loads one group and the cart it came from. Because the link is read-only, you can’t create or dismiss it with `link.create`: it always follows the `cart_id` column.
## Child orders
-The group doesn't store line items itself. Those live on the child `Order`
-records, linked through the `order_group_order` table. Loading a group's
-`orders.*` gives you each seller's slice, each with its own fulfillment, payment,
-returns, and refunds.
+A group holds no line items. The items live on the child `Order` records, one per seller, connected through the `order_group_order` link table. Each child order is a regular Medusa order with its own items, shipping methods, fulfillments, returns, and refunds:
+
+- **Seller**: each child order links to the seller who fulfills it
+- **Line items**: each order line item links to the offer it was bought from
+- **Cart**: each child order also links back to the completed cart
+
+```ts
+const { data: [group] } = await query.graph({
+ entity: "order_group",
+ fields: ["id", "orders.id", "orders.seller.name", "orders.status"],
+ filters: { id: "og_01JD8Q1234567" },
+})
+```
+
+The query returns the group with each child order and the seller behind it. To go from an order to its group, query the `order_group_order` link entity by `order_id`.
+
+## Related
+
+- [How checkout splits a cart into child orders](/platform/order-group/concepts/order-splitting)
+- [How `seller_count` and `total` are computed](/platform/order-group/concepts/computed-totals)
+- [Every link around an order group](/platform/order-group/reference/links)
diff --git a/apps/docs/platform/order-group/guides/list-order-groups.mdx b/apps/docs/platform/order-group/guides/list-order-groups.mdx
index 787946f1e..473689fd4 100644
--- a/apps/docs/platform/order-group/guides/list-order-groups.mdx
+++ b/apps/docs/platform/order-group/guides/list-order-groups.mdx
@@ -1,71 +1,111 @@
---
-title: "List order groups"
+title: "List and filter order groups"
sidebarTitle: "List order groups"
-description: "Page through order groups and scope them to a seller with getOrderGroupsListWorkflow."
+description: "Page through order groups, filter them, and scope them to one seller with getOrderGroupsListWorkflow."
---
-In this guide, you'll learn how to list order groups from server code, page
-through the results, and optionally scope them to a single seller.
-
-Mercur exposes a `getOrderGroupsListWorkflow` that returns groups with their
-aggregated child orders and a total count for pagination.
-
-## Run the workflow
-
-```ts title="src/api/custom/order-groups/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { getOrderGroupsListWorkflow } from "@mercurjs/core/workflows"
-
-export async function GET(req: MedusaRequest, res: MedusaResponse) {
- const { result } = await getOrderGroupsListWorkflow(req.scope).run({
- input: {
- fields: ["id", "display_id", "total", "seller_count"],
- variables: {
- skip: 0,
- take: 20,
- order: { created_at: "DESC" },
- },
- },
- })
-
- res.json({
- order_groups: result.rows,
- count: result.metadata?.count ?? 0,
- })
-}
-```
+List order groups from server code when you build an order history, a report, or a seller-facing view of purchases.
-The workflow returns `{ rows, metadata }`, where `metadata` carries the `count`,
-`skip`, and `take` you need to drive pagination.
+## List groups in an API route
-<Note>
- Filters go inside `variables`: the group repository understands `id`,
- `customer_id`, `seller_id`, `status`, `sales_channel_id`, `created_at`,
- `updated_at`, and a free-text `q` (matched against group id and customer id).
- Order-level filters (`seller_id`, `status`, `sales_channel_id`) only decide
- which groups match. A matching group's `seller_count` and `total` still
- describe every order in the group, as covered in
- [Computed totals](/platform/order-group/concepts/computed-totals).
-</Note>
+<Steps>
+ <Step title="Run the list workflow">
+ Pass the fields you want and put filters and pagination in `variables`.
+
+ ```ts title="src/api/admin/purchases/route.ts"
+ import type {
+ MedusaRequest,
+ MedusaResponse,
+ } from "@medusajs/framework/http"
+ import { getOrderGroupsListWorkflow } from "@mercurjs/core/workflows"
+
+ export async function GET(req: MedusaRequest, res: MedusaResponse) {
+ const { result } = await getOrderGroupsListWorkflow(req.scope).run({
+ input: {
+ fields: ["id", "display_id", "total", "seller_count"],
+ variables: { skip: 0, take: 20, order: { display_id: "DESC" } },
+ },
+ })
+
+ res.json({
+ order_groups: result.rows,
+ count: result.metadata?.count ?? 0,
+ })
+ }
+ ```
+
+ The workflow returns `{ rows, metadata }`. `metadata` carries `count`, `skip`, and `take` for pagination. Every row includes its child `orders` with `payment_status` and `fulfillment_status`.
+ </Step>
+ <Step title="Add filters">
+ Put filter keys next to the pagination keys in `variables`:
+
+ ```ts
+ variables: {
+ customer_id: "cus_01JD8Q1234567",
+ payment_status: ["captured", "partially_captured"],
+ created_at: { $gte: "2026-10-01T00:00:00Z" },
+ take: 20,
+ }
+ ```
+
+ This returns the customer’s groups from October 2026 that have at least one captured or partially captured child order.
+ </Step>
+</Steps>
+
+## Filters you can use
+
+The Seller module reads groups through a custom repository that understands a fixed set of top-level keys:
+
+- **Group filters**: `id`, `customer_id`, `cart_id`, as a string or an array
+- **Order filters**: `seller_id`, `status`, `payment_status`, `sales_channel_id`, which match a group when at least one child order matches
+- **Dates**: `created_at` and `updated_at`, with `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$nin`, `$like`, `$ilike`
+- **Search**: `q`, which matches the group id or customer id, and a display id such as `#G98`, `G98`, or `98` on the group or a child order
+
+You can sort by `display_id`, `created_at`, or `updated_at`. Without an `order`, groups come back newest first.
+
+<Warning>
+ The repository ignores keys it doesn’t know, including `$and` and `$or`. Pass `id` as a plain string or array, not `{ $in: [...] }`. If you need two id constraints, intersect them yourself before you call the workflow.
+</Warning>
-## Scope to a seller
+## Scope groups to one seller
-Pass a `sellerId` to get a vendor's slice. The workflow filters each group's
-child orders down to that seller, so vendors only ever see their own orders
-within a group.
+To show a seller only their part of each purchase, filter the groups and trim their orders:
```ts
-await getOrderGroupsListWorkflow(req.scope).run({
+const sellerId = "sel_01JD8Q1234567"
+
+const { result } = await getOrderGroupsListWorkflow(req.scope).run({
input: {
- fields: ["id", "display_id"],
- variables: { seller_id: "sel_123", take: 20 },
- sellerId: "sel_123",
+ fields: ["id", "display_id", "orders.total"],
+ variables: { seller_id: sellerId, take: 20 },
+ sellerId,
},
})
```
-<Tip>
- Admin surfaces call this workflow with no `sellerId` for platform-wide
- visibility. Vendor surfaces pass the resolved seller so both the query and the
- returned child orders stay scoped to that store.
-</Tip>
+The two inputs do different jobs. `variables.seller_id` keeps only the groups where the seller has an order. `sellerId` removes the other sellers’ orders from each returned group. `sellerId` also accepts an array of seller ids.
+
+<Note>
+ `seller_count` and `total` still describe the whole group when you scope it. Sum the trimmed `orders` to get the seller’s share.
+</Note>
+
+## List groups without child orders
+
+When you only need group rows, call the Seller module service. It skips the child order expansion and the status work:
+
+```ts
+const sellerModuleService = req.scope.resolve(MercurModules.SELLER)
+
+const [groups, count] = await sellerModuleService.listAndCountOrderGroups(
+ { customer_id: "cus_01JD8Q1234567" },
+ { take: 20, order: { created_at: "DESC" } }
+)
+```
+
+`MercurModules` comes from `@mercurjs/types`. The rows still include the computed `seller_count` and `total`.
+
+## Next steps
+
+- [Retrieve one group with its child orders](/platform/order-group/guides/retrieve-an-order-group)
+- [Why filters don’t change the totals](/platform/order-group/concepts/computed-totals#filters-pick-groups-not-orders)
+- [`getOrderGroupsListWorkflow` reference](/platform/order-group/reference/workflows#getordergroupslistworkflow)
diff --git a/apps/docs/platform/order-group/guides/retrieve-an-order-group.mdx b/apps/docs/platform/order-group/guides/retrieve-an-order-group.mdx
index 1facc5e7c..d975fbf87 100644
--- a/apps/docs/platform/order-group/guides/retrieve-an-order-group.mdx
+++ b/apps/docs/platform/order-group/guides/retrieve-an-order-group.mdx
@@ -1,63 +1,114 @@
---
-title: "Retrieve an order group"
+title: "Retrieve an order group with its child orders"
sidebarTitle: "Retrieve an order group"
-description: "Load an order group and its aggregated child orders with getOrderGroupDetailWorkflow."
+description: "Load one order group, its child orders, and their payment and fulfillment status with getOrderGroupDetailWorkflow."
---
-In this guide, you'll learn how to load a single order group together with its
-child orders from your own server code.
+Load one order group from server code when you build an order page, an email, or an export that needs the whole purchase.
-Mercur exposes a `getOrderGroupDetailWorkflow` that fetches the group, expands
-its child orders, and derives each order's payment and fulfillment status. Run it
-from any place that has access to the Medusa container.
+## Before you begin
-## Run the workflow
+You need the following:
-```ts title="src/api/custom/order-group/[id]/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { getOrderGroupDetailWorkflow } from "@mercurjs/core/workflows"
+- **A completed multi-seller cart**: at least one order group in your database, for example from a storefront checkout
+- **The group id**: an id with the `og` prefix, such as `og_01JD8Q1234567`
-export async function GET(req: MedusaRequest, res: MedusaResponse) {
- const { result: order_group } = await getOrderGroupDetailWorkflow(
- req.scope
- ).run({
- input: {
- order_group_id: req.params.id,
- fields: ["id", "display_id", "total", "seller_count", "cart_id"],
- },
- })
+## Load the group in an API route
- res.json({ order_group })
-}
-```
+<Steps>
+ <Step title="Create the route">
+ Run `getOrderGroupDetailWorkflow` with the group id and the fields you want back.
+
+ ```ts title="src/api/admin/purchases/[id]/route.ts"
+ import type {
+ MedusaRequest,
+ MedusaResponse,
+ } from "@medusajs/framework/http"
+ import { getOrderGroupDetailWorkflow } from "@mercurjs/core/workflows"
+
+ export async function GET(req: MedusaRequest, res: MedusaResponse) {
+ const { result: order_group } = await getOrderGroupDetailWorkflow(
+ req.scope
+ ).run({
+ input: {
+ order_group_id: req.params.id,
+ fields: ["id", "display_id", "total", "seller_count", "cart_id"],
+ },
+ })
+
+ res.json({ order_group })
+ }
+ ```
+
+ The workflow adds the child order fields it needs on top of yours, so `order_group.orders` is always populated. Each order carries `payment_status` and `fulfillment_status`.
+ </Step>
+ <Step title="Add the child order fields you display">
+ Ask for extra order fields with the `orders.` prefix.
+
+ ```ts
+ const fields = [
+ "id",
+ "display_id",
+ "total",
+ "orders.display_id",
+ "orders.total",
+ "orders.seller.name",
+ ]
+ ```
-The workflow always expands the group's child orders regardless of the `fields`
-you pass, so `order_group.orders` is populated with each seller's slice.
+ The workflow always returns `orders.id`, `orders.status`, `orders.currency_code`, and `orders.items.*`. Everything else on the order comes from your list.
+ </Step>
+ <Step title="Handle a missing group">
+ The workflow throws a `NOT_FOUND` error when no group has the id. Inside an API route, Medusa’s error handler turns it into a 404 response, so you don’t need to check the result.
+ </Step>
+</Steps>
+
+## Keep payment collections and fulfillments in the response
+
+The workflow loads every child order’s payment collections and fulfillments to compute the statuses, then drops them from the result. To keep them, include a field that contains `payment_collections` or `fulfillments`:
+
+```ts
+fields: [
+ "id",
+ "orders.payment_collections.id",
+ "orders.fulfillments.id",
+]
+```
-<Note>
- The workflow only fetches heavy relations when you ask for them: include a
- `payment_collections` field to get per-order `payment_status`, and a
- `fulfillments` field to get `fulfillment_status`. Otherwise those collections
- are stripped from the response to keep it lean.
-</Note>
+Before the payment is captured, `payment_collections` holds the cart’s shared collection. After capture, it holds the order’s own collection. Fields that start with `orders.cart` keep the child orders’ `cart` in the result too.
## Follow the cart link
-The group's read-only `cart_id` points back to the immutable cart it came from.
-Expand it through the module link when you need the original basket:
+Expand the read-only cart link to get the basket the group came from:
```ts
-await getOrderGroupDetailWorkflow(req.scope).run({
- input: {
- order_group_id: req.params.id,
- fields: ["id", "cart.id", "cart.email", "orders.id", "orders.total"],
- },
+fields: ["id", "cart.id", "cart.email", "cart.completed_at"]
+```
+
+The cart is completed and frozen, so these values match what the shopper paid for.
+
+## Find the group for an order
+
+When you start from a child order id, look up the group through the `order_group_order` link entity, then run the workflow with its id:
+
+```ts
+const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
+
+const { data: [link] } = await query.graph({
+ entity: "order_group_order",
+ fields: ["order_group_id"],
+ filters: { order_id: "order_01JD8Q1234568" },
})
```
+`ContainerRegistrationKeys` comes from `@medusajs/framework/utils`. `link` is `undefined` when the order isn’t part of a group.
+
<Tip>
- Prefer the workflow over reading the record directly. It does the child-order
- status aggregation for you. The raw
- [service method](/platform/order-group/reference/service) returns only the
- group row and its computed totals.
+ Use the workflow rather than `retrieveOrderGroup` when you need child orders. The service method returns the group row and its computed totals only, without orders or statuses.
</Tip>
+
+## Next steps
+
+- [List and filter order groups](/platform/order-group/guides/list-order-groups)
+- [How the child order statuses are derived](/platform/order-group/concepts/computed-totals#child-order-statuses)
+- [`getOrderGroupDetailWorkflow` reference](/platform/order-group/reference/workflows#getordergroupdetailworkflow)
diff --git a/apps/docs/platform/order-group/guides/split-a-cart.mdx b/apps/docs/platform/order-group/guides/split-a-cart.mdx
index 704e85fe4..abe9d2835 100644
--- a/apps/docs/platform/order-group/guides/split-a-cart.mdx
+++ b/apps/docs/platform/order-group/guides/split-a-cart.mdx
@@ -1,58 +1,133 @@
---
-title: "Split a cart into orders"
+title: "Split a cart into an order group"
sidebarTitle: "Split a cart"
-description: "Complete a multi-seller cart into a group of per-seller orders with completeCartWithSplitOrdersWorkflow."
+description: "Run completeCartWithSplitOrdersWorkflow from your own code and change the split with its validate and setOrderStatus hooks."
---
-In this guide, you'll learn how the checkout split works and how to run it from
-your own server code, such as a custom complete-cart route.
+Run the checkout split yourself when you build a custom completion flow, or hook into it when you need to block a checkout or set the initial status of each seller’s order.
-Mercur replaces Medusa's single-order checkout with
-`completeCartWithSplitOrdersWorkflow`. It takes a cart that may hold offers from
-several sellers, creates one order per seller, and wraps them in an `OrderGroup`.
+## Before you begin
-## Run the workflow
+You need the following:
-```ts title="src/api/store/carts/[id]/complete/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { completeCartWithSplitOrdersWorkflow } from "@mercurjs/core/workflows"
+- **A cart ready to complete**: items bought through offers, a shipping method for each seller that ships, and a payment session
+- **Mercur’s cart completion in place**: Mercur’s cart completion route already runs this workflow, so you only need your own route for a custom flow
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
- const { result } = await completeCartWithSplitOrdersWorkflow(req.scope).run({
- input: { cart_id: req.params.id },
- })
+## Complete a cart from a custom route
+
+<Steps>
+ <Step title="Run the workflow">
+ Call `completeCartWithSplitOrdersWorkflow` with the cart id. Set `throwOnError: false` so you can handle payment errors yourself.
+
+ ```ts title="src/api/store/carts/[id]/place/route.ts"
+ import type {
+ MedusaRequest,
+ MedusaResponse,
+ } from "@medusajs/framework/http"
+ import {
+ completeCartWithSplitOrdersWorkflow,
+ } from "@mercurjs/core/workflows"
+
+ export async function POST(req: MedusaRequest, res: MedusaResponse) {
+ const { result, errors } = await completeCartWithSplitOrdersWorkflow(
+ req.scope
+ ).run({
+ input: { cart_id: req.params.id },
+ throwOnError: false,
+ })
+
+ if (errors?.[0]) {
+ throw errors[0].error
+ }
+
+ res.json({ order_group_id: result.order_group_id })
+ }
+ ```
+
+ The workflow returns `{ order_group_id }`. It runs once per cart: a second call for the same cart returns the existing group’s id.
+ </Step>
+ <Step title="Return the group to the shopper">
+ Load the group with `query.graph` and send it back instead of the bare id:
+
+ ```ts
+ const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
+
+ const { data: [order_group] } = await query.graph({
+ entity: "order_group",
+ fields: ["id", "display_id", "total", "orders.id", "orders.total"],
+ filters: { id: result.order_group_id },
+ })
+ ```
+
+ `ContainerRegistrationKeys` comes from `@medusajs/framework/utils`.
+ </Step>
+</Steps>
+
+## Handle a failed payment authorization
+
+The workflow authorizes the payment session after it creates the orders. If authorization fails, the workflow rolls back: it deletes the group, and Medusa’s steps undo the orders, links, and reservations. Mercur’s own route answers `PAYMENT_AUTHORIZATION_ERROR` and `PAYMENT_REQUIRES_MORE_ERROR` with a `200` that carries the cart and the error, so the storefront can retry payment. Do the same in a custom route:
+
+```ts
+import { MedusaError } from "@medusajs/framework/utils"
- res.json({ order_group_id: result.order_group_id })
+const retryable: string[] = [
+ MedusaError.Types.PAYMENT_AUTHORIZATION_ERROR,
+ MedusaError.Types.PAYMENT_REQUIRES_MORE_ERROR,
+]
+
+if (errors?.[0] && retryable.includes(errors[0].error?.type)) {
+ res.json({ type: "cart", error: errors[0].error.message })
+ return
}
```
-The workflow is idempotent per cart: if a group already exists for the cart it
-returns the existing `order_group_id` instead of splitting again. It acquires a
-lock on the cart id for the duration of the split so concurrent completions can't
-create duplicate orders.
+Throw every other error so Medusa’s error handler responds with the matching status.
+
+## Block a checkout with the validate hook
+
+The `validate` hook runs before the split and receives the workflow `input` and the `cart`. Throw to stop the checkout:
+
+```ts title="src/workflows/hooks/validate-split-cart.ts"
+import { MedusaError } from "@medusajs/framework/utils"
+import { completeCartWithSplitOrdersWorkflow } from "@mercurjs/core/workflows"
+
+completeCartWithSplitOrdersWorkflow.hooks.validate(async ({ cart }) => {
+ if (!cart.email) {
+ throw new MedusaError(
+ MedusaError.Types.INVALID_DATA,
+ "Add an email address before you complete the cart"
+ )
+ }
+})
+```
+
+The hook runs on every cart completion, including completions started by a payment webhook through `processPaymentWorkflow`.
+
+## Set the initial order status with setOrderStatus
-<Note>
- Line items are grouped by `item.offer.seller_id`. Sellers sell against the
- shared master catalog through **offers**, so a line item's seller comes from
- its offer, never from product ownership.
-</Note>
+Child orders start as `pending`. Return a status from the `setOrderStatus` hook to change that, for example when sellers must accept an order before they fulfill it:
+
+```ts title="src/workflows/hooks/set-split-order-status.ts"
+import { OrderStatus } from "@medusajs/framework/utils"
+import { StepResponse } from "@medusajs/framework/workflows-sdk"
+import { completeCartWithSplitOrdersWorkflow } from "@mercurjs/core/workflows"
+
+completeCartWithSplitOrdersWorkflow.hooks.setOrderStatus(async () => {
+ return new StepResponse({
+ status: OrderStatus.REQUIRES_ACTION,
+ status_by_seller_id: { sel_01JD8Q1234567: OrderStatus.PENDING },
+ })
+})
+```
-## What happens during the split
+`status` applies to every child order. `status_by_seller_id` overrides it for the sellers you list. Return nothing to keep `pending`.
-For the cart, the workflow validates payments and per-seller shipping, then in a
-single transaction:
+## React to the new group
-- creates the parent `OrderGroup` (`customer_id`, `cart_id`)
-- creates one child `Order` per seller from that seller's items and shipping
-- links each order to the group, its seller, and the originating cart
-- mirrors line-item → offer links, reserves offer inventory, and splits payment captures proportionally
-- refreshes commission lines per order and marks the cart `completed_at`
+The split emits `order_group.created` with the group id, and `order.placed` once for each child order. Subscribe to the first for purchase-level work, such as a single confirmation email, and to the second for per-seller work. The [event reference](/platform/order-group/reference/events) has a subscriber example.
-Finally it emits `order.placed` for the created orders and `order_group.created`
-for the group.
+## Next steps
-<Tip>
- The workflow exposes hooks `validate`, `beforePaymentAuthorization`, and
- `orderGroupCreated`, so you can inject marketplace-specific logic around the
- split without forking it.
-</Tip>
+- [How the split assigns items, shipping, and promotions](/platform/order-group/concepts/order-splitting)
+- [`completeCartWithSplitOrdersWorkflow` reference](/platform/order-group/reference/workflows#completecartwithsplitordersworkflow)
+- [Retrieve the new group](/platform/order-group/guides/retrieve-an-order-group)
diff --git a/apps/docs/platform/order-group/overview.mdx b/apps/docs/platform/order-group/overview.mdx
index d9db6d274..0c00ad2b8 100644
--- a/apps/docs/platform/order-group/overview.mdx
+++ b/apps/docs/platform/order-group/overview.mdx
@@ -1,83 +1,93 @@
---
-title: "Order Group"
+title: "Order groups"
sidebarTitle: "Overview"
-description: "Wrap a multi-seller cart into one shopper-facing order made of independent per-seller orders."
+description: "Turn a cart with items from several sellers into per-seller orders under one group the shopper can track."
---
-Use Order Groups to turn a single customer cart that spans multiple sellers into
-one coherent order for the shopper.
+Use order groups to give the shopper one purchase while each seller gets an order of their own.
-A marketplace cart can contain offers from several sellers at once. On checkout,
-Mercur splits that cart into one child order per seller and wraps them in an
-**Order Group**. This is the aggregate the shopper sees as "their order". Each
-child order is then fulfilled, returned, and refunded independently, while the
-group gives you a single handle over the whole purchase.
+A marketplace cart can hold offers from several sellers. At checkout, Mercur creates one child order per seller and wraps them in an order group. The group is the record the shopper sees as “my order”, while each seller fulfills, returns, and refunds their own child order. The group stores almost nothing itself: its seller count and total are summed from the child orders every time you read it.
+
+<img className="block dark:hidden" src="/images/figures/order-group-overview-light.svg" alt="The order_group record og_01JD8Q1234567 in front, with display_id 98, its customer and read-only cart link, and computed seller_count 2 and total 87.00. Behind it, the order_group_order link lists the two child orders it sums: 47.00 for ACME and 40.00 for GLOBEX." />
+<img className="hidden dark:block" src="/images/figures/order-group-overview-dark.svg" alt="The order_group record og_01JD8Q1234567 in front, with display_id 98, its customer and read-only cart link, and computed seller_count 2 and total 87.00. Behind it, the order_group_order link lists the two child orders it sums: 47.00 for ACME and 40.00 for GLOBEX." />
<Note>
- An order group is the `OrderGroup` entity. It lives in the **Seller module**
- (id prefix `og`), not a module of its own. There is no `ORDER_GROUP` module
- key. Resolve its service through `MercurModules.SELLER`.
+ An order group is the `OrderGroup` data model (id prefix `og`). It belongs to the Seller module, not a module of its own, so there is no `ORDER_GROUP` key. Resolve its service with `MercurModules.SELLER`.
</Note>
## Key features
-- **Multi-seller checkout:** one cart with offers from many sellers becomes one group of per-seller orders.
-- **Human-readable id:** an auto-incrementing `display_id` the shopper and operator can reference.
-- **Immutable cart link:** a read-only `cart_id` back to the originating cart. Carts are frozen after checkout.
-- **Computed totals:** `seller_count` and `total` are derived at query time, never stored.
-- **Independent child orders:** fulfillment, returns, and refunds happen per seller order.
-- **Scoped visibility:** admins see every group platform-wide. Vendors see only their slice.
+Order groups cover a multi-seller purchase from checkout to the order history:
+
+- **Split checkout**: `completeCartWithSplitOrdersWorkflow` turns one cart into one order per seller under a single group
+- **One group per cart**: completing the same cart twice returns the existing group instead of splitting again
+- **Readable reference**: an auto-incrementing `display_id` that shoppers and operators can quote
+- **Frozen cart link**: a read-only `cart_id` that points at the completed cart
+- **Live totals**: `seller_count` and `total` are computed from the child orders at query time, never stored
+- **Derived child statuses**: the read workflows add `payment_status` and `fulfillment_status` to every child order
+- **Seller scoping**: the list workflow can trim each group down to one seller’s orders
+
+## How it works
+
+A group comes to life when a cart completes:
+
+1. The shopper completes a cart that holds offers from ACME and GLOBEX.
+2. `completeCartWithSplitOrdersWorkflow` groups the line items by `item.offer.seller_id`.
+3. It creates one `OrderGroup` and one child `Order` per seller, then links them.
+4. It authorizes the cart’s payment and refreshes commission lines for each order.
+5. It emits `order.placed` for each child order and `order_group.created` for the group.
+6. When you read the group, the Seller module sums its child orders into `seller_count` and `total`.
## Get started
-Learn how the domain fits together.
+Learn how the group, the split, and the computed totals fit together.
<CardGroup cols={2}>
<Card title="The order group" icon="layer-group" href="/platform/order-group/concepts/the-order-group">
- The aggregate entity, its `display_id`, and the read-only cart link.
+ The record over a multi-seller purchase, its `display_id`, and the cart link.
</Card>
<Card title="Order splitting" icon="scissors" href="/platform/order-group/concepts/order-splitting">
- How a multi-seller cart is split into per-seller child orders.
+ How checkout turns one cart into one order per seller.
</Card>
<Card title="Computed totals" icon="calculator" href="/platform/order-group/concepts/computed-totals">
- Why `seller_count` and `total` are calculated at query time.
+ Where `seller_count`, `total`, and child order statuses come from.
</Card>
</CardGroup>
## Examples
-Build against Order Groups in your own code.
+Build against order groups in your own server code.
<CardGroup cols={2}>
<Card title="Retrieve an order group" icon="magnifying-glass" href="/platform/order-group/guides/retrieve-an-order-group">
- Load a group and its aggregated child orders.
+ Load one group with its child orders and their statuses.
</Card>
<Card title="List order groups" icon="list" href="/platform/order-group/guides/list-order-groups">
- Page through groups, optionally scoped to a seller.
+ Filter, page, and scope groups to a seller.
</Card>
<Card title="Split a cart" icon="scissors" href="/platform/order-group/guides/split-a-cart">
- Complete a multi-seller cart into a group of orders.
+ Complete a cart into a group and hook into the split.
</Card>
</CardGroup>
## Resources
-Data models, links, workflows, service methods, and events for Order Groups.
+The data model, links, workflows, service methods, and events behind order groups.
<CardGroup cols={2}>
<Card title="Data models" icon="table" href="/platform/order-group/reference/data-models">
- The `OrderGroup` entity and its fields.
+ The `OrderGroup` model, its fields, and indexes.
</Card>
<Card title="Links" icon="link" href="/platform/order-group/reference/links">
- How order groups link to carts, orders, sellers, and offers.
+ How a group connects to its cart, orders, sellers, and offers.
</Card>
<Card title="Workflows" icon="diagram-project" href="/platform/order-group/reference/workflows">
- Splitting, retrieving, and listing order groups.
+ The checkout split, the read workflows, and their hooks.
</Card>
<Card title="Service" icon="gear" href="/platform/order-group/reference/service">
- Seller module methods for working with groups directly.
+ Seller module methods for order group records.
</Card>
<Card title="Events" icon="bell" href="/platform/order-group/reference/events">
- Events emitted as order groups are created.
+ The events emitted when a cart splits into a group.
</Card>
</CardGroup>
diff --git a/apps/docs/platform/order-group/reference/data-models.mdx b/apps/docs/platform/order-group/reference/data-models.mdx
index 530dddcdb..bab2faa31 100644
--- a/apps/docs/platform/order-group/reference/data-models.mdx
+++ b/apps/docs/platform/order-group/reference/data-models.mdx
@@ -1,40 +1,57 @@
---
-title: "Data models"
+title: "Order group data models"
sidebarTitle: "Data models"
-description: "The data model owned by the Order Group domain."
+description: "Fields, indexes, and relations of the OrderGroup data model in the Seller module."
---
-The Order Group domain is owned by the **Seller module**. There is no separate
-order-group module. This reference lists its data model and fields. For the full
-module overview, see the [Order Group overview](/platform/order-group/overview).
+Order groups have one data model, `OrderGroup`, registered on the Seller module. There is no separate order group module: resolve it with `MercurModules.SELLER`. The model is defined in `packages/core/src/modules/seller/models/order-group.ts`, and its record type is `OrderGroupDTO` from `@mercurjs/types`.
## OrderGroup
-Table `order_group`, id prefix `og`. The aggregate over the per-seller orders
-created from a single cart.
+The parent record over the child orders created from one completed cart. Table `order_group`, id prefix `og`.
-| Field | Type | Notes |
+| Field | Type | Description |
| --- | --- | --- |
-| `id` | text | Primary key (prefix `og`) |
-| `display_id` | integer | Auto-incrementing, human-readable reference |
-| `customer_id` | text | Nullable; who placed the group |
-| `cart_id` | text | The originating cart (read-only link to Cart) |
-| `seller_count` | number | **Computed**: distinct sellers with a child order |
-| `total` | bigNumber | **Computed**: sum of child order totals |
-| `created_at` / `updated_at` | dateTime | Timestamps |
-| `deleted_at` | dateTime | Nullable; soft-delete marker |
-
-Relations: `orders` (one-to-many through the `order_group_order` link table),
-`cart` (read-only, via `cart_id`).
-
-<Note>
- `seller_count` and `total` are marked `computed()`. They hold no value on the
- row and are aggregated from the group's child orders each time it's read. See
- [Computed totals](/platform/order-group/concepts/computed-totals).
-</Note>
-
-<Warning>
- The `cart_id` link is **read-only**. The cart is frozen (`completed_at` is set)
- the moment the split runs, so it's a historical reference and can't be written
- through the group.
-</Warning>
+| `id` | `text` | Primary key with the prefix `og` |
+| `display_id` | `autoincrement` | Integer assigned by the database in creation order, for people to quote |
+| `customer_id` | `text`, nullable | Id of the customer on the completed cart, or `null` when the cart had none |
+| `cart_id` | `text` | Id of the completed cart; backs the read-only link to the Cart module |
+| `seller_count` | `number`, computed | Number of distinct sellers across the group’s child orders; not stored |
+| `total` | `bigNumber`, computed | Sum of the child orders’ `current_order_total`; not stored, returned as a `number` |
+| `created_at` | `dateTime` | Set when the record is created |
+| `updated_at` | `dateTime` | Set when the record changes |
+| `deleted_at` | `dateTime`, nullable | Soft-delete marker |
+
+The computed fields are filled by the Seller module’s `OrderGroupRepository` on every read. See [Computed totals](/platform/order-group/concepts/computed-totals).
+
+### Indexes
+
+The model declares three partial indexes, each limited to rows where `deleted_at IS NULL`:
+
+| Index | Columns | Serves |
+| --- | --- | --- |
+| `IDX_order_group_cart_id` | `cart_id` | The one-group-per-cart lookup at checkout |
+| `IDX_order_group_customer_id_created_at` | `customer_id`, `created_at` | A customer’s order history, newest first |
+| `IDX_order_group_created_at` | `created_at` | The default newest-first list |
+
+### Relations
+
+`OrderGroup` has no relations inside the Seller module. It reaches other modules through module links:
+
+| Alias | Target | Cardinality | Link |
+| --- | --- | --- | --- |
+| `orders` | `Order` (Order module) | One group to many orders | `order_group_order` |
+| `cart` | `Cart` (Cart module) | One group to one cart, read-only | `cart_id` field |
+
+See [Links](/platform/order-group/reference/links) for the definitions and `query.graph` examples.
+
+## Mutation types
+
+`@mercurjs/types` exports the input shapes for the generated create and update methods:
+
+| Type | Fields |
+| --- | --- |
+| `CreateOrderGroupDTO` | `cart_id: string`, `customer_id?: string \| null` |
+| `UpdateOrderGroupDTO` | `id: string`, `customer_id?: string`, `cart_id?: string` |
+
+Checkout creates every group through `createOrderGroupStep`. Mercur never updates a group after that.
diff --git a/apps/docs/platform/order-group/reference/events.mdx b/apps/docs/platform/order-group/reference/events.mdx
index c22bdde68..9598dcc0b 100644
--- a/apps/docs/platform/order-group/reference/events.mdx
+++ b/apps/docs/platform/order-group/reference/events.mdx
@@ -1,22 +1,40 @@
---
-title: "Event reference"
+title: "Order group events"
sidebarTitle: "Events"
-description: "Events emitted by the Order Group domain, for subscribers and side effects."
+description: "The events emitted when checkout splits a cart into an order group, with their payloads and a subscriber example."
---
-The Order Group domain emits an event when a group is created during checkout.
-Subscribe to it to run side effects such as sending an order confirmation,
-syncing external systems, or kicking off follow-up workflows, instead of polling.
+Order groups emit one event of their own, `order_group.created`, when checkout splits a cart. The same run emits Medusa’s `order.placed` for every child order. Subscribe to these events to send confirmations, sync external systems, or start follow-up workflows.
+
+## Events
+
+Both events come from `completeCartWithSplitOrdersWorkflow`. Neither is emitted when the workflow returns an existing group for a cart that was already split.
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `order_group.created` | Checkout creates a group for a completed cart | `{ id }`, the group id |
+| `order.placed` | Checkout creates a child order, once per seller | `{ id }`, the order id |
+
+The event name is available as `OrderGroupWorkflowEvents.CREATED` from `@mercurjs/core/workflows`. `order.placed` is Medusa’s `OrderWorkflowEvents.PLACED` from `@medusajs/framework/utils`.
+
+## Subscribe to a new group
+
+Use `order_group.created` for work that concerns the whole purchase, such as one confirmation email for a checkout that spans three sellers:
```ts title="src/subscribers/order-group-created.ts"
import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+import { getOrderGroupDetailWorkflow } from "@mercurjs/core/workflows"
export default async function orderGroupCreatedHandler({
event,
container,
}: SubscriberArgs<{ id: string }>) {
- const orderGroupId = event.data.id
- // ...send a confirmation, notify sellers, etc.
+ const { result: group } = await getOrderGroupDetailWorkflow(container).run({
+ input: {
+ order_group_id: event.data.id,
+ fields: ["id", "display_id", "total", "orders.seller.name"],
+ },
+ })
}
export const config: SubscriberConfig = {
@@ -24,14 +42,8 @@ export const config: SubscriberConfig = {
}
```
-## Order group events
-
-| Event | Emitted when | Payload |
-| --- | --- | --- |
-| `order_group.created` | A cart is split and its parent group is created | `{ id }` |
+The subscriber loads the new group with its child orders and sellers, ready to pass to your notification provider.
-<Note>
- The same checkout split also emits `order.placed` for each child order created.
- Subscribe to `order.placed` when you need to react per seller order, and to
- `order_group.created` when you need the purchase as a whole.
-</Note>
+<Tip>
+ Subscribe to `order.placed` instead when the work belongs to one seller, such as notifying that seller of a new order. Each child order fires its own event.
+</Tip>
diff --git a/apps/docs/platform/order-group/reference/links.mdx b/apps/docs/platform/order-group/reference/links.mdx
index 3deb66963..83004664f 100644
--- a/apps/docs/platform/order-group/reference/links.mdx
+++ b/apps/docs/platform/order-group/reference/links.mdx
@@ -1,45 +1,106 @@
---
-title: "Links to other modules"
+title: "Order group links"
sidebarTitle: "Links"
-description: "How the Order Group domain links to carts, orders, sellers, and offers."
+description: "The module links that connect an order group to its cart and child orders, and its orders to sellers and offers."
---
-Modules in Mercur never reference each other directly. They connect through
-**module links**. The `OrderGroup` entity (owned by the Seller module) sits at
-the center of a completed multi-seller purchase, linking the cart it came from to
-the per-seller orders it produced. Once a link is defined, you retrieve related
-records with `query.graph` using the link alias.
+Mercur modules never reference each other directly, so an order group reaches carts and orders through module links. Two links start at the group. Two more, on the child orders, connect each order to its seller and each order line item to its offer. All four are defined in `packages/core/src/links/`, and checkout creates their rows when it splits a cart.
+
+## Order group to order
+
+Connects a group to its child orders, one per seller.
+
+| | |
+| --- | --- |
+| **Sides** | `OrderGroup` (Seller module) and `Order` (Order module) |
+| **Cardinality** | One group to many orders |
+| **Table** | `order_group_order` |
+| **Defined in** | `order-group-order-link.ts` |
```ts
-const { data: groups } = await query.graph({
+const { data: [group] } = await query.graph({
entity: "order_group",
- fields: ["id", "display_id", "cart.id", "orders.id", "orders.total"],
+ fields: ["id", "display_id", "orders.id", "orders.total"],
+ filters: { id: "og_01JD8Q1234567" },
+})
+```
+
+To go from an order to its group, query the link entity directly:
+
+```ts
+const { data: [row] } = await query.graph({
+ entity: "order_group_order",
+ fields: ["order_group_id"],
+ filters: { order_id: "order_01JD8Q1234568" },
})
```
-## Group links
+## Order group to cart
-| Linked module | Relationship |
+Exposes the completed cart a group was created from. The link is read-only: it reads the group’s `cart_id` column and has no table of its own.
+
+| | |
| --- | --- |
-| **Cart** | A group references the one cart it was created from (`order_group.cart_id`, **read-only**). Carts are immutable after checkout. |
-| **Order** | A group has many child orders, one per seller, through the `order_group_order` table. |
+| **Sides** | `OrderGroup.cart_id` (Seller module) and `Cart` (Cart module) |
+| **Cardinality** | One group to one cart |
+| **Table** | None, `readOnly: true` |
+| **Defined in** | `order-group-cart-link.ts` |
-## Order links
+```ts
+const { data: [group] } = await query.graph({
+ entity: "order_group",
+ fields: ["id", "cart.id", "cart.email", "cart.completed_at"],
+ filters: { id: "og_01JD8Q1234567" },
+})
+```
-The child orders produced by the split carry their own marketplace links:
+You can’t create or dismiss this link with `link.create` or `link.dismiss`. It changes only if `cart_id` changes, and Mercur never updates it.
-| Linked module | Relationship |
+## Order to seller
+
+Connects each child order to the seller who fulfills it.
+
+| | |
| --- | --- |
-| **Seller** | Each order belongs to one seller (`order_order_seller_seller`); a seller has many orders. |
-| **Offer** | Each order line item links to the offer it was purchased from (`order_line_item` → `offer`, list on the line-item side so one offer can back many order lines). |
-
-<Note>
- The `cart_id` link is resolved from the field on the group and can't be written
- through the link itself. The split sets it once, at creation.
-</Note>
-
-<Tip>
- To scope a group to a single seller, filter its child orders by
- `orders.seller.id`. The list workflow does exactly this when you pass a
- `sellerId`. See [List order groups](/platform/order-group/guides/list-order-groups).
-</Tip>
+| **Sides** | `Order` (Order module) and `Seller` (Seller module) |
+| **Cardinality** | Many orders to one seller |
+| **Link entity** | `order_seller` |
+| **Defined in** | `order-seller-link.ts` |
+
+```ts
+const { data: [group] } = await query.graph({
+ entity: "order_group",
+ fields: ["id", "orders.id", "orders.seller.id", "orders.seller.name"],
+ filters: { id: "og_01JD8Q1234567" },
+})
+```
+
+`getOrderGroupsListWorkflow` reads `orders.seller.id` to trim each group to one seller when you pass `sellerId`.
+
+## Order line item to offer
+
+Records which offer each order line item was bought from. Checkout copies it from the matching cart line item’s offer link.
+
+| | |
+| --- | --- |
+| **Sides** | `OrderLineItem` (Order module) and `Offer` (Offer module) |
+| **Cardinality** | Many order line items to one offer |
+| **Defined in** | `order-line-item-offer-link.ts` |
+
+```ts
+const { data: [group] } = await query.graph({
+ entity: "order_group",
+ fields: ["id", "orders.items.id", "orders.items.offer.id"],
+ filters: { id: "og_01JD8Q1234567" },
+})
+```
+
+The line item side is a list, so one offer can back line items in any number of orders and groups.
+
+## Links checkout creates for each order
+
+Besides the links above, `completeCartWithSplitOrdersWorkflow` creates these rows for every child order:
+
+- **Order to cart**: Medusa’s own link from each child order to the completed cart
+- **Order to promotion**: for each promotion owned by the order’s seller
+- **Seller to customer**: when the customer hasn’t bought from that seller before
diff --git a/apps/docs/platform/order-group/reference/service.mdx b/apps/docs/platform/order-group/reference/service.mdx
index beab02695..512a3fb3c 100644
--- a/apps/docs/platform/order-group/reference/service.mdx
+++ b/apps/docs/platform/order-group/reference/service.mdx
@@ -1,50 +1,74 @@
---
-title: "Service reference"
+title: "Order group service methods"
sidebarTitle: "Service"
-description: "The Seller module service and its methods for working with order group records directly."
+description: "Seller module service methods for OrderGroup records, the filters they accept, and how they compute totals."
---
-Order groups are owned by the **Seller module**, so you resolve the same service
-you'd use for stores. Resolve it from the Medusa container to read and write
-`OrderGroup` records directly, without going through a workflow. Use it inside
-custom services, subscribers, or scheduled jobs.
+Order group records live in the Seller module, so you read and write them through the Seller module service. Use it in subscribers, scheduled jobs, and custom steps when you need group rows without child orders. For child orders and their statuses, use the [read workflows](/platform/order-group/reference/workflows) instead.
+
+## Resolve the service
+
+Resolve the Seller module from the Medusa container with `MercurModules.SELLER`. There is no `ORDER_GROUP` module key.
```ts
import { MercurModules } from "@mercurjs/types"
const sellerModuleService = container.resolve(MercurModules.SELLER)
-const [orderGroups, count] = await sellerModuleService.listAndCountOrderGroups({
- customer_id: "cus_123",
-})
+const [groups, count] = await sellerModuleService.listAndCountOrderGroups(
+ { customer_id: "cus_01JD8Q1234567" },
+ { take: 20 }
+)
```
-<Note>
- There is no `ORDER_GROUP` module key. The `OrderGroup` model is registered on
- the Seller module, so its service methods live on `MercurModules.SELLER`.
-</Note>
+The call returns the customer’s 20 newest groups and the total number of groups that match.
-## Generated methods
+## Read methods
-The `OrderGroup` model gets the standard set of auto-generated methods:
+The Seller module overrides the generated read methods for `OrderGroup`. All three run one SQL query through `OrderGroupRepository`, which fills `seller_count` and `total`:
-| Method | Description |
+| Method | Returns |
| --- | --- |
-| `createOrderGroups(data)` | Create one or more order groups |
-| `retrieveOrderGroup(id, config?)` | Retrieve a group by id (with computed `seller_count` / `total`) |
-| `listOrderGroups(filters?, config?)` | List groups matching filters |
-| `listAndCountOrderGroups(filters?, config?)` | List groups with a total count |
-| `updateOrderGroups(data)` | Update one or more groups |
-| `deleteOrderGroups(ids)` | Delete one or more groups |
-
-The list, count, and retrieve methods run through the module's order-group
-repository, which aggregates each group's child orders to fill in the computed
-`seller_count` and `total`. Supported filters include `id`, `customer_id`,
-`seller_id`, `status`, `sales_channel_id`, `created_at`, `updated_at`, and `q`.
+| `listOrderGroups(filters?, config?, sharedContext?)` | `Promise<OrderGroupDTO[]>` |
+| `listAndCountOrderGroups(filters?, config?, sharedContext?)` | `Promise<[OrderGroupDTO[], number]>` |
+| `retrieveOrderGroup(id, config?, sharedContext?)` | `Promise<OrderGroupDTO>` |
+
+From `config`, the repository reads `take`, `skip`, and `order` only. It ignores `select` and `relations` and always returns every column plus the two computed fields.
<Warning>
- Prefer [workflows](/platform/order-group/reference/workflows) for reads that
- need aggregated child-order status, and for the checkout split. The service
- returns the group row and its computed totals but does **not** expand child
- orders' payment/fulfillment status, emit events, or run compensation.
+ `retrieveOrderGroup` doesn’t throw when no group has the id: it resolves to `undefined`. Check the value before you use it, or use `getOrderGroupDetailWorkflow`, which throws `NOT_FOUND`.
</Warning>
+
+## Write methods
+
+The write methods are the ones `MedusaService` generates for the model:
+
+| Method | Description |
+| --- | --- |
+| `createOrderGroups(data)` | Creates one group from a `CreateOrderGroupDTO`, or several from an array |
+| `updateOrderGroups(data)` | Updates groups from `UpdateOrderGroupDTO` objects |
+| `deleteOrderGroups(ids)` | Deletes groups by id |
+| `softDeleteOrderGroups(ids)` | Sets `deleted_at` on groups |
+| `restoreOrderGroups(ids)` | Clears `deleted_at` on groups |
+
+Creating a group doesn’t create orders or links. Checkout does that in `completeCartWithSplitOrdersWorkflow`, so prefer the workflow over calling `createOrderGroups` yourself.
+
+## Filters and sorting
+
+The repository builds its own SQL and reads only the top-level keys below. It ignores every other key, including `$and` and `$or`.
+
+| Filter | Matches |
+| --- | --- |
+| `id` | Group id, as a string or an array |
+| `customer_id` | Customer id, as a string or an array |
+| `cart_id` | Cart id, as a string or an array |
+| `seller_id` | Groups with at least one child order from the seller |
+| `status` | Groups with at least one child order in the status |
+| `payment_status` | Groups with at least one child order in the derived payment status |
+| `sales_channel_id` | Groups with at least one child order in the sales channel |
+| `created_at`, `updated_at` | A date or an operator map: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$nin`, `$like`, `$ilike` |
+| `q` | Group id or customer id containing the text, or a display id such as `#G98`, `G98`, or `98` on the group or a child order |
+
+The order-level filters only choose which groups match. `seller_count` and `total` still cover every order in each matching group. Pass `id` as a plain string or array: an `{ $in: [...] }` map isn’t read.
+
+`config.order` sorts by `display_id`, `created_at`, or `updated_at`, with `ASC` or `DESC`. Other keys are ignored. Without a valid key, groups come back by `created_at` descending.
diff --git a/apps/docs/platform/order-group/reference/workflows.mdx b/apps/docs/platform/order-group/reference/workflows.mdx
index e62b17693..b92998688 100644
--- a/apps/docs/platform/order-group/reference/workflows.mdx
+++ b/apps/docs/platform/order-group/reference/workflows.mdx
@@ -1,39 +1,98 @@
---
-title: "Workflows"
+title: "Order group workflows"
sidebarTitle: "Workflows"
-description: "Order group workflows, service methods, and events."
+description: "Input, output, hooks, steps, and events of the checkout split and the order group read workflows."
---
-This reference lists the workflows, service methods, and events for the Order
-Group domain. Import workflows from `@mercurjs/core/workflows` and run them
-against the Medusa container.
+Three workflows and one step make up the order group surface: the checkout split that creates groups, and two read workflows that return groups with derived child order statuses. Import them from `@mercurjs/core/workflows` and run them with the Medusa container.
-## Checkout workflow
+```ts
+import {
+ completeCartWithSplitOrdersWorkflow,
+ createOrderGroupStep,
+ getOrderGroupDetailWorkflow,
+ getOrderGroupsListWorkflow,
+} from "@mercurjs/core/workflows"
+```
-| Workflow | Input | Purpose |
+## completeCartWithSplitOrdersWorkflow
+
+Completes a cart by creating one order per seller under a new order group. Workflow id `complete-cart-with-split-orders`. Mercur’s cart completion route and `processPaymentWorkflow` both run it.
+
+| Input | Type | Description |
| --- | --- | --- |
-| `completeCartWithSplitOrdersWorkflow` | `{ cart_id }` | Split a multi-seller cart into per-seller orders and create the parent `OrderGroup`. Returns `{ order_group_id }`. Idempotent per cart. |
+| `cart_id` | `string` | The cart to complete |
+
+It returns `{ order_group_id: string }`. If a group with the same `cart_id` already exists, the workflow skips the split and returns that group’s id.
-## Read workflows
+The workflow stores its execution (`store: true`) and keeps it for 3 days. It holds a lock on the cart id with a 30-second wait timeout and a 2-minute time to live, so concurrent completions of one cart run one at a time.
-| Workflow | Input | Purpose |
+### Hooks
+
+| Hook | Receives | Use it to |
| --- | --- | --- |
-| `getOrderGroupDetailWorkflow` | `{ order_group_id, fields }` | Load one group with its child orders and derived per-order payment/fulfillment status |
-| `getOrderGroupsListWorkflow` | `{ fields, variables?, sellerId? }` | List groups with a count; `sellerId` scopes each group's child orders to a seller |
+| `validate` | `{ input, cart }` | Throw to stop the checkout before anything is created |
+| `setOrderStatus` | `{ cart }` | Return `{ status?, status_by_seller_id? }` to set each child order’s initial status; the default is `pending` |
+
+`SetOrderStatusHookResult` is exported with the workflow. `status_by_seller_id` is keyed by seller id and takes precedence over `status`.
+
+### Steps
+
+The workflow runs these steps in order. Steps 3 to 6 run only when no group exists for the cart:
+
+1. `acquireLockStep` on the cart id, then a query for an existing group and the cart.
+2. `validateCartPaymentsStep`, then the `validate` and `setOrderStatus` hooks.
+3. `validateSellerCartItemsStep` and `validateSellerCartShippingStep`.
+4. `createOrderGroupStep` and `createOrdersStep`, in parallel.
+5. `createRemoteLinkStep`, `mirrorLineItemOfferLinksToOrderStep`, `updateCartsStep` to set `completed_at`, `reserveInventoryStep`, `registerUsageStep`, and two `emitEventStep` calls.
+6. `authorizePaymentSessionStep`, then `splitCapturedCartPaymentWorkflow` and `refreshOrderCommissionLinesWorkflow` as steps.
+7. `releaseLockStep` on the cart id.
+
+### Events
+
+| Event | Payload |
+| --- | --- |
+| `order.placed` | `{ id }`, once per child order |
+| `order_group.created` | `{ id }` of the new group |
+
+## getOrderGroupDetailWorkflow
+
+Retrieves one order group with its child orders and sets `payment_status` and `fulfillment_status` on each order. Workflow id `get-order-group-detail`. Its input type is `GetOrderGroupDetailWorkflowInput`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `order_group_id` | `string` | The group to retrieve |
+| `fields` | `string[]` | Fields to return, in `query.graph` syntax |
+
+It returns the group. The workflow always adds `id`, `orders.id`, `orders.status`, `orders.version`, `orders.currency_code`, and `orders.items.*` to your fields, plus the payment collection and fulfillment fields it needs for the statuses. It throws `NOT_FOUND` when no group has the id.
+
+The workflow removes some data it loaded for itself before it returns:
+
+- **`orders.payment_collections`**: kept only when a requested field contains `payment_collections`
+- **`orders.fulfillments`**: kept only when a requested field contains `fulfillments`
+- **`orders.cart`**: kept only when a requested field starts with `orders.cart`
+
+## getOrderGroupsListWorkflow
+
+Lists order groups with their child orders and derived statuses. Workflow id `get-order-groups-list`. Its input type is `GetOrderGroupsListWorkflowInput`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `fields` | `string[]` | Fields to return, in `query.graph` syntax |
+| `variables` | `object`, optional | Filters plus `skip`, `take`, and `order` |
+| `sellerId` | `string \| string[]`, optional | Removes other sellers’ orders from each returned group |
+
+It returns `{ rows, metadata }`, where `metadata` holds `count`, `skip`, and `take`. It adds the same child order fields as the detail workflow and removes the same data, and adds `orders.seller.id` when you pass `sellerId`.
+
+`sellerId` trims orders but doesn’t filter groups. Pass `variables.seller_id` as well to return only groups where the seller has an order. The filter keys are listed in [Filters and sorting](/platform/order-group/reference/service#filters-and-sorting).
-<Note>
- The read workflows always expand the group's child `orders`. Heavy relations
- (`payment_collections`, `fulfillments`) are only kept in the response when you
- request a matching field, and are used to derive each order's `payment_status`
- and `fulfillment_status`.
-</Note>
+## createOrderGroupStep
-## Step
+Creates one `OrderGroup` record. Step id `create-order-group`.
-| Step | Input | Purpose |
+| Input | Type | Description |
| --- | --- | --- |
-| `createOrderGroupStep` | `{ customer_id?, cart_id }` | Create the `OrderGroup` record (used inside the checkout workflow, with a compensating delete) |
+| `cart_id` | `string` | The completed cart |
+| `customer_id` | `string \| null`, optional | The customer on the cart |
-To work with records directly instead of through a workflow, see the
-[Service reference](/platform/order-group/reference/service). To run side effects
-when a group is created, see the [Event reference](/platform/order-group/reference/events).
+It returns the created group. On rollback, it deletes the group with `deleteOrderGroups`. Use it in your own workflow only when you also create and link the child orders yourself.
diff --git a/apps/docs/platform/payout/concepts/account-lifecycle.mdx b/apps/docs/platform/payout/concepts/account-lifecycle.mdx
index d86d6fc28..214859588 100644
--- a/apps/docs/platform/payout/concepts/account-lifecycle.mdx
+++ b/apps/docs/platform/payout/concepts/account-lifecycle.mdx
@@ -1,75 +1,72 @@
---
-title: "Account lifecycle"
+title: "Payout account and payout statuses"
sidebarTitle: "Account lifecycle"
-description: "Payout account statuses and the webhook-driven transitions between them."
+description: "The statuses a payout account and a payout move through, and the provider webhooks that move them."
---
-In this document, you'll learn about the payout account lifecycle and how its
-status stays in sync with the provider.
-
-## Status
-
-A payout account's state is held in the `status` field of the `PayoutAccount`
-model, typed by the `PayoutAccountStatus` enum. An account moves through four
-statuses.
-
-```
- ┌──────────┐
- │ PENDING │
- └────┬─────┘
- │ account.activated
- ▼
- ┌────────────┐ ┌────────┐
- │ RESTRICTED │◄─►│ ACTIVE │
- └────────────┘ └───┬────┘
- │ account.rejected
- ▼
- ┌──────────┐
- │ REJECTED │
- └──────────┘
-```
-
-| Status | Meaning |
-| --- | --- |
-| `PENDING` | Account created, provider onboarding not yet complete. |
-| `ACTIVE` | Fully onboarded. Can receive payouts. |
-| `RESTRICTED` | Provider flagged the account, for example missing KYC. No payouts. |
-| `REJECTED` | Provider permanently disabled the account. |
+A payout account’s status says whether the seller can receive money, and a payout’s status says where one transfer stands. Neither is set by an operator. The provider decides, sends a webhook, and `processPayoutForWebhookWorkflow` writes the new status. Read this page to know when `createPayoutWorkflow` will accept an account, and what each webhook does.
+
+## Account statuses
+
+An account’s state is the `status` field on `PayoutAccount`, typed by the `PayoutAccountStatus` enum from `@mercurjs/types`. It defaults to `pending`, and the provider’s `createPayoutAccount` response can overwrite it.
+
+| Status | Value | Meaning |
+| --- | --- | --- |
+| `PENDING` | `pending` | Created, setup not finished |
+| `ACTIVE` | `active` | Can receive payouts |
+| `RESTRICTED` | `restricted` | Missing information or a compliance issue |
+| `REJECTED` | `rejected` | Permanently disabled by the provider |
+
+Only `active` matters to the rest of the module. `createPayouts` throws `Account 'pacc_…' is not active` for any other status, so a payout never starts on a pending, restricted, or rejected account.
+
+## Webhooks set the account status
+
+The provider owns the account status, and a webhook carries each change. The provider’s `getWebhookActionAndData` turns a raw webhook into an action and the `pacc` id it applies to. `processPayoutForWebhookWorkflow` then runs the matching step.
+
+<img className="block dark:hidden" src="/images/figures/payout-account-lifecycle-light.svg" alt="A Stripe account.updated webhook behind the process-payout-for-webhook workflow. The workflow maps account.activated to the activate-payout-account step and the Active status, account.restricted to Restricted, account.rejected to Rejected, and not_supported to no change." />
+<img className="hidden dark:block" src="/images/figures/payout-account-lifecycle-dark.svg" alt="A Stripe account.updated webhook behind the process-payout-for-webhook workflow. The workflow maps account.activated to the activate-payout-account step and the Active status, account.restricted to Restricted, account.rejected to Rejected, and not_supported to no change." />
+
+The workflow doesn’t check the current status before it writes. Any action can move an account from any status, so the provider’s view always wins:
+
+| Action | Step | New status |
+| --- | --- | --- |
+| `account.activated` | `activate-payout-account` | `active` |
+| `account.restricted` | `restrict-payout-account` | `restricted` |
+| `account.rejected` | `reject-payout-account` | `rejected` |
+| `not_supported` | none | unchanged |
+
+Each step is `updatePayoutAccountStep`, renamed with `.config({ name })`. It saves the previous status and restores it if the workflow rolls back.
+
+## How Stripe Connect maps account updates
+
+The Stripe Connect provider handles only Stripe’s `account.updated` event, and it reads the `pacc` id from the Stripe account’s `metadata.account_id`. It picks the action in this order:
+
+1. `account.rejected` when `requirements.disabled_reason` starts with `rejected.`
+2. `account.activated` when every enabled `accountValidation` check passes
+3. `account.restricted` in every other case
+
+The default checks are `detailsSubmitted`, `chargesEnabled`, `payoutsEnabled`, and `noOutstandingRequirements`, all `true`, with no `requiredCapabilities`.
<Note>
- Payouts are only created against an `ACTIVE` account. The module rejects a
- payout for an account in any other status.
+ With Stripe Connect, an account can skip `pending` and go to `restricted` first. Stripe sends `account.updated` while the seller is still onboarding, and an account with outstanding requirements maps to `account.restricted`. It becomes `active` on a later update.
</Note>
-## Webhook-driven transitions
-
-Unlike the store lifecycle, payout account transitions are **not** operator
-actions. They follow the provider. The provider sends a webhook, a subscriber
-resolves it to an action, and `processPayoutForWebhookWorkflow` updates the
-status.
-
-| Webhook action | Resulting status |
-| --- | --- |
-| `account.activated` | `ACTIVE` |
-| `account.restricted` | `RESTRICTED` |
-| `account.rejected` | `REJECTED` |
-
-```ts
-// Inside processPayoutForWebhookWorkflow
-when({ input }, ({ input }) => input.action === "account.activated")
- .then(() =>
- updatePayoutAccountStep({ id: input.data!.id, status: PayoutAccountStatus.ACTIVE })
- )
-```
-
-<Tip>
- A `RESTRICTED` account is not terminal. Once the seller resolves the
- provider's requirements, the provider emits `account.activated` again and the
- account returns to `ACTIVE`. `REJECTED` is the only permanent state.
-</Tip>
-
-## Payout status
-
-An individual transfer carries its own `PayoutStatus` (`PENDING` → `PROCESSING`
-→ `PAID`, or `FAILED` / `CANCELED`). Provider webhooks advance it through the
-same workflow. See [The payout pipeline](/platform/payout/concepts/payout-pipeline).
+## Payout statuses
+
+Each payout carries its own `PayoutStatus`. The module creates the row as `pending`, then stores the status the provider’s `createPayout` returns.
+
+| Status | Value | Set by |
+| --- | --- | --- |
+| `PENDING` | `pending` | Row creation |
+| `PROCESSING` | `processing` | A `payout.processing` webhook |
+| `PAID` | `paid` | The provider response or a `payout.paid` webhook |
+| `FAILED` | `failed` | A `payout.failed` webhook |
+| `CANCELED` | `canceled` | A `payout.canceled` webhook |
+
+The Stripe Connect provider returns `paid` as soon as Stripe creates the transfer, and it maps no Stripe event to a `payout.*` action. The `payout.*` branches exist for providers that settle asynchronously.
+
+## Related
+
+- [Process a provider webhook](/platform/payout/guides/process-a-provider-webhook) to see the webhook path end to end
+- [The payout pipeline](/platform/payout/concepts/payout-pipeline) for what happens once an account is active
+- [Workflows reference](/platform/payout/reference/workflows) for every step name
diff --git a/apps/docs/platform/payout/concepts/accounts-and-onboarding.mdx b/apps/docs/platform/payout/concepts/accounts-and-onboarding.mdx
index 3d0627b8f..64058656d 100644
--- a/apps/docs/platform/payout/concepts/accounts-and-onboarding.mdx
+++ b/apps/docs/platform/payout/concepts/accounts-and-onboarding.mdx
@@ -1,70 +1,80 @@
---
-title: "Accounts & onboarding"
+title: "Payout accounts and onboarding"
sidebarTitle: "Accounts & onboarding"
-description: "The payout account, its onboarding record, and provider-specific data."
+description: "How a seller connects to the payout provider, and where provider data such as account ids and onboarding links lives."
---
-In this document, you'll learn how a seller connects to a payment provider and
-where provider-specific data lives.
+A payout account is a seller’s connection to the payout provider, and onboarding is the provider-side setup the seller completes before money can reach them. You need both before you can pay a seller. Mercur stores the provider’s own data on each record without reading it, so the same records work for any provider.
-## Payout account
+## The payout account
-A payout account is the seller's connection to the payment provider. It is the
-record funds are transferred to. A payout account is represented by the
-`PayoutAccount` data model (table `payout_account`, id prefix `pacc`). It is
-created for a seller through `createPayoutAccountWorkflow`, which also links the
-account to the store.
+A payout account is the record a payout is sent to. It’s the `PayoutAccount` data model (table `payout_account`, id prefix `pacc`), and the `seller_payout_account` link ties it to exactly one seller.
+
+You create one with `createPayoutAccountWorkflow`. The workflow checks the seller has no account yet, asks the module to create the account, and links it to the seller:
```ts
+import { createPayoutAccountWorkflow } from "@mercurjs/core/workflows"
+
const { result } = await createPayoutAccountWorkflow(container).run({
input: {
- seller_id: "sel_123",
- context: { /* forwarded to the provider */ },
- data: { /* forwarded to the provider */ },
+ seller_id: "sel_01JD8Q1234567",
+ data: { country: "US" },
},
})
```
-Creating an account is a two-step operation. The module first persists the
-`PayoutAccount`. It then calls the provider to create the connected account and
-stores what the provider returns in the account's `data` field. A seller has
-**exactly one** payout account.
+Inside the module, `createPayoutAccount` runs 3 writes in order:
+
+1. Create the `PayoutAccount` row with your `data` and `context`
+2. Call the provider’s `createPayoutAccount` with `data.account_id` set to the new `pacc` id and `context.idempotency_key` defaulting to the same id
+3. Overwrite the row’s `data` and `status` with what the provider returns
+
+If the provider call throws, the module deletes the new row and rethrows. The Stripe Connect provider returns `pending` and the full Stripe account object. The built-in `system` provider returns `active` and an empty object.
<Note>
- A store can only have **one** payout account. `createPayoutAccountWorkflow`
- validates that the seller doesn't already have one before creating it.
+ A seller can have only one payout account. `validateSellerPayoutAccountStep` queries `seller_payout_account` and fails with `Seller already has a payout account` when a row exists.
</Note>
## Onboarding
-Before an account can receive funds, the seller usually has to complete
-provider-side setup, such as identity verification, bank details, or KYC. That
-state is held in the `Onboarding` data model (table `onboarding`, id prefix
-`onb`). The record is a one-to-one satellite of the payout account.
+Onboarding is the provider’s setup flow: identity checks, bank details, and anything else the provider needs. Its state lives in the `Onboarding` data model (table `onboarding`, id prefix `onb`), a one-to-one child of the payout account.
+
+`createOnboardingWorkflow` takes an `account_id` and calls the provider’s `createOnboarding`. The module merges the account’s stored `data` with the `data` you pass, so the provider sees both. With Stripe Connect, the account’s `data.id` is the Stripe account id, and you pass `refresh_url` and `return_url`:
```ts
-await createOnboardingWorkflow(container).run({
+import { createOnboardingWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await createOnboardingWorkflow(container).run({
input: {
- account_id: "pacc_123",
- context: { return_url: "https://store.example.com/settings/payouts" },
+ account_id: "pacc_01JD8Q1234567",
+ data: {
+ refresh_url: "https://vendor.example.com/payouts/refresh",
+ return_url: "https://vendor.example.com/payouts",
+ },
},
})
```
-The workflow asks the provider to produce onboarding data (for Stripe Connect,
-an onboarding link) and stores it on the record. Running it again on an account
-that already has an onboarding record **updates** it rather than creating a
-second one.
+The result’s `data` holds what the provider returned. For Stripe Connect, that’s an account link object, and `data.url` is the hosted onboarding page. The workflow is safe to re-run:
+
+- **First run**: creates the `Onboarding` record
+- **Later runs**: update the same record with new provider data, which you need when a Stripe link expires
+
+## Provider data and context
+
+Every payout record has a `data` JSON field, and accounts and onboarding records also have `context`. They play different roles:
+
+- **`data`**: the provider’s durable payload, such as the Stripe account, the account link, or the transfer
+- **`context`**: per-call hints for the provider, today only `idempotency_key`
+
+The module never interprets `data`. It passes it to the provider and stores what comes back. When you switch providers, the records keep the same shape.
-## Provider data
+<Warning>
+ A payout account’s `data` holds the raw provider object. For Stripe Connect, that’s the full `Stripe.Account`, so select only the fields you need before you return it from a public route.
+</Warning>
-The `data` JSON field on `PayoutAccount`, `Onboarding`, and `Payout` is where
-provider-specific values live, such as the Stripe account id, onboarding URLs, or
-transfer references. The module never interprets these fields. It forwards them
-to and from the provider.
+## Related
-<Tip>
- `context` carries per-request hints such as an `idempotency_key` or a
- `return_url`, while `data` carries the durable provider payload. Both are
- passed straight through the `IPayoutProvider` interface.
-</Tip>
+- [Account lifecycle](/platform/payout/concepts/account-lifecycle) for the statuses an account moves through after onboarding
+- [Create a payout account](/platform/payout/guides/create-a-payout-account) for a full route example
+- [Start provider onboarding](/platform/payout/guides/start-provider-onboarding) for the onboarding route
diff --git a/apps/docs/platform/payout/concepts/payout-pipeline.mdx b/apps/docs/platform/payout/concepts/payout-pipeline.mdx
index c72297f43..0a1e20474 100644
--- a/apps/docs/platform/payout/concepts/payout-pipeline.mdx
+++ b/apps/docs/platform/payout/concepts/payout-pipeline.mdx
@@ -1,99 +1,96 @@
---
-title: "The payout pipeline"
+title: "How a payout reaches a seller"
sidebarTitle: "The payout pipeline"
-description: "Capture check, payment capture, daily payout, transfer, and the provider interface."
+description: "What Mercur ships for payouts, what you trigger yourself, and how the provider interface fits in."
---
-In this document, you'll learn how an authorized payment becomes a transfer to a
-seller, and how the provider interface fits in.
+The payout pipeline is the path from a placed order to money in a seller’s account. Mercur ships the building blocks: the workflows, the webhook route and subscriber, and the provider interface. It doesn’t ship the scheduler that decides when an order is paid out. You choose that moment and call `createPayoutWorkflow` yourself.
-## Payout
+## What ships in `@mercurjs/core`
-A payout is a single transfer of a seller's earnings for one order. It is
-represented by the `Payout` data model (table `payout`, id prefix `pout`). Its
-`amount` is the order total minus the order's commission lines, and it belongs to
-the seller's `PayoutAccount`.
+The core plugin gives you every piece that talks to the provider or writes payout records:
-```ts
-// createPayoutWorkflow computes the seller's share
-const amount = MathBN.sub(order.total, totalCommission)
-```
+- **Workflows**: `createPayoutAccountWorkflow`, `createOnboardingWorkflow`, `createPayoutWorkflow`, and `processPayoutForWebhookWorkflow`
+- **Webhook route**: `POST /hooks/payout` keeps the raw body and emits `payout.webhook_received` with a 5000 ms delay and 3 attempts
+- **Webhook subscriber**: `payout-webhook` parses the event through the provider and runs `processPayoutForWebhookWorkflow`
+- **Providers**: the built-in `system` provider, plus `@mercurjs/payout-stripe-connect` as a separate package
-The flow is designed to run automatically. Scheduled jobs and event-driven
-subscribers move each order from authorized payment to settled transfer with no
-manual step.
+## What you wire yourself
-<Note>
- The payout **workflows** (`createPayoutWorkflow`, `createPayoutAccountWorkflow`,
- `createOnboardingWorkflow`, `processPayoutForWebhookWorkflow`) and the provider
- **webhook subscriber** ship in `@mercurjs/core`. The **scheduled jobs** that
- drive capture and daily payout are wired up in your project (under
- `apps/api/src/jobs`), along with the `order.capture_requested` and
- `payout.requested` events they emit. The steps below describe that intended
- pipeline and its integration points, not jobs bundled in the core plugin.
-</Note>
+No scheduled job, subscriber, or route in core calls `createPayoutWorkflow`. Core also has no `jobs` directory, so nothing captures authorized payments on a timer.
-## 1. Capture check (every 15 min)
+`@mercurjs/types` exports a `PayoutEvents` enum with `order.capture_requested`, `order.authorization_expired`, and `payout.requested`, but nothing emits these events or subscribes to them. The enum carries a TODO to move them to order events. Treat the names as reserved, not as hooks you can listen to.
-A scheduled job scans for orders ready for capture. An order qualifies when its
-payment is `authorized`, the seller has an `ACTIVE` payout account, the order
-meets the required fulfillment status (default `fulfilled`), and no payout
-exists yet. As the capture deadline nears (authorization window minus safety
-buffer), it emits `order.capture_requested`. If the authorization already
-expired, it emits `order.authorization_expired`.
+The module options also describe a capture and payout schedule. `PayoutModuleOptions` and `PAYOUT_MODULE_OPTION_DEFAULTS` define them, and `getOptions()` returns them with defaults applied, but no core code reads them:
-## 2. Payment capture (event-driven)
+| Option | Default | Intended meaning |
+| --- | --- | --- |
+| `disabled` | `false` | Turn off capture checks and daily payouts |
+| `authorizationWindowMs` | `604800000` (7 days) | How long an authorization stays valid |
+| `sellerActionWindowMs` | `259200000` (72 hours) | How long a seller has to act on an order |
+| `captureSafetyBufferMs` | `86400000` (24 hours) | Margin before authorization expiry |
+| `requiredFulfillmentStatus` | `"fulfilled"` | Minimum fulfillment status for a payout |
-A subscriber listens for `order.capture_requested` and runs Medusa's
-`capturePaymentWorkflow` to capture the authorized payment. On success, the order
-is marked captured. On failure, it's flagged so it isn't retried.
+<Tip>
+ Read these options in your own job with `container.resolve(MercurModules.PAYOUT).getOptions()`. That keeps your schedule configurable from `medusa-config.ts`.
+</Tip>
-## 3. Daily payout (1 AM UTC)
+## How createPayoutWorkflow computes the amount
-A daily job scans captured orders that haven't been paid out and emits
-`payout.requested` for each one. An order qualifies when its payment is captured,
-no payout exists yet, and the seller's account is `ACTIVE`.
+`createPayoutWorkflow` takes one `order_id` and pays the seller’s share of that order. It runs 4 stages:
-## 4. Transfer (event-driven)
+1. Load the order with `total`, `currency_code`, `seller.payout_account`, items, and shipping methods
+2. Load every `commission_line` for those items and shipping methods, then sum their `amount`
+3. Call `createPayoutStep` with `order.total` minus the commission sum, in the order’s currency
+4. Link the payout to the seller and run the `payoutCreated` hook with `order_id` and `payout_id`
-A subscriber listens for `payout.requested` and runs `createPayoutWorkflow`,
-which loads the order with its seller, payout account, and commission lines,
-computes the seller's share, calls the provider to initiate the transfer, and
-creates a `Payout` record linked to the seller.
+For an order with a total of 47.00 and 4.70 in commission lines, the payout amount is 42.30. The workflow throws `Seller does not have a payout account` when the seller has none, and the module throws when the account isn’t `active`.
-<Note>
- The order id is used as the payout's `idempotency_key`, so a re-emitted
- `payout.requested` event never produces a duplicate transfer.
-</Note>
+The provider receives the order id as its idempotency key. With Stripe Connect, the order id also becomes the transfer’s `transfer_group`, and the seller id goes into its metadata.
-## The provider interface
+<Warning>
+ `createPayoutWorkflow` doesn’t check payment capture, fulfillment status, or earlier payouts for the order. Each run creates a new `Payout` row. Put those checks in the code that triggers it.
+</Warning>
-Every external operation goes through the `IPayoutProvider` contract, and the
-module registers **exactly one** provider. Stripe Connect ships out of the box.
-Any other processor implements the same four methods.
+## Trigger payouts from your own code
-| Method | Purpose |
-| --- | --- |
-| `createPayoutAccount` | Create the connected account with the provider |
-| `createOnboarding` | Produce onboarding data (e.g. a Stripe onboarding link) |
-| `createPayout` | Initiate a transfer to the seller |
-| `getWebhookActionAndData` | Parse a raw webhook into a `PayoutWebhookResult` |
+You decide when an order is ready. This subscriber pays out when Medusa emits `order.fulfillment_created`:
-<Tip>
- Provider-specific values, such as account ids, onboarding URLs, or transfer
- references, are stored in the `data` JSON fields and never interpreted by the
- module. The same code path works for any provider.
-</Tip>
+```ts title="src/subscribers/payout-on-fulfillment.ts"
+import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+import { createPayoutWorkflow } from "@mercurjs/core/workflows"
-## Configuration
+export default async function payoutOnFulfillment({
+ event,
+ container,
+}: SubscriberArgs<{ order_id: string }>) {
+ await createPayoutWorkflow(container).run({
+ input: { order_id: event.data.order_id },
+ })
+}
-The pipeline's timing is tunable via the payout module options in
-`medusa-config.ts`:
+export const config: SubscriberConfig = {
+ event: "order.fulfillment_created",
+}
+```
-| Option | Default | Description |
+This fires once per fulfillment, so a partially fulfilled order would be paid more than once. Before you ship it, add a guard that skips orders already paid and orders whose payment isn’t captured. A scheduled job in `src/jobs` that scans orders works the same way.
+
+## The provider interface
+
+Every external call goes through `IPayoutProvider` from `@mercurjs/types`. The module loads exactly one provider and throws `Payout module should be initialized with exactly one provider` otherwise.
+
+| Method | Called by | Returns |
| --- | --- | --- |
-| `disabled` | `false` | Disable both scheduled jobs |
-| `authorizationWindowMs` | 7 days | How long a payment authorization stays valid |
-| `sellerActionWindowMs` | 72 hours | Time a seller has to fulfill before the order is rejected |
-| `captureSafetyBufferMs` | 24 hours | Margin before authorization expiry to trigger capture |
-| `requiredFulfillmentStatus` | `"fulfilled"` | Minimum fulfillment status before an order is eligible |
+| `createPayoutAccount` | `createPayoutAccount` | Provider `id`, optional `status`, `data` |
+| `createOnboarding` | `createOnboarding` | `data`, such as a Stripe account link |
+| `createPayout` | `createPayouts` | Optional `status`, `data` |
+| `getWebhookActionAndData` | `getWebhookActionAndData` | A `PayoutWebhookResult` |
+
+When you register no provider, the module loads `system`. It returns `active` accounts and `paid` payouts without moving money, which suits local development and tests. Register Stripe Connect in `medusa-config.ts` with the [Stripe Connect integration](/resources/integrations/stripe-connect).
+
+## Related
+
+- [Account lifecycle](/platform/payout/concepts/account-lifecycle) for the statuses the webhooks set
+- [Workflows reference](/platform/payout/reference/workflows) for the `payoutCreated` hook
+- [Order commission lines](/platform/commission/concepts/order-commission-lines) for where the commission sum comes from
diff --git a/apps/docs/platform/payout/guides/create-a-payout-account.mdx b/apps/docs/platform/payout/guides/create-a-payout-account.mdx
index 383ed4074..52dc12423 100644
--- a/apps/docs/platform/payout/guides/create-a-payout-account.mdx
+++ b/apps/docs/platform/payout/guides/create-a-payout-account.mdx
@@ -1,59 +1,83 @@
---
-title: "Create a payout account"
+title: "Create a payout account for a seller"
sidebarTitle: "Create a payout account"
-description: "Create a seller's payout account with createPayoutAccountWorkflow."
+description: "Run createPayoutAccountWorkflow from your own route to connect a seller to the payout provider."
---
-In this guide, you'll learn how to create a payout account for a seller from your
-own server code. This is useful in an onboarding flow or a custom API route.
+Create a seller’s payout account from server code, for example in an operator route or a custom signup flow. The Vendor API already does this for sellers at `POST /vendor/payout-accounts`.
-Mercur exposes a `createPayoutAccountWorkflow` that persists the `PayoutAccount`,
-calls the configured provider to create the connected account, and links the
-account to the store. Run it from any place that has access to the Medusa
-container.
+## Before you begin
-## Run the workflow
+You need:
-```ts title="src/api/custom/payout-account/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { createPayoutAccountWorkflow } from "@mercurjs/core/workflows"
+- A seller id, such as `sel_01JD8Q1234567`
+- A payout provider. Without one, the `system` provider creates accounts that are `active` at once
+- For Stripe Connect, `@mercurjs/payout-stripe-connect` registered on the payout module, as in the [Stripe Connect integration](/resources/integrations/stripe-connect)
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
- const { result } = await createPayoutAccountWorkflow(req.scope).run({
- input: {
- seller_id: req.params.id,
- },
- })
+## Create the account
- res.status(201).json({ payout_account: result })
-}
-```
+<Steps>
+ <Step title="Add a route that runs the workflow">
+ Create an admin route that takes the seller id from the path and the provider data from the body:
+
+ ```ts title="src/api/admin/payout-setup/[id]/route.ts"
+ import type {
+ AuthenticatedMedusaRequest,
+ MedusaResponse,
+ } from "@medusajs/framework/http"
+ import { createPayoutAccountWorkflow } from "@mercurjs/core/workflows"
+
+ type Body = { country: string }
+
+ export async function POST(
+ req: AuthenticatedMedusaRequest<Body>,
+ res: MedusaResponse
+ ) {
+ const { result } = await createPayoutAccountWorkflow(req.scope).run({
+ input: {
+ seller_id: req.params.id,
+ data: { country: req.body.country },
+ },
+ })
+
+ res.status(201).json({ payout_account: { id: result.id } })
+ }
+ ```
-The new account starts in `PENDING` and can't receive payouts until the provider
-marks it `ACTIVE`. See [Start onboarding](/platform/payout/guides/start-provider-onboarding).
+ The workflow validates the seller has no account, creates it through the provider, and links it to the seller. The response returns only the id, because `result.data` holds the full provider object.
+ </Step>
+ <Step title="Call the route">
+ Send the seller’s country. Stripe Connect requires `country` and throws `"country" is required` without it:
-<Note>
- A seller can have **only one** payout account. The workflow validates this
- first and fails if the store already has one.
-</Note>
+ ```bash
+ curl -X POST http://localhost:9000/admin/payout-setup/sel_01JD8Q1234567 \
+ -H "Authorization: Bearer your_admin_token" \
+ -H "Content-Type: application/json" \
+ -d '{ "country": "US" }'
+ ```
-## Forward provider data
+ With Stripe Connect, the new account is `pending` and its `data` holds the Express account Stripe created.
+ </Step>
+</Steps>
-The workflow accepts `data` and `context` payloads that are passed straight to
-the provider when it creates the connected account. Use them to hand the
-provider anything it needs up front.
+## Handle a seller that already has an account
+
+`validateSellerPayoutAccountStep` runs first and throws a `MedusaError` of type `INVALID_DATA` with the message `Seller already has a payout account`. Medusa returns it as a `400`. To reuse the existing account instead, look it up through the seller link:
```ts
-await createPayoutAccountWorkflow(req.scope).run({
- input: {
- seller_id: "sel_123",
- context: { idempotency_key: "sel_123" },
- data: { business_type: "company" },
- },
+const { data: [seller] } = await query.graph({
+ entity: "seller",
+ fields: ["id", "payout_account.id", "payout_account.status"],
+ filters: { id: "sel_01JD8Q1234567" },
})
```
-<Warning>
- If the provider call fails after the record is created, the workflow rolls the
- account back so you don't leave a dangling `PayoutAccount` behind.
-</Warning>
+## What happens when the provider call fails
+
+The module creates the `PayoutAccount` row before it calls the provider. If the provider throws, the module deletes that row and rethrows, so no orphaned account is left. The provider receives the new `pacc` id as `data.account_id` and as the default `context.idempotency_key`. Stripe Connect stores that id in the Stripe account’s `metadata.account_id`, which is how webhooks find the account later.
+
+## Next steps
+
+- [Start provider onboarding](/platform/payout/guides/start-provider-onboarding) so the seller can finish setup
+- [Account lifecycle](/platform/payout/concepts/account-lifecycle) for how the account becomes `active`
+- [Workflows reference](/platform/payout/reference/workflows) for the steps inside this workflow
diff --git a/apps/docs/platform/payout/guides/process-a-provider-webhook.mdx b/apps/docs/platform/payout/guides/process-a-provider-webhook.mdx
index 19df0f942..45eed3951 100644
--- a/apps/docs/platform/payout/guides/process-a-provider-webhook.mdx
+++ b/apps/docs/platform/payout/guides/process-a-provider-webhook.mdx
@@ -1,38 +1,70 @@
---
-title: "Process a provider webhook"
+title: "Process payout provider webhooks"
sidebarTitle: "Process a webhook"
-description: "Turn a provider webhook into account and payout status updates."
+description: "Route provider webhooks to Mercur so payout accounts and payouts pick up the provider's status changes."
---
-In this guide, you'll learn how a provider webhook becomes account and payout
-status changes. Mercur already wires this up. A subscriber listens for
-`payout.webhook_received` and drives the update workflow. Understanding the path
-lets you emit the event yourself or extend the flow.
+Connect your payout provider’s webhooks to Mercur so account and payout statuses follow the provider. You need this before any Stripe Connect account can become `active`.
-## The built-in path
+## Before you begin
-The `payout-webhook` subscriber resolves the raw payload to an action through the
-provider, then runs `processPayoutForWebhookWorkflow`:
+You need:
-```ts title="src/subscribers/payout-webhook.ts (shipped)"
-const processedEvent = await payoutService.getWebhookActionAndData(input)
+- A payout provider registered on the payout module, such as Stripe Connect
+- For Stripe Connect, a webhook signing secret set as the provider’s `webhookSecret` option
+- The [Stripe CLI](https://docs.stripe.com/stripe-cli) for local testing
-if (!processedEvent.data) {
- return
-}
+## Receive webhooks
-const wfEngine = container.resolve(Modules.WORKFLOW_ENGINE)
-await wfEngine.run(processPayoutForWebhookWorkflowId, { input: processedEvent })
-```
+Mercur ships the route, the subscriber, and the workflow. You point the provider at the route and check the result.
+
+<Steps>
+ <Step title="Point the provider at /hooks/payout">
+ In production, add a Stripe webhook endpoint for events on connected accounts, with the URL `https://your_backend_url/hooks/payout` and the `account.updated` event. Locally, forward Connect events with the Stripe CLI:
+
+ ```bash
+ stripe listen --events account.updated \
+ --forward-connect-to localhost:9000/hooks/payout
+ ```
+
+ The CLI prints a signing secret. Use it as the provider’s `webhookSecret`.
+ </Step>
+ <Step title="Let the subscriber run the workflow">
+ The route emits `payout.webhook_received` with the body, raw body, and headers. It delays the event by 5000 ms and retries up to 3 times. The shipped `payout-webhook` subscriber then parses it and runs the workflow:
+
+ ```ts title="src/subscribers/payout-webhook.ts (in @mercurjs/core)"
+ const processedEvent = await payoutService.getWebhookActionAndData(input)
+
+ if (!processedEvent.data) {
+ return
+ }
+
+ const wfEngine = container.resolve(Modules.WORKFLOW_ENGINE)
+ await wfEngine.run(processPayoutForWebhookWorkflowId, {
+ input: processedEvent,
+ })
+ ```
+
+ Stripe Connect verifies the `stripe-signature` header against `webhookSecret`. A bad signature throws, and the event bus retries.
+ </Step>
+ <Step title="Check the account status">
+ Read the account to confirm the update landed:
+
+ ```ts
+ const payoutService = container.resolve(MercurModules.PAYOUT)
-`getWebhookActionAndData` delegates to the provider, which parses its own payload
-and returns a `PayoutWebhookResult`. The result is an `action` plus the affected
-`id`.
+ const account = await payoutService.retrievePayoutAccount(
+ "pacc_01JD8Q1234567"
+ )
+ ```
+
+ The `status` is `active`, `restricted`, or `rejected`, depending on what Stripe reported.
+ </Step>
+</Steps>
## Run the workflow directly
-To process an already-parsed result yourself, run the workflow with a
-`PayoutWebhookResult`:
+`processPayoutForWebhookWorkflow` takes a `PayoutWebhookResult`, so you can apply a status change without a webhook, for example in a test or a backfill script:
```ts
import { processPayoutForWebhookWorkflow } from "@mercurjs/core/workflows"
@@ -40,35 +72,49 @@ import { processPayoutForWebhookWorkflow } from "@mercurjs/core/workflows"
await processPayoutForWebhookWorkflow(container).run({
input: {
action: "payout.paid",
- data: { id: "pout_123" },
+ data: { id: "pout_01JD8Q1234567" },
},
})
```
-The workflow branches on `action`, updating the account or the payout:
+The workflow runs at most one step: the one that matches `action`. An `account.*` action needs a `pacc` id, and a `payout.*` action needs a `pout` id. A missing `data.id` or the `not_supported` action changes nothing.
+
+## Map webhooks in your own provider
+
+When you write a provider, `getWebhookActionAndData` decides what each webhook means. Return the action and the Mercur id, not the provider’s id:
+
+```ts title="src/providers/acme-payouts/service.ts"
+async getWebhookActionAndData(
+ payload: PayoutWebhookActionInput
+): Promise<PayoutWebhookResult> {
+ const body = payload.data as { type: string; reference: string }
+
+ if (body.type === "transfer.settled") {
+ return { action: "payout.paid", data: { id: body.reference } }
+ }
-| Action | Effect |
-| --- | --- |
-| `account.activated` / `account.restricted` / `account.rejected` | Set account status to `ACTIVE` / `RESTRICTED` / `REJECTED` |
-| `payout.processing` / `payout.paid` / `payout.failed` / `payout.canceled` | Set payout status accordingly |
+ return { action: "not_supported" }
+}
+```
-<Note>
- Actions the provider can't map return `not_supported` (or a missing `data.id`),
- and the workflow makes no change. It is safe to hand it every event the provider
- sends.
-</Note>
+Verify the provider’s signature here with `payload.rawData` and `payload.headers` before you trust the body. The route keeps the raw body for this purpose.
-## Emit the event yourself
+## Emit the event from another route
-To route a custom provider integration through the same path, emit
-`payout.webhook_received` with the raw payload and let the shipped subscriber
-take over.
+If your provider must post to a different URL, emit `payout.webhook_received` yourself with the same shape. The shipped subscriber picks it up:
```ts
const eventBus = container.resolve(Modules.EVENT_BUS)
await eventBus.emit({
name: "payout.webhook_received",
- data: { rawData, headers, data },
+ data: { data: req.body, rawData: req.rawBody, headers: req.headers },
})
```
+
+Enable `preserveRawBody` on that route’s body parser, or signature checks will fail.
+
+## Next steps
+
+- [Account lifecycle](/platform/payout/concepts/account-lifecycle) for every action and the status it sets
+- [Events reference](/platform/payout/reference/events) for the `payout.webhook_received` payload
diff --git a/apps/docs/platform/payout/guides/start-provider-onboarding.mdx b/apps/docs/platform/payout/guides/start-provider-onboarding.mdx
index eeaed7315..e38ca0936 100644
--- a/apps/docs/platform/payout/guides/start-provider-onboarding.mdx
+++ b/apps/docs/platform/payout/guides/start-provider-onboarding.mdx
@@ -1,50 +1,94 @@
---
-title: "Start provider onboarding"
+title: "Start provider onboarding for a seller"
sidebarTitle: "Start onboarding"
-description: "Kick off provider onboarding with createOnboardingWorkflow."
+description: "Run createOnboardingWorkflow to get a provider onboarding link, such as a Stripe Connect account link, for a seller."
---
-In this guide, you'll learn how to start provider onboarding for a payout
-account from server code. Onboarding is what moves an account from `PENDING`
-toward `ACTIVE`. For Stripe Connect, it produces the hosted link the seller uses
-to submit their details.
-
-## Run the workflow
-
-`createOnboardingWorkflow` asks the provider to produce onboarding data and
-stores it as an `Onboarding` record on the account.
-
-```ts title="src/api/custom/onboarding/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { createOnboardingWorkflow } from "@mercurjs/core/workflows"
-
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
- const { result } = await createOnboardingWorkflow(req.scope).run({
- input: {
- account_id: req.params.id,
- context: {
- return_url: "https://store.example.com/settings/payouts",
- },
- },
- })
-
- res.status(201).json({ onboarding: result })
-}
-```
-
-The provider-specific payload (for Stripe Connect, the onboarding URL) is stored
-in the record's `data` field for you to return to the seller.
-
-<Tip>
- Running the workflow again on an account that already has an onboarding record
- **updates** it in place instead of creating a second one. It is safe to call
- whenever a seller needs a fresh link.
-</Tip>
-
-## Reaching `ACTIVE`
-
-Onboarding kicks off the flow, but the account only becomes `ACTIVE` when the
-provider confirms it via webhook. Handle that step in
-[Process a webhook](/platform/payout/guides/process-a-provider-webhook), and see
-[Account lifecycle](/platform/payout/concepts/account-lifecycle) for the full
-state model.
+Create or refresh a seller’s onboarding link from server code, so they can finish the provider’s setup. The Vendor API already does this at `POST /vendor/payout-accounts/:id/onboarding`.
+
+## Before you begin
+
+You need:
+
+- A payout account for the seller, created with [Create a payout account](/platform/payout/guides/create-a-payout-account)
+- For Stripe Connect, a `refresh_url` and a `return_url` in your vendor app
+
+## Create the onboarding link
+
+<Steps>
+ <Step title="Find the seller's payout account">
+ Onboarding runs against a `pacc` id, not a seller id. Resolve it through the `seller_payout_account` link:
+
+ ```ts title="src/api/admin/payout-setup/[id]/onboarding/helpers.ts"
+ import type { MedusaContainer } from "@medusajs/framework/types"
+ import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
+
+ export async function getPayoutAccountId(
+ container: MedusaContainer,
+ sellerId: string
+ ) {
+ const query = container.resolve(ContainerRegistrationKeys.QUERY)
+ const { data: [seller] } = await query.graph({
+ entity: "seller",
+ fields: ["payout_account.id"],
+ filters: { id: sellerId },
+ })
+ return seller?.payout_account?.id as string | undefined
+ }
+ ```
+ </Step>
+ <Step title="Run the workflow from a route">
+ Pass the URLs in `data`. The module merges them with the account’s stored `data`, which carries the Stripe account `id`:
+
+ ```ts title="src/api/admin/payout-setup/[id]/onboarding/route.ts"
+ import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+ import { MedusaError } from "@medusajs/framework/utils"
+ import { createOnboardingWorkflow } from "@mercurjs/core/workflows"
+ import { getPayoutAccountId } from "./helpers"
+
+ export async function POST(req: MedusaRequest, res: MedusaResponse) {
+ const accountId = await getPayoutAccountId(req.scope, req.params.id)
+ if (!accountId) {
+ throw new MedusaError(MedusaError.Types.NOT_FOUND, "No payout account")
+ }
+
+ const { result } = await createOnboardingWorkflow(req.scope).run({
+ input: {
+ account_id: accountId,
+ data: {
+ refresh_url: "https://vendor.example.com/payouts/refresh",
+ return_url: "https://vendor.example.com/payouts",
+ },
+ },
+ })
+
+ res.json({ url: result.data?.url })
+ }
+ ```
+
+ For Stripe Connect, `result.data` is the Stripe account link, and `url` is the page you redirect the seller to.
+ </Step>
+</Steps>
+
+## Refresh an expired link
+
+Stripe account links expire. Call the same route again: the module finds the account’s existing `Onboarding` record and updates its `data` instead of creating a second one. Point `refresh_url` at a page in your vendor app that calls this route, so Stripe can send the seller back for a fresh link.
+
+## Required data for Stripe Connect
+
+The Stripe Connect provider checks 3 values and throws a `MedusaError` of type `INVALID_DATA` when one is missing:
+
+- **`id`**: the Stripe account id, read from the payout account’s stored `data`
+- **`refresh_url`**: where Stripe sends the seller when the link is no longer valid
+- **`return_url`**: where Stripe sends the seller after they leave the flow
+
+Put the URLs in `data`, not `context`. The module forwards `context` to the provider, but Stripe Connect reads the URLs only from `data`.
+
+## The account becomes active by webhook
+
+Finishing onboarding doesn’t change the account by itself. Stripe sends `account.updated`, the `payout-webhook` subscriber maps it to an action, and `processPayoutForWebhookWorkflow` sets the status.
+
+## Next steps
+
+- [Process a provider webhook](/platform/payout/guides/process-a-provider-webhook) to follow the status update
+- [Account lifecycle](/platform/payout/concepts/account-lifecycle) for how Stripe updates map to statuses
diff --git a/apps/docs/platform/payout/overview.mdx b/apps/docs/platform/payout/overview.mdx
index f9b18ae2f..3a86ab1dd 100644
--- a/apps/docs/platform/payout/overview.mdx
+++ b/apps/docs/platform/payout/overview.mdx
@@ -1,86 +1,95 @@
---
-title: "Payout"
+title: "Payouts"
sidebarTitle: "Overview"
-description: "Onboard sellers to a payment provider and settle their earnings automatically."
+description: "Connect each seller to a payout provider, onboard them, and transfer their share of an order to their own account."
---
-Use Mercur to control how each seller is onboarded and settled, while the
-payment provider handles KYC.
+Use Mercur to connect each seller to a payment provider and send them their share of every order.
-Settlement you control is the Payout domain. Once an order is placed and
-fulfilled, it splits each seller's share out to their own connected account, so
-funds are settled per seller rather than pooled. The seller's share is the order
-total minus commission. Onboarding is provider-driven, with the payment provider
-carrying KYC, and the domain ships with a pluggable provider interface and a
-**Stripe Connect** implementation out of the box. It also runs a fully automated
-capture-and-transfer pipeline driven by scheduled jobs and provider webhooks.
+A payout is a transfer from the marketplace to one seller, for one order. The Payout module holds 3 records: the seller’s payout account, its onboarding state, and the payouts made to it. Every external call goes through a single payout provider. Stripe Connect ships as a package, and a built-in `system` provider runs when you register none.
+
+<img className="block dark:hidden" src="/images/figures/payout-overview-light.svg" alt="A Payouts list in front of a Payout accounts list. Payout #12 for ACME is accented: an order total of € 47.00 minus € 4.70 commission gives a € 42.30 payout, marked Paid. Behind it, ACME's payout account is Active and GLOBEX's is Restricted." />
+<img className="hidden dark:block" src="/images/figures/payout-overview-dark.svg" alt="A Payouts list in front of a Payout accounts list. Payout #12 for ACME is accented: an order total of € 47.00 minus € 4.70 commission gives a € 42.30 payout, marked Paid. Behind it, ACME's payout account is Active and GLOBEX's is Restricted." />
<Note>
- **Provider-agnostic.** The module talks to exactly one registered payout
- provider through a single interface. Stripe Connect ships by default; any
- other processor is a drop-in implementation of the same `IPayoutProvider`
- contract.
+ Resolve the module service with `MercurModules.PAYOUT` from `@mercurjs/types`. Import the payout workflows from `@mercurjs/core/workflows`.
</Note>
## Key features
-- **Pluggable provider interface:** one `IPayoutProvider` contract, with Stripe Connect included.
-- **Payout accounts and onboarding:** a per-seller account plus a provider onboarding record.
-- **Webhook-driven lifecycle:** account status (`PENDING` → `ACTIVE` ↔ `RESTRICTED` / `REJECTED`) tracks the provider.
-- **Automated pipeline:** a capture-check job, payment capture, a daily payout job, and transfer, with no manual steps.
-- **Commission-aware transfers:** each payout is the order total minus its commission lines.
-- **Tunable timing:** authorization window, seller-action window, capture buffer, and required fulfillment status.
+The Payout module covers a seller’s connection to the provider and each transfer made through it:
+
+- **One provider interface**: `IPayoutProvider` has 4 methods, and the module loads exactly one implementation
+- **Stripe Connect provider**: `@mercurjs/payout-stripe-connect` creates Express accounts, onboarding links, and transfers
+- **One account per store**: `createPayoutAccountWorkflow` refuses a second account for the same seller
+- **Re-runnable onboarding**: `createOnboardingWorkflow` creates the onboarding record once and updates it after that
+- **Webhook-driven statuses**: provider webhooks move accounts and payouts between statuses through `processPayoutForWebhookWorkflow`
+- **Commission-aware amounts**: `createPayoutWorkflow` pays the order total minus the order’s commission lines
+
+## How it works
+
+A seller moves from no account to a paid order in 5 steps:
+
+1. Run `createPayoutAccountWorkflow` for the seller. The provider creates a connected account.
+2. Run `createOnboardingWorkflow`. The provider returns onboarding data, such as a Stripe onboarding link.
+3. The provider posts webhooks to `/hooks/payout`, and the `payout-webhook` subscriber sets the account to `active`, `restricted`, or `rejected`.
+4. Run `createPayoutWorkflow` with an order id. It computes the seller’s share and asks the provider to transfer it.
+5. Later provider webhooks update the payout’s status.
+
+<Warning>
+ Mercur doesn’t trigger step 4 for you. No scheduled job or subscriber in `@mercurjs/core` captures payments or runs `createPayoutWorkflow`. Call it from your own job, subscriber, or route. See [The payout pipeline](/platform/payout/concepts/payout-pipeline).
+</Warning>
## Get started
-Learn how the domain fits together.
+Learn how accounts, onboarding, and transfers fit together.
<CardGroup cols={2}>
<Card title="Accounts & onboarding" icon="id-card" href="/platform/payout/concepts/accounts-and-onboarding">
- The payout account, its onboarding record, and provider data.
+ The payout account, its onboarding record, and the provider data they carry.
</Card>
<Card title="Account lifecycle" icon="arrows-rotate" href="/platform/payout/concepts/account-lifecycle">
- Statuses and the webhook-driven transitions between them.
+ Account and payout statuses, and the webhooks that change them.
</Card>
<Card title="The payout pipeline" icon="arrows-turn-right" href="/platform/payout/concepts/payout-pipeline">
- Capture check, capture, daily payout, transfer, and the provider interface.
+ What ships, what you wire yourself, and the provider interface.
</Card>
</CardGroup>
## Examples
-Build against the Payout domain in your own code.
+Build against payouts in your own server code.
<CardGroup cols={2}>
<Card title="Create a payout account" icon="plus" href="/platform/payout/guides/create-a-payout-account">
Run `createPayoutAccountWorkflow` for a seller.
</Card>
<Card title="Start onboarding" icon="link" href="/platform/payout/guides/start-provider-onboarding">
- Kick off provider onboarding with `createOnboardingWorkflow`.
+ Create a provider onboarding link with `createOnboardingWorkflow`.
</Card>
<Card title="Process a webhook" icon="bell" href="/platform/payout/guides/process-a-provider-webhook">
- Turn a provider webhook into account and payout status updates.
+ Turn a provider webhook into account and payout status changes.
</Card>
</CardGroup>
## Resources
-Data models, workflows, service methods, and events for the Payout domain.
+The data models, links, workflows, service methods, and events behind payouts.
<CardGroup cols={2}>
<Card title="Data models" icon="table" href="/platform/payout/reference/data-models">
- The `PayoutAccount`, `Onboarding`, and `Payout` entities.
+ `PayoutAccount`, `Onboarding`, and `Payout`, with every field.
</Card>
<Card title="Links" icon="link" href="/platform/payout/reference/links">
- How the Payout domain links to sellers and orders.
+ How payout records link to sellers and orders.
</Card>
<Card title="Workflows" icon="diagram-project" href="/platform/payout/reference/workflows">
- Account, onboarding, payout, and webhook workflows.
+ The 4 payout workflows, their steps, and their hooks.
</Card>
<Card title="Service" icon="gear" href="/platform/payout/reference/service">
- Module service methods for working with records directly.
+ Generated and provider-backed methods on the module service.
</Card>
<Card title="Events" icon="bell" href="/platform/payout/reference/events">
- Events that drive the payout pipeline.
+ The webhook event, the data-model events, and the reserved event names.
</Card>
</CardGroup>
diff --git a/apps/docs/platform/payout/reference/data-models.mdx b/apps/docs/platform/payout/reference/data-models.mdx
index 2274599ae..f7f4897cf 100644
--- a/apps/docs/platform/payout/reference/data-models.mdx
+++ b/apps/docs/platform/payout/reference/data-models.mdx
@@ -1,61 +1,88 @@
---
-title: "Data models"
+title: "Payout data models"
sidebarTitle: "Data models"
-description: "The data models owned by the Payout domain."
+description: "Every field of PayoutAccount, Onboarding, and Payout, plus the PayoutAccountStatus and PayoutStatus enums."
---
-The Payout domain is owned by the **Payout module**. This reference lists its
-data models and their fields. For the full module overview, see the
-[Payout overview](/platform/payout/overview).
+The Payout module owns 3 data models: `PayoutAccount`, `Onboarding`, and `Payout`. They’re defined in `packages/core/src/modules/payout/models`, and the module service is registered as `MercurModules.PAYOUT`. Every model also gets Medusa’s `created_at`, `updated_at`, and `deleted_at` columns.
## PayoutAccount
-Table `payout_account`, id prefix `pacc`. A seller's connection to the payment
-provider. This is the record funds are transferred to.
+A seller’s connection to the payout provider. Table `payout_account`, id prefix `pacc`.
-| Field | Type | Notes |
+| Field | Type | Description |
| --- | --- | --- |
-| `id` | text | Primary key |
-| `status` | enum | `PayoutAccountStatus`, default `pending` |
-| `data` | json | Provider-specific account data |
-| `context` | json | Nullable; per-request provider hints |
+| `id` | `text` | Primary key, such as `pacc_01JD8Q1234567` |
+| `status` | `enum` | `PayoutAccountStatus`, default `pending` |
+| `data` | `json` | Provider account data, default `{}` |
+| `context` | `json`, nullable | Provider context passed at creation |
-Relations: `onboarding` (one-to-one, nullable), `payouts` (one-to-many).
+Relations:
+
+- **`onboarding`**: `hasOne` `Onboarding`, nullable, mapped by `account`
+- **`payouts`**: `hasMany` `Payout`, mapped by `account`
+
+The seller is reached through the `seller_payout_account` link, not a column. See [Links](/platform/payout/reference/links).
## Onboarding
-Table `onboarding`, id prefix `onb`. Provider setup state for a payout account
-(for Stripe Connect, the onboarding link).
+The provider’s onboarding state for one payout account. Table `onboarding`, id prefix `onb`.
-| Field | Type | Notes |
+| Field | Type | Description |
| --- | --- | --- |
-| `id` | text | Primary key |
-| `data` | json | Nullable; provider onboarding data |
-| `context` | json | Nullable; per-request provider hints |
-| `account_id` | text | Belongs to a `PayoutAccount` |
+| `id` | `text` | Primary key, such as `onb_01JD8Q1234567` |
+| `data` | `json`, nullable | Provider onboarding data, such as a Stripe account link |
+| `context` | `json`, nullable | Provider context from the last onboarding call |
+| `account_id` | `text` | Foreign key to `PayoutAccount` |
+
+Relations:
-<Note>
- `Onboarding` is one-to-one with `PayoutAccount`. Re-running the onboarding
- workflow updates the existing record rather than creating a second one.
-</Note>
+- **`account`**: `belongsTo` `PayoutAccount`, mapped by `onboarding`
## Payout
-Table `payout`, id prefix `pout`. A single transfer of a seller's earnings for
-one order.
+One transfer to a seller’s payout account. Table `payout`, id prefix `pout`.
-| Field | Type | Notes |
+| Field | Type | Description |
| --- | --- | --- |
-| `id` | text | Primary key |
-| `display_id` | number | Auto-incrementing, human-readable |
-| `currency_code` | text | The payout's currency |
-| `amount` | bigNumber | Order total minus commission |
-| `data` | json | Nullable; provider transfer data |
-| `status` | enum | `PayoutStatus`, default `pending` |
-| `account_id` | text | Belongs to a `PayoutAccount` |
+| `id` | `text` | Primary key, such as `pout_01JD8Q1234567` |
+| `display_id` | `autoincrement` | Human-readable sequence number |
+| `currency_code` | `text` | Currency of the transfer |
+| `amount` | `bigNumber` | Amount sent to the seller |
+| `data` | `json`, nullable | Provider transfer data, such as a Stripe transfer |
+| `status` | `enum` | `PayoutStatus`, default `pending` |
+| `account_id` | `text` | Foreign key to `PayoutAccount` |
+
+Relations:
+
+- **`account`**: `belongsTo` `PayoutAccount`, mapped by `payouts`
+
+Indexes, both limited to rows where `deleted_at IS NULL`:
+
+- **`IDX_payout_account_id_created_at`**: on `account_id`, `created_at`
+- **`IDX_payout_status_created_at`**: on `status`, `created_at`
+
+`createPayoutWorkflow` sets `amount` to the order total minus the order’s commission lines. The model itself doesn’t store an order id. The order travels to the provider as the idempotency key, and Stripe Connect stores it as the transfer’s `transfer_group` in `data`.
## Enums
-**`PayoutAccountStatus`:** `pending`, `active`, `restricted`, `rejected`.
+Both enums are exported from `@mercurjs/types`.
+
+`PayoutAccountStatus`:
+
+| Member | Value |
+| --- | --- |
+| `PENDING` | `pending` |
+| `ACTIVE` | `active` |
+| `RESTRICTED` | `restricted` |
+| `REJECTED` | `rejected` |
+
+`PayoutStatus`:
-**`PayoutStatus`:** `pending`, `processing`, `paid`, `failed`, `canceled`.
+| Member | Value |
+| --- | --- |
+| `PENDING` | `pending` |
+| `PROCESSING` | `processing` |
+| `PAID` | `paid` |
+| `FAILED` | `failed` |
+| `CANCELED` | `canceled` |
diff --git a/apps/docs/platform/payout/reference/events.mdx b/apps/docs/platform/payout/reference/events.mdx
index 42b9b6336..109cd8b99 100644
--- a/apps/docs/platform/payout/reference/events.mdx
+++ b/apps/docs/platform/payout/reference/events.mdx
@@ -1,48 +1,74 @@
---
-title: "Event reference"
+title: "Payout events"
sidebarTitle: "Events"
-description: "Events that drive the payout pipeline, for subscribers and side effects."
+description: "The payout webhook event, the data-model events the Payout module emits, and the reserved PayoutEvents names that nothing emits yet."
---
-The Payout domain is event-driven. Scheduled jobs emit events, and subscribers
-react to them to capture payments and transfer funds. Subscribe to these events
-to run your own side effects, such as notifications, ledger syncing, or follow-up
-workflows, instead of polling.
+The Payout module has one event of its own, `payout.webhook_received`, which carries provider webhooks to the shipped subscriber. Medusa also emits a created, updated, or deleted event whenever a payout record changes. Subscribe to those for side effects such as seller notifications or ledger syncs.
-```ts title="src/subscribers/payout-requested.ts"
+## Webhook event
+
+The `POST /hooks/payout` route emits this event with a 5000 ms delay and 3 attempts.
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `payout.webhook_received` | The provider posts to `/hooks/payout` | `{ data, rawData, headers }` |
+
+`data` is the parsed body, `rawData` is the raw body, and `headers` are the request headers. The `payout-webhook` subscriber, with subscriber id `payout-webhook-handler`, handles it and runs `processPayoutForWebhookWorkflow`. The event bus serializes `rawData` as a buffer object, and the subscriber turns it back into a `Buffer` before signature checks.
+
+## Data-model events
+
+`PayoutModuleService` extends `MedusaService`, so Medusa emits an event for each row it creates, updates, or deletes. The name is the module name, the kebab-case model name, and the action. The payload is `{ id }`.
+
+| Event | Emitted when |
+| --- | --- |
+| `payout.payout-account.created` | `createPayoutAccount` inserts an account |
+| `payout.payout-account.updated` | The provider response is stored, or a webhook changes the status |
+| `payout.payout-account.deleted` | The provider call fails and the new account is removed |
+| `payout.onboarding.created` | `createOnboarding` runs for the first time on an account |
+| `payout.onboarding.updated` | `createOnboarding` runs again on the same account |
+| `payout.payout.created` | `createPayouts` inserts a `pending` payout |
+| `payout.payout.updated` | The provider response is stored, or a webhook changes the status |
+| `payout.payout.deleted` | The provider call fails and the new payout is removed |
+
+An `updated` event doesn’t say which field changed. Retrieve the record in your subscriber and read its `status`.
+
+```ts title="src/subscribers/payout-account-updated.ts"
import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+import { MercurModules, PayoutAccountStatus } from "@mercurjs/types"
-export default async function payoutRequestedHandler({
+export default async function payoutAccountUpdated({
event,
container,
-}: SubscriberArgs<{ order_id: string }>) {
- const orderId = event.data.order_id
- // ...notify the seller, write to an external ledger, etc.
+}: SubscriberArgs<{ id: string }>) {
+ const payoutService = container.resolve(MercurModules.PAYOUT)
+ const account = await payoutService.retrievePayoutAccount(event.data.id)
+
+ if (account.status === PayoutAccountStatus.RESTRICTED) {
+ const logger = container.resolve("logger")
+ logger.warn(`Payout account ${account.id} is restricted`)
+ }
}
export const config: SubscriberConfig = {
- event: "payout.requested",
+ event: "payout.payout-account.updated",
}
```
-## Pipeline events
+This subscriber logs a warning each time an account lands in `restricted`, which is where you’d send the seller a reminder to finish onboarding.
-| Event | Emitted when | Handled by |
-| --- | --- | --- |
-| `order.capture_requested` | Capture check finds an order ready to capture | The payment-capture subscriber runs `capturePaymentWorkflow` |
-| `order.authorization_expired` | Capture check finds an authorization that already expired | Order is flagged so it isn't retried |
-| `payout.requested` | Daily job finds a captured order not yet paid out | The transfer subscriber runs `createPayoutWorkflow` |
+## Reserved event names
-## Webhook events
+`@mercurjs/types` exports a `PayoutEvents` enum. Nothing in `@mercurjs/core` emits these events or subscribes to them, and the enum carries a TODO to move them to order events.
-| Event | Emitted when | Handled by |
-| --- | --- | --- |
-| `payout.webhook_received` | A provider webhook arrives | The `payout-webhook` subscriber runs `processPayoutForWebhookWorkflow` |
-
-<Note>
- `order.capture_requested`, `order.authorization_expired`, and
- `payout.requested` are defined on the `PayoutEvents` enum in `@mercurjs/types`.
- The webhook subscriber resolves `payout.webhook_received` to a provider action
- before updating status. See
- [Account lifecycle](/platform/payout/concepts/account-lifecycle).
-</Note>
+| Member | Name |
+| --- | --- |
+| `OrderCaptureRequested` | `order.capture_requested` |
+| `OrderAuthorizationExpired` | `order.authorization_expired` |
+| `PayoutRequested` | `payout.requested` |
+
+You can emit them from your own payout trigger and subscribe to them in your project. See [The payout pipeline](/platform/payout/concepts/payout-pipeline).
+
+## Workflow hook
+
+`createPayoutWorkflow` exposes a `payoutCreated` hook with `{ order_id, payout_id }`. Use it instead of `payout.payout.created` when you need the order id, because the data-model event carries only the payout id.
diff --git a/apps/docs/platform/payout/reference/links.mdx b/apps/docs/platform/payout/reference/links.mdx
index 932bd65f5..ba94d7542 100644
--- a/apps/docs/platform/payout/reference/links.mdx
+++ b/apps/docs/platform/payout/reference/links.mdx
@@ -1,36 +1,66 @@
---
-title: "Links to other modules"
+title: "Payout module links"
sidebarTitle: "Links"
-description: "How the Payout domain links to sellers and orders across the marketplace."
+description: "The 3 module links that connect payout accounts and payouts to sellers and orders."
---
-Modules in Mercur never reference each other directly. They connect through
-**module links**. The Payout module links to the Seller and Order modules. Once a
-link is defined, you retrieve related records with `query.graph` using the link
-alias.
+The Payout module never references other modules directly. 3 module links in `packages/core/src/links` connect its records to sellers and orders. Read across them with `query.graph`, and query a link’s own table by its entry name.
+
+| Link | Entry name | Cardinality | Created by |
+| --- | --- | --- | --- |
+| Seller ↔ payout account | `seller_payout_account` | One to one | `createPayoutAccountWorkflow` |
+| Payout ↔ seller | `payout_seller` | Many payouts to one seller | `createPayoutWorkflow` |
+| Order ↔ payout | `order_payout` | One order to many payouts | Nothing in core |
+
+## Seller and payout account
+
+Defined in `seller-payout-account-link.ts` between `SellerModule.linkable.seller` and `PayoutModule.linkable.payoutAccount`. Neither side is a list, so a seller has one payout account and an account belongs to one seller. `validateSellerPayoutAccountStep` enforces the one-account rule before a new link is created.
```ts
-const { data: sellers } = await query.graph({
+const { data: [seller] } = await query.graph({
entity: "seller",
- fields: ["id", "name", "payout_account.*", "payouts.*"],
+ fields: ["id", "name", "payout_account.id", "payout_account.status"],
+ filters: { id: "sel_01JD8Q1234567" },
})
```
-## Sellers
+## Payout and seller
+
+Defined in `payout-seller-link.ts` between `PayoutModule.linkable.payout`, marked `isList: true`, and `SellerModule.linkable.seller`. A seller has many payouts, and each payout has one seller. `createPayoutWorkflow` creates this link right after the payout.
-| Linked module | Relationship |
-| --- | --- |
-| **Seller** (account) | A store has **one** payout account (`seller` ↔ `payout_account`). |
-| **Seller** (payouts) | A store has **many** payouts (`seller` ↔ `payout`, list). |
+```ts
+const { data: payouts } = await query.graph({
+ entity: "payout",
+ fields: ["id", "amount", "status", "seller.id", "seller.name"],
+ filters: { status: "paid" },
+})
+```
-## Orders
+The Vendor API scopes payouts by querying the link table directly, with `entity: "payout_seller"` and filters on `seller_id` and `payout_id`.
-| Linked module | Relationship |
-| --- | --- |
-| **Order** | An order has **many** payouts (`order` ↔ `payout`, list). |
+## Order and payout
+
+Defined in `order-payout-link.ts` between Medusa’s `OrderModule.linkable.order` and `PayoutModule.linkable.payout`, marked `isList: true`. An order can have many payouts.
+
+<Warning>
+ No workflow in core creates `order_payout` rows, so `order.payouts` is empty by default. To use this link, create it in the `payoutCreated` hook of `createPayoutWorkflow`, which receives `order_id` and `payout_id`.
+</Warning>
+
+```ts title="src/workflows/hooks/link-payout-to-order.ts"
+import { createPayoutWorkflow } from "@mercurjs/core/workflows"
+import { ContainerRegistrationKeys, Modules } from "@medusajs/framework/utils"
+import { MercurModules } from "@mercurjs/types"
+
+createPayoutWorkflow.hooks.payoutCreated(
+ async ({ order_id, payout_id }, { container }) => {
+ const link = container.resolve(ContainerRegistrationKeys.LINK)
+
+ await link.create({
+ [Modules.ORDER]: { order_id },
+ [MercurModules.PAYOUT]: { payout_id },
+ })
+ }
+)
+```
-<Note>
- A payout is linked to both the order it settles and the seller it pays. The
- account link is one-to-one, while the seller-payouts and order-payouts links
- are lists.
-</Note>
+Once the hook runs, read an order’s payouts with `fields: ["id", "payouts.id", "payouts.status"]` on the `order` entity.
diff --git a/apps/docs/platform/payout/reference/service.mdx b/apps/docs/platform/payout/reference/service.mdx
index f4fe82b5d..173f64e8d 100644
--- a/apps/docs/platform/payout/reference/service.mdx
+++ b/apps/docs/platform/payout/reference/service.mdx
@@ -1,53 +1,92 @@
---
-title: "Service reference"
+title: "Payout module service"
sidebarTitle: "Service"
-description: "The Payout module service: methods for working with records directly."
+description: "Resolve the Payout module service, and use its generated data methods and its provider-backed methods."
---
-The Payout module exposes a service you can resolve from the Medusa container to
-read and write records directly, without going through a workflow. Use it inside
-custom services, subscribers, or scheduled jobs.
+`PayoutModuleService` reads and writes payout records, and it’s the only code that calls the payout provider. Resolve it from the container in subscribers, jobs, steps, and routes. Prefer the [workflows](/platform/payout/reference/workflows) when you also need links or a rollback.
+
+## Resolve the service
+
+The service is registered under `MercurModules.PAYOUT`, whose value is `"payout"`:
```ts
import { MercurModules } from "@mercurjs/types"
-const payoutModuleService = container.resolve(MercurModules.PAYOUT)
+const payoutService = container.resolve(MercurModules.PAYOUT)
-const [payouts, count] = await payoutModuleService.listAndCountPayouts({
- status: "paid",
-})
+const [payouts, count] = await payoutService.listAndCountPayouts(
+ { status: "paid" },
+ { take: 20, order: { created_at: "DESC" } }
+)
```
## Generated methods
-Each data model gets a standard set of auto-generated methods. For `Payout`:
+The service extends `MedusaService({ Onboarding, Payout, PayoutAccount })`, so each model gets Medusa’s standard methods:
-| Method | Description |
+| Model | Methods |
| --- | --- |
-| `retrievePayout(id, config?)` | Retrieve a payout by id |
-| `listPayouts(filters?, config?)` | List payouts matching filters |
-| `listAndCountPayouts(filters?, config?)` | List payouts with a total count |
-| `updatePayouts(data)` | Update one or more payouts |
-| `deletePayouts(ids)` | Delete one or more payouts |
+| `PayoutAccount` | `retrievePayoutAccount`, `listPayoutAccounts`, `listAndCountPayoutAccounts`, `createPayoutAccounts`, `updatePayoutAccounts`, `deletePayoutAccounts`, `softDeletePayoutAccounts`, `restorePayoutAccounts` |
+| `Onboarding` | `retrieveOnboarding`, `listOnboardings`, `listAndCountOnboardings`, `createOnboardings`, `updateOnboardings`, `deleteOnboardings`, `softDeleteOnboardings`, `restoreOnboardings` |
+| `Payout` | `retrievePayout`, `listPayouts`, `listAndCountPayouts`, `updatePayouts`, `deletePayouts`, `softDeletePayouts`, `restorePayouts` |
+
+`createPayouts` isn’t in the `Payout` row because the service overrides it. The generated create and update methods write rows only. They never call the provider.
+
+## Provider-backed methods
+
+These methods call the payout provider as part of the write.
+
+### createPayoutAccount
+
+```ts
+createPayoutAccount(input: CreatePayoutAccountDTO): Promise<PayoutAccountDTO>
+```
+
+Creates the row, calls the provider with `data.account_id` set to the new id, then stores the provider’s `data` and `status`. Deletes the row if the provider throws. `input` takes optional `data` and `context`.
+
+### createOnboarding
+
+```ts
+createOnboarding(input: CreateOnboardingDTO): Promise<OnboardingDTO>
+```
+
+Calls the provider with the account’s `data` merged with `input.data`, then creates the onboarding record or updates the existing one. `input` takes `account_id` and optional `data` and `context`.
-The same set exists for `PayoutAccount` and `Onboarding` (e.g.
-`retrievePayoutAccount`, `listPayoutAccounts`, `updateOnboardings`).
+### createPayouts
-## Provider-integrated methods
+```ts
+createPayouts(input: CreatePayoutDTO): Promise<PayoutDTO>
+```
+
+Takes one payout, not an array. Throws a `NOT_ALLOWED` error when the account isn’t `active`. Otherwise it creates a `pending` row, calls the provider, and stores the provider’s `data` and `status`. Deletes the row if the provider throws. `input` takes `account_id`, `amount`, `currency_code`, and optional `data` and `context`.
+
+### getWebhookActionAndData
+
+```ts
+getWebhookActionAndData(
+ input: PayoutWebhookActionInput
+): Promise<PayoutWebhookResult>
+```
+
+Passes `{ data, rawData, headers }` to the provider and returns its action and Mercur id. It doesn’t change any record.
-These overrides call the configured provider as part of the operation. Prefer
-them over the raw generated creates.
+### getOptions
-| Method | Description |
+```ts
+getOptions(): PayoutModuleOptions
+```
+
+Returns the module options merged over `PAYOUT_MODULE_OPTION_DEFAULTS`. Core reads none of the timing options, so use them in your own payout trigger. See [The payout pipeline](/platform/payout/concepts/payout-pipeline).
+
+## Idempotency keys
+
+Each provider-backed method sets `context.idempotency_key` before it calls the provider, unless you pass one:
+
+| Method | Default key |
| --- | --- |
-| `createPayoutAccount(input)` | Create the account and the provider's connected account |
-| `createOnboarding(input)` | Create or update onboarding via the provider |
-| `createPayouts(input)` | Initiate a transfer through the provider (account must be `ACTIVE`) |
-| `getWebhookActionAndData(input)` | Ask the provider to parse a raw webhook payload |
-| `getOptions()` | Read the module's configured options (with defaults applied) |
-
-<Warning>
- Prefer [workflows](/platform/payout/reference/workflows) for anything that
- touches the provider or links records. The generated `updatePayouts` /
- `updatePayoutAccounts` write status directly and do **not** call the provider.
-</Warning>
+| `createPayoutAccount` | The new `pacc` id |
+| `createOnboarding` | The `account_id` |
+| `createPayouts` | The new `pout` id |
+
+`createPayoutWorkflow` passes the order id, which replaces the `pout` default. Stripe Connect forwards the key to Stripe on account and transfer creation.
diff --git a/apps/docs/platform/payout/reference/workflows.mdx b/apps/docs/platform/payout/reference/workflows.mdx
index 5cad89e26..5ec5fb47d 100644
--- a/apps/docs/platform/payout/reference/workflows.mdx
+++ b/apps/docs/platform/payout/reference/workflows.mdx
@@ -1,32 +1,93 @@
---
-title: "Workflows"
+title: "Payout workflows"
sidebarTitle: "Workflows"
-description: "Payout account, onboarding, payout, and webhook workflows."
+description: "The 4 payout workflows and 6 payout steps exported from @mercurjs/core/workflows, with their inputs, steps, and hooks."
---
-This reference lists the workflows for the Payout domain. Import them from
-`@mercurjs/core/workflows` and run them against the Medusa container.
+The Payout module ships 4 workflows in `packages/core/src/workflows/payout`. Import them, and their steps, from `@mercurjs/core/workflows`. None of them emits a custom event. Medusa’s data-model events still fire for the records they write, as listed in [Events](/platform/payout/reference/events).
-## Account & onboarding workflows
+## createPayoutAccountWorkflow
-| Workflow | Input | Purpose |
+Creates a payout account for a seller through the provider and links it to the seller. Workflow id `create-payout-account-for-seller`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `seller_id` | `string` | Seller to create the account for |
+| `data` | `Record<string, unknown>`, optional | Passed to the provider; Stripe Connect needs `country` |
+| `context` | `PayoutProviderContext`, optional | Provider context, such as `idempotency_key` |
+
+Steps, in order:
+
+1. `validate-seller-payout-account`: fails with `Seller already has a payout account` when a `seller_payout_account` row exists
+2. `create-payout-account`: calls the service’s `createPayoutAccount`
+3. `create-remote-links`: links the seller and the account
+
+Returns the `PayoutAccountDTO`. Exposes no hooks.
+
+## createOnboardingWorkflow
+
+Creates or updates the onboarding record for a payout account through the provider. Workflow id `create-onboarding`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `account_id` | `string` | The `pacc` id |
+| `data` | `Record<string, unknown>`, optional | Merged over the account’s `data`; Stripe Connect needs `refresh_url` and `return_url` |
+| `context` | `PayoutProviderContext`, optional | Provider context, stored on the record |
+
+It runs one step, `create-onboarding`, and returns the `OnboardingDTO`. Exposes no hooks.
+
+## createPayoutWorkflow
+
+Pays the seller’s share of one order through the provider. Workflow id `create-payout`, exported as `createPayoutWorkflowId`.
+
+```ts
+const { result } = await createPayoutWorkflow(container).run({
+ input: { order_id: "order_01JD8Q1234567" },
+})
+```
+
+Steps, in order:
+
+1. `fetch-order`: loads `total`, `currency_code`, `seller.payout_account`, items, and shipping methods
+2. `fetch-commission-lines`: loads the `commission_line` rows for those items and shipping methods
+3. `create-payout-step`: creates the payout for `total` minus the commission sum, with the order id as `context.idempotency_key`
+4. `create-remote-links`: links the payout to the seller
+
+It throws `Seller does not have a payout account` when the seller has none. Returns the `PayoutDTO`.
+
+| Hook | Payload | Use it to |
+| --- | --- | --- |
+| `payoutCreated` | `{ order_id, payout_id }` | Link the payout to the order, notify the seller, or sync a ledger |
+
+## processPayoutForWebhookWorkflow
+
+Applies a parsed provider webhook to an account or a payout. Workflow id `process-payout-for-webhook`, exported as `processPayoutForWebhookWorkflowId`. Its input is a `PayoutWebhookResult`: an `action` and an optional `data.id`.
+
+| Action | Step name | Effect |
| --- | --- | --- |
-| `createPayoutAccountWorkflow` | `{ seller_id, data?, context? }` | Create a payout account, call the provider, link it to the store |
-| `createOnboardingWorkflow` | `{ account_id, data?, context? }` | Create or update the account's onboarding record via the provider |
+| `account.activated` | `activate-payout-account` | Account `status` to `active` |
+| `account.restricted` | `restrict-payout-account` | Account `status` to `restricted` |
+| `account.rejected` | `reject-payout-account` | Account `status` to `rejected` |
+| `payout.processing` | `processing-payout` | Payout `status` to `processing` |
+| `payout.paid` | `paid-payout` | Payout `status` to `paid` |
+| `payout.failed` | `failed-payout` | Payout `status` to `failed` |
+| `payout.canceled` | `canceled-payout` | Payout `status` to `canceled` |
-## Payout workflows
+Each branch runs only when `data.id` is set. `not_supported` runs no step. Returns nothing and exposes no hooks.
-| Workflow | Input | Purpose |
+## Steps
+
+You can compose these steps into your own workflows:
+
+| Step | Id | Compensation |
| --- | --- | --- |
-| `createPayoutWorkflow` | `{ order_id }` | Compute the seller's share (total − commission) and initiate a transfer |
-| `processPayoutForWebhookWorkflow` | `PayoutWebhookResult` | Apply a provider webhook to account or payout status |
+| `validateSellerPayoutAccountStep` | `validate-seller-payout-account` | None |
+| `createPayoutAccountStep` | `create-payout-account` | None |
+| `createOnboardingStep` | `create-onboarding` | None |
+| `createPayoutStep` | `create-payout-step` | None |
+| `updatePayoutAccountStep` | `update-payout-account-step` | Restores the previous status |
+| `updatePayoutStep` | `update-payout-step` | Restores the previous status |
<Note>
- `createPayoutWorkflow` reads the order with its seller, payout account, and
- commission lines, then uses the order id as the transfer's idempotency key so
- a re-run never double-pays.
+ The create steps have no compensation. If a later step fails, the account, onboarding record, or payout stays, and the provider-side object stays too. The service only deletes a new row when the provider call itself throws.
</Note>
-
-To work with records directly instead of through a workflow, see the
-[Service reference](/platform/payout/reference/service). For the events that
-drive these workflows, see the [Event reference](/platform/payout/reference/events).
diff --git a/apps/docs/platform/product-edit/concepts/change-actions.mdx b/apps/docs/platform/product-edit/concepts/change-actions.mdx
index 5c95dec7f..09d122936 100644
--- a/apps/docs/platform/product-edit/concepts/change-actions.mdx
+++ b/apps/docs/platform/product-edit/concepts/change-actions.mdx
@@ -1,66 +1,73 @@
---
-title: "Change actions"
+title: "What a change action records and how it applies"
sidebarTitle: "Change actions"
-description: "The typed actions that make up a change and the details they carry."
+description: "The ProductChangeAction types, the details each one carries, and the order they apply in."
---
-In this document, you'll learn how the individual operations inside a change are
-modeled.
+A change action is one operation inside a product change: set a field, add a variant, detach an attribute, delete the product. Splitting a change into typed actions lets an operator see exactly what a seller asked for, and lets Mercur apply each operation through the right Medusa workflow when the change is confirmed.
-## Product change action
+## The action record
-Each operation inside a change is a `ProductChangeAction` (table
-`product_change_action`, id prefix `prodchact`). An action belongs to a parent
-`ProductChange`, targets a `product_id`, and names the operation in its `action`
-field. The operation's payload lives in the `details` JSON, and an `applied`
-boolean records whether it has already been written to the product.
+A `ProductChangeAction` (id prefix `prodchact`) belongs to a parent change through `product_change_id` and targets a `product_id`. Its `action` field names the operation, and its `details` JSON holds the payload. The `applied` boolean starts `false` and flips to `true` once the action has been written to the product.
+
+Actions also carry an auto-incrementing `ordering`, plus `reference` and `reference_id` columns. Mercur’s workflows don’t set the reference columns, so you can use them to point an action at a record of your own.
```ts
const action = {
- product_id: "prod_123",
- action: "UPDATE",
- details: { field: "title", value: "New title" },
+ product_id: "prod_01JD8Q1234567",
+ action: ProductChangeActionType.UPDATE,
+ details: { field: "title", value: "Linen shirt" },
}
```
-Actions carry an autoincrementing `ordering` so a change with several operations
-applies them deterministically.
+This is the shape you pass to `stageProductChangeWorkflow` in its `actions` array. `ProductChangeActionType` is exported from `@mercurjs/types`.
## Action types
-The `action` field is one of the `ProductChangeActionType` values. Each type
-reads a different shape out of `details`:
+The `action` field takes one of the 11 `ProductChangeActionType` values. The edit workflows also store the previous value in `details`, so a reviewer can see the before and after:
-| Action | `details` shape | Applies |
+| Action | `details` written by Mercur | Applies |
| --- | --- | --- |
-| `UPDATE` | `{ field, value }` | A single product field update |
-| `STATUS_CHANGE` | `{ status }` | A product status change |
-| `VARIANT_ADD` | `{ variant }` | Create a variant |
-| `VARIANT_UPDATE` | `{ variant_id, fields }` | Update a variant (scalars + image links) |
-| `VARIANT_REMOVE` | `{ variant_id }` | Delete a variant |
-| `ATTRIBUTE_ADD` | `{ attribute }` | Attach a product attribute |
-| `ATTRIBUTE_UPDATE` | `{ update }` | Change an attached attribute |
-| `ATTRIBUTE_REMOVE` | `{ attribute_id }` | Detach an attribute |
-| `PRODUCT_ADD` | None | Record a product creation in the trail |
-| `PRODUCT_DELETE` | None | Delete the product |
-| `CHANGE_REQUESTED` | `{ message }` | Record an operator revision request |
-
-<Note>
- `CHANGE_REQUESTED` mutates nothing. It's an audit-only marker for a revision
- request. The operator's message rides on both the action's `details.message`
- and the parent change's `external_note`. See
- [Status & auto-confirm](/platform/product-edit/concepts/status-and-auto-confirm).
-</Note>
+| `UPDATE` | `{ field, value, previous_value }` | Sets one product field |
+| `STATUS_CHANGE` | `{ status, previous_status }` | Sets the product status |
+| `VARIANT_ADD` | `{ variant }` | Creates a variant |
+| `VARIANT_UPDATE` | `{ variant_id, fields, previous_fields }` | Updates a variant and its image links |
+| `VARIANT_REMOVE` | `{ variant_id }` | Deletes a variant |
+| `ATTRIBUTE_ADD` | `{ attribute, attribute_id, previous_value }` | Attaches an attribute |
+| `ATTRIBUTE_UPDATE` | `{ update, attribute_id, value, previous_value }` | Changes an attached attribute |
+| `ATTRIBUTE_REMOVE` | `{ attribute_id, previous_value }` | Detaches an attribute |
+| `PRODUCT_DELETE` | `{}` | Deletes the product and its offers |
+| `PRODUCT_ADD` | `{ status, attribute_ids }` | Nothing: records the product’s creation |
+| `CHANGE_REQUESTED` | `{ message }` | Nothing: records a revision request |
+
+`PRODUCT_ADD` and `CHANGE_REQUESTED` only appear on audit changes, which Mercur stores with `applied: true`. See [The change pipeline](/platform/product-edit/concepts/change-pipeline#audit-changes).
+
+## What the edit workflows diff
+
+The edit workflows stage an action only when your input differs from the product. Arrays of relations compare by id or URL, ignoring order, so resending the same categories stages nothing:
+
+- **Product fields**: `title`, `subtitle`, `handle`, `description`, `discountable`, `is_giftcard`, `thumbnail`, `images`, `material`, `weight`, `length`, `height`, `width`, `hs_code`, `mid_code`, `origin_country`, `type_id`, `collection_id`, `categories`, `tags`, `sales_channels`, `metadata`
+- **Status**: a `status` key in the update becomes a `STATUS_CHANGE` action instead of an `UPDATE`
+- **Variants**: `manage_inventory` is skipped on update, and `images` takes `{ add, remove }` image ids
+- **Attributes**: an add the product already holds, or a remove of an attribute it doesn’t hold, stages nothing
+
+A key outside the product field list is ignored by `productEditUpdateProductWorkflow`.
## How actions apply
-When a change is confirmed, its **not-yet-applied** actions are bucketed by type
-and dispatched to the matching Medusa workflows in one pass: product updates,
-variant creates/updates/deletes, and the attribute batch. Each action is then
-flipped to `applied: true` so a re-run never applies it twice.
+When a change is confirmed, `applyProductChangeActionsWorkflow` loads its actions with `applied: false`, groups them by type, and runs each group once. The groups run in this order:
+
+1. `STATUS_CHANGE` and `UPDATE`, merged per product into one `updateProductsWorkflow` call
+2. `VARIANT_REMOVE` through `deleteProductVariantsWorkflow`
+3. `VARIANT_ADD` through `createProductVariantsWorkflow`
+4. `VARIANT_UPDATE` scalar fields through `updateProductVariantsWorkflow`, then the variant image links
+5. `ATTRIBUTE_*` as one batch through `createAndLinkProductAttributesToProductWorkflow`
+6. `PRODUCT_DELETE` through `deleteProductsWorkflow`, followed by `deleteOffersWorkflow` for the product’s offers
+
+The workflow then marks every action it handled as `applied: true`, so running the apply workflow again on the same change never writes an action twice. Types it doesn’t handle, `PRODUCT_ADD` and `CHANGE_REQUESTED`, keep whatever `applied` value they were stored with.
+
+## Related
-<Tip>
- Audit-trail changes (publish approvals, revision requests) are stored with
- their actions already `applied`, so confirming them is a no-op on the product
- itself. They exist purely as history.
-</Tip>
+- [The change lifecycle and auto-confirm](/platform/product-edit/concepts/status-and-auto-confirm)
+- [Stage actions directly](/platform/product-edit/guides/edit-a-product#stage-actions-directly)
+- [The `ProductChangeAction` data model](/platform/product-edit/reference/data-models#productchangeaction)
diff --git a/apps/docs/platform/product-edit/concepts/change-pipeline.mdx b/apps/docs/platform/product-edit/concepts/change-pipeline.mdx
index 9fa0f5610..7e772551a 100644
--- a/apps/docs/platform/product-edit/concepts/change-pipeline.mdx
+++ b/apps/docs/platform/product-edit/concepts/change-pipeline.mdx
@@ -1,69 +1,77 @@
---
-title: "The change pipeline"
+title: "How product changes are staged and recorded"
sidebarTitle: "The change pipeline"
-description: "The ProductChange record, its immutability, and the audit trail."
+description: "How an edit becomes a ProductChange, who can have one open, and how the audit trail builds up."
---
-In this document, you'll learn how a product edit is captured and why the
-pipeline is built on immutable records.
+A product change is one reviewable edit to one product. Because every seller sells against the same shared product, a seller’s edit can’t take effect the moment it’s made. Mercur stores the edit as a `ProductChange` with its actions, holds it for review, and applies it only on confirmation. The same records double as the product’s history.
-## Product change
+## The product change record
-A product change is a single reviewable edit to one product, represented by the
-`ProductChange` data model (table `product_change`, id prefix `prodch`). It
-references the target product through `product_id`, carries the `status` of the
-review, and records who created and resolved it (`created_by`, `confirmed_by`,
-`declined_by`, `canceled_by`) with matching timestamps.
+A `ProductChange` (id prefix `prodch`) points at its product through `product_id` and carries a `status` from the `ProductChangeStatus` enum. It owns one or more `ProductChangeAction` rows in `actions`, one per operation it will apply. The change is the unit you review. The actions are what gets written.
+
+Each resolution stamps an actor and a time on the record:
+
+- **Staging**: `created_by`
+- **Confirm**: `confirmed_by`, `confirmed_at`
+- **Decline**: `declined_by`, `declined_at`, `declined_reason`
+- **Cancel**: `canceled_by`, `canceled_at`
+
+The actor fields are plain text. Vendor routes write the seller id (`sel_…`) into `created_by`, and admin routes write the operator’s user id. Two notes travel with the change: `internal_note` for operators and `external_note` for the seller.
```ts
-const productChangeModuleService = container.resolve(MercurModules.PRODUCT_EDIT)
+import { MercurModules } from "@mercurjs/types"
-const change = await productChangeModuleService.retrieveProductChange(id, {
- relations: ["actions"],
-})
+const productEdit = container.resolve(MercurModules.PRODUCT_EDIT)
+
+const change = await productEdit.retrieveProductChange(
+ "prodch_01JD8Q1234567",
+ { relations: ["actions"] }
+)
```
-A change owns one or more `ProductChangeAction` records (`actions`). The change
-is the reviewable unit; the actions are the individual operations it will apply.
-See [Change actions](/platform/product-edit/concepts/change-actions).
+The service call loads one change with its actions. To read a product’s full history, use the `product.changes` link instead, covered in [Links](/platform/product-edit/reference/links).
-<Note>
- A product can have **only one active (pending) change at a time**. Staging a
- new change while one is still pending is rejected. The vendor resolves or
- cancels the open change first.
-</Note>
+## How an edit is staged
-## Immutability & the audit trail
+Seller edits reach the pipeline through four edit workflows. Each one loads the current product, compares your input against it, and passes only the differences to `stageProductChangeWorkflow`:
-A change is never rewritten in place. It is created, its actions are appended,
-and it is resolved by moving `status` forward and stamping the actor and time.
-Because nothing is overwritten, the set of `ProductChange` rows on a product is a
-durable history of who changed what and who approved it.
+- **`productEditUpdateProductWorkflow`**: product fields and status, as `UPDATE` and `STATUS_CHANGE` actions
+- **`productEditUpdateVariantsWorkflow`**: variant add, update, and remove operations, as `VARIANT_*` actions
+- **`productEditUpdateAttributesWorkflow`**: attribute add, update, and remove, as `ATTRIBUTE_*` actions
+- **`productEditDeleteProductWorkflow`**: a single `PRODUCT_DELETE` action
-Some events aren't vendor edits at all, such as a publish approval or a revision
-request. They still belong in the history. Those are recorded as changes created
-already `confirmed`, so the audit trail captures them without waiting on review.
+`stageProductChangeWorkflow` creates the `pending` change, creates its actions, emits `product-change.created`, and then runs `autoConfirmProductChangeWorkflow`. Whether the change confirms in that same run is covered in [Status & auto-confirm](/platform/product-edit/concepts/status-and-auto-confirm).
-```ts
-await recordProductAuditChangeWorkflow(container).run({
- input: {
- actor_id: "user_123",
- changes: [
- {
- product_id: "prod_123",
- external_note: "Approved for publish",
- actions: [
- { product_id: "prod_123", action: "STATUS_CHANGE", details: { status: "published" } },
- ],
- },
- ],
- },
-})
-```
+## One open change per author
+
+The edit workflows and `createProductChangeWorkflow` refuse to stage a change when the same author already has a `pending` change on that product. The check is scoped by `created_by`, so two different sellers can each have one open change on the same shared product. When `created_by` is missing, the check covers every pending change on the product.
+
+<Warning>
+ `stageProductChangeWorkflow` doesn’t run this check. Call it directly only when you’ve handled conflicts yourself, or prefer an edit workflow.
+</Warning>
+
+The conflict surfaces as a `NOT_ALLOWED` error: “There is already an active update request for this product. Only one request can be active at a time.” The author resolves it by canceling the open change or waiting for an operator to resolve it.
+
+## Audit changes
+
+Some events change a product without a review, yet still belong in its history. `recordProductAuditChangeWorkflow` stores them as changes created already `confirmed`, with every action marked `applied`, so confirming never replays them. Mercur’s product workflows call it in four places:
+
+| Workflow | Action recorded | `details` |
+| --- | --- | --- |
+| `createProductsWorkflow` | `PRODUCT_ADD` | `{ status, attribute_ids }` |
+| `confirmProductsWorkflow` | `STATUS_CHANGE` | `{ status: "published" }` |
+| `rejectProductWorkflow` | `STATUS_CHANGE` | `{ status: "rejected" }` |
+| `requestProductChangeWorkflow` | `CHANGE_REQUESTED` | `{ message }` |
+
+The `PRODUCT_ADD` record does real work: its `created_by` is the seller who submitted the product, and the vendor API reads it to tell which products a seller created.
+
+<Note>
+ Operator edits through the admin product update route run Medusa’s `updateProductsWorkflow` directly and don’t create a change. The pipeline governs seller edits.
+</Note>
+
+## Related
-<Tip>
- Read a product's full history through the read-only `product.changes` link
- (see the [Links reference](/platform/product-edit/reference/links)) rather than
- querying the module directly. The link keeps the audit trail attached to the
- product.
-</Tip>
+- [The action types and their `details`](/platform/product-edit/concepts/change-actions)
+- [Statuses, revision requests, and auto-confirm](/platform/product-edit/concepts/status-and-auto-confirm)
+- [Stage an edit from your own route](/platform/product-edit/guides/edit-a-product)
diff --git a/apps/docs/platform/product-edit/concepts/status-and-auto-confirm.mdx b/apps/docs/platform/product-edit/concepts/status-and-auto-confirm.mdx
index a3b190a4c..f12a5c824 100644
--- a/apps/docs/platform/product-edit/concepts/status-and-auto-confirm.mdx
+++ b/apps/docs/platform/product-edit/concepts/status-and-auto-confirm.mdx
@@ -1,66 +1,63 @@
---
-title: "Status & auto-confirm"
+title: "Change statuses, revision requests, and auto-confirm"
sidebarTitle: "Status & auto-confirm"
-description: "The change status lifecycle, revision requests, and auto-confirm."
+description: "The four ProductChangeStatus values, how a revision request fits in, and when a change confirms without review."
---
-In this document, you'll learn about the states a change moves through and when
-it resolves without operator review.
+Every product change has a status that says whether it’s waiting for review or already resolved. A change starts `pending` and is resolved exactly once: confirmed, declined, or canceled. Whether a seller’s edit waits for an operator at all depends on the `product_request` feature flag and on the `auto_confirm` input.
-## Status
+## The status lifecycle
-A change's state is held in the `status` field of the `ProductChange` model,
-typed by the `ProductChangeStatus` enum. A change moves through four statuses:
+The `status` field takes one of the four `ProductChangeStatus` values, exported from `@mercurjs/types`. Each resolution has its own workflow, which checks that the change is still `pending`, stamps the actor field, and emits an event.
-```
- ┌───────────┐
- │ pending │
- └─────┬─────┘
- ┌───────────┼───────────┐
- confirm decline cancel
- ▼ ▼ ▼
- ┌───────────┐ ┌──────────┐ ┌──────────┐
- │ confirmed │ │ declined │ │ canceled │
- └───────────┘ └──────────┘ └──────────┘
-```
+<img className="block dark:hidden" src="/images/figures/product-edit-lifecycle-light.svg" alt="The ProductChangeStatus table: a change enters pending through stageProductChangeWorkflow, then confirmProductChangeWorkflow, rejectProductChangeWorkflow, or cancelProductChangeWorkflow moves it to confirmed, declined, or canceled, each emitting its own event and stamping its own actor field." />
+<img className="hidden dark:block" src="/images/figures/product-edit-lifecycle-dark.svg" alt="The ProductChangeStatus table: a change enters pending through stageProductChangeWorkflow, then confirmProductChangeWorkflow, rejectProductChangeWorkflow, or cancelProductChangeWorkflow moves it to confirmed, declined, or canceled, each emitting its own event and stamping its own actor field." />
+
+| Status | Meaning | Product touched |
+| --- | --- | --- |
+| `pending` | Staged and waiting for review. The default | No |
+| `confirmed` | Approved, or recorded as an audit change | Yes, its actions are applied |
+| `declined` | Rejected by an operator, with an optional `declined_reason` | No |
+| `canceled` | Withdrawn, by the seller or an operator, before review | No |
-| Status | Meaning |
-| --- | --- |
-| `pending` | Awaiting operator review. The default for a staged edit |
-| `confirmed` | Approved; its actions are applied to the product |
-| `declined` | Rejected by the operator; nothing is applied |
-| `canceled` | Withdrawn (e.g. by the vendor) before review |
+Confirming, declining, or canceling a change that isn’t `pending` fails with a `NOT_ALLOWED` error. Each resolution step saves the previous values, so if a later step fails, the workflow restores the change to `pending`.
<Note>
- Only a `pending` change can be confirmed, declined, or canceled. The
- resolution workflows validate the current status first, so a change is
- resolved exactly once.
+ The model also has `requires_action_by`, `requires_action_at`, and `requires_action_reason` columns, but `ProductChangeStatus` has no `requires_action` value and no workflow writes those columns.
</Note>
## Revision requests
-When an operator wants a submission reworked rather than approved or rejected,
-they **request a revision**. This is recorded as a `CHANGE_REQUESTED` audit
-action (a `confirmed` audit change) carrying the operator's message, and it emits
-`product.change-requested`. The product stays with the vendor to revise and
-resubmit. A revision request is a signal in the audit trail, not a fourth
-resolution of the pending change.
+A revision request sends a proposed product back to its seller without approving or rejecting it. `requestProductChangeWorkflow` checks that the product status is `proposed`, records an audit change with a `CHANGE_REQUESTED` action, and emits `product.change-requested`. The product stays `proposed` for the seller to revise.
+
+A revision request isn’t a fifth status, and it doesn’t resolve any pending change. It’s an already-`confirmed` entry in the product’s history. The operator’s message is stored twice: in the action’s `details.message` and in the change’s `external_note`.
## Auto-confirm
-Staging a change runs `autoConfirmProductChangeWorkflow`. Whether it confirms
-immediately depends on the marketplace's review setting:
+Staging always runs `autoConfirmProductChangeWorkflow` right after the change is created. It runs `confirmProductChangeWorkflow` in the same workflow run when either condition holds:
+
+- **The flag is off**: the `product_request` feature flag is disabled
+- **Forced**: the caller passed `auto_confirm: true`, which reaches the workflow as `force`
+
+Otherwise the change stays `pending`. The flag is on by default. Turn it off with an environment variable:
+
+```bash title=".env"
+MEDUSA_FF_PRODUCT_REQUEST=false
+```
+
+With the flag off, every seller edit applies immediately and still leaves a confirmed change in the trail. The same flag also controls product creation: while it’s on, a seller can only create products as `draft` or `proposed`.
+
+## When Mercur forces auto-confirm
+
+There’s no risk scoring: Mercur doesn’t classify edits as low or high risk. It forces auto-confirm in two places:
+
+- **Draft deletes**: `productEditDeleteProductWorkflow` defaults `auto_confirm` to `true` when the product is a `draft`
+- **Operator deletes**: the admin product delete route always passes `auto_confirm: true`
-- **Review off:** the change is confirmed and applied in the same run, so
- low-friction edits don't wait for an operator.
-- **Review on:** the change stays `pending` for an operator to resolve.
+An auto-confirmed change goes through the same `confirmProductChangeWorkflow` as a manual approval. It emits `product-change.confirmed` and fires the same hooks, with `confirmed_by` set to the change’s author.
-You can also force auto-confirm for a specific change (for example a
-trusted-source import) via the `auto_confirm` flag on the staging workflow,
-regardless of the review setting.
+## Related
-<Tip>
- Auto-confirm reuses the exact same `confirmProductChangeWorkflow` as a manual
- approval, so an auto-confirmed change is applied and audited identically to one
- an operator approves by hand.
-</Tip>
+- [Confirm, decline, or cancel a change in code](/platform/product-edit/guides/confirm-or-decline-a-change)
+- [Request a revision](/platform/product-edit/guides/request-a-revision)
+- [The events each transition emits](/platform/product-edit/reference/events)
diff --git a/apps/docs/platform/product-edit/guides/confirm-or-decline-a-change.mdx b/apps/docs/platform/product-edit/guides/confirm-or-decline-a-change.mdx
index 79ff33e2b..19dd3bb63 100644
--- a/apps/docs/platform/product-edit/guides/confirm-or-decline-a-change.mdx
+++ b/apps/docs/platform/product-edit/guides/confirm-or-decline-a-change.mdx
@@ -1,76 +1,124 @@
---
-title: "Confirm or decline a change"
+title: "Confirm, decline, or cancel a product change"
sidebarTitle: "Confirm or decline"
-description: "Resolve a pending product change from server code."
+description: "Resolve a pending product change from server code and react to the result."
---
-In this guide, you'll learn how to resolve a pending change from your own server
-code. Each resolution has a dedicated workflow so the side effects (applying
-actions, events, compensation) run consistently.
+Resolve a pending product change from your own code, for example in a custom review tool or an automated approval rule. Each resolution has its own workflow, so the status update, the product write, and the event always happen together.
+
+## Before you begin
+
+You need the following in place:
+
+- A Mercur server with `@mercurjs/core` installed through `withMercur()`
+- A change in `pending` status. Changes stay `pending` only while the `product_request` feature flag is on, the default
+
+## Review and resolve a change
+
+Find the pending change, then confirm or decline it.
+
+<Steps>
+ <Step title="Find pending changes">
+ List the pending changes on a product with their actions, so a reviewer can see what each one does.
+
+ ```ts
+ const query = container.resolve("query")
+
+ const { data: changes } = await query.graph({
+ entity: "product_change",
+ fields: ["id", "created_by", "external_note", "actions.*"],
+ filters: {
+ product_id: "prod_01JD8Q1234567",
+ status: "pending",
+ },
+ })
+ ```
+
+ Each action’s `details` holds the proposed value and the previous one, as described in [Change actions](/platform/product-edit/concepts/change-actions).
+ </Step>
+ <Step title="Confirm the change">
+ `confirmProductChangeWorkflow` sets the changes to `confirmed`, applies their actions to the product, and emits `product-change.confirmed`.
+
+ ```ts title="src/api/admin/custom/changes/[id]/confirm/route.ts"
+ import type {
+ AuthenticatedMedusaRequest,
+ MedusaResponse,
+ } from "@medusajs/framework/http"
+ import { confirmProductChangeWorkflow } from "@mercurjs/core/workflows"
+
+ export async function POST(
+ req: AuthenticatedMedusaRequest,
+ res: MedusaResponse
+ ) {
+ await confirmProductChangeWorkflow(req.scope).run({
+ input: {
+ ids: [req.params.id],
+ confirmed_by: req.auth_context.actor_id,
+ },
+ })
+
+ res.json({ id: req.params.id, status: "confirmed" })
+ }
+ ```
+
+ The input takes an `ids` array. Pass `internal_note` or `external_note` to overwrite the change’s notes as you confirm it.
+ </Step>
+ <Step title="Or decline it">
+ `rejectProductChangeWorkflow` sets one change to `declined` and leaves the product untouched. Give the seller a reason in `declined_reason`.
+
+ ```ts
+ import { rejectProductChangeWorkflow } from "@mercurjs/core/workflows"
+
+ await rejectProductChangeWorkflow(container).run({
+ input: {
+ id: "prodch_01JD8Q1234567",
+ declined_by: "user_01JD8Q1234567",
+ declined_reason: "Photos don't meet the image guidelines",
+ },
+ })
+ ```
+
+ The workflow emits `product-change.declined` with the change id.
+ </Step>
+</Steps>
-## Confirm a change
-
-`confirmProductChangeWorkflow` marks the changes `confirmed`, applies their
-pending actions to the product, and emits `product-change.confirmed`.
-
-```ts title="src/api/custom/confirm/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { confirmProductChangeWorkflow } from "@mercurjs/core/workflows"
-
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
- await confirmProductChangeWorkflow(req.scope).run({
- input: {
- ids: [req.params.id],
- confirmed_by: req.auth_context?.actor_id,
- },
- })
-
- res.sendStatus(200)
-}
-```
-
-<Note>
- Confirmation only applies actions that aren't already `applied`, so re-running
- it never writes the same edit twice.
-</Note>
-
-## Decline a change
+## Cancel a change
-`rejectProductChangeWorkflow` moves a `pending` change to `declined` without
-touching the product, and emits `product-change.declined`.
+Cancel a change when it should be withdrawn rather than judged, for example when a seller retracts their own edit. Canceling frees the author to stage a new change on the product.
```ts
-import { rejectProductChangeWorkflow } from "@mercurjs/core/workflows"
+import { cancelProductChangeWorkflow } from "@mercurjs/core/workflows"
-await rejectProductChangeWorkflow(container).run({
+await cancelProductChangeWorkflow(container).run({
input: {
- id: "prodch_123",
- declined_by: "user_123",
- declined_reason: "Images don't meet guidelines",
+ id: "prodch_01JD8Q1234567",
+ canceled_by: "sel_01JD8Q1234567",
},
})
```
-## Cancel a change
+The workflow sets `canceled_by` and `canceled_at`, then emits `product-change.canceled`.
-When the change should be withdrawn rather than judged (for example the vendor
-retracting their own submission), use `cancelProductChangeWorkflow`:
+## Confirm several changes at once
-```ts
-import { cancelProductChangeWorkflow } from "@mercurjs/core/workflows"
+`confirmProductChangeWorkflow` loads every id in `ids` before it writes anything. If one id doesn’t exist, it throws a `NOT_FOUND` error. If one change isn’t `pending`, it throws `NOT_ALLOWED`, and none of the changes are confirmed.
-await cancelProductChangeWorkflow(container).run({
- input: { id: "prodch_123", canceled_by: "user_123" },
-})
-```
+## Handle a failed apply
+
+Applying actions runs Medusa’s product workflows inside the confirm workflow. If one of them fails, for example because a variant was already deleted, the workflow compensates: it restores the change to `pending` and clears `confirmed_by` and `confirmed_at`. Fix the cause, then confirm again.
+
+## Run your own logic on a resolution
+
+Each resolution workflow has a hook that receives the change ids and the `additional_data` you passed in:
+
+- **`confirmProductChangeWorkflow`**: `productChangeConfirmed`, with `{ ids, additional_data }`
+- **`rejectProductChangeWorkflow`**: `productChangeRejected`, with `{ id, additional_data }`
+- **`cancelProductChangeWorkflow`**: `productChangeCanceled`, with `{ id, additional_data }`
-<Warning>
- Confirm, decline, and cancel all require the change to be `pending`. Resolving
- an already-resolved change fails validation. A change is resolved exactly once.
-</Warning>
+Use a hook when your logic must succeed or fail together with the resolution. For side effects that can run later, such as an email to the seller, subscribe to the events listed in the [Events reference](/platform/product-edit/reference/events).
-## React to resolutions
+## Next steps
-To run your own side effects when a change resolves, subscribe to the events
-these workflows emit rather than polling. See the
-[Event reference](/platform/product-edit/reference/events).
+- [Send a proposed product back for a revision](/platform/product-edit/guides/request-a-revision)
+- [How actions apply on confirm](/platform/product-edit/concepts/change-actions#how-actions-apply)
+- [Workflow inputs and hooks](/platform/product-edit/reference/workflows)
diff --git a/apps/docs/platform/product-edit/guides/edit-a-product.mdx b/apps/docs/platform/product-edit/guides/edit-a-product.mdx
index faf7d4b4e..b7711e81c 100644
--- a/apps/docs/platform/product-edit/guides/edit-a-product.mdx
+++ b/apps/docs/platform/product-edit/guides/edit-a-product.mdx
@@ -1,74 +1,154 @@
---
-title: "Edit a product"
+title: "Stage a product edit from server code"
sidebarTitle: "Edit a product"
-description: "Stage a product change from server code with the edit workflows."
+description: "Route a product edit through the review pipeline from a custom API route, a script, or a bulk tool."
---
-In this guide, you'll learn how to route a product edit through the change
-pipeline from your own server code, such as a custom API route or a bulk tool.
+Stage a product edit as a `ProductChange` instead of writing to the product, so it goes through the same review as an edit from the Vendor panel. Use this when you build your own edit surface, such as a bulk editor or an import.
-Instead of writing to a product directly, you stage a `ProductChange`. Mercur
-exposes high-level edit workflows that diff your update against the current
-product and stage only the fields that actually changed.
+## Before you begin
-## Update product fields
+You need the following in place:
-`productEditUpdateProductWorkflow` diffs the `update` payload against the product
-and stages an `UPDATE` action per changed field.
+- A Mercur server with `@mercurjs/core` installed through `withMercur()`
+- A product id, and the id of the actor making the edit, such as a seller id (`sel_…`)
-```ts title="src/api/custom/edit/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { productEditUpdateProductWorkflow } from "@mercurjs/core/workflows"
+## Stage a field edit
+
+`productEditUpdateProductWorkflow` compares your update with the product and stages one action per field that differs.
+
+<Steps>
+ <Step title="Create the route">
+ Add a route under `/admin` so Medusa authenticates the caller, and pass the update to the workflow. The workflow returns the staged change.
+
+ ```ts title="src/api/admin/custom/products/[id]/edit/route.ts" {13-19}
+ import type {
+ AuthenticatedMedusaRequest,
+ MedusaResponse,
+ } from "@medusajs/framework/http"
+ import { productEditUpdateProductWorkflow } from "@mercurjs/core/workflows"
+
+ type Body = { title?: string; material?: string }
+
+ export async function POST(
+ req: AuthenticatedMedusaRequest<Body>,
+ res: MedusaResponse
+ ) {
+ const { result } = await productEditUpdateProductWorkflow(req.scope).run({
+ input: {
+ product_id: req.params.id,
+ created_by: req.auth_context.actor_id,
+ update: req.body,
+ },
+ })
+
+ res.status(202).json({ product_change: result })
+ }
+ ```
+
+ The route answers `202` because the edit isn’t on the product yet. With the default `product_request` flag on, `result.status` is `pending`.
+ </Step>
+ <Step title="Handle an open change">
+ If the same `created_by` already has a `pending` change on the product, the workflow throws a `NOT_ALLOWED` error before it stages anything. Medusa’s error handler turns it into a `400` response. Cancel the open change with `cancelProductChangeWorkflow`, or wait for an operator to resolve it.
+ </Step>
+ <Step title="Read the staged actions">
+ Load the change with its actions to show the seller what’s waiting for review.
+
+ ```ts
+ const query = req.scope.resolve("query")
+
+ const { data: [change] } = await query.graph({
+ entity: "product_change",
+ fields: ["id", "status", "actions.action", "actions.details"],
+ filters: { id: result.id },
+ })
+ ```
+
+ Each `UPDATE` action carries `field`, `value`, and `previous_value` in `details`.
+ </Step>
+</Steps>
+
+If no field differs, the workflow still stages a change, with no actions. Compare the input yourself first when an empty change would confuse your reviewers.
+
+## Stage variant and attribute edits
+
+Variants and attributes have their own edit workflows, with the same pending check. `productEditUpdateVariantsWorkflow` takes a list of typed operations:
+
+```ts
+import { productEditUpdateVariantsWorkflow } from "@mercurjs/core/workflows"
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
- const { result } = await productEditUpdateProductWorkflow(req.scope).run({
- input: {
- product_id: req.params.id,
- created_by: req.auth_context?.actor_id,
- update: { title: "Updated title", material: "Cotton" },
- },
- })
-
- res.status(201).json({ product_change: result })
-}
+await productEditUpdateVariantsWorkflow(container).run({
+ input: {
+ product_id: "prod_01JD8Q1234567",
+ created_by: "sel_01JD8Q1234567",
+ operations: [
+ {
+ type: "update",
+ variant_id: "variant_01JD8Q1234567",
+ fields: { sku: "LINEN-M" },
+ },
+ { type: "remove", variant_id: "variant_01JD8Q1234568" },
+ ],
+ },
+})
```
-<Note>
- If a product already has a `pending` change, staging another one is rejected.
- Only one active change per product is allowed. Resolve or cancel the open
- change first.
-</Note>
+Each operation becomes a `VARIANT_ADD`, `VARIANT_UPDATE`, or `VARIANT_REMOVE` action. An update whose fields all match the current variant stages nothing. For attributes, pass `add`, `remove`, and `update` arrays to `productEditUpdateAttributesWorkflow`, in the same shapes as the attribute batch.
## Stage actions directly
-For finer control (variants, attributes, mixed operations), stage the actions
-yourself with `stageProductChangeWorkflow`:
+For a mixed change, build the actions yourself and pass them to `stageProductChangeWorkflow`. It skips the diff and the pending check, so check for an open change first.
```ts
+import { ProductChangeActionType } from "@mercurjs/types"
import { stageProductChangeWorkflow } from "@mercurjs/core/workflows"
await stageProductChangeWorkflow(container).run({
input: {
- product_id: "prod_123",
- created_by: "user_123",
+ product_id: "prod_01JD8Q1234567",
+ created_by: "sel_01JD8Q1234567",
+ external_note: "Spring catalog refresh",
actions: [
- { product_id: "prod_123", action: "UPDATE", details: { field: "subtitle", value: "New" } },
- { product_id: "prod_123", action: "VARIANT_REMOVE", details: { variant_id: "variant_123" } },
+ {
+ product_id: "prod_01JD8Q1234567",
+ action: ProductChangeActionType.UPDATE,
+ details: { field: "subtitle", value: "Washed linen" },
+ },
],
},
})
```
-## Auto-confirm
+Every action needs its own `product_id`. The workflow fills in `product_change_id` for you.
+
+## Apply an edit without review
+
+Pass `auto_confirm: true` to `stageProductChangeWorkflow` or `productEditDeleteProductWorkflow` to confirm and apply the change in the same run. Use it for trusted sources, such as an operator tool. The change still lands in the trail as `confirmed`, and `product-change.confirmed` still fires.
+
+## Attach custom data with additional_data
+
+`productEditUpdateProductWorkflow` and `productEditUpdateAttributesWorkflow` accept `additional_data` and pass it to their `productChangeCreated` hook. Use the hook to store your own data on the change:
+
+```ts title="src/workflows/hooks/product-change-created.ts"
+import { productEditUpdateProductWorkflow } from "@mercurjs/core/workflows"
+import { MercurModules } from "@mercurjs/types"
+
+productEditUpdateProductWorkflow.hooks.productChangeCreated(
+ async ({ product_change, additional_data }, { container }) => {
+ const productEdit = container.resolve(MercurModules.PRODUCT_EDIT)
+
+ await productEdit.updateProductChanges({
+ id: product_change.id,
+ metadata: { ticket_id: additional_data?.ticket_id },
+ })
+ }
+)
+```
+
+The hook runs after staging and auto-confirm, so `product_change` is the record the workflow returns.
-Both workflows run auto-confirm after staging: with review off the change
-applies immediately, with review on it stays `pending`. Pass `auto_confirm: true`
-to `stageProductChangeWorkflow` to force immediate application regardless of the
-review setting.
+## Next steps
-<Tip>
- Dedicated helpers exist for common shapes, such as
- `productEditUpdateVariantsWorkflow`, `productEditUpdateAttributesWorkflow`, and
- `productEditDeleteProductWorkflow`. Each stages the right action types for you.
- See the [Workflows reference](/platform/product-edit/reference/workflows).
-</Tip>
+- [Confirm or decline the staged change](/platform/product-edit/guides/confirm-or-decline-a-change)
+- [Every action type and its `details`](/platform/product-edit/concepts/change-actions)
+- [Edit workflow inputs and hooks](/platform/product-edit/reference/workflows#edit-workflows)
diff --git a/apps/docs/platform/product-edit/guides/request-a-revision.mdx b/apps/docs/platform/product-edit/guides/request-a-revision.mdx
index 39e3e3bee..b3a17f99d 100644
--- a/apps/docs/platform/product-edit/guides/request-a-revision.mdx
+++ b/apps/docs/platform/product-edit/guides/request-a-revision.mdx
@@ -1,54 +1,114 @@
---
-title: "Request a revision"
+title: "Send a proposed product back for a revision"
sidebarTitle: "Request a revision"
-description: "Send a product submission back to the vendor from server code."
+description: "Ask a seller to rework a proposed product, record the request, and notify the seller."
---
-In this guide, you'll learn how to ask a vendor to rework a submission instead of
-approving or rejecting it outright.
+Ask a seller to rework a product they’ve proposed, instead of publishing or rejecting it. The request leaves the product `proposed`, adds a `CHANGE_REQUESTED` entry to its history, and emits an event you can use to notify the seller.
-A revision request doesn't mutate the product. It records a `CHANGE_REQUESTED`
-action in the audit trail carrying your message, and emits
-`product.change-requested` so the vendor is notified. The product stays with the
-vendor to revise and resubmit.
+## Before you begin
-## Run the workflow
+You need the following in place:
-`requestProductChangeWorkflow` validates that the product is in `proposed`,
-records the audit action, and emits the event.
+- A Mercur server with `@mercurjs/core` installed through `withMercur()`
+- A product with status `proposed`. The workflow fails for any other status
-```ts title="src/api/custom/request-revision/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { requestProductChangeWorkflow } from "@mercurjs/core/workflows"
+## Request and notify
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
- await requestProductChangeWorkflow(req.scope).run({
- input: {
- product_id: req.params.id,
- actor_id: req.auth_context?.actor_id,
- message: "Please add a size guide and sharper photos.",
- },
- })
+Run the workflow from an admin route, then notify the seller from a subscriber.
- res.sendStatus(200)
-}
+<Steps>
+ <Step title="Run the workflow">
+ `requestProductChangeWorkflow` checks the product status, records the audit change, and emits `product.change-requested`.
+
+ ```ts title="src/api/admin/custom/products/[id]/revise/route.ts"
+ import type {
+ AuthenticatedMedusaRequest,
+ MedusaResponse,
+ } from "@medusajs/framework/http"
+ import { requestProductChangeWorkflow } from "@mercurjs/core/workflows"
+
+ export async function POST(
+ req: AuthenticatedMedusaRequest<{ message: string }>,
+ res: MedusaResponse
+ ) {
+ await requestProductChangeWorkflow(req.scope).run({
+ input: {
+ product_id: req.params.id,
+ actor_id: req.auth_context.actor_id,
+ message: req.body.message,
+ },
+ })
+
+ res.json({ id: req.params.id })
+ }
+ ```
+
+ The message is optional. Without it, the action’s `details.message` is `null`.
+ </Step>
+ <Step title="Notify the seller">
+ Subscribe to `product.change-requested`. The payload carries the product id, not a change id, plus the message and the operator’s id.
+
+ ```ts title="src/subscribers/product-change-requested.ts"
+ import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+
+ type Payload = { id: string; message?: string; actor_id?: string }
+
+ export default async function handler({
+ event,
+ container,
+ }: SubscriberArgs<Payload>) {
+ const logger = container.resolve("logger")
+
+ logger.info(
+ `Revision requested on ${event.data.id}: ${event.data.message ?? ""}`
+ )
+ }
+
+ export const config: SubscriberConfig = {
+ event: "product.change-requested",
+ }
+ ```
+
+ Replace the log line with your notification, for example a call to Medusa’s Notification module.
+ </Step>
+</Steps>
+
+## Where the request is stored
+
+`requestProductChangeWorkflow` calls `recordProductAuditChangeWorkflow`, which stores the request as a change that starts out `confirmed`. The message is saved in two places:
+
+- **`details.message`**: on the `CHANGE_REQUESTED` action
+- **`external_note`**: on the change, where the seller-facing note lives
+
+Read every revision request on a product by querying its actions:
+
+```ts
+const { data: requests } = await query.graph({
+ entity: "product_change_action",
+ fields: ["details", "product_change.created_by", "created_at"],
+ filters: {
+ product_id: "prod_01JD8Q1234567",
+ action: "CHANGE_REQUESTED",
+ },
+})
```
-<Note>
- The request is only valid while the product is `proposed`. The workflow
- validates the product status first and fails otherwise.
-</Note>
+`product_change.created_by` is the operator who asked.
+
+## Publish or reject instead
+
+When the product is ready or can’t be fixed, resolve it with a product workflow instead. Both require the product to be `proposed`, and both record a confirmed `STATUS_CHANGE` audit change:
+
+- **`confirmProductsWorkflow`**: takes `product_ids`, sets them to `published`, and emits `product.published`
+- **`rejectProductWorkflow`**: takes `product_id` and an optional `message`, sets it to `rejected`, and emits `product.rejected`
+
+## Attach custom data with additional_data
-## Where the message goes
+`requestProductChangeWorkflow` passes `additional_data` to its `productChangeRequested` hook, along with `product_id` and `message`. Use it to store, for example, the checklist items the seller has to fix.
-The `message` is stored in two places for durability: the `CHANGE_REQUESTED`
-action's `details.message`, and the parent change's `external_note` (the
-vendor-facing note). Because the audit change is created already `confirmed`, the
-request is a permanent entry in the product's history.
+## Next steps
-<Tip>
- Subscribe to `product.change-requested` to send the vendor a notification. The
- payload includes the `id` (product), the `message`, and the `actor_id` of the
- operator who asked. See the
- [Event reference](/platform/product-edit/reference/events).
-</Tip>
+- [How audit changes fit the trail](/platform/product-edit/concepts/change-pipeline#audit-changes)
+- [Revision requests and statuses](/platform/product-edit/concepts/status-and-auto-confirm#revision-requests)
+- [Event payloads](/platform/product-edit/reference/events)
diff --git a/apps/docs/platform/product-edit/overview.mdx b/apps/docs/platform/product-edit/overview.mdx
index c7c3976fd..49eb25f1f 100644
--- a/apps/docs/platform/product-edit/overview.mdx
+++ b/apps/docs/platform/product-edit/overview.mdx
@@ -1,85 +1,92 @@
---
-title: "Product Edit"
+title: "Product edits"
sidebarTitle: "Overview"
-description: "Route every product edit through a reviewable, immutable change pipeline."
+description: "Review every seller edit to a shared product before it lands, and keep a record of who changed what."
---
-Use Mercur to keep a full audit trail of every product change and govern your
-master data before it changes.
+Use Mercur to put seller edits to the shared catalog through review, and to keep a durable history of every change to a product.
-Master-data governance depends on knowing who changed what, and reviewing it
-before it takes effect. The Product Edit domain is that auditable change
-pipeline. Every edit becomes an immutable, attributed `ProductChange` record that
-enters an approval queue, so no change to a shared product is silently written.
-Each record carries typed actions and a status lifecycle, and the trail records
-who changed what and who approved it.
+Products in Mercur form one shared catalog that every seller sells against, so a seller can’t write to a product directly. Each edit becomes a `ProductChange` record that holds typed actions, one per changed field, variant, or attribute. The change waits as `pending` until an operator confirms or declines it, or its author cancels it. Confirmed changes, together with publish approvals, rejections, and revision requests, form the product’s audit trail.
+
+<img className="block dark:hidden" src="/images/figures/product-edit-overview-light.svg" alt="A product's Changes list read through product.changes: a pending UPDATE from the seller sits on top of confirmed PRODUCT_ADD, CHANGE_REQUESTED, UPDATE, and STATUS_CHANGE records that form the audit trail." />
+<img className="hidden dark:block" src="/images/figures/product-edit-overview-dark.svg" alt="A product's Changes list read through product.changes: a pending UPDATE from the seller sits on top of confirmed PRODUCT_ADD, CHANGE_REQUESTED, UPDATE, and STATUS_CHANGE records that form the audit trail." />
<Note>
- **Product Edit ≠ product ownership.** Products are the shared master catalog,
- and sellers sell against them through offers. Product Edit governs *changes* to
- a product. It never makes a store the owner of one.
+ The Product Edit module (`MercurModules.PRODUCT_EDIT`) governs changes to a product. It never makes a store the owner of one. Products live in Medusa’s Product module, and sellers sell them through [offers](/platform/offer/overview).
</Note>
+## How it works
+
+A seller edit moves through the pipeline in five steps:
+
+1. A vendor route runs an edit workflow such as `productEditUpdateProductWorkflow`, which diffs the input against the product and stages a `pending` change with one action per difference.
+2. `autoConfirmProductChangeWorkflow` runs right after staging. With the `product_request` feature flag on, the default, the change stays `pending`.
+3. An operator confirms or declines the change, or the seller cancels it.
+4. On confirm, `applyProductChangeActionsWorkflow` writes the actions to the product through Medusa’s product workflows and marks each action `applied`.
+5. Product creation, publish approvals, rejections, and revision requests are recorded as changes that start out `confirmed`, so the trail is complete without a review.
+
## Key features
-- **Immutable audit trail:** every edit is an attributed `ProductChange` that is never rewritten, only appended to and resolved.
-- **Typed change actions:** each edit is expressed as `ProductChangeAction` rows such as `UPDATE`, `VARIANT_*`, `ATTRIBUTE_*`, `STATUS_CHANGE`, or `PRODUCT_ADD/DELETE`.
-- **Approval queue:** a change moves `pending` → `confirmed` / `declined` / `canceled`, each through a dedicated workflow.
-- **Deferred application:** actions are applied to the product only on confirmation, then marked `applied`.
-- **Auto-confirm:** when review is off, staged changes confirm and apply immediately.
-- **Revision requests:** operators send a submission back to the vendor as a recorded `CHANGE_REQUESTED` audit action.
-- **One active change per product:** a product can't have two pending changes at once.
+The module covers the full path of an edit, from diff to audit record:
+
+- **Field-level diffs**: the edit workflows stage only the fields, variants, and attributes that differ from the current product
+- **Typed actions**: each change holds `ProductChangeAction` rows such as `UPDATE`, `VARIANT_ADD`, `ATTRIBUTE_UPDATE`, or `PRODUCT_DELETE`
+- **Review queue**: a change moves from `pending` to `confirmed`, `declined`, or `canceled`, each through its own workflow and event
+- **Deferred writes**: actions touch the product only when the change is confirmed
+- **Auto-confirm**: turn off the `product_request` flag, or pass `auto_confirm`, to apply a change in the same run
+- **Revision requests**: an operator sends a proposed product back to its seller with a recorded `CHANGE_REQUESTED` action
+- **One open change per author**: the edit workflows reject a new change while the same author has one pending on the product
## Get started
-Learn how the domain fits together:
+Learn how changes, actions, and statuses fit together.
<CardGroup cols={2}>
<Card title="The change pipeline" icon="clock-rotate-left" href="/platform/product-edit/concepts/change-pipeline">
- The `ProductChange` record, immutability, and the audit trail.
+ How an edit becomes a `ProductChange` and how the audit trail builds up.
</Card>
<Card title="Change actions" icon="list-check" href="/platform/product-edit/concepts/change-actions">
- The typed actions that make up a change and their `details`.
+ The action types, the `details` each one carries, and how they apply.
</Card>
<Card title="Status & auto-confirm" icon="arrows-rotate" href="/platform/product-edit/concepts/status-and-auto-confirm">
- The status lifecycle, revision requests, and auto-confirm.
+ The status lifecycle, revision requests, and when a change skips review.
</Card>
</CardGroup>
## Examples
-Build against the Product Edit domain in your own code:
+Build against the change pipeline in your own server code.
<CardGroup cols={2}>
<Card title="Edit a product" icon="pen" href="/platform/product-edit/guides/edit-a-product">
- Stage a product change from server code.
+ Stage field, variant, and attribute changes from a custom route.
</Card>
<Card title="Confirm or decline" icon="gavel" href="/platform/product-edit/guides/confirm-or-decline-a-change">
- Resolve a pending change in code.
+ Resolve a pending change and react to the result.
</Card>
<Card title="Request a revision" icon="rotate-left" href="/platform/product-edit/guides/request-a-revision">
- Send a submission back to the vendor.
+ Send a proposed product back to its seller with a message.
</Card>
</CardGroup>
## Resources
-Data models, workflows, service methods, and events for the Product Edit domain:
+The data models, links, workflows, service methods, and events behind product edits.
<CardGroup cols={2}>
<Card title="Data models" icon="table" href="/platform/product-edit/reference/data-models">
- The `ProductChange` and `ProductChangeAction` entities.
+ The `ProductChange` and `ProductChangeAction` models and their enums.
</Card>
<Card title="Links" icon="link" href="/platform/product-edit/reference/links">
- How the Product Edit domain links to other modules.
+ The read-only `product.changes` link to Medusa’s Product module.
</Card>
<Card title="Workflows" icon="diagram-project" href="/platform/product-edit/reference/workflows">
- Create, confirm, decline, cancel, and stage workflows.
+ Staging, resolution, apply, edit, and audit workflows with their hooks.
</Card>
<Card title="Service" icon="gear" href="/platform/product-edit/reference/service">
- Module service methods for working with records directly.
+ Generated methods on the Product Edit module service.
</Card>
<Card title="Events" icon="bell" href="/platform/product-edit/reference/events">
- Events emitted as changes move through the pipeline.
+ The `product-change.*` events and the revision request event.
</Card>
</CardGroup>
diff --git a/apps/docs/platform/product-edit/reference/data-models.mdx b/apps/docs/platform/product-edit/reference/data-models.mdx
index d3f0886db..25fbfc1de 100644
--- a/apps/docs/platform/product-edit/reference/data-models.mdx
+++ b/apps/docs/platform/product-edit/reference/data-models.mdx
@@ -1,65 +1,91 @@
---
-title: "Data models"
+title: "Product Edit data models"
sidebarTitle: "Data models"
-description: "The data models owned by the Product Edit domain."
+description: "Fields, enums, indexes, and relations of the ProductChange and ProductChangeAction models."
---
-The Product Edit domain is owned by the **Product Edit module**
-(`MercurModules.PRODUCT_EDIT`). This reference lists its data models and their
-fields.
+The Product Edit module, resolved with `MercurModules.PRODUCT_EDIT` (`"product_edit"`), owns two data models: `ProductChange` and `ProductChangeAction`. Both are defined in `packages/core/src/modules/product-edit/models`. Every model also gets `created_at`, `updated_at`, and `deleted_at` from Medusa.
## ProductChange
-Table `product_change`, id prefix `prodch`. A single reviewable edit to one
-product.
+A single reviewable edit to one product. Table `product_change`, id prefix `prodch`.
-| Field | Type | Notes |
+| Field | Type | Description |
| --- | --- | --- |
-| `id` | text | Primary key |
-| `product_id` | text | The product this change targets (indexed) |
-| `status` | enum | `ProductChangeStatus`, default `pending` (indexed) |
-| `internal_note` | text | Nullable; operator-only note |
-| `external_note` | text | Nullable; vendor-facing note |
-| `created_by` | text | Nullable; actor who staged the change |
-| `confirmed_by` / `confirmed_at` | text / dateTime | Nullable; set on confirm |
-| `declined_by` / `declined_at` | text / dateTime | Nullable; set on decline |
-| `declined_reason` | text | Nullable |
-| `canceled_by` / `canceled_at` | text / dateTime | Nullable; set on cancel |
-| `requires_action_by` / `requires_action_at` | text / dateTime | Nullable |
-| `requires_action_reason` | text | Nullable |
-| `metadata` | json | Nullable |
-
-Relations: `actions` (one-to-many `ProductChangeAction`, cascade-deleted with the
-change).
-
-<Note>
- The `status` enum has four values: `pending`, `confirmed`, `declined`, and
- `canceled`. A revision request is recorded as a `CHANGE_REQUESTED` audit action
- rather than a distinct status.
-</Note>
+| `id` | `text` | Primary key, prefixed `prodch` |
+| `product_id` | `text` | The product the change targets |
+| `status` | `enum` | A `ProductChangeStatus` value. Default `pending` |
+| `internal_note` | `text`, nullable | Note for operators |
+| `external_note` | `text`, nullable | Note shown to the seller. Holds the message of a revision request |
+| `created_by` | `text`, nullable | Actor who staged the change: a seller id from vendor routes, a user id from admin routes |
+| `confirmed_by` | `text`, nullable | Actor who confirmed the change |
+| `confirmed_at` | `dateTime`, nullable | When the change was confirmed |
+| `declined_by` | `text`, nullable | Actor who declined the change |
+| `declined_at` | `dateTime`, nullable | When the change was declined |
+| `declined_reason` | `text`, nullable | Reason given on decline |
+| `canceled_by` | `text`, nullable | Actor who canceled the change |
+| `canceled_at` | `dateTime`, nullable | When the change was canceled |
+| `requires_action_by` | `text`, nullable | Reserved. No workflow writes it |
+| `requires_action_at` | `dateTime`, nullable | Reserved. No workflow writes it |
+| `requires_action_reason` | `text`, nullable | Reserved. No workflow writes it |
+| `metadata` | `json`, nullable | Custom key-value data |
+
+Relations:
+
+- **`actions`**: has many `ProductChangeAction`. The model cascades deletes to its actions
+
+Indexes on `status`, on `product_id`, and on `(product_id, status)`, all excluding soft-deleted rows.
## ProductChangeAction
-Table `product_change_action`, id prefix `prodchact`. A single typed operation
-inside a change.
+A single typed operation inside a change. Table `product_change_action`, id prefix `prodchact`.
-| Field | Type | Notes |
+| Field | Type | Description |
| --- | --- | --- |
-| `id` | text | Primary key |
-| `product_id` | text | The product the action targets (indexed) |
-| `product_change_id` | text | Nullable FK to the parent change (`ON DELETE SET NULL`, indexed) |
-| `ordering` | autoincrement | Deterministic apply order (indexed) |
-| `action` | text | A `ProductChangeActionType` value |
-| `details` | json | Default `{}`; the operation payload |
-| `internal_note` | text | Nullable |
-| `applied` | boolean | Default `false`; set `true` once written to the product |
+| `id` | `text` | Primary key, prefixed `prodchact` |
+| `product_id` | `text` | The product the action targets |
+| `product_change_id` | `text`, nullable | The parent change. The foreign key is `ON DELETE SET NULL` |
+| `ordering` | `autoincrement` | Insertion order across all actions |
+| `action` | `text` | A `ProductChangeActionType` value |
+| `details` | `json` | The operation payload. Default `{}` |
+| `reference` | `text`, nullable | Free-form type of a related record. Not set by Mercur |
+| `reference_id` | `text`, nullable | Free-form id of a related record. Not set by Mercur |
+| `internal_note` | `text`, nullable | Note for operators |
+| `applied` | `boolean` | `true` once the action is written to the product. Default `false` |
+
+Relations:
+
+- **`product_change`**: belongs to `ProductChange`, nullable
+
+Indexes on `product_change_id`, `product_id`, `(reference, reference_id)`, and `ordering`, all excluding soft-deleted rows.
+
+## ProductChangeStatus
+
+The values of `ProductChange.status`, exported from `@mercurjs/types`:
+
+| Value | Meaning |
+| --- | --- |
+| `pending` | Waiting for review |
+| `confirmed` | Approved and applied, or recorded as an audit change |
+| `declined` | Rejected by an operator |
+| `canceled` | Withdrawn before review |
-## Enums
+## ProductChangeActionType
-`ProductChangeStatus`: `pending`, `confirmed`, `declined`, `canceled`.
+The values of `ProductChangeAction.action`, exported from `@mercurjs/types`:
-`ProductChangeActionType`: `UPDATE`, `STATUS_CHANGE`, `VARIANT_ADD`,
-`VARIANT_UPDATE`, `VARIANT_REMOVE`, `ATTRIBUTE_ADD`, `ATTRIBUTE_UPDATE`,
-`ATTRIBUTE_REMOVE`, `PRODUCT_ADD`, `PRODUCT_DELETE`, `CHANGE_REQUESTED`.
+| Value | Applied on confirm |
+| --- | --- |
+| `UPDATE` | Yes |
+| `STATUS_CHANGE` | Yes |
+| `VARIANT_ADD` | Yes |
+| `VARIANT_UPDATE` | Yes |
+| `VARIANT_REMOVE` | Yes |
+| `ATTRIBUTE_ADD` | Yes |
+| `ATTRIBUTE_UPDATE` | Yes |
+| `ATTRIBUTE_REMOVE` | Yes |
+| `PRODUCT_DELETE` | Yes |
+| `PRODUCT_ADD` | No, audit only |
+| `CHANGE_REQUESTED` | No, audit only |
-Both enums are exported from `@mercurjs/types`.
+The `details` shape for each type is listed in [Change actions](/platform/product-edit/concepts/change-actions#action-types). The matching DTOs are `ProductChangeDTO` and `ProductChangeActionDTO`, and the create inputs are `CreateProductChangeDTO` and `CreateProductChangeActionDTO`, all from `@mercurjs/types`.
diff --git a/apps/docs/platform/product-edit/reference/events.mdx b/apps/docs/platform/product-edit/reference/events.mdx
index 76fa5da8e..27cb53a62 100644
--- a/apps/docs/platform/product-edit/reference/events.mdx
+++ b/apps/docs/platform/product-edit/reference/events.mdx
@@ -1,22 +1,52 @@
---
-title: "Event reference"
+title: "Product Edit events"
sidebarTitle: "Events"
-description: "Events emitted by the Product Edit domain, for subscribers and side effects."
+description: "Events emitted as product changes are staged and resolved, and when an operator requests a revision."
---
-The Product Edit domain emits events as changes move through the pipeline.
-Subscribe to them to run side effects instead of polling. Use them to notify a
-vendor, sync external systems, or kick off follow-up workflows.
+Product change workflows emit events after they commit, so you can run side effects, such as notifying a seller or reindexing search, without polling. The change events are in `ProductChangeWorkflowEvents`, and the revision request event is in `ProductWorkflowEvents`, both exported from `@mercurjs/core/workflows`.
+
+## Change events
+
+Each change event carries the id of one change. A workflow that handles several changes emits one event per change.
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `product-change.created` | `stageProductChangeWorkflow` or `createProductChangeWorkflow` creates a change | `{ id }` |
+| `product-change.confirmed` | `confirmProductChangeWorkflow` confirms a change, including auto-confirm | `{ id }` |
+| `product-change.declined` | `rejectProductChangeWorkflow` declines a change | `{ id }` |
+| `product-change.canceled` | `cancelProductChangeWorkflow` cancels a change | `{ id }` |
+
+Audit changes from `recordProductAuditChangeWorkflow` emit no change event. An auto-confirmed change emits `product-change.created` and then `product-change.confirmed`.
+
+## Revision request event
+
+The revision request event comes from `requestProductChangeWorkflow`. Its `id` is the product id, because the request is recorded on the product rather than resolving a change.
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `product.change-requested` | An operator requests a revision on a `proposed` product | `{ id, message, actor_id }` |
+
+## Subscribe to an event
+
+This subscriber loads a confirmed change with its actions:
```ts title="src/subscribers/product-change-confirmed.ts"
import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
-export default async function productChangeConfirmedHandler({
+export default async function handler({
event,
container,
}: SubscriberArgs<{ id: string }>) {
- const changeId = event.data.id
- // ...notify the vendor, sync search, etc.
+ const query = container.resolve("query")
+
+ const { data: [change] } = await query.graph({
+ entity: "product_change",
+ fields: ["product_id", "created_by", "actions.action"],
+ filters: { id: event.data.id },
+ })
+
+ // notify change.created_by that change.product_id was updated
}
export const config: SubscriberConfig = {
@@ -24,24 +54,4 @@ export const config: SubscriberConfig = {
}
```
-## Change events
-
-| Event | Emitted when | Payload |
-| --- | --- | --- |
-| `product-change.created` | A change is staged | `{ id }` |
-| `product-change.confirmed` | A change is confirmed | `{ id }` |
-| `product-change.declined` | A change is declined | `{ id }` |
-| `product-change.canceled` | A change is canceled | `{ id }` |
-
-## Revision events
-
-| Event | Emitted when | Payload |
-| --- | --- | --- |
-| `product.change-requested` | An operator requests a revision | `{ id, message, actor_id }` |
-
-<Note>
- `product.change-requested` carries the **product** id (not a change id) along
- with the operator's `message` and `actor_id`, because a revision request is
- recorded against the product's audit trail rather than resolving a pending
- change.
-</Note>
+`created_by` tells you who to notify: a seller id for edits from the Vendor panel. To react to declines with the reason, read `declined_reason` the same way from a `product-change.declined` subscriber.
diff --git a/apps/docs/platform/product-edit/reference/links.mdx b/apps/docs/platform/product-edit/reference/links.mdx
index e78bc1a93..2929b1f71 100644
--- a/apps/docs/platform/product-edit/reference/links.mdx
+++ b/apps/docs/platform/product-edit/reference/links.mdx
@@ -1,39 +1,47 @@
---
-title: "Links to other modules"
+title: "Product Edit links"
sidebarTitle: "Links"
-description: "How the Product Edit domain links to other modules across the marketplace."
+description: "The read-only link that exposes a product's change history as product.changes."
---
-Modules in Mercur never reference each other directly. They connect through
-**module links**. Once a link is defined, you retrieve related records with
-`query.graph` using the link alias.
+Mercur modules never import each other. They connect through module links, which you read with `query.graph`. The Product Edit module has one link, to Medusa’s Product module.
-## Product
+## Product to product changes
-The Product Edit domain links to the Product module so a product's change
-history hangs off the product itself.
+A read-only link that lists a product’s changes under the `changes` alias. It’s defined in `packages/core/src/links/product-change-link.ts`.
-| Linked module | Relationship |
-| --- | --- |
-| **Product** | A product has many changes (`product_change.product_id`, read-only). Exposed as `product.changes`. |
+| Side | Module | Linkable | Key |
+| --- | --- | --- | --- |
+| Source | Product (`Modules.PRODUCT`) | `product` | `id` |
+| Target | Product Edit (`MercurModules.PRODUCT_EDIT`) | `product_change` | `product_id` |
+
+- **Cardinality**: one product to many changes
+- **Alias**: `changes`, read as `product.changes`
+- **Storage**: no pivot table. The link reads the `product_id` column on `product_change`
+- **Writes**: none. The link is `readOnly`, so you create changes with the [workflows](/platform/product-edit/reference/workflows), never through the link
+
+Read a product’s history with its actions:
```ts
-const { data: products } = await query.graph({
+const query = container.resolve("query")
+
+const { data: [product] } = await query.graph({
entity: "product",
- fields: ["id", "title", "changes.status", "changes.actions.action"],
+ fields: [
+ "id",
+ "title",
+ "changes.id",
+ "changes.status",
+ "changes.created_by",
+ "changes.actions.action",
+ "changes.actions.details",
+ ],
+ filters: { id: "prod_01JD8Q1234567" },
})
```
-<Note>
- The link is **read-only** and has no pivot table. The FK lives directly on the
- `product_change` row. It exists so you read the audit trail through
- `product.changes`. You can't write a change through the link itself. Stage
- changes with the [workflows](/platform/product-edit/reference/workflows).
-</Note>
+`product.changes` returns every change on the product, including audit changes and resolved ones. To filter by status, query the `product_change` entity with a `product_id` filter instead, because `query.graph` can’t filter on linked records.
-## Actor references
+## Actor fields
-The `created_by`, `confirmed_by`, `declined_by`, and `canceled_by` fields hold
-actor ids (the dashboard user who staged or resolved the change). They are plain
-text references for the audit trail, not module links, so they aren't resolved
-through `query.graph`.
+`created_by`, `confirmed_by`, `declined_by`, and `canceled_by` hold actor ids as plain text: a seller id when the change came from a vendor route, a user id when it came from an admin route. They aren’t module links, so `query.graph` can’t expand them. Resolve the seller or user yourself when you need their details.
diff --git a/apps/docs/platform/product-edit/reference/service.mdx b/apps/docs/platform/product-edit/reference/service.mdx
index f8e0af3f4..2cde5a7e3 100644
--- a/apps/docs/platform/product-edit/reference/service.mdx
+++ b/apps/docs/platform/product-edit/reference/service.mdx
@@ -1,43 +1,62 @@
---
-title: "Service reference"
+title: "Product Edit module service"
sidebarTitle: "Service"
-description: "The Product Edit module service methods for working with records directly."
+description: "Resolve the Product Edit module service and call its generated methods for changes and actions."
---
-The Product Edit module exposes a service you can resolve from the Medusa
-container to read and write records directly, without going through a workflow.
-Use it inside custom services, subscribers, or scheduled jobs.
+The Product Edit module service, `ProductChangeModuleService`, reads and writes `ProductChange` and `ProductChangeAction` records directly. It’s a plain `MedusaService` with generated methods only, and no custom methods. Use it in subscribers, scheduled jobs, and workflow steps.
+
+## Resolve the service
+
+Resolve the service from the Medusa container with `MercurModules.PRODUCT_EDIT`:
```ts
import { MercurModules } from "@mercurjs/types"
-const productChangeModuleService = container.resolve(MercurModules.PRODUCT_EDIT)
+const productEdit = container.resolve(MercurModules.PRODUCT_EDIT)
-const [changes, count] = await productChangeModuleService.listAndCountProductChanges({
- status: "pending",
-})
+const [changes, count] = await productEdit.listAndCountProductChanges(
+ { product_id: "prod_01JD8Q1234567", status: "pending" },
+ { relations: ["actions"], take: 20 }
+)
```
-## Generated methods
+This returns the first 20 pending changes on a product, with their actions, and the total count. For a typed handle, import the class with `import type { ProductChangeModuleService } from "@mercurjs/core/modules/product-edit"` and pass it as the `resolve` generic.
+
+## ProductChange methods
+
+Medusa generates these methods for the `ProductChange` model:
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `retrieveProductChange` | `(id, config?)` | Retrieve one change. Throws if it doesn’t exist |
+| `listProductChanges` | `(filters?, config?)` | List changes matching the filters |
+| `listAndCountProductChanges` | `(filters?, config?)` | List changes and return `[changes, count]` |
+| `createProductChanges` | `(data)` | Create one change or an array of them |
+| `updateProductChanges` | `(data)` | Update by `id`, or pass `{ selector, data }` |
+| `deleteProductChanges` | `(ids)` | Delete changes. The model cascades deletes to their actions |
+| `softDeleteProductChanges` | `(ids, config?)` | Soft-delete changes |
+| `restoreProductChanges` | `(ids, config?)` | Restore soft-deleted changes |
+
+## ProductChangeAction methods
+
+The same set exists for `ProductChangeAction`:
-Each data model gets a standard set of auto-generated methods. For
-`ProductChange`:
+| Method | Signature | Description |
+| --- | --- | --- |
+| `retrieveProductChangeAction` | `(id, config?)` | Retrieve one action |
+| `listProductChangeActions` | `(filters?, config?)` | List actions matching the filters |
+| `listAndCountProductChangeActions` | `(filters?, config?)` | List actions and return `[actions, count]` |
+| `createProductChangeActions` | `(data)` | Create one action or an array of them |
+| `updateProductChangeActions` | `(data)` | Update by `id`, or pass `{ selector, data }` |
+| `deleteProductChangeActions` | `(ids)` | Delete actions |
+| `softDeleteProductChangeActions` | `(ids, config?)` | Soft-delete actions |
+| `restoreProductChangeActions` | `(ids, config?)` | Restore soft-deleted actions |
-| Method | Description |
-| --- | --- |
-| `createProductChanges(data)` | Create one or more changes |
-| `retrieveProductChange(id, config?)` | Retrieve a change by id |
-| `listProductChanges(filters?, config?)` | List changes matching filters |
-| `listAndCountProductChanges(filters?, config?)` | List changes with a total count |
-| `updateProductChanges(data)` | Update one or more changes |
-| `deleteProductChanges(ids)` | Delete one or more changes |
+## When to use a workflow instead
-The same set exists for `ProductChangeAction`: `createProductChangeActions`,
-`listProductChangeActions`, `updateProductChangeActions`, and so on.
+The service writes rows and nothing else. Setting `status` to `confirmed` through `updateProductChanges` doesn’t apply the actions, stamp `confirmed_at`, emit `product-change.confirmed`, or run the hooks.
<Warning>
- Prefer [workflows](/platform/product-edit/reference/workflows) for anything with
- side effects (confirming, declining, applying actions). The service writes
- records directly and does **not** apply actions to the product, emit events, or
- run compensation.
+ Use the [workflows](/platform/product-edit/reference/workflows) for any status change. Keep the service for reads and for fields with no side effects, such as `metadata`.
</Warning>
diff --git a/apps/docs/platform/product-edit/reference/workflows.mdx b/apps/docs/platform/product-edit/reference/workflows.mdx
index fdaadab00..18d77c75d 100644
--- a/apps/docs/platform/product-edit/reference/workflows.mdx
+++ b/apps/docs/platform/product-edit/reference/workflows.mdx
@@ -1,49 +1,191 @@
---
-title: "Workflows"
+title: "Product Edit workflows"
sidebarTitle: "Workflows"
-description: "Product change workflows, service methods, and events."
+description: "Inputs, hooks, and events of every product change workflow, from staging to audit records."
---
-This reference lists the workflows for the Product Edit domain. Import them from
-`@mercurjs/core/workflows` and run them against the Medusa container.
+This page lists the workflows that stage, resolve, apply, and record product changes. Import them from `@mercurjs/core/workflows` and run them with the Medusa container, for example `confirmProductChangeWorkflow(container).run({ input })`. Each section gives the workflow id, the input, the hooks, and the events.
-## Lifecycle workflows
+## Edit workflows
-| Workflow | Input | Purpose |
+These workflows load the current product, diff your input against it, check that the author has no pending change on the product, and stage the result through `stageProductChangeWorkflow`. They return the staged `ProductChangeDTO`.
+
+### productEditUpdateProductWorkflow
+
+Id `product-edit-update-product`. Stages an `UPDATE` action per changed product field, and a `STATUS_CHANGE` action when `status` differs.
+
+| Input | Type | Description |
| --- | --- | --- |
-| `createProductChangeWorkflow` | `{ changes[], additional_data? }` | Create pending changes (rejects if one is already pending) |
-| `stageProductChangeWorkflow` | `{ product_id, actions[], created_by?, internal_note?, external_note?, auto_confirm? }` | Create a change with actions, then run auto-confirm |
-| `confirmProductChangeWorkflow` | `{ ids[], confirmed_by?, internal_note?, external_note? }` | Mark `confirmed` and apply pending actions |
-| `rejectProductChangeWorkflow` | `{ id, declined_by?, declined_reason? }` | Move a `pending` change to `declined` |
-| `cancelProductChangeWorkflow` | `{ id, canceled_by? }` | Move a `pending` change to `canceled` |
-| `autoConfirmProductChangeWorkflow` | `{ change_id, confirmed_by?, force? }` | Confirm when review is off, or when `force` is set |
+| `product_id` | `string` | The product to edit |
+| `created_by` | `string`, optional | The author. Scopes the pending check |
+| `update` | `Record<string, unknown>` | Proposed values. Keys outside the diffed field list are ignored |
+| `additional_data` | `Record<string, unknown>`, optional | Passed to the `productChangeCreated` hook |
-## Apply workflows
+Hooks: `validate` with `{ input }`, and `productChangeCreated` with `{ product_change, additional_data }`.
+
+### productEditUpdateVariantsWorkflow
+
+Id `product-edit-update-variants`. Stages `VARIANT_ADD`, `VARIANT_UPDATE`, and `VARIANT_REMOVE` actions.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `product_id` | `string` | The product to edit |
+| `created_by` | `string`, optional | The author. Scopes the pending check |
+| `operations` | `ProductEditVariantOperation[]` | `{ type: "add", variant }`, `{ type: "update", variant_id, fields }`, or `{ type: "remove", variant_id }` |
+
+An update stages only the fields that differ, and `manage_inventory` is never staged. No hooks.
+
+### productEditUpdateAttributesWorkflow
+
+Id `product-edit-update-attributes`. Stages `ATTRIBUTE_ADD`, `ATTRIBUTE_UPDATE`, and `ATTRIBUTE_REMOVE` actions, skipping entries that wouldn’t change the product.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `product_id` | `string` | The product to edit |
+| `created_by` | `string`, optional | The author. Scopes the pending check |
+| `add` | `ProductAttributeBatchAdd[]`, optional | Attributes to attach |
+| `remove` | `string[]`, optional | Attribute ids to detach |
+| `update` | `ProductAttributeBatchUpdate[]`, optional | Changes to attached attributes |
+| `additional_data` | `Record<string, unknown>`, optional | Passed to the `productChangeCreated` hook |
+
+Hooks: `validate` with `{ input }`, and `productChangeCreated` with `{ product_change, additional_data }`.
+
+### productEditDeleteProductWorkflow
+
+Id `product-edit-delete-product`. Stages a single `PRODUCT_DELETE` action.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `product_id` | `string` | The product to delete |
+| `created_by` | `string`, optional | The author. Scopes the pending check |
+| `auto_confirm` | `boolean`, optional | Defaults to `true` when the product is a `draft`, else `false` |
+
+No hooks. On confirm, the product and its offers are deleted.
+
+## Staging and resolution workflows
+
+These workflows create a change and move it through its statuses.
+
+### stageProductChangeWorkflow
+
+Id `stage-product-change`. Creates one `pending` change with the given actions, emits `product-change.created`, then runs `autoConfirmProductChangeWorkflow`. It doesn’t check for an open change.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `product_id` | `string` | The product the change targets |
+| `actions` | `Omit<CreateProductChangeActionDTO, "product_change_id">[]` | The actions to stage |
+| `created_by` | `string`, optional | The author. Also used as `confirmed_by` on auto-confirm |
+| `internal_note` | `string`, optional | Note for operators |
+| `external_note` | `string`, optional | Note for the seller |
+| `auto_confirm` | `boolean`, optional | Confirm and apply in the same run |
+
+No hooks. Returns the created `ProductChangeDTO`, without its actions.
+
+### createProductChangeWorkflow
+
+Id `create-product-change`. Creates `pending` changes without actions, after checking that none of the products has a pending change from the same author. When the batch spans several authors, the check covers every pending change on those products.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `changes` | `CreateProductChangeDTO[]` | `product_id`, plus optional notes, `created_by`, and `metadata` |
+| `additional_data` | `Record<string, unknown>`, optional | Passed to the `productChangeCreated` hook |
+
+Hooks: `validate` with `{ input }`, and `productChangeCreated` with `{ changes, additional_data }`. Emits `product-change.created` per change.
-| Workflow | Input | Purpose |
+### autoConfirmProductChangeWorkflow
+
+Id `auto-confirm-product-change`. Runs `confirmProductChangeWorkflow` when `force` is `true` or the `product_request` feature flag is off. Otherwise it does nothing.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `change_id` | `string` | The change to confirm |
+| `confirmed_by` | `string`, optional | Stamped on the change |
+| `force` | `boolean`, optional | Confirm regardless of the flag |
+
+### confirmProductChangeWorkflow
+
+Id `confirm-product-change`. Sets every change in `ids` to `confirmed`, runs `applyProductChangeActionsWorkflow`, and emits `product-change.confirmed` per change. Fails if any change is missing or not `pending`.
+
+| Input | Type | Description |
| --- | --- | --- |
-| `applyProductChangeActionsWorkflow` | `{ change_ids[] }` | Bucket not-yet-applied actions and dispatch them to product/variant workflows |
-| `applyProductAttributeChangeActionsWorkflow` | `{ product_id, add[], remove[], update[] }` | Apply the attribute batch for a change |
+| `ids` | `string[]` | The changes to confirm |
+| `confirmed_by` | `string`, optional | Stamped on each change |
+| `internal_note` | `string`, optional | Overwrites the operator note |
+| `external_note` | `string`, optional | Overwrites the seller note |
+| `additional_data` | `Record<string, unknown>`, optional | Passed to the `productChangeConfirmed` hook |
-## Edit helpers
+Hooks: `validate` with `{ input }`, and `productChangeConfirmed` with `{ ids, additional_data }`.
-High-level workflows that diff your input and stage the right actions for you.
+### rejectProductChangeWorkflow
-| Workflow | Input | Purpose |
+Id `reject-product-change`. Sets one `pending` change to `declined` and emits `product-change.declined`.
+
+| Input | Type | Description |
| --- | --- | --- |
-| `productEditUpdateProductWorkflow` | `{ product_id, update, created_by? }` | Diff and stage `UPDATE` actions per changed field |
-| `productEditUpdateVariantsWorkflow` | `{ product_id, ... }` | Stage `VARIANT_*` actions |
-| `productEditUpdateAttributesWorkflow` | `{ product_id, ... }` | Stage `ATTRIBUTE_*` actions |
-| `productEditDeleteProductWorkflow` | `{ product_id, ... }` | Stage a `PRODUCT_DELETE` action |
+| `id` | `string` | The change to decline |
+| `declined_by` | `string`, optional | Stamped on the change |
+| `declined_reason` | `string`, optional | Reason for the seller |
+| `additional_data` | `Record<string, unknown>`, optional | Passed to the `productChangeRejected` hook |
+
+Hooks: `validate` with `{ input }`, and `productChangeRejected` with `{ id, additional_data }`.
-## Audit-trail workflows
+### cancelProductChangeWorkflow
-| Workflow | Input | Purpose |
+Id `cancel-product-change`. Sets one `pending` change to `canceled` and emits `product-change.canceled`.
+
+| Input | Type | Description |
| --- | --- | --- |
-| `recordProductAuditChangeWorkflow` | `{ actor_id?, changes[] }` | Record already-`confirmed` audit changes (actions stored `applied`) |
-| `requestProductChangeWorkflow` | `{ product_id, message?, actor_id? }` | Record a `CHANGE_REQUESTED` revision request on a `proposed` product |
+| `id` | `string` | The change to cancel |
+| `canceled_by` | `string`, optional | Stamped on the change |
+| `additional_data` | `Record<string, unknown>`, optional | Passed to the `productChangeCanceled` hook |
+
+Hooks: `validate` with `{ input }`, and `productChangeCanceled` with `{ id, additional_data }`.
+
+## Apply workflows
+
+`confirmProductChangeWorkflow` runs these for you, so you rarely call them yourself.
+
+### applyProductChangeActionsWorkflow
+
+Id `apply-product-change-actions`. Input `{ change_ids: string[] }`. Loads the unapplied actions of the given changes, groups them by type, runs Medusa’s product and variant workflows, deletes the offers of deleted products, and marks the handled actions `applied`. No hooks, no events of its own.
+
+### applyProductAttributeChangeActionsWorkflow
+
+Id `apply-product-attribute-change-actions`. Input `{ product_id, add, remove, update }`. Runs `createAndLinkProductAttributesToProductWorkflow` when any array is non-empty. No hooks.
+
+## Audit workflows
+
+These workflows record history that doesn’t need review.
+
+### recordProductAuditChangeWorkflow
+
+Id `record-product-audit-change`. Creates changes that start `confirmed`, with `actor_id` as both `created_by` and `confirmed_by`, and stores every action with `applied: true`. It doesn’t touch the product and emits no event.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `actor_id` | `string`, optional | The actor to stamp |
+| `changes` | `array` | Each entry has `product_id`, `actions`, and optional `internal_note` and `external_note` |
+
+### requestProductChangeWorkflow
+
+Id `mercur-request-product-change`. Checks that the product is `proposed`, records a `CHANGE_REQUESTED` audit change with the message as `external_note`, and emits `product.change-requested`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `product_id` | `string` | The proposed product |
+| `message` | `string`, optional | What the seller should change |
+| `actor_id` | `string`, optional | The operator making the request |
+| `additional_data` | `Record<string, unknown>`, optional | Passed to the hook |
+
+Hooks: `productChangeRequested` with `{ product_id, message, additional_data }`.
+
+## Steps
+
+The module’s steps are exported from `@mercurjs/core/workflows` for your own workflows:
+
+- **Create**: `createProductChangesStep`, `createProductChangeActionsStep`, `addProductChangeActionStep`
+- **Resolve**: `confirmProductChangesStep`, `declineProductChangeStep`, `cancelProductChangeStep`
+- **Update**: `updateProductChangeActionsStep`, `applyVariantImageLinksStep`
+- **Validate**: `validateNoPendingProductChangeStep`, `validateProductChangeIsPendingStep`, `confirmProductChangeValidationStep`
-To work with records directly instead of through a workflow, see the
-[Service reference](/platform/product-edit/reference/service). To run side effects
-when a change resolves, see the
-[Event reference](/platform/product-edit/reference/events).
+The create, resolve, and `updateProductChangeActionsStep` steps compensate by deleting or restoring what they wrote. `applyVariantImageLinksStep` has no compensation, and the validation steps write nothing.
diff --git a/apps/docs/platform/review/concepts/product-vs-seller-reviews.mdx b/apps/docs/platform/review/concepts/product-vs-seller-reviews.mdx
index 16a06f8f5..fd57697a3 100644
--- a/apps/docs/platform/review/concepts/product-vs-seller-reviews.mdx
+++ b/apps/docs/platform/review/concepts/product-vs-seller-reviews.mdx
@@ -1,63 +1,64 @@
---
-title: "Product vs seller reviews"
+title: "Product reviews and store reviews"
sidebarTitle: "Product vs seller reviews"
-description: "The reference discriminator and the links that anchor each review."
+description: "How the reference field picks a review's target, and the four links that anchor every review."
---
-This page covers how one review model serves two targets and how each review is
-anchored to the rest of the marketplace.
+A customer can rate the product they bought, the store that sold it, or both. Mercur uses one `Review` model for both cases and sets `reference` to `product` or `seller` to say which one a review rates. The target itself is stored as a module link, written when the review is created, alongside links to the order and the customer.
-## Reference
+## The reference field picks the link
-The `reference` field on the `Review` model decides what a review is about. It's
-an enum with two values, `product` and `seller`, and it works together with the
-review's link to the target record. There is no polymorphic id column on the
-model itself; the target is resolved through a module link.
+You pass `reference` and `reference_id` to `createReviewWorkflow`. The workflow stores `reference` on the review, then writes one link from `reference_id` to the review:
+
+| `reference` | `reference_id` is | Link written |
+| --- | --- | --- |
+| `product` | A product id, such as `prod_01JD8Q1234567` | Product to review |
+| `seller` | A seller id, such as `sel_01JD8Q1234567` | Seller to review |
+
+`reference_id` isn’t stored on the review. To read the target back, follow the relation that matches `reference`:
```ts
-// A product review
-{ reference: "product", reference_id: "prod_123", rating: 5 }
+const { data: [review] } = await query.graph({
+ entity: "review",
+ fields: ["id", "reference", "rating", "product.title", "seller.name"],
+ filters: { id: "rev_01JD8Q1234567" },
+})
-// A seller review
-{ reference: "seller", reference_id: "sel_123", rating: 4 }
+const target = review.reference === "product"
+ ? review.product
+ : review.seller
```
-When a review is created, the `reference` value selects which link is written:
-`reference: "product"` links the review to a product, and `reference: "seller"`
-links it to a seller. Reading a review back, you follow the matching relation
-(`review.product` or `review.seller`) to reach its target.
+Only one of `review.product` and `review.seller` is set on any review.
<Note>
- Products are the shared master catalog, not seller-owned. A **product** review
- rates the master product; a **seller** review rates the store. They are
- independent. A customer can leave both for the same order.
+ Products are Mercur’s shared master catalog, not owned by a store. A product review rates the master product, so it has no link to the store that sold it. Only seller reviews are linked to a seller.
</Note>
-## Order & customer links
+## Every review links to its order and customer
-Beyond its target, every review is anchored to the order that earned it and the
-customer who wrote it. Creating a review writes two more links, one to the
-`Order` and one to the `Customer`, so a review always has a verifiable purchase
-behind it.
+Apart from its target, each review is linked to the order that earned it and the customer who wrote it. The `create-review` step writes both links in the same step that creates the record. These links back the ownership checks across the APIs:
-```ts
-// resolved through the customer link when listing a customer's own reviews
-const { data } = await query.graph({
- entity: "customer_customer_review_review",
- fields: ["review.*"],
- filters: { customer_id: "cus_123" },
-})
-```
+- **Store API**: a customer can read, edit, and delete only reviews linked to their customer id
+- **Vendor API**: a store can list, read, and answer only reviews linked to its seller id
+- **Validation**: duplicate checks look up existing reviews through the order link
-## One review per target, per order
+## Stores see only seller reviews
-Because a review is tied to an order, the create flow enforces that a customer
-can leave **at most one review per target per order**. Submitting a second review
-for the same `reference` and `reference_id` on the same order is rejected. The
-order must also belong to the customer submitting the review.
+Because product reviews carry no seller link, the Vendor API never returns them. `GET /vendor/reviews` filters on the seller link, and answering a review checks the same link. A store can’t answer a review of a product it sells: only an operator can, through the Admin API.
+
+## One review per target per order
+
+`createReviewWorkflow` rejects a second review of the same target from the same order. It loads every review linked to `order_id` and fails with “Review already exists” when one has the same `reference` and the same target id. It also fails with “Order not found!” when the order doesn’t belong to `customer_id`.
<Tip>
- A single order can still produce several reviews, one per distinct target. For
- example, a customer may review the master product *and* the store that
- fulfilled it from the same order.
+ One order can back several reviews, one per distinct target. A customer can rate the master product and the store from the same order, as order `#1001` does in the overview figure.
</Tip>
+
+The workflow doesn’t check that `reference_id` appears in the order. A customer with any order can review any product or seller id. Add that check in your own route if your marketplace needs it.
+
+## Related
+
+- [The four review links and their query.graph aliases](/platform/review/reference/links)
+- [Respond to a review as a store](/platform/review/guides/respond-to-a-review)
+- [What a review stores](/platform/review/concepts/the-review-model)
diff --git a/apps/docs/platform/review/concepts/ratings-and-moderation.mdx b/apps/docs/platform/review/concepts/ratings-and-moderation.mdx
index 2e8f0ed05..3a14a7947 100644
--- a/apps/docs/platform/review/concepts/ratings-and-moderation.mdx
+++ b/apps/docs/platform/review/concepts/ratings-and-moderation.mdx
@@ -1,64 +1,65 @@
---
-title: "Ratings & moderation"
+title: "How reviews are moderated and rated"
sidebarTitle: "Ratings & moderation"
-description: "The review status lifecycle, store responses, and aggregate ratings."
+description: "The review status values, who can change them, how a store answers, and how average ratings are computed."
---
-This page covers how a review moves from submission to a public rating, and how
-per-product and per-seller averages are computed.
+A review reaches shoppers only after an operator approves it, and a store can add one public answer. Moderation is a change to the review’s `status` field, an answer is a write to its `seller_note`, and removal is a soft delete. Average ratings aren’t stored anywhere: the Review module service computes them from the review rows each time you ask.
-## Status
+## Status values
-A review's state is held in the `status` field of the `Review` model. A review
-moves through three statuses:
-
-```
- ┌──────────┐ publish ┌────────────┐
- │ pending │───────────►│ published │
- └────┬─────┘ └────────────┘
- │ reject
- ▼
- ┌────────────┐
- │ rejected │
- └────────────┘
-```
+A review’s `status` holds one of three values. Every review starts as `pending`, and only `updateReviewWorkflow` changes it.
| Status | Meaning |
| --- | --- |
-| `pending` | Submitted, awaiting moderation. The default on creation |
-| `published` | Approved and visible on the storefront |
-| `rejected` | Declined by a moderator |
+| `pending` | Submitted and waiting for an operator. The default |
+| `published` | Approved for display |
+| `rejected` | Declined by an operator |
+
+<img className="block dark:hidden" src="/images/figures/review-moderation-light.svg" alt="Behind, a review record. In front, the changes each workflow makes: updateReviewWorkflow moves status between pending, published, and rejected in any direction, respondReviewWorkflow sets seller_note once, and deleteReviewWorkflow sets deleted_at." />
+<img className="hidden dark:block" src="/images/figures/review-moderation-dark.svg" alt="Behind, a review record. In front, the changes each workflow makes: updateReviewWorkflow moves status between pending, published, and rejected in any direction, respondReviewWorkflow sets seller_note once, and deleteReviewWorkflow sets deleted_at." />
+
+The workflow enforces no order between statuses. An operator can publish a rejected review or move a published one back to `pending`. Who can set the status depends on the API:
+
+- **Admin API**: `POST /admin/reviews/:id` sets `status`, `rating`, and `customer_note`
+- **Vendor API**: a store can’t change `status` or `rating`; the respond route ignores both fields
+- **Store API**: a customer can edit `rating` and `customer_note`, but not `status`
-A review is created as `pending`. Moderation moves it to `published` or
-`rejected` by updating the `status` field. See
-[Moderate a review](/platform/review/guides/moderate-a-review).
+<Warning>
+ A customer edit doesn’t reset a published review to `pending`. If edited reviews should go back through moderation, wrap the Store route or `updateReviewWorkflow` and set the status yourself.
+</Warning>
-## Store responses
+## Store answers
-A store can attach a single public response to any of its reviews. The response
-lives in the `seller_note` field and is added through a dedicated respond flow,
-which refuses to overwrite an existing response.
+A store answers a review by writing `seller_note` through `respondReviewWorkflow`. The workflow refuses a second answer: it fails when `seller_note` is already set, so the first answer stays until someone clears it with `updateReviewWorkflow`. Answering never touches `status`, so a store can answer a `pending` review before it’s published.
-<Note>
- Responding is separate from moderation. A store adds its `seller_note`, while
- the `status` transition (`published` / `rejected`) stays an operator decision.
-</Note>
+Over HTTP, a store answers with `POST /vendor/reviews/:id`, which only accepts reviews linked to that store, so only seller reviews. An operator answers any review with `POST /admin/reviews/:id/respond`.
-## Aggregate ratings
+## Deletion is soft
-The module service computes average ratings on demand rather than storing a
-denormalized column. `getAvgRating` returns the average for a single product or
-seller, and `getProductsWithRating` / `getSellersWithRating` return records with
-their average rating joined in for list views.
+`deleteReviewWorkflow` soft deletes the review: it sets `deleted_at` and keeps the row and its links. `query.graph` and the APIs stop returning it, and the workflow restores it if a later step fails. Operators delete with `DELETE /admin/reviews/:id`, and customers delete their own reviews with `DELETE /store/reviews/:id`.
+
+## Average ratings are computed on read
+
+The service’s rating helpers run an `AVG(rating)` query over the review table, joined through the product or seller link table. There’s no stored average to keep in sync. The helpers apply no filters beyond the target, which affects what counts:
+
+- **Every status counts**: `pending` and `rejected` reviews are part of the average
+- **Soft deleted reviews count**: the query doesn’t check `deleted_at`, and the link rows stay in place
+- **No reviews**: `getAvgRating` returns `null`
```ts
-const service = container.resolve(MercurModules.REVIEW)
+const reviewService = container.resolve(MercurModules.REVIEW)
-const avg = await service.getAvgRating("seller", "sel_123")
+const average = await reviewService.getAvgRating(
+ "seller",
+ "sel_01JD8Q1234567"
+)
```
-<Tip>
- Because averages are computed at query time, they always reflect the current
- set of reviews. There's no cache to invalidate when a review is added, removed,
- or moderated.
-</Tip>
+This returns the store’s average as a numeric string, such as `"4.5000000000000000"`, or `null`. When only published reviews should count, compute the average from `query.graph` results instead, as shown in [Compute aggregate ratings](/platform/review/guides/compute-aggregate-ratings).
+
+## Related
+
+- [Moderate a review from server code](/platform/review/guides/moderate-a-review)
+- [Respond to a review](/platform/review/guides/respond-to-a-review)
+- [Rating helper signatures](/platform/review/reference/service)
diff --git a/apps/docs/platform/review/concepts/the-review-model.mdx b/apps/docs/platform/review/concepts/the-review-model.mdx
index f7f29be41..395a6b7b9 100644
--- a/apps/docs/platform/review/concepts/the-review-model.mdx
+++ b/apps/docs/platform/review/concepts/the-review-model.mdx
@@ -1,56 +1,63 @@
---
-title: "The review model"
+title: "What a review stores"
sidebarTitle: "The review model"
-description: "The single review entity, its rating, notes, and moderation status."
+description: "The fields of a review: its target type, rating, the customer's note, the store's answer, and its status."
---
-This page covers the review record and the fields that make up a rating.
+A review is one customer’s rating of one product or one store, earned by an order. Mercur stores it as a single `Review` record (table `review`, id prefix `rev`) in the Review module. Knowing its fields tells you what a review can hold, what a store can add to it, and what an operator changes when moderating it.
-## Review
+## One record per rating
-A review is a customer's rating of a single target, either a product or a seller.
-It's represented by the `Review` data model (table `review`, id prefix `rev`). It
-holds the numeric rating, an optional customer note, an optional store response,
-and the moderation status.
+Every review has the same shape, whatever it rates. The record holds the score and the text around it, while the product, store, order, and customer it belongs to live in module links rather than columns.
+
+| Field | Holds |
+| --- | --- |
+| `id` | The review id, such as `rev_01JD8Q1234567` |
+| `display_id` | An auto-incrementing number for people to read |
+| `reference` | The target type: `product` or `seller` |
+| `rating` | The score as an integer |
+| `customer_note` | The customer’s text, or `null` |
+| `seller_note` | The store’s answer, or `null` |
+| `status` | `pending`, `published`, or `rejected` |
+
+A review has no `product_id` or `seller_id` column. The `reference` value tells you which link to follow, as covered in [Product vs seller reviews](/platform/review/concepts/product-vs-seller-reviews).
+
+## Ratings are integers from 1 to 5 at the API
+
+The `rating` column is an integer with no range check in the model itself. The Store and Admin API validators accept whole numbers from 1 to 5, so every review created over HTTP falls in that range:
+
+- **Store API**: `rating` is required on create and update, and must be an integer from 1 to 5
+- **Admin API**: `rating` is optional on update, with the same 1 to 5 range
+- **Workflows**: `createReviewWorkflow` and `updateReviewWorkflow` store whatever number you pass
+
+<Warning>
+ When you run the workflows from your own code, validate `rating` yourself. A value outside 1 to 5 is stored as is and skews every average that includes it.
+</Warning>
+
+## Two notes, two authors
+
+A review keeps the two sides of the conversation in separate fields. The customer writes `customer_note` when they submit or edit the review, and the store writes `seller_note` once, through `respondReviewWorkflow`. Both are nullable text fields marked searchable, so a `q` search in the Admin and Vendor APIs matches their content.
```ts
-const { result } = await createReviewWorkflow(container).run({
- input: {
- order_id: "order_123",
- reference: "product",
- reference_id: "prod_123",
- rating: 5,
- customer_note: "Exactly as described, fast shipping.",
- customer_id: "cus_123",
- },
-})
+const review = {
+ id: "rev_01JD8Q1234567",
+ display_id: 1042,
+ reference: "product",
+ rating: 4,
+ customer_note: "Fits well, the colour is darker than shown.",
+ seller_note: "Thanks, we've updated the product photos.",
+ status: "published",
+}
```
-Every review carries the same shape regardless of what it targets:
+This is the shape `query.graph` returns for a review’s own fields. The Store API caps `customer_note` at 300 characters, the Admin API at 1000, and both APIs cap `seller_note` at 300.
-| Field | Purpose |
-| --- | --- |
-| `rating` | The numeric score the customer gave |
-| `reference` | Whether the review is about a `product` or a `seller` |
-| `customer_note` | The customer's optional free-text note |
-| `seller_note` | The store's optional public response |
-| `status` | The moderation state: `pending`, `published`, or `rejected` |
-| `display_id` | A human-readable auto-incrementing number |
-
-<Note>
- There is no separate table for product reviews and seller reviews. A single
- `Review` row is discriminated by its `reference` field. See
- [Product vs seller reviews](/platform/review/concepts/product-vs-seller-reviews).
-</Note>
-
-## Notes
-
-A review separates the two sides of the conversation into two nullable text
-fields. `customer_note` is written by the customer when they submit the review;
-`seller_note` is the store's single response, added later through the respond
-flow. Both are searchable so operators can find reviews by their content.
-
-<Tip>
- A store can respond **once**. The respond flow refuses to overwrite an existing
- `seller_note`. To change a response, clear it first.
-</Tip>
+## Status starts at pending
+
+Every new review gets `status: "pending"`, the model default. An operator then sets it to `published` or `rejected` with `updateReviewWorkflow`. Nothing in core hides a pending review from a storefront for you, since core has no public review listing: your own route decides which statuses to show. See [Ratings and moderation](/platform/review/concepts/ratings-and-moderation) for the full set of changes.
+
+## Related
+
+- [How reviews pick their target](/platform/review/concepts/product-vs-seller-reviews)
+- [Every field and index of the Review model](/platform/review/reference/data-models)
+- [Create a review from a custom route](/platform/review/guides/create-a-review)
diff --git a/apps/docs/platform/review/guides/compute-aggregate-ratings.mdx b/apps/docs/platform/review/guides/compute-aggregate-ratings.mdx
index b2f098836..a86acfecd 100644
--- a/apps/docs/platform/review/guides/compute-aggregate-ratings.mdx
+++ b/apps/docs/platform/review/guides/compute-aggregate-ratings.mdx
@@ -1,57 +1,82 @@
---
-title: "Compute aggregate ratings"
+title: "Show average ratings on your storefront"
sidebarTitle: "Aggregate ratings"
-description: "Compute average ratings for products and sellers from server code."
+description: "Serve average ratings for products and stores from a custom route, with the service helpers or from published reviews only."
---
-In this guide, you'll learn how to compute average ratings for products and
-sellers from your own server code. This is useful when surfacing a rating on a
-storefront page or in a custom API route.
+Add a Store API route that returns a product’s or a store’s average rating, because core ships no public rating endpoint. You can call the Review module service’s rating helpers, which average every linked review, or compute the average from published reviews with `query.graph`.
-The Review module service computes averages on demand instead of storing a
-denormalized column, so the numbers always reflect the current set of reviews.
-Resolve the service from the container to use its rating helpers.
+## Before you begin
-## Average for one target
+Pick the approach that matches what should count toward the number:
-`getAvgRating` returns the average rating for a single product or seller:
+- **Rating helpers**: one SQL query per call; counts `pending`, `rejected`, and soft deleted reviews too
+- **Published only**: loads the target’s reviews with `query.graph` and averages the `published` ones
-```ts title="src/api/custom/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { MercurModules } from "@mercurjs/types"
+<Steps>
+ <Step title="Return a store's average from the service">
+ Resolve the service with `MercurModules.REVIEW` and call `getAvgRating`:
-export async function GET(req: MedusaRequest, res: MedusaResponse) {
- const reviewModuleService = req.scope.resolve(MercurModules.REVIEW)
+ ```ts title="src/api/store/sellers/[id]/rating/route.ts"
+ import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+ import { MercurModules } from "@mercurjs/types"
- const rating = await reviewModuleService.getAvgRating("seller", "sel_123")
+ export async function GET(req: MedusaRequest, res: MedusaResponse) {
+ const reviewService = req.scope.resolve(MercurModules.REVIEW)
- res.json({ rating })
-}
-```
+ const average = await reviewService.getAvgRating("seller", req.params.id)
+
+ res.json({ rating: average === null ? null : Number(average) })
+ }
+ ```
+
+ The first argument is `"product"` or `"seller"`, the second the target’s id. The method returns a numeric string, or `null` when the target has no reviews, so the route converts it to a number.
+ </Step>
+ <Step title="Average published reviews only">
+ Load the product’s linked reviews with `query.graph` and average the published ones:
+
+ ```ts title="src/api/store/products/[id]/rating/route.ts"
+ import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+ import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
-The first argument is the target type (`"product"` or `"seller"`), the second is
-its id. The method returns `null` when the target has no reviews yet.
+ export async function GET(req: MedusaRequest, res: MedusaResponse) {
+ const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
+ const { data: [product] } = await query.graph({
+ entity: "product",
+ fields: ["id", "reviews.rating", "reviews.status"],
+ filters: { id: req.params.id },
+ })
-## Ratings for a list
+ const ratings = (product?.reviews ?? [])
+ .filter((review) => review?.status === "published")
+ .map((review) => review!.rating)
+ const rating = ratings.length
+ ? ratings.reduce((sum, value) => sum + value, 0) / ratings.length
+ : null
-For list views, `getProductsWithRating` and `getSellersWithRating` return records
-with their average rating joined in, so you don't fan out a call per row:
+ res.json({ rating, count: ratings.length })
+ }
+ ```
+
+ `reviews` is the alias the product to review link adds to a product. Soft deleted reviews don’t come back from `query.graph`, so they never count.
+ </Step>
+</Steps>
+
+## Rate every product or store in one query
+
+For list pages, `getProductsWithRating` and `getSellersWithRating` return every row of the `product` or `seller` table with its average joined in:
```ts
-const reviewModuleService = container.resolve(MercurModules.REVIEW)
+const reviewService = container.resolve(MercurModules.REVIEW)
-const sellers = await reviewModuleService.getSellersWithRating([
- "id",
- "name",
-])
-// => [{ id, name, rating }, ...]
+const sellers = await reviewService.getSellersWithRating(["id", "name"])
+// [{ id: "sel_01JD8Q1234567", name: "ACME", rating: "4.5000000000000000" }]
```
-Pass the fields you want selected from the target table; each returned record
-gains a `rating` field with the average.
+Pass column names of the target table. Each row gains a `rating` string, or `null` for rows without reviews. The helpers take no filters or pagination and include soft deleted products and sellers, so filter the result before you return it.
+
+## Next steps
-<Tip>
- These helpers average across a target's linked reviews. Combine them with your
- own `status` filter if you only want `published` reviews to count toward the
- public number.
-</Tip>
+- [Learn what the rating helpers count](/platform/review/concepts/ratings-and-moderation)
+- [See every service method](/platform/review/reference/service)
+- [Query reviews through their links](/platform/review/reference/links)
diff --git a/apps/docs/platform/review/guides/create-a-review.mdx b/apps/docs/platform/review/guides/create-a-review.mdx
index 05a57f464..ef323063f 100644
--- a/apps/docs/platform/review/guides/create-a-review.mdx
+++ b/apps/docs/platform/review/guides/create-a-review.mdx
@@ -1,55 +1,125 @@
---
-title: "Create a review"
+title: "Create a review from your own route"
sidebarTitle: "Create a review"
-description: "Create a review programmatically with createReviewWorkflow."
+description: "Run createReviewWorkflow from a custom API route, an import script, or a seed."
---
-In this guide, you'll learn how to create a review from your own server code. This
-is useful in a custom storefront route, an import script, or a seed.
+Run `createReviewWorkflow` to create a review outside the built-in `POST /store/reviews` route, for example in a custom checkout follow-up, an import script, or a seed. The workflow validates the order, creates the review as `pending`, and writes its four links.
-Mercur exposes a `createReviewWorkflow` that validates the submission, creates the
-`Review` record, and links it to its target, order, and customer in one step. Run
-it from any place that has access to the Medusa container.
+## Before you begin
-## Run the workflow
+You need the following:
-```ts title="src/api/custom/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { createReviewWorkflow } from "@mercurjs/core/workflows"
+- **A customer and an order**: the order’s `customer_id` must match the customer you pass
+- **A target id**: a product id for a product review, or a seller id for a store review
+- **Mercur core installed**: the Review module ships in `@mercurjs/core`, so there’s nothing else to register
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
- const { result } = await createReviewWorkflow(req.scope).run({
- input: {
- order_id: "order_123",
- reference: "product",
- reference_id: "prod_123",
- rating: 5,
- customer_note: "Exactly as described.",
- customer_id: "cus_123",
- },
- })
+<Steps>
+ <Step title="Add the route">
+ Create a route that reads the signed-in customer and runs the workflow:
- res.status(201).json({ review: result })
+ ```ts title="src/api/store/order-reviews/route.ts" {14-22}
+ import type {
+ AuthenticatedMedusaRequest,
+ MedusaResponse,
+ } from "@medusajs/framework/http"
+ import { createReviewWorkflow } from "@mercurjs/core/workflows"
+
+ type Body = { order_id: string; product_id: string; rating: number }
+
+ export async function POST(
+ req: AuthenticatedMedusaRequest<Body>,
+ res: MedusaResponse
+ ) {
+ const { order_id, product_id, rating } = req.body
+ const { result } = await createReviewWorkflow(req.scope).run({
+ input: {
+ order_id,
+ reference: "product",
+ reference_id: product_id,
+ rating,
+ customer_id: req.auth_context.actor_id,
+ },
+ })
+
+ res.status(201).json({ review: result })
+ }
+ ```
+
+ The route always creates a product review. Pass `reference: "seller"` with a seller id in `reference_id` to rate a store instead. `customer_note` is optional and defaults to `null`.
+ </Step>
+ <Step title="Require a signed-in customer">
+ Custom `/store` routes aren’t authenticated by default. Add the `authenticate` middleware so `auth_context.actor_id` holds the customer id:
+
+ ```ts title="src/api/middlewares.ts"
+ import { authenticate, defineMiddlewares } from "@medusajs/framework/http"
+
+ export default defineMiddlewares({
+ routes: [
+ {
+ method: ["POST"],
+ matcher: "/store/order-reviews",
+ middlewares: [authenticate("customer", ["session", "bearer"])],
+ },
+ ],
+ })
+ ```
+
+ This is the same middleware the built-in Store review routes use.
+ </Step>
+ <Step title="Call the route">
+ Send a request as the customer who placed the order:
+
+ ```bash
+ curl -X POST http://localhost:9000/store/order-reviews \
+ -H "Authorization: Bearer your_customer_token" \
+ -H "x-publishable-api-key: your_publishable_key" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "order_id": "order_01JD8Q1234567",
+ "product_id": "prod_01JD8Q1234568",
+ "rating": 5
+ }'
+ ```
+
+ The response holds the new review with `status: "pending"`.
+ </Step>
+</Steps>
+
+## Validate the rating and the target
+
+`createReviewWorkflow` checks only that the order belongs to the customer and that the order hasn’t reviewed this target yet. It stores any `rating` you pass and doesn’t check that the product or seller was part of the order. Validate both before you run it:
+
+```ts title="src/api/store/order-reviews/route.ts"
+if (!Number.isInteger(rating) || rating < 1 || rating > 5) {
+ throw new MedusaError(MedusaError.Types.INVALID_DATA, "Invalid rating")
+}
+
+const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
+const { data: [order] } = await query.graph({
+ entity: "order",
+ fields: ["items.product_id"],
+ filters: { id: order_id },
+})
+
+if (!order?.items?.some((item) => item?.product_id === product_id)) {
+ throw new MedusaError(MedusaError.Types.NOT_ALLOWED, "Not in order")
}
```
-The `reference` field selects the target: pass `"product"` with a product id, or
-`"seller"` with a seller id, in `reference_id`.
+Import `MedusaError` and `ContainerRegistrationKeys` from `@medusajs/framework/utils`. Put this block before the workflow call.
+
+## Handle a rejected submission
+
+The workflow throws a `MedusaError` with type `INVALID_DATA` in two cases, and Medusa returns them as `400` responses:
-<Note>
- The workflow validates that the `order_id` belongs to `customer_id` and that
- the customer hasn't already reviewed the same target on that order. Either
- check failing raises an error and no review is created.
-</Note>
+- **“Order not found!”**: the order doesn’t exist or belongs to another customer
+- **“Review already exists”**: this order already has a review with the same `reference` and target id
-## Statuses on creation
+When either check fails, nothing is written. If a later step fails, the workflow deletes the review it created.
-A new review is created as `pending` and stays hidden until it's moderated. See
-[Moderate a review](/platform/review/guides/moderate-a-review) to publish or
-reject it.
+## Next steps
-<Tip>
- A single order can back several reviews, one per distinct target. Create the
- product review and the seller review as two separate calls with different
- `reference` / `reference_id` values.
-</Tip>
+- [Moderate the new review](/platform/review/guides/moderate-a-review)
+- [Check createReviewWorkflow’s steps and input](/platform/review/reference/workflows)
+- [Learn how reference picks the target](/platform/review/concepts/product-vs-seller-reviews)
diff --git a/apps/docs/platform/review/guides/moderate-a-review.mdx b/apps/docs/platform/review/guides/moderate-a-review.mdx
index c4189ae9c..46fe38abc 100644
--- a/apps/docs/platform/review/guides/moderate-a-review.mdx
+++ b/apps/docs/platform/review/guides/moderate-a-review.mdx
@@ -1,58 +1,104 @@
---
-title: "Moderate a review"
+title: "Publish, reject, and delete reviews in code"
sidebarTitle: "Moderate a review"
-description: "Publish, reject, and delete reviews from server code."
+description: "Set a review's status with updateReviewWorkflow and remove it with deleteReviewWorkflow."
---
-In this guide, you'll learn how to moderate reviews from your own server code.
-Moderation is a change to the review's `status`; removal is a soft delete that
-can be undone.
+Moderate reviews from your own code when the Admin API doesn’t fit, for example to auto-publish high ratings or to reject reviews flagged by a spam filter. Moderation is an `updateReviewWorkflow` run that sets `status`, and removal is a `deleteReviewWorkflow` run that soft deletes the review.
-## Publish or reject
+<Steps>
+ <Step title="Set the status">
+ Run `updateReviewWorkflow` with the review id and the new status:
-Move a `pending` review to `published` or `rejected` with `updateReviewWorkflow`,
-setting the `status` field:
+ ```ts title="src/api/admin/review-moderation/[id]/route.ts" {13-15}
+ import type {
+ AuthenticatedMedusaRequest,
+ MedusaResponse,
+ } from "@medusajs/framework/http"
+ import { updateReviewWorkflow } from "@mercurjs/core/workflows"
-```ts title="src/api/custom/moderate/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+ type Body = { status: "published" | "rejected" }
+
+ export async function POST(
+ req: AuthenticatedMedusaRequest<Body>,
+ res: MedusaResponse
+ ) {
+ const { result } = await updateReviewWorkflow(req.scope).run({
+ input: { id: req.params.id, status: req.body.status },
+ })
+
+ res.json({ review: result })
+ }
+ ```
+
+ Routes under `/admin` require an authenticated admin user by default. The workflow returns the updated review.
+ </Step>
+ <Step title="Delete a review">
+ Add a `DELETE` handler to the same file that runs `deleteReviewWorkflow` with the review id as its whole input:
+
+ ```ts title="src/api/admin/review-moderation/[id]/route.ts"
+ import { deleteReviewWorkflow } from "@mercurjs/core/workflows"
+
+ export async function DELETE(
+ req: AuthenticatedMedusaRequest,
+ res: MedusaResponse
+ ) {
+ await deleteReviewWorkflow(req.scope).run({ input: req.params.id })
+
+ res.json({ id: req.params.id, object: "review", deleted: true })
+ }
+ ```
+
+ The review gets a `deleted_at` timestamp. Its row and its four links stay in the database.
+ </Step>
+</Steps>
+
+## Publish reviews automatically
+
+Run the moderation from a subscriber to publish reviews without an operator. The module emits `review.review.created` with the new review’s id, so you can load the review and decide:
+
+```ts title="src/subscribers/auto-publish-reviews.ts"
+import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+import { MercurModules } from "@mercurjs/types"
import { updateReviewWorkflow } from "@mercurjs/core/workflows"
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
- await updateReviewWorkflow(req.scope).run({
- input: {
- id: req.params.id,
- status: "published",
- },
- })
+export default async function autoPublish({
+ event,
+ container,
+}: SubscriberArgs<{ id: string }>) {
+ const reviewService = container.resolve(MercurModules.REVIEW)
+ const review = await reviewService.retrieveReview(event.data.id)
- res.sendStatus(200)
+ if (review.rating >= 4) {
+ await updateReviewWorkflow(container).run({
+ input: { id: review.id, status: "published" },
+ })
+ }
}
+
+export const config: SubscriberConfig = { event: "review.review.created" }
```
-`updateReviewWorkflow` also accepts `rating`, `customer_note`, and `seller_note`,
-so the same workflow is used for any correction to a review. It captures the
-previous values for compensation, so a failure downstream rolls the record back.
+This publishes every review rated 4 or 5 and leaves the rest `pending` for an operator. See the [Events reference](/platform/review/reference/events) for the payload.
-## Delete a review
+## Correct a review’s content
-Remove a review with `deleteReviewWorkflow`. This is a **soft delete**. The row
-is retained and restored automatically if the workflow is rolled back:
+`updateReviewWorkflow` also accepts `rating`, `customer_note`, and `seller_note`. Use it to fix a rating, redact a note, or clear a store’s answer:
```ts
-import { deleteReviewWorkflow } from "@mercurjs/core/workflows"
-
-await deleteReviewWorkflow(container).run({ input: "rev_123" })
+await updateReviewWorkflow(container).run({
+ input: { id: "rev_01JD8Q1234567", customer_note: null },
+})
```
-<Warning>
- A soft-deleted review stops counting toward aggregate ratings, but its row (and
- its links) are kept. Use a hard delete through the service only if you need the
- record gone permanently.
-</Warning>
+The workflow saves the previous `rating`, `customer_note`, `seller_note`, and `status` before it writes, and restores them if a later step fails.
+
+## Account for soft deleted reviews in averages
+
+A soft deleted review disappears from `query.graph` and the APIs, but the service’s rating helpers still count it, because their query doesn’t check `deleted_at`. Compute averages with `query.graph` if deletions must change the number, as shown in [Compute aggregate ratings](/platform/review/guides/compute-aggregate-ratings).
-## React to moderation
+## Next steps
-To run your own side effects when a review is published or rejected, wrap
-`updateReviewWorkflow` in a route that also runs your follow-up logic, or add a
-hook. See the [Events reference](/platform/review/reference/events) for the
-current state of review-domain events.
+- [Let the store answer the review](/platform/review/guides/respond-to-a-review)
+- [Learn which status changes are allowed](/platform/review/concepts/ratings-and-moderation)
+- [Check updateReviewWorkflow’s input](/platform/review/reference/workflows)
diff --git a/apps/docs/platform/review/guides/respond-to-a-review.mdx b/apps/docs/platform/review/guides/respond-to-a-review.mdx
index 64665577d..cb4571abe 100644
--- a/apps/docs/platform/review/guides/respond-to-a-review.mdx
+++ b/apps/docs/platform/review/guides/respond-to-a-review.mdx
@@ -1,61 +1,106 @@
---
-title: "Respond to a review"
+title: "Answer a review as a store"
sidebarTitle: "Respond to a review"
-description: "Attach a store's public response with respondReviewWorkflow."
+description: "Attach a store's public answer to a review with respondReviewWorkflow."
---
-In this guide, you'll learn how to attach a store's response to a review from your
-own server code. A response is a single public note the store adds to a review it
-received.
+Run `respondReviewWorkflow` to attach a store’s answer to a review, for example from a custom vendor route or a support tool. The workflow writes `seller_note` once and refuses to overwrite an existing answer.
-## Run the workflow
+## Before you begin
-`respondReviewWorkflow` writes the `seller_note` on an existing review:
+Check which reviews a store may answer before you build on this workflow:
-```ts title="src/api/custom/respond/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { respondReviewWorkflow } from "@mercurjs/core/workflows"
+- **Seller reviews only**: product reviews have no seller link, so the built-in Vendor API can’t reach them
+- **One answer per review**: a second call fails until `seller_note` is cleared
+- **No status change**: answering leaves `status` as it is
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
- await respondReviewWorkflow(req.scope).run({
- input: {
- id: req.params.id,
- seller_note: "Thanks for the feedback, glad it arrived quickly!",
- },
- })
+<Steps>
+ <Step title="Check that the review belongs to the store">
+ Look up the seller link before you write. The built-in Vendor route runs the same check:
- res.sendStatus(200)
-}
-```
+ ```ts title="src/api/vendor/review-answers/[id]/helpers.ts"
+ import { MedusaContainer } from "@medusajs/framework"
+ import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
-<Note>
- A store can respond **once**. The workflow throws if the review already has a
- `seller_note`, and it throws `NOT_FOUND` if the review id doesn't exist. It
- captures the previous value so a rollback clears the response again.
-</Note>
+ export async function storeOwnsReview(
+ scope: MedusaContainer,
+ sellerId: string,
+ reviewId: string
+ ) {
+ const query = scope.resolve(ContainerRegistrationKeys.QUERY)
+ const { data } = await query.graph({
+ entity: "seller_seller_review_review",
+ fields: ["review_id"],
+ filters: { seller_id: sellerId, review_id: reviewId },
+ })
-## Clearing a response
+ return data.length > 0
+ }
+ ```
-The respond flow won't overwrite an existing note. To replace a response, first
-clear it with `updateReviewWorkflow`, then respond again:
+ `seller_seller_review_review` is the link table between sellers and reviews.
+ </Step>
+ <Step title="Run the workflow">
+ Call `respondReviewWorkflow` with the review id and the answer:
-```ts
-import {
- updateReviewWorkflow,
- respondReviewWorkflow,
-} from "@mercurjs/core/workflows"
+ ```ts title="src/api/vendor/review-answers/[id]/route.ts" {16-18}
+ import type {
+ AuthenticatedMedusaRequest,
+ MedusaResponse,
+ } from "@medusajs/framework/http"
+ import { MedusaError } from "@medusajs/framework/utils"
+ import { respondReviewWorkflow } from "@mercurjs/core/workflows"
+ import { storeOwnsReview } from "./helpers"
+
+ export async function POST(req: AuthenticatedMedusaRequest<{
+ seller_note: string
+ }>, res: MedusaResponse) {
+ const sellerId = req.seller_context!.seller_id
+ if (!(await storeOwnsReview(req.scope, sellerId, req.params.id))) {
+ throw new MedusaError(MedusaError.Types.NOT_FOUND, "Review not found")
+ }
+ const { result } = await respondReviewWorkflow(req.scope).run({
+ input: { id: req.params.id, seller_note: req.body.seller_note },
+ })
+
+ res.json({ review: result })
+ }
+ ```
+
+ Mercur fills `req.seller_context` on `/vendor` routes with the signed-in member’s current store.
+ </Step>
+</Steps>
+
+## Handle a second answer
+
+`respondReviewWorkflow` throws in two cases:
+- **`NOT_FOUND`, “Review not found”**: no review has this id
+- **`NOT_ALLOWED`, “This review already has a response”**: `seller_note` is already set
+
+The built-in routes return `400` for the second case. If a later step fails after the write, the workflow sets `seller_note` back to `null`.
+
+## Replace an existing answer
+
+The respond workflow never overwrites. To replace an answer, clear it with `updateReviewWorkflow`, then respond again:
+
+```ts
await updateReviewWorkflow(container).run({
- input: { id: "rev_123", seller_note: null },
+ input: { id: "rev_01JD8Q1234567", seller_note: null },
})
await respondReviewWorkflow(container).run({
- input: { id: "rev_123", seller_note: "Updated response." },
+ input: {
+ id: "rev_01JD8Q1234567",
+ seller_note: "Sorry for the delay, a replacement is on its way.",
+ },
})
```
-<Tip>
- Responding never changes the review's `status`. A store can respond to a
- `pending` review, but the response only becomes public once the review is
- [published](/platform/review/guides/moderate-a-review).
-</Tip>
+Import both workflows from `@mercurjs/core/workflows`. The built-in APIs cap `seller_note` at 300 characters, while the workflow itself doesn’t.
+
+## Next steps
+
+- [Publish the review so the answer is shown](/platform/review/guides/moderate-a-review)
+- [Learn why stores see only seller reviews](/platform/review/concepts/product-vs-seller-reviews)
+- [Check respondReviewWorkflow’s input](/platform/review/reference/workflows)
diff --git a/apps/docs/platform/review/overview.mdx b/apps/docs/platform/review/overview.mdx
index e04b86ce8..758a5e5a6 100644
--- a/apps/docs/platform/review/overview.mdx
+++ b/apps/docs/platform/review/overview.mdx
@@ -1,87 +1,97 @@
---
-title: "Review"
+title: "Reviews"
sidebarTitle: "Overview"
-description: "Collect, moderate, and surface customer ratings for products and sellers."
+description: "Let customers rate the products and stores they bought from, then moderate, answer, and average those ratings."
---
-Use Mercur to let customers rate the products they bought and the stores they
-bought from.
+Use Mercur to let customers rate the products they bought and the stores that sold them.
-The Review domain captures a single rating model that points at either a product
-or a seller. It ties each review back to the order that earned it, and it moves
-through a moderation lifecycle before it goes public. Stores can respond to their
-reviews, and aggregate ratings roll up onto public seller and product pages. All
-of it is exposed directly through the Admin, Vendor, and Store APIs.
+A review is one customer’s rating of one target: a master product or a store. Each review is tied to the order that earned it, starts as `pending`, and waits for an operator to publish or reject it. The Review module ships inside `@mercurjs/core`, so it’s registered with the rest of the marketplace modules and needs no extra install. It connects to products, stores, orders, and customers through module links.
+
+<img className="block dark:hidden" src="/images/figures/review-overview-light.svg" alt="Behind, createReviewWorkflow, which writes every review. In front, the review table: order #1001 backs a published seller review of ACME and a pending product review of the linen shirt, beside a rejected review from order #998." />
+<img className="hidden dark:block" src="/images/figures/review-overview-dark.svg" alt="Behind, createReviewWorkflow, which writes every review. In front, the review table: order #1001 backs a published seller review of ACME and a pending product review of the linen shirt, beside a rejected review from order #998." />
<Note>
- **One model, two targets.** A single `Review` entity (id prefix `rev`) covers
- both product and seller reviews. A `reference` discriminator decides which one
- a given review is about. There is no separate product-review or seller-review
- table.
+ The panels call the target a store. The code calls the same record a `Seller`, so a store review has `reference: "seller"`. Reviews use the id prefix `rev` and resolve with `MercurModules.REVIEW`.
</Note>
## Key features
-- **Product & seller reviews:** one rating model, discriminated by a `reference` field.
-- **Order-backed:** every review is linked to the order that earned it, with one review per target per order.
-- **Moderation lifecycle:** reviews start `pending` and are moderated to `published` or `rejected`.
-- **Store responses:** a store can attach a single public response to each of its reviews.
-- **Aggregate ratings:** average ratings computed per product and per seller for storefront display.
-- **Customer notes:** an optional free-text note alongside the numeric rating.
+The Review module covers a review from submission to the number on a storefront:
+
+- **One model, two targets**: a single `Review` record rates a product or a store, chosen by its `reference` field
+- **Order-backed**: the order must belong to the customer, and each order can review a given target once
+- **Moderation**: reviews start `pending`, and an operator sets them to `published` or `rejected`
+- **Store responses**: a store answers a review once through `seller_note`
+- **Rating helpers**: service methods compute average ratings per product or per store at query time
+- **Compensation**: every review workflow rolls its write back if a later step fails
+
+## How it works
+
+A review moves through four stages:
+
+1. A customer calls `POST /store/reviews` with an order they own, which runs `createReviewWorkflow`
+2. The workflow validates the order, creates the review as `pending`, and links it to its customer, order, and target
+3. An operator publishes or rejects it with `updateReviewWorkflow`, and the store answers it with `respondReviewWorkflow`
+4. Your own storefront route reads published reviews and averages them with the service’s rating helpers
+
+<Warning>
+ Core ships no public endpoint that lists a product’s or a store’s published reviews, and no route returns an average rating. `GET /store/reviews` returns only the signed-in customer’s own reviews. Add a route for storefront display, as shown in [Compute aggregate ratings](/platform/review/guides/compute-aggregate-ratings).
+</Warning>
## Get started
-Learn how the domain fits together.
+Learn how reviews, their targets, and their statuses fit together.
<CardGroup cols={2}>
<Card title="The review model" icon="star" href="/platform/review/concepts/the-review-model">
- The single review entity, its rating, notes, and status.
+ The fields of a review: rating, notes, status, and display id.
</Card>
<Card title="Product vs seller reviews" icon="tags" href="/platform/review/concepts/product-vs-seller-reviews">
- The reference discriminator and the links that anchor each review.
+ How `reference` picks the target and which links anchor each review.
</Card>
<Card title="Ratings & moderation" icon="gauge" href="/platform/review/concepts/ratings-and-moderation">
- The status lifecycle, store responses, and aggregate ratings.
+ Status changes, store responses, and how averages are computed.
</Card>
</CardGroup>
## Examples
-Build against the Review domain in your own code.
+Build against reviews in your own server code.
<CardGroup cols={2}>
<Card title="Create a review" icon="plus" href="/platform/review/guides/create-a-review">
- Run `createReviewWorkflow` from a route or script.
+ Run `createReviewWorkflow` from a custom route.
</Card>
<Card title="Moderate a review" icon="gavel" href="/platform/review/guides/moderate-a-review">
Publish, reject, and delete reviews in code.
</Card>
<Card title="Respond to a review" icon="reply" href="/platform/review/guides/respond-to-a-review">
- Attach a store's response with `respondReviewWorkflow`.
+ Attach a store’s answer with `respondReviewWorkflow`.
</Card>
<Card title="Aggregate ratings" icon="calculator" href="/platform/review/guides/compute-aggregate-ratings">
- Compute average ratings for products and sellers.
+ Serve average ratings for products and stores.
</Card>
</CardGroup>
## Resources
-Data models, links, workflows, service methods, and events for the Review domain.
+The data model, links, workflows, service methods, and events behind reviews.
<CardGroup cols={2}>
<Card title="Data models" icon="table" href="/platform/review/reference/data-models">
- The `Review` entity and its fields.
+ The `Review` model, its fields, and its indexes.
</Card>
<Card title="Links" icon="link" href="/platform/review/reference/links">
- How reviews link to products, sellers, orders, and customers.
+ The four links to products, sellers, orders, and customers.
</Card>
<Card title="Workflows" icon="diagram-project" href="/platform/review/reference/workflows">
- Create, update, respond, and delete workflows.
+ Create, update, respond, and delete workflows with their steps.
</Card>
<Card title="Service" icon="gear" href="/platform/review/reference/service">
- Module service methods, including aggregate-rating helpers.
+ Generated methods and the rating helpers.
</Card>
<Card title="Events" icon="bell" href="/platform/review/reference/events">
- Running side effects as reviews change.
+ The mutation events the module emits.
</Card>
</CardGroup>
diff --git a/apps/docs/platform/review/reference/data-models.mdx b/apps/docs/platform/review/reference/data-models.mdx
index 6f3b73e06..632e33df4 100644
--- a/apps/docs/platform/review/reference/data-models.mdx
+++ b/apps/docs/platform/review/reference/data-models.mdx
@@ -1,36 +1,50 @@
---
-title: "Data models"
+title: "Review data model"
sidebarTitle: "Data models"
-description: "The data models owned by the Review domain."
+description: "Every field and index of the Review model in the Review module."
---
-The Review domain is owned by the **Review module**. This reference lists its
-data model and fields.
+The Review module owns one data model, `Review`. It’s defined in `packages/core/src/modules/review/models/review.ts` and stored in the `review` table. Resolve the module with `MercurModules.REVIEW`.
## Review
-Table `review`, id prefix `rev`. A customer's rating of a single product or
-seller.
+A customer’s rating of one product or one seller. Table `review`, id prefix `rev`.
-| Field | Type | Notes |
+| Field | Type | Description |
| --- | --- | --- |
-| `id` | text | Primary key |
-| `display_id` | serial | Human-readable auto-incrementing number |
-| `reference` | enum | `product` or `seller`, the review's target type |
-| `rating` | integer | The numeric score |
-| `customer_note` | text | Nullable, searchable. The customer's note |
-| `seller_note` | text | Nullable, searchable. The store's single response |
-| `status` | enum | `pending`, `published`, or `rejected`; default `pending` |
-| `created_at` | dateTime | Set on creation |
-| `updated_at` | dateTime | Updated on change |
-| `deleted_at` | dateTime | Nullable; set by soft delete |
-
-The target record itself is not a column on this model. It's resolved through a
-module link chosen by the `reference` value. See the
-[Links reference](/platform/review/reference/links).
-
-<Note>
- The `review` table is indexed on `deleted_at` for soft-delete filtering.
- Deleting a review through the workflow is a soft delete. The row is retained
- and can be restored.
-</Note>
+| `id` | `text` | Primary key with the prefix `rev`, such as `rev_01JD8Q1234567` |
+| `display_id` | `autoincrement` | Serial number for display, stored as a Postgres `serial` |
+| `reference` | `enum` | The target type: `product` or `seller`. Required |
+| `rating` | `number` | The score, stored as an `integer`. Required, no range constraint in the model |
+| `customer_note` | `text` | The customer’s text. Nullable, searchable |
+| `seller_note` | `text` | The store’s answer. Nullable, searchable |
+| `status` | `enum` | `pending`, `published`, or `rejected`. Default `pending` |
+| `created_at` | `timestamptz` | Set on creation |
+| `updated_at` | `timestamptz` | Set on every change |
+| `deleted_at` | `timestamptz` | Nullable. Set by a soft delete |
+
+The model has no column for its target, order, or customer. Those live in [module links](/platform/review/reference/links), and `reference` tells you whether to follow `product` or `seller`.
+
+### Indexes
+
+Two indexes speed up the lists the APIs run:
+
+| Index | Columns | Condition |
+| --- | --- | --- |
+| `IDX_review_deleted_at` | `deleted_at` | `deleted_at IS NULL` |
+| `IDX_review_reference_status_created_at` | `reference`, `status`, `created_at` | `deleted_at IS NULL` |
+
+### Relations
+
+The model defines no relations of its own. Through links, a review exposes these `query.graph` fields:
+
+| Field | Target | Set when |
+| --- | --- | --- |
+| `product` | Product | `reference` is `product` |
+| `seller` | Seller | `reference` is `seller` |
+| `order` | Order | Always |
+| `customer` | Customer | Always |
+
+### Types
+
+`@mercurjs/types` exports `ReviewDTO`, `ReviewReference` (`"product" | "seller"`), and `ReviewStatus` (`"pending" | "published" | "rejected"`) for this model.
diff --git a/apps/docs/platform/review/reference/events.mdx b/apps/docs/platform/review/reference/events.mdx
index 9efd023bf..411ee0b7e 100644
--- a/apps/docs/platform/review/reference/events.mdx
+++ b/apps/docs/platform/review/reference/events.mdx
@@ -1,61 +1,79 @@
---
-title: "Event reference"
+title: "Review events"
sidebarTitle: "Events"
-description: "Running side effects as reviews are created, moderated, and answered."
+description: "The mutation events the Review module service emits, and how to subscribe to them."
---
-The Review workflows handle validation, links, moderation, and compensation. They
-do **not** currently emit their own domain events. There is no `review.created`
-or `review.published` event to subscribe to today.
+Mercur defines no review events of its own, and the review workflows don’t call `emitEventStep`. The Review module service emits Medusa’s standard mutation events instead, because every method `MedusaService` generates publishes an event when it changes a `Review` row. Subscribe to these to notify a store, refresh a search index, or recompute a cached rating.
-To run side effects when a review changes, wrap the review workflows in your own
-route or workflow and run the follow-up logic there, or emit your own event and
-subscribe to it.
+## Event list
-## Emit your own event
+Event names follow Medusa’s `<module>.<model>.<action>` pattern, with the module and the model both named `review`:
-Emit an event alongside the workflow, then handle it in a subscriber:
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `review.review.created` | `createReviewWorkflow` or `createReviews` creates a review | `{ id }` |
+| `review.review.updated` | `updateReviewWorkflow`, `respondReviewWorkflow`, or `updateReviews` changes a review | `{ id }` |
+| `review.review.deleted` | `deleteReviewWorkflow` or `softDeleteReviews` soft deletes a review, or `deleteReviews` removes one | `{ id }` |
+| `review.review.restored` | `restoreReviews` restores a soft deleted review, including a delete rollback | `{ id }` |
-```ts title="src/api/custom/route.ts"
-import { Modules } from "@medusajs/framework/utils"
-import { createReviewWorkflow } from "@mercurjs/core/workflows"
+The payload holds only the review id. Load the review in the subscriber when you need its fields or links.
-export async function POST(req, res) {
- const { result } = await createReviewWorkflow(req.scope).run({
- input: req.body,
- })
+<Note>
+ `review.review.updated` doesn’t say which field changed. A moderation, a customer edit, and a store answer all emit the same event, so compare against your own state when you need to tell them apart.
+</Note>
- const eventBus = req.scope.resolve(Modules.EVENT_BUS)
- await eventBus.emit({ name: "review.created", data: { id: result.id } })
+## Subscribe to an event
- res.status(201).json({ review: result })
-}
-```
+Create a subscriber that loads the review and its links:
```ts title="src/subscribers/review-created.ts"
import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
-export default async function reviewCreatedHandler({
+export default async function reviewCreated({
event,
container,
}: SubscriberArgs<{ id: string }>) {
- const reviewId = event.data.id
- // ...notify the store, update a search index, etc.
-}
+ const query = container.resolve(ContainerRegistrationKeys.QUERY)
+ const { data: [review] } = await query.graph({
+ entity: "review",
+ fields: ["rating", "reference", "seller.email", "product.title"],
+ filters: { id: event.data.id },
+ })
-export const config: SubscriberConfig = {
- event: "review.created",
+ const logger = container.resolve(ContainerRegistrationKeys.LOGGER)
+ logger.info(`Review ${event.data.id} rated ${review.rating}`)
}
+
+export const config: SubscriberConfig = { event: "review.review.created" }
```
-<Note>
- Because the module ships no events of its own, the event name in the example
- above is one **you** define. Keep it consistent across the emit site and the
- subscriber.
-</Note>
+This logs each new review. Replace the log with your side effect, such as a notification to `review.seller.email` for a store review.
+
+## Emit a named event
+
+To give a moderation step its own event, wrap `updateReviewWorkflow` in your own workflow and add Medusa’s `emitEventStep`:
-## React without an event
+```ts title="src/workflows/publish-review.ts"
+import {
+ createWorkflow,
+ WorkflowResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { emitEventStep } from "@medusajs/medusa/core-flows"
+import { updateReviewWorkflow } from "@mercurjs/core/workflows"
+
+export const publishReviewWorkflow = createWorkflow(
+ "publish-review",
+ (input: { id: string }) => {
+ const review = updateReviewWorkflow.runAsStep({
+ input: { id: input.id, status: "published" },
+ })
+ emitEventStep({ eventName: "review.published", data: { id: input.id } })
+
+ return new WorkflowResponse(review)
+ }
+)
+```
-For side effects that must run transactionally with the review change, add a step
-to your own workflow that wraps the review workflow, rather than relying on an
-event. Events are handled asynchronously and outside the workflow's compensation.
+`review.published` is a name you define, so subscribe to the same string.
diff --git a/apps/docs/platform/review/reference/links.mdx b/apps/docs/platform/review/reference/links.mdx
index 7d305fbdf..12e08fe72 100644
--- a/apps/docs/platform/review/reference/links.mdx
+++ b/apps/docs/platform/review/reference/links.mdx
@@ -1,43 +1,101 @@
---
-title: "Links to other modules"
+title: "Review links"
sidebarTitle: "Links"
-description: "How the Review domain links to products, sellers, orders, and customers."
+description: "The four module links that connect reviews to products, sellers, orders, and customers."
---
-Modules in Mercur never reference each other directly. They connect through
-**module links**. A review carries no foreign keys to its target on the model
-itself. Instead, four links anchor each review to the rest of the marketplace.
-Once a link is defined, you retrieve related records with `query.graph` using the
-link alias.
+A review stores no foreign keys. Four module links in `packages/core/src/links/` connect it to the records around it, and `query.graph` follows them by alias. Every link is a list link on the other module’s side: one product, seller, order, or customer has many reviews, and each review has one of each it’s linked to.
```ts
const { data: reviews } = await query.graph({
entity: "review",
- fields: ["id", "rating", "product.*", "seller.*"],
+ fields: ["id", "rating", "product.title", "seller.name", "order.id"],
+ filters: { status: "published" },
})
```
-## Targets
+This loads published reviews with their target and order. Only one of `product` and `seller` is set on each review.
-| Linked module | Relationship |
+## Product and review
+
+Connects a master product to its product reviews. Written by `createReviewWorkflow` through the `create-remote-links` step when `reference` is `product`.
+
+| Property | Value |
| --- | --- |
-| **Product** | A product has many reviews (`product_product_review_review`). Written when `reference` is `product`. |
-| **Seller** | A seller has many reviews (`seller_seller_review_review`). Written when `reference` is `seller`. |
+| File | `product-review.ts` |
+| Sides | `Modules.PRODUCT` `product` and `MercurModules.REVIEW` `review` |
+| Cardinality | One product, many reviews |
+| Link table | `product_product_review_review` |
+| Aliases | `review.product`, `product.reviews` |
-A review is linked to **either** a product or a seller, never both. The
-`reference` field on the review decides which link is created.
+```ts
+const { data: [product] } = await query.graph({
+ entity: "product",
+ fields: ["title", "reviews.rating", "reviews.status"],
+ filters: { id: "prod_01JD8Q1234567" },
+})
+```
+
+## Seller and review
-## Provenance
+Connects a seller to its store reviews. Written by `createReviewWorkflow` through the `create-remote-links` step when `reference` is `seller`. The Vendor API scopes reviews to a store through this link.
-| Linked module | Relationship |
+| Property | Value |
| --- | --- |
-| **Order** | Each review is linked to the order that earned it (`order_order_review_review`). |
-| **Customer** | Each review is linked to the customer who wrote it (`customer_customer_review_review`). |
+| File | `seller-review.ts` |
+| Sides | `MercurModules.SELLER` `seller` and `MercurModules.REVIEW` `review` |
+| Cardinality | One seller, many reviews |
+| Link table | `seller_seller_review_review` |
+| Aliases | `review.seller`, `seller.reviews` |
-These two links are written for every review and back the validation that a
-customer can review a target only once per order.
+```ts
+const { data: [seller] } = await query.graph({
+ entity: "seller",
+ fields: ["name", "reviews.rating", "reviews.seller_note"],
+ filters: { id: "sel_01JD8Q1234567" },
+})
+```
+
+## Order and review
+
+Connects a review to the order that earned it. Written for every review by the `create-review` step. `createReviewWorkflow` reads it to reject a second review of the same target from one order.
+
+| Property | Value |
+| --- | --- |
+| File | `order-review.ts` |
+| Sides | `Modules.ORDER` `order` and `MercurModules.REVIEW` `review` |
+| Cardinality | One order, many reviews |
+| Link table | `order_order_review_review` |
+| Aliases | `review.order`, `order.reviews` |
+
+```ts
+const { data: [order] } = await query.graph({
+ entity: "order",
+ fields: ["display_id", "reviews.reference", "reviews.rating"],
+ filters: { id: "order_01JD8Q1234567" },
+})
+```
+
+## Customer and review
+
+Connects a review to the customer who wrote it. Written for every review by the `create-review` step. The Store API limits a customer to their own reviews through this link.
+
+| Property | Value |
+| --- | --- |
+| File | `customer-review.ts` |
+| Sides | `Modules.CUSTOMER` `customer` and `MercurModules.REVIEW` `review` |
+| Cardinality | One customer, many reviews |
+| Link table | `customer_customer_review_review` |
+| Aliases | `review.customer`, `customer.reviews` |
+
+```ts
+const { data: [customer] } = await query.graph({
+ entity: "customer",
+ fields: ["email", "reviews.id", "reviews.status"],
+ filters: { id: "cus_01JD8Q1234567" },
+})
+```
<Note>
- All four links are list links (`isList: true`) on the owning side. A product,
- seller, order, or customer has many reviews.
+ `deleteReviewWorkflow` soft deletes the review but keeps all of its link rows. The service’s rating helpers join through the product and seller link tables, so they still count a soft deleted review.
</Note>
diff --git a/apps/docs/platform/review/reference/service.mdx b/apps/docs/platform/review/reference/service.mdx
index 8cdfa6652..cf726b825 100644
--- a/apps/docs/platform/review/reference/service.mdx
+++ b/apps/docs/platform/review/reference/service.mdx
@@ -1,54 +1,82 @@
---
-title: "Service reference"
+title: "Review module service"
sidebarTitle: "Service"
-description: "The Review module service: CRUD methods and aggregate-rating helpers."
+description: "Resolve the Review module service, its generated CRUD methods, and its three rating helpers."
---
-The Review module exposes a service you can resolve from the Medusa container to
-read and write records directly, without going through a workflow. Use it inside
-custom services, subscribers, scheduled jobs, or route handlers.
+The Review module service, `ReviewModuleService`, reads and writes `Review` records directly and computes average ratings. Use it in subscribers, scheduled jobs, and routes when you don’t need a workflow’s validation, links, or compensation.
+
+## Resolve the service
+
+Resolve the service from the Medusa container with `MercurModules.REVIEW`, which is the string `"review"`:
```ts
import { MercurModules } from "@mercurjs/types"
-const reviewModuleService = container.resolve(MercurModules.REVIEW)
+const reviewService = container.resolve(MercurModules.REVIEW)
-const [reviews, count] = await reviewModuleService.listAndCountReviews({
- status: "published",
-})
+const [reviews, count] = await reviewService.listAndCountReviews(
+ { status: "published" },
+ { order: { created_at: "DESC" }, take: 20 }
+)
```
+This lists the 20 newest published reviews and the total count. Filters apply to the review’s own fields, so you can’t filter by product or seller here: use `query.graph` from the linked side, as shown in the [Links reference](/platform/review/reference/links).
+
+<Warning>
+ Writing through the service skips the workflow checks. `createReviews` doesn’t validate the order, reject duplicates, or write any link, and `updateReviews` doesn’t stop a second store answer.
+</Warning>
+
## Generated methods
-The `Review` model gets a standard set of auto-generated methods:
+`MedusaService` generates these methods for the `Review` model:
| Method | Description |
| --- | --- |
-| `createReviews(data)` | Create one or more reviews |
-| `retrieveReview(id, config?)` | Retrieve a review by id |
-| `listReviews(filters?, config?)` | List reviews matching filters |
-| `listAndCountReviews(filters?, config?)` | List reviews with a total count |
-| `updateReviews(data)` | Update one or more reviews |
-| `deleteReviews(ids)` | Delete one or more reviews |
-| `softDeleteReviews(ids)` | Soft-delete reviews (restorable) |
-| `restoreReviews(ids)` | Restore soft-deleted reviews |
+| `retrieveReview(id, config?)` | Retrieve one review. Throws when it doesn’t exist |
+| `listReviews(filters?, config?)` | List reviews |
+| `listAndCountReviews(filters?, config?)` | List reviews and the total count |
+| `createReviews(data)` | Create one review or an array of reviews |
+| `updateReviews(data)` | Update by `id`, or by `{ selector, data }` |
+| `deleteReviews(ids)` | Delete reviews permanently |
+| `softDeleteReviews(ids)` | Set `deleted_at` on reviews |
+| `restoreReviews(ids)` | Clear `deleted_at` on reviews |
-## Aggregate-rating methods
+Each write emits a mutation event, listed in the [Events reference](/platform/review/reference/events).
-The service adds three helpers that compute average ratings on demand:
+## getAvgRating
-| Method | Description |
-| --- | --- |
-| `getAvgRating(type, id)` | Average rating for one `"product"` or `"seller"`; `null` when it has no reviews |
-| `getProductsWithRating(fields)` | Product records with an average `rating` joined in |
-| `getSellersWithRating(fields)` | Seller records with an average `rating` joined in |
+Returns the average rating of one product or one seller.
+
+```ts
+getAvgRating(
+ type: "seller" | "product",
+ id: string
+): Promise<string | null>
+```
-See [Compute aggregate ratings](/platform/review/guides/compute-aggregate-ratings)
-for usage.
+The result is the Postgres `AVG` of `rating` as a numeric string, such as `"4.5000000000000000"`, or `null` when the target has no linked reviews. It counts every linked review whatever its `status`, including soft deleted ones.
-<Warning>
- Prefer [workflows](/platform/review/reference/workflows) for anything with side
- effects (creation with its validation and links, responses, moderation). The
- service writes records directly and does **not** run the create-flow validation
- or manage the target/order/customer links.
-</Warning>
+## getProductsWithRating
+
+Returns every product with its average rating.
+
+```ts
+getProductsWithRating(fields: string[]): Promise<Record<string, unknown>[]>
+```
+
+`fields` are column names of the `product` table, such as `["id", "title"]`. Each row gains a `rating` numeric string, or `null`. The query left joins the `product_product_review_review` link table and groups by product, with no filters, pagination, or `deleted_at` checks.
+
+## getSellersWithRating
+
+Returns every seller with its average rating.
+
+```ts
+getSellersWithRating(fields: string[]): Promise<Record<string, unknown>[]>
+```
+
+`fields` are column names of the `seller` table, such as `["id", "name"]`. It works like `getProductsWithRating`, joining through `seller_seller_review_review`.
+
+<Note>
+ The return types above describe the rows. The source declares no explicit return type for the two list helpers, so TypeScript infers Knex’s result type.
+</Note>
diff --git a/apps/docs/platform/review/reference/workflows.mdx b/apps/docs/platform/review/reference/workflows.mdx
index 0be14429d..fafc00a07 100644
--- a/apps/docs/platform/review/reference/workflows.mdx
+++ b/apps/docs/platform/review/reference/workflows.mdx
@@ -1,31 +1,87 @@
---
-title: "Workflows"
+title: "Review workflows"
sidebarTitle: "Workflows"
-description: "Review workflows for creating, moderating, responding, and deleting."
+description: "The four review workflows, their inputs, steps, compensation, and errors."
---
-This reference lists the workflows for the Review domain. Import them from
-`@mercurjs/core/workflows` and run them against the Medusa container.
+Core ships four review workflows in `packages/core/src/workflows/review/`. Import them from `@mercurjs/core/workflows` and run them with the Medusa container. None of them exposes a workflow hook, and none emits an event of its own: the events come from the module service, as listed in the [Events reference](/platform/review/reference/events).
-## Review workflows
+```ts
+import { createReviewWorkflow } from "@mercurjs/core/workflows"
-| Workflow | Input | Purpose |
+const { result: review } = await createReviewWorkflow(container).run({
+ input: {
+ order_id: "order_01JD8Q1234567",
+ reference: "seller",
+ reference_id: "sel_01JD8Q1234567",
+ rating: 5,
+ customer_id: "cus_01JD8Q1234567",
+ },
+})
+```
+
+## createReviewWorkflow
+
+Validates a submission, creates a `pending` review, and writes its customer, order, and target links. Workflow id `create-review`. Input type `CreateReviewDTO`, returns the created review.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `order_id` | `string` | The order that earned the review. Must belong to `customer_id` |
+| `reference` | `"product" \| "seller"` | The target type |
+| `reference_id` | `string` | The product id or seller id |
+| `rating` | `number` | The score. Not range checked |
+| `customer_note` | `string \| null` | Optional. Defaults to `null` |
+| `customer_id` | `string` | The customer writing the review |
+
+The workflow runs three steps:
+
+1. **`validate-review`**: fails with `INVALID_DATA` “Order not found!” when no order matches `order_id` and `customer_id`, and with “Review already exists” when the order has a review with the same `reference` and target id
+2. **`create-review`**: creates the review and links it to the customer and the order; on rollback, deletes the review
+3. **`create-remote-links`**: Medusa’s `createRemoteLinkStep`, which links the review to the product or the seller
+
+## updateReviewWorkflow
+
+Updates any of a review’s editable fields, including `status`. Workflow id `update-review`. Input type `UpdateReviewDTO`, returns the updated review.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | The review id |
+| `rating` | `number` | Optional |
+| `customer_note` | `string \| null` | Optional |
+| `seller_note` | `string \| null` | Optional. Pass `null` to clear an answer |
+| `status` | `"pending" \| "published" \| "rejected"` | Optional. Any value from any status |
+
+Its single step, `update-review`, reads the review before writing. On rollback it restores the previous `rating`, `customer_note`, `seller_note`, and `status`.
+
+## respondReviewWorkflow
+
+Writes a store’s answer to `seller_note`, once. Workflow id `respond-review`. Input type `RespondReviewDTO`, returns the updated review.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | The review id |
+| `seller_note` | `string` | The answer |
+
+Its single step, `respond-review`, fails with `NOT_FOUND` “Review not found” for an unknown id and with `NOT_ALLOWED` “This review already has a response” when `seller_note` is set. On rollback it sets `seller_note` back to `null`. The workflow doesn’t check which store owns the review: the Vendor API checks the seller link before running it.
+
+## deleteReviewWorkflow
+
+Soft deletes a review. Workflow id `delete-review`. The input is the review id as a plain string, and the workflow returns that id.
+
+```ts
+await deleteReviewWorkflow(container).run({ input: "rev_01JD8Q1234567" })
+```
+
+Its single step, `delete-review`, calls `softDeleteReviews` and leaves the review’s links in place. On rollback it calls `restoreReviews`.
+
+## Steps
+
+`@mercurjs/core/workflows` also exports each step, so you can compose them into your own workflows:
+
+| Step | Id | Input |
| --- | --- | --- |
-| `createReviewWorkflow` | `{ order_id, reference, reference_id, rating, customer_note?, customer_id }` | Validate and create a review, linking it to its target, order, and customer |
-| `updateReviewWorkflow` | `{ id, rating?, customer_note?, seller_note?, status? }` | Update a review, including moderating its `status` |
-| `respondReviewWorkflow` | `{ id, seller_note }` | Attach a store's single response to a review |
-| `deleteReviewWorkflow` | `id` | Soft-delete a review (restorable on rollback) |
-
-Each workflow supports compensation: `createReviewWorkflow` deletes the review it
-created on failure, `updateReviewWorkflow` and `respondReviewWorkflow` restore the
-previous values, and `deleteReviewWorkflow` restores the soft-deleted row.
-
-<Note>
- `createReviewWorkflow` validates that the order belongs to the customer and
- that the target hasn't already been reviewed on that order. `respondReviewWorkflow`
- refuses to overwrite an existing response.
-</Note>
-
-To work with records directly instead of through a workflow, see the
-[Service reference](/platform/review/reference/service). To run side effects when
-a review changes, see the [Event reference](/platform/review/reference/events).
+| `validateReviewStep` | `validate-review` | `CreateReviewDTO` |
+| `createReviewStep` | `create-review` | `CreateReviewDTO` |
+| `updateReviewStep` | `update-review` | `UpdateReviewDTO` |
+| `respondReviewStep` | `respond-review` | `RespondReviewDTO` |
+| `deleteReviewStep` | `delete-review` | `string` |
diff --git a/apps/docs/platform/store/concepts/lifecycle.mdx b/apps/docs/platform/store/concepts/lifecycle.mdx
index b048cfd12..151827c12 100644
--- a/apps/docs/platform/store/concepts/lifecycle.mdx
+++ b/apps/docs/platform/store/concepts/lifecycle.mdx
@@ -1,62 +1,86 @@
---
-title: "Lifecycle"
+title: "Store statuses and transitions"
sidebarTitle: "Lifecycle"
-description: "Store statuses, transitions, scheduled closures, and premium."
+description: "The four store statuses, the workflow behind each transition, scheduled closures, and the premium flag."
---
-This page covers the store account lifecycle and the states a store moves through.
+Every store has a status that decides whether it can trade. The status lives in the `status` field of `Seller`, typed by the `SellerStatus` enum, and only dedicated workflows move it. Each transition validates the current status, records a reason or a timestamp, emits an event, and exposes a hook you can extend.
-## Status
+## The four statuses
-A store's state lives in the `status` field of the `Seller` model, typed by the
-`SellerStatus` enum. A store moves through four statuses.
-
-```
- ┌───────────────────┐
- │ pending_approval │
- └─────────┬─────────┘
- │ approve
- ▼
- ┌───────────┐ ┌────────┐
- │ suspended │◄───►│ open │
- └───────────┘ └───┬────┘
- │ terminate
- ▼
- ┌────────────┐
- │ terminated │
- └────────────┘
-```
+A store is in exactly one status at a time. New stores start in `pending_approval` unless you pass another status to `createSellersWorkflow`.
| Status | Meaning |
| --- | --- |
-| `pending_approval` | Registered, waiting for operator review. |
-| `open` | Active. Can list offers, take orders, and collect payouts. |
-| `suspended` | Temporarily frozen. Offers stay listed but cannot be purchased. |
-| `terminated` | Permanently closed. This status is irreversible. |
+| `pending_approval` | Registered and waiting for operator review |
+| `open` | Trading: listed in the Store API with its offers |
+| `suspended` | Frozen by the operator, hidden from the Store API |
+| `terminated` | Closed by the operator, hidden from the Store API and from its members’ store list |
-Only the operator can change a store's status. Each transition runs through a
-dedicated workflow: `approveSellerWorkflow`, `suspendSellerWorkflow`,
-`unsuspendSellerWorkflow`, and `terminateSellerWorkflow`.
+The Store API seller and offer listings return only `open` stores that aren’t inside a closure window. A store in any other status disappears from those listings, but its records stay intact.
-<Note>
- Termination is irreversible. All orders and payouts must be resolved before a
- store can be terminated.
-</Note>
+## Transitions
+
+Each transition is its own workflow, and each one checks the starting status before it writes.
+
+<img className="block dark:hidden" src="/images/figures/store-lifecycle-light.svg" alt="A Status transitions table for the Seller module listing each lifecycle workflow with the status it starts from, the status it sets, and the event it emits, with the terminate row highlighted because only a suspended or pending store can be terminated." />
+<img className="hidden dark:block" src="/images/figures/store-lifecycle-dark.svg" alt="A Status transitions table for the Seller module listing each lifecycle workflow with the status it starts from, the status it sets, and the event it emits, with the terminate row highlighted because only a suspended or pending store can be terminated." />
+
+The workflows accept these starting statuses:
+
+| Workflow | Allowed from | Sets |
+| --- | --- | --- |
+| `approveSellerWorkflow` | `pending_approval` | `open`, and `approved_at` on first approval |
+| `suspendSellerWorkflow` | `pending_approval`, `open` | `suspended`, `status_reason`, and `rejected_at` on first suspension |
+| `unsuspendSellerWorkflow` | `suspended` | `open`, and clears `status_reason` |
+| `terminateSellerWorkflow` | `pending_approval`, `suspended` | `terminated` and `status_reason` |
+| `unterminateSellerWorkflow` | `terminated` | `suspended`, and clears `status_reason` |
+
+Any other starting status fails with a `NOT_ALLOWED` error and changes nothing.
+
+<Warning>
+ You can’t terminate an `open` store. Suspend it first, then terminate it.
+</Warning>
+
+Termination isn’t final: `unterminateSellerWorkflow` brings a store back as `suspended`, and you then unsuspend it to reopen. Use suspension to reject a pending application: it stamps `rejected_at` and keeps the reason in `status_reason`.
## Scheduled closures
-A store can schedule a temporary closure with the `closed_from` and `closed_to`
-fields without changing its status. During the window, the storefront shows as
-unavailable and no new orders are accepted. The account stays `open` and resumes
-on its own once `closed_to` passes.
+A scheduled closure takes a store offline for a window without changing its status. Set `closed_from` and `closed_to`, and optionally a `closure_note` for the reason. Both the operator and the store’s own members can set these fields.
-<Tip>
- A closure overlays the current status. It is not a status of its own, and it
- does not affect the transition rules.
-</Tip>
+The Store API filter shows a store only when both bounds allow it:
+
+- **`closed_from`**: `null`, or later than now
+- **`closed_to`**: `null`, or earlier than now
+
+The store comes back once `closed_to` passes, with no job or workflow involved. Set the fields as the closure starts, for example from a scheduled job, because a future `closed_to` hides the store right away even when `closed_from` is also in the future.
+
+```ts
+import { updateSellersWorkflow } from "@mercurjs/core/workflows"
+
+await updateSellersWorkflow(container).run({
+ input: {
+ selector: { id: "sel_01JD8Q1234567" },
+ update: {
+ closed_from: new Date(),
+ closed_to: new Date("2026-12-27"),
+ },
+ },
+})
+```
+
+This closes the store from now until December 27. A `closed_from` in the past with a `null` `closed_to` hides the store until you clear the fields.
+
+<Note>
+ Closures filter the Store API seller and offer listings. They don’t block cart or checkout workflows, so add your own check there if a closed store must refuse orders.
+</Note>
## Premium
-The `is_premium` boolean is set only by the operator. Stores cannot designate
-themselves as premium. The storefront uses the flag for featured placement,
-badges, and curation priority.
+`is_premium` is a boolean that defaults to `false`. The Admin API accepts it on create and update, and the Vendor API doesn’t, so only the operator can set it. Mercur stores the flag and returns it, and your storefront decides what premium means, such as featured placement or a badge.
+
+## Related
+
+- [Moderate stores](/platform/store/guides/moderate-a-store)
+- [Event reference](/platform/store/reference/events)
+- [Workflows reference](/platform/store/reference/workflows)
diff --git a/apps/docs/platform/store/concepts/store-entity.mdx b/apps/docs/platform/store/concepts/store-entity.mdx
index ec30d43e8..13157c13c 100644
--- a/apps/docs/platform/store/concepts/store-entity.mdx
+++ b/apps/docs/platform/store/concepts/store-entity.mdx
@@ -1,19 +1,27 @@
---
-title: "The store entity"
+title: "What a store is made of"
sidebarTitle: "The store"
-description: "The seller record, its business identity, and its satellite data."
+description: "The seller record, its currency and regions, and the satellite records that hold its business details."
---
-This page covers the store record and the data models that make up its business
-identity.
+A store is the `Seller` record: the account a seller trades under on your marketplace. It holds the public profile customers see, the single currency the store settles in, and its status. Three satellite records carry its business details: an address, professional details, and bank payment details.
-## Store
+## The seller record
-A store is the marketplace vendor. It owns offers, orders, and payouts, and it
-holds the profile shown to customers on the storefront. A store is represented by
-the `Seller` data model (table `seller`, id prefix `sel`).
+The `Seller` data model (table `seller`, id prefix `sel`) is the root of everything a store owns. Offers, orders, payouts, and price lists link to it from their own modules.
+
+A seller has four unique fields besides its id:
+
+- **`name`**: unique among stores that aren’t deleted
+- **`handle`**: unique, URL safe, and generated from `name` when you omit it
+- **`email`**: unique, the store’s contact address
+- **`external_id`**: optional, unique when set, for mapping to an outside system
+
+The service validates `handle` on create and update. A handle with characters that aren’t URL safe fails with an `INVALID_DATA` error.
```ts
+import { createSellersWorkflow } from "@mercurjs/core/workflows"
+
const { result } = await createSellersWorkflow(container).run({
input: {
sellers: [
@@ -21,33 +29,43 @@ const { result } = await createSellersWorkflow(container).run({
name: "Acme Supplies",
currency_code: "usd",
+ member: { email: "[email protected]" },
},
],
},
})
```
-<Tip>
- A store settles in exactly one currency, set by `currency_code`. A seller who
- needs to trade in several currencies creates a separate store for each one, and
- each store operates independently.
-</Tip>
+This creates a store with the handle `acme-supplies` and the status `pending_approval`. It also invites `[email protected]` to join the team as an administrator.
+
+## Currency and regions
+
+A store settles in one currency, set by `currency_code` when you create it. `UpdateSellerDTO` has no `currency_code` field, so the currency stays fixed for the life of the store. The vendor request context carries it as `seller_context.currency_code`.
+
+A store also links to one or more regions through the `region_seller` link:
+
+- **On create**: the store links to the default region of your Medusa store, plus any `region_ids` you pass
+- **On change**: `linkSellerRegionsWorkflow` adds and removes region links in one call
+- **Rule**: a store must keep at least one region, so removing the last one fails
+
+## Business details
+
+Three one-to-one records hang off the seller. Each workflow that writes them creates the record when it’s missing and updates it otherwise.
+
+| Model | Holds | Written by |
+| --- | --- | --- |
+| `SellerAddress` | The store’s postal address and contact name | `updateSellerAddressWorkflow` |
+| `ProfessionalDetails` | Corporate name, registration number, tax id | `updateSellerProfessionalDetailsWorkflow` |
+| `PaymentDetails` | Bank account holder, IBAN, BIC, routing and account numbers | `updateSellerPaymentDetailsWorkflow` |
-## Professional details
+You remove professional details with `deleteSellerProfessionalDetailsWorkflow`. Deleting a seller cascades to all three records and to its pending invites, and detaches its members without deleting them.
-A store can carry professional details: a corporate name, a registration number,
-and a tax id. These are represented by the `ProfessionalDetails` data model. When
-this record is present, the store is a registered business. When it is absent,
-the store is an individual seller.
+## Fulfillment defaults
-## Addresses and payment details
+`default_leadtime_to_ship` holds the number of days a store needs before it ships, and defaults to `2`. Vendors can change it on their own store.
-A store keeps its addresses as `SellerAddress` records, one each for a warehouse,
-return, or business address. The bank details used to settle payouts live on a
-`PaymentDetails` record. Both are satellite records of the store, and fulfillment
-and payout settlement read from them.
+## Related
-<Note>
- `ProfessionalDetails`, `SellerAddress`, and `PaymentDetails` are one-to-one with
- the store and are deleted along with it.
-</Note>
+- [Team & members](/platform/store/concepts/team)
+- [Lifecycle](/platform/store/concepts/lifecycle)
+- [Data models reference](/platform/store/reference/data-models)
diff --git a/apps/docs/platform/store/concepts/team.mdx b/apps/docs/platform/store/concepts/team.mdx
index b6344b3ef..12b781028 100644
--- a/apps/docs/platform/store/concepts/team.mdx
+++ b/apps/docs/platform/store/concepts/team.mdx
@@ -1,50 +1,71 @@
---
-title: "Team & members"
+title: "How store teams work"
sidebarTitle: "Team & members"
-description: "Members, roles, invites, and the many-to-many store relationship."
+description: "Members, memberships, owners, roles, invites, and how a member picks the store they act for."
---
-This page covers how a store's team is modeled and how access is structured.
+A store’s team is the set of people who can sign in to the Vendor panel and act for that store. Mercur models the person and the membership separately, so one person can work for several stores with a different role in each. This matters as soon as an agency, a franchise, or a holding company runs more than one store on your marketplace.
-## Member
+## Members and memberships
-A member is a dashboard user who can manage one or more stores. A member is
-represented by the `Member` data model (table `member`, id prefix `mem`). Their
-identity is tied to their `email`, which is unique across the system.
+A `Member` (id prefix `mem`) is a person. Their `email` is unique across the whole marketplace, so the same person never has two member records. A member can be deactivated with `is_active` without touching their memberships.
-## Seller member
+A `SellerMember` (id prefix `selmem`) is one person’s membership in one store. It’s the pivot between `Seller` and `Member`, and it’s unique on `(seller_id, member_id)`. Each membership carries:
-The relationship between stores and members is many-to-many. A store can have
-several members, and a member can belong to several stores. Each membership is a
-`SellerMember` record, the pivot between `Seller` and `Member`, unique on
-`(seller_id, member_id)`.
+- **`role_id`**: the member’s role in this store, one of the `SellerRole` values
+- **`is_owner`**: `true` for the store’s owner membership, `false` for everyone else
+- **`metadata`**: free-form data for your own extensions
-```ts
-await addSellerMemberWorkflow(container).run({
- input: {
- seller_id: "sel_123",
- member: { email: "[email protected]" },
- },
-})
-```
+## Roles
+
+`SellerRole` from `@mercurjs/types` lists the five roles a membership can hold. The membership stores the role as a plain string.
+
+| `SellerRole` key | Stored value |
+| --- | --- |
+| `SELLER_ADMINISTRATION` | `role_seller_administration` |
+| `INVENTORY_MANAGEMENT` | `role_seller_inventory_management` |
+| `ORDER_MANAGEMENT` | `role_seller_order_management` |
+| `ACCOUNTING` | `role_seller_accounting` |
+| `SUPPORT` | `role_seller_support` |
+
+The vendor membership check confirms that a member belongs to the store they’re acting for. It doesn’t restrict routes by role, so enforce role rules in your own middleware when you need them.
+
+## The owner
+
+Every store has at most one owner membership, flagged with `is_owner`. Mercur sets it in two places:
+
+- **Self-registration**: `createSellerAccountWorkflow` adds the registering member as owner with `role_seller_administration`
+- **First accepted invite**: `acceptMemberInviteWorkflow` makes the new member owner when the store has none yet
-Every membership carries a `role_id`, resolved against the RBAC roles module, and
-an `is_owner` flag.
+`updateMemberRoleWorkflow` and `removeSellerMemberWorkflow` both reject the owner membership with a `NOT_ALLOWED` error. That keeps every store with someone who can administer it.
-<Tip>
- A store must always keep at least one member with admin access. The last admin
- cannot be removed or demoted.
-</Tip>
+## Invites
-## Member invite
+A `MemberInvite` (id prefix `meminv`) is a pending offer to join one store with one role. The service signs a JWT for each invite, stores it in `token`, and sets `expires_at` 7 days out unless you change the module’s `invite_valid_duration` option.
+
+Invites follow these rules:
+
+- **One open invite per email and store**: a unique index covers `(email, seller_id)` while `accepted` is `false`
+- **No invites for existing members**: inviting an email that already belongs to the store fails
+- **Existing accounts are reused**: accepting an invite for a known email links the existing member instead of creating one
+- **Single use**: accepting deletes the invite, and an expired or accepted token fails validation
+
+## The active store
+
+A member who belongs to several stores picks the active one per request. The vendor middleware reads the store id from the `x-seller-id` header, or from the session, and checks for a matching `SellerMember`. It then exposes the store on `req.seller_context`, typed by the `SellerContext` interface:
+
+```ts
+interface SellerContext {
+ seller_id: string
+ currency_code: string
+ seller_member: SellerMemberDTO
+}
+```
-Pending invitations are represented by the `MemberInvite` data model. If an
-invited email already belongs to a user, accepting the invite links the new store
-association to their existing account instead of creating a new one.
+Every vendor route scopes its reads and writes to `seller_context.seller_id`, so switching stores in the Vendor panel never shows another store’s data. The store list a member sees leaves out terminated stores.
-## Store switcher
+## Related
-A user who belongs to several stores uses the store switcher in the Vendor panel
-to change the active store. Each store context is fully isolated. Switching stores
-shows only that store's offers, orders, and payouts, and it never leaks data
-across stores.
+- [Manage the team](/platform/store/guides/manage-the-team)
+- [Workflows reference](/platform/store/reference/workflows)
+- [What a store is made of](/platform/store/concepts/store-entity)
diff --git a/apps/docs/platform/store/guides/create-a-store.mdx b/apps/docs/platform/store/guides/create-a-store.mdx
index 954c656cb..35fb0e446 100644
--- a/apps/docs/platform/store/guides/create-a-store.mdx
+++ b/apps/docs/platform/store/guides/create-a-store.mdx
@@ -1,55 +1,122 @@
---
-title: "Create a store"
+title: "Create a store from server code"
sidebarTitle: "Create a store"
-description: "Create a seller programmatically with createSellersWorkflow."
+description: "Create stores with createSellersWorkflow from a route, a seed script, or an import job, and extend creation with hooks."
---
-In this guide, you'll learn how to create a store from your own server code. This
-is useful in a seed script, a custom API route, or an onboarding flow.
+Create a store from your own server code when you seed a marketplace, import sellers from another system, or build a custom onboarding flow. `createSellersWorkflow` creates the `Seller`, links its regions, and invites its first team member.
-Mercur exposes a `createSellersWorkflow` that creates the `Seller` record along
-with its defaults. Run it from any place that has access to the Medusa container.
+## Before you begin
-## Run the workflow
+You need the following in place:
-```ts title="src/api/custom/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { createSellersWorkflow } from "@mercurjs/core/workflows"
+- A Mercur server with `@mercurjs/core` installed through `withMercur()`
+- A default region set on your Medusa store, since every new store links to it
+
+## Create the store
+
+<Steps>
+ <Step title="Add a route that runs the workflow">
+ Create an API route and run the workflow against the request’s container. Each entry in `sellers` needs a `member.email`: the workflow sends that address an invite with the `role_seller_administration` role.
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
- const { result } = await createSellersWorkflow(req.scope).run({
- input: {
- sellers: [
- {
- name: "Acme Supplies",
- email: "[email protected]",
- currency_code: "usd",
+ ```ts title="src/api/admin/import-sellers/route.ts"
+ import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+ import { createSellersWorkflow } from "@mercurjs/core/workflows"
+
+ export async function POST(req: MedusaRequest, res: MedusaResponse) {
+ const { result: sellers } = await createSellersWorkflow(req.scope).run({
+ input: {
+ sellers: [
+ {
+ name: "Acme Supplies",
+ email: "[email protected]",
+ currency_code: "usd",
+ member: { email: "[email protected]" },
+ region_ids: ["reg_01JD8Q1234567"],
+ },
+ ],
},
- ],
- },
- })
+ })
+
+ res.status(201).json({ sellers })
+ }
+ ```
+
+ The store gets the handle `acme-supplies` and links to the default region plus `reg_01JD8Q1234567`.
+ </Step>
+ <Step title="Open the store">
+ New stores start in `pending_approval`. Run `approveSellerWorkflow` to open one, or pass `status: "open"` in the seller input when you import stores you’ve already vetted.
+
+ ```ts
+ import { approveSellerWorkflow } from "@mercurjs/core/workflows"
+
+ await approveSellerWorkflow(req.scope).run({
+ input: { seller_id: sellers[0].id },
+ })
+ ```
+
+ Approval stamps `approved_at` and emits `seller.approved`.
+ </Step>
+ <Step title="Let the owner accept the invite">
+ The workflow emits `member_invite.created` with the invite’s `id`, `token`, and `expires_at`. Send the token to the invitee from a subscriber. When they accept it through `acceptMemberInviteWorkflow`, they join as the store’s owner. [Manage the team](/platform/store/guides/manage-the-team) shows both the subscriber and the accept call.
+ </Step>
+</Steps>
+
+## Attach custom data with additional_data
- res.status(201).json({ seller: result[0] })
-}
+The workflow passes `additional_data` to its `sellersCreated` hook. Use the hook to save data that belongs to your extension, such as a referral code, without changing the workflow.
+
+```ts title="src/workflows/hooks/sellers-created.ts"
+import { createSellersWorkflow } from "@mercurjs/core/workflows"
+
+createSellersWorkflow.hooks.sellersCreated(
+ async ({ sellers, additional_data }, { container }) => {
+ const referralCode = additional_data?.referral_code
+ if (!referralCode) {
+ return
+ }
+ const logger = container.resolve("logger")
+ logger.info(`${sellers.length} sellers joined via ${referralCode}`)
+ }
+)
```
-<Note>
- An operator can set a new store to `open` right away. A store created through
- the public self-registration flow starts in `pending_approval` and waits for
- operator review. See [Moderate stores](/platform/store/guides/moderate-a-store).
-</Note>
+Pass `additional_data: { referral_code: "SPRING25" }` next to `sellers` in the workflow input to reach this hook. The workflow also has a `validate` hook that runs before anything is written, so you can throw there to reject the input.
-## Attach custom data
+## Create the owner membership directly
-The workflow accepts an `additional_data` payload. It is passed to the workflow's
-hooks, so you can persist marketplace-specific data alongside the store without
-forking the workflow.
+`createSellersWorkflow` invites the owner. When the person already signed in, for example in a custom registration route, run `createSellerAccountWorkflow` instead. It creates the store in `pending_approval` and adds the member as owner in one call.
```ts
-await createSellersWorkflow(req.scope).run({
+import { createSellerAccountWorkflow } from "@mercurjs/core/workflows"
+
+const { result: seller } = await createSellerAccountWorkflow(
+ req.scope
+).run({
input: {
- sellers: [{ name: "Acme Supplies", email: "[email protected]", currency_code: "usd" }],
- additional_data: { referral_code: "SPRING25" },
+ auth_identity_id: req.auth_context.auth_identity_id,
+ member_email: "[email protected]",
+ seller: {
+ name: "Acme Supplies",
+ email: "[email protected]",
+ currency_code: "usd",
+ },
},
})
```
+
+The workflow upserts the member by email and stores its id on the auth identity under the `member` actor type. It also accepts `address`, `professional_details`, and `payment_details`, and writes each one when present.
+
+## Handle a failed creation
+
+The workflow rolls back every step when one fails. These inputs fail:
+
+- **Duplicate `name`, `email`, `handle`, or `external_id`**: the unique indexes reject the insert
+- **Invalid `handle`**: a handle with characters that aren’t URL safe fails with `INVALID_DATA`
+- **Unknown region**: a `region_ids` entry that doesn’t exist fails with `NOT_FOUND`
+
+## Next steps
+
+- [Moderate stores](/platform/store/guides/moderate-a-store)
+- [Manage the team](/platform/store/guides/manage-the-team)
+- [Workflows reference](/platform/store/reference/workflows)
diff --git a/apps/docs/platform/store/guides/manage-the-team.mdx b/apps/docs/platform/store/guides/manage-the-team.mdx
index 46de91314..9d1b3fbae 100644
--- a/apps/docs/platform/store/guides/manage-the-team.mdx
+++ b/apps/docs/platform/store/guides/manage-the-team.mdx
@@ -1,55 +1,145 @@
---
-title: "Manage the team"
+title: "Manage a store's team from server code"
sidebarTitle: "Manage the team"
-description: "Invite and add store members from server code."
+description: "Invite members, accept invites, add existing members, change roles, and remove members with the Seller module workflows."
---
-In this guide, you'll learn how to manage a store's team from your own server
-code. You can invite members, add them directly, and update their roles.
+Manage a store’s team from your own server code when you migrate staff from another system, sync people from an identity provider, or build your own team screens. Every change runs through a workflow that validates the owner rules and emits an event.
-## Invite a member
+## Before you begin
-`inviteSellerWorkflow` creates a `MemberInvite` and sends the invitation email.
-The invitee sets up access and is linked to the store when they accept.
+You need the following in place:
-```ts title="src/api/custom/invite/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { inviteSellerWorkflow } from "@mercurjs/core/workflows"
+- A store id, such as `sel_01JD8Q1234567`
+- A notification provider for email, if you send invite links from a subscriber
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
- await inviteSellerWorkflow(req.scope).run({
- input: {
- email: "[email protected]",
- seller_id: req.params.id,
- },
- })
+## Invite and onboard a member
- res.sendStatus(200)
-}
-```
+<Steps>
+ <Step title="Create the invite">
+ `createMemberInvitesWorkflow` takes an array of invites, each with `seller_id`, `email`, and `role_id`. It signs a token for each one and fails if an email already belongs to the store.
+
+ ```ts
+ import { SellerRole } from "@mercurjs/types"
+ import { createMemberInvitesWorkflow } from "@mercurjs/core/workflows"
+
+ const { result: invites } = await createMemberInvitesWorkflow(
+ container
+ ).run({
+ input: [
+ {
+ seller_id: "sel_01JD8Q1234567",
+ email: "[email protected]",
+ role_id: SellerRole.ORDER_MANAGEMENT,
+ },
+ ],
+ })
+ ```
+ </Step>
+ <Step title="Send the invite link">
+ The workflow emits `member_invite.created` once per invite, with `id`, `token`, and `expires_at`. Mercur doesn’t email team invites itself, so send the link from a subscriber.
+
+ ```ts title="src/subscribers/member-invite-created.ts"
+ import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+ import { Modules } from "@medusajs/framework/utils"
+ import { MercurModules } from "@mercurjs/types"
+
+ export default async function inviteCreated({
+ event,
+ container,
+ }: SubscriberArgs<{ id: string; token: string }>) {
+ const sellers = container.resolve(MercurModules.SELLER)
+ const invite = await sellers.retrieveMemberInvite(event.data.id)
+ await container.resolve(Modules.NOTIFICATION).createNotifications({
+ to: invite.email,
+ channel: "email",
+ template: "member-invite",
+ data: { token: event.data.token },
+ })
+ }
+
+ export const config: SubscriberConfig = { event: "member_invite.created" }
+ ```
+ </Step>
+ <Step title="Accept the invite">
+ When the invitee signs up or signs in, run `acceptMemberInviteWorkflow` with the token and their auth identity. It returns the member.
+
+ ```ts
+ import { acceptMemberInviteWorkflow } from "@mercurjs/core/workflows"
-## Add a member directly
+ const { result: member } = await acceptMemberInviteWorkflow(
+ req.scope
+ ).run({
+ input: {
+ invite_token: "your_invite_token",
+ auth_identity_id: req.auth_context.auth_identity_id,
+ first_name: "Ola",
+ last_name: "Nordmann",
+ },
+ })
+ ```
-When you already have the user, for example during a migration, add them to a
-store without the invite step. Use `addSellerMemberWorkflow`.
+ The workflow upserts the member by email, creates the membership with the invite’s role, and deletes the invite. Pass `member_id` when the person is already a member of another store, so the workflow leaves their auth identity as it is.
+ </Step>
+</Steps>
+
+## Resend or revoke an invite
+
+`resendMemberInviteWorkflow` takes `invite_id` and `seller_id`. It deletes the invite and creates a fresh one with a new token and expiry, then emits `member_invite.created` again. `deleteMemberInviteWorkflow` takes `invite_id` and deletes the invite without a replacement.
+
+## Add an existing member directly
+
+Skip the invite when the person already has a `Member` record, for example after a migration. `addSellerMemberWorkflow` creates the membership and returns it.
```ts
+import { SellerRole } from "@mercurjs/types"
import { addSellerMemberWorkflow } from "@mercurjs/core/workflows"
await addSellerMemberWorkflow(container).run({
input: {
- seller_id: "sel_123",
- member: { email: "[email protected]" },
+ seller_id: "sel_01JD8Q1234567",
+ member_id: "mem_01JD8Q1234567",
+ role_id: SellerRole.SUPPORT,
},
})
```
-<Tip>
- Every store must keep at least one admin member. A workflow that would remove or
- demote the last admin fails instead of leaving a store unadministered.
-</Tip>
+The membership is unique on `(seller_id, member_id)`, so adding the same member twice fails.
+
+## Change a role or remove a member
+
+Both workflows take the membership id, `seller_member_id`, not the member id. Both reject the owner membership with a `NOT_ALLOWED` error.
+
+```ts
+import { SellerRole } from "@mercurjs/types"
+import {
+ removeSellerMemberWorkflow,
+ updateMemberRoleWorkflow,
+} from "@mercurjs/core/workflows"
+
+await updateMemberRoleWorkflow(container).run({
+ input: {
+ seller_member_id: "selmem_01JD8Q1234567",
+ role_id: SellerRole.ACCOUNTING,
+ },
+})
+
+await removeSellerMemberWorkflow(container).run({
+ input: {
+ seller_member_id: "selmem_01JD8Q1234567",
+ seller_id: "sel_01JD8Q1234567",
+ },
+})
+```
+
+Removing a membership keeps the `Member` record, so the person keeps access to their other stores.
+
+## Update a member’s profile
+
+`updateMemberWorkflow` changes `first_name`, `last_name`, and `locale` on members that match a `selector`. It exposes a `membersUpdated` hook and doesn’t emit an event.
-## Accept an invite
+## Next steps
-The invitee's acceptance runs through `acceptMemberInviteWorkflow`. It links the
-member to the store, and if the email already exists, it reuses their account.
+- [How store teams work](/platform/store/concepts/team)
+- [Event reference](/platform/store/reference/events)
+- [Workflows reference](/platform/store/reference/workflows)
diff --git a/apps/docs/platform/store/guides/moderate-a-store.mdx b/apps/docs/platform/store/guides/moderate-a-store.mdx
index ef664e874..6d8902cfd 100644
--- a/apps/docs/platform/store/guides/moderate-a-store.mdx
+++ b/apps/docs/platform/store/guides/moderate-a-store.mdx
@@ -1,59 +1,128 @@
---
-title: "Moderate stores"
+title: "Approve, suspend, and terminate stores"
sidebarTitle: "Moderate stores"
-description: "Approve, suspend, and terminate stores from server code."
+description: "Move stores through their lifecycle from server code, extend each transition with a hook, and react to the events."
---
-In this guide, you'll learn how to drive a store through its lifecycle from your
-own server code. Each transition has a dedicated workflow, so the side effects
-(events, notifications, and compensation) run consistently.
+Drive a store through its lifecycle from your own server code, for example to auto-approve vetted sellers or to suspend a store when a risk check fails. Each transition is a workflow that validates the current status, writes the change, emits an event, and exposes a hook.
-## Approve a store
+## Moderate a store
-Move a `pending_approval` store to `open` with `approveSellerWorkflow`.
+<Steps>
+ <Step title="Approve a pending store">
+ `approveSellerWorkflow` moves a `pending_approval` store to `open` and stamps `approved_at`.
-```ts title="src/api/custom/approve/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { approveSellerWorkflow } from "@mercurjs/core/workflows"
+ ```ts title="src/api/admin/stores/[id]/vet/route.ts"
+ import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+ import { approveSellerWorkflow } from "@mercurjs/core/workflows"
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
- await approveSellerWorkflow(req.scope).run({
- input: { seller_id: req.params.id },
- })
+ export async function POST(req: MedusaRequest, res: MedusaResponse) {
+ await approveSellerWorkflow(req.scope).run({
+ input: { seller_id: req.params.id },
+ })
- res.sendStatus(200)
-}
-```
+ res.sendStatus(200)
+ }
+ ```
+ </Step>
+ <Step title="Suspend and reinstate a store">
+ `suspendSellerWorkflow` takes an optional `reason`, which it saves in `status_reason`. `unsuspendSellerWorkflow` reopens the store and clears the reason.
-## Suspend and reinstate
+ ```ts
+ import {
+ suspendSellerWorkflow,
+ unsuspendSellerWorkflow,
+ } from "@mercurjs/core/workflows"
-Freeze an `open` store's operations, then reinstate it once the issue is resolved.
+ await suspendSellerWorkflow(container).run({
+ input: { seller_id: "sel_01JD8Q1234567", reason: "Chargeback review" },
+ })
-```ts
-import {
- suspendSellerWorkflow,
- unsuspendSellerWorkflow,
-} from "@mercurjs/core/workflows"
-
-await suspendSellerWorkflow(container).run({ input: { seller_id } })
-// ...later
-await unsuspendSellerWorkflow(container).run({ input: { seller_id } })
-```
+ await unsuspendSellerWorkflow(container).run({
+ input: { seller_id: "sel_01JD8Q1234567" },
+ })
+ ```
+ </Step>
+ <Step title="Terminate a store">
+ `terminateSellerWorkflow` accepts a `pending_approval` or `suspended` store. Suspend an `open` store first.
+
+ ```ts
+ import { terminateSellerWorkflow } from "@mercurjs/core/workflows"
+
+ await terminateSellerWorkflow(container).run({
+ input: { seller_id: "sel_01JD8Q1234567", reason: "Policy breach" },
+ })
+ ```
-## Terminate a store
+ To undo it, run `unterminateSellerWorkflow`. It returns the store to `suspended`, and you reopen it with `unsuspendSellerWorkflow`.
+ </Step>
+</Steps>
+
+## Reject a pending application
+
+Mercur has no separate reject workflow. Run `suspendSellerWorkflow` on the `pending_approval` store with a `reason`: it stamps `rejected_at` and keeps the store out of the Store API. Terminate it afterwards if the decision is final.
+
+## Handle a failed transition
+
+Each workflow checks the starting status and fails with a `NOT_ALLOWED` error when the transition isn’t allowed. Nothing is written in that case. Pass `throwOnError: false` to read the error instead of catching it.
```ts
+import { MedusaError } from "@medusajs/framework/utils"
import { terminateSellerWorkflow } from "@mercurjs/core/workflows"
-await terminateSellerWorkflow(container).run({ input: { seller_id } })
+const { errors } = await terminateSellerWorkflow(container).run({
+ input: { seller_id: "sel_01JD8Q1234567" },
+ throwOnError: false,
+})
+
+const notAllowed = errors.some(
+ ({ error }) => error.type === MedusaError.Types.NOT_ALLOWED
+)
+```
+
+An `open` store makes `notAllowed` true here, with the message “Cannot terminate an open seller. Suspend or close first.”
+
+The workflow also fails when the seller id doesn’t exist, because its lookup step runs with `throwIfKeyNotFound`.
+
+## Extend a transition with a hook
+
+Each lifecycle workflow exposes a hook that receives `seller_id` and `additional_data`. Register a handler to run your own step inside the transition.
+
+```ts title="src/workflows/hooks/seller-approved.ts"
+import { approveSellerWorkflow } from "@mercurjs/core/workflows"
+
+approveSellerWorkflow.hooks.sellerApproved(
+ async ({ seller_id }, { container }) => {
+ const logger = container.resolve("logger")
+ logger.info(`Store ${seller_id} approved`)
+ }
+)
```
-<Warning>
- Termination is irreversible. All orders and payouts must be resolved first.
-</Warning>
+The other hooks follow the same shape: `sellerSuspended`, `sellerUnsuspended`, `sellerTerminated`, and `sellerUnterminated`.
+
+## Run side effects from a subscriber
+
+Subscribe to the lifecycle events for work that shouldn’t block the transition, such as emails. Each event carries `{ id }`, the seller id.
+
+```ts title="src/subscribers/store-suspended.ts"
+import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+
+export default async function storeSuspended({
+ event,
+ container,
+}: SubscriberArgs<{ id: string }>) {
+ const logger = container.resolve("logger")
+ logger.info(`Store ${event.data.id} suspended`)
+}
+
+export const config: SubscriberConfig = {
+ event: "seller.suspended",
+}
+```
-## React to lifecycle changes
+## Next steps
-To run your own side effects when a store's status changes, subscribe to the
-events these workflows emit instead of polling. The
-[Event reference](/platform/store/reference/events) lists the event names.
+- [Store statuses and transitions](/platform/store/concepts/lifecycle)
+- [Event reference](/platform/store/reference/events)
+- [Workflows reference](/platform/store/reference/workflows)
diff --git a/apps/docs/platform/store/overview.mdx b/apps/docs/platform/store/overview.mdx
index 5254ca887..cf8d8a576 100644
--- a/apps/docs/platform/store/overview.mdx
+++ b/apps/docs/platform/store/overview.mdx
@@ -1,46 +1,53 @@
---
-title: "Store"
+title: "Stores"
sidebarTitle: "Overview"
-description: "Manage sellers, their teams, and their lifecycle on the marketplace."
+description: "Control who sells on your marketplace, who works on each store, and when a store can trade."
---
-Use Mercur to control who is allowed to sell on your marketplace and what each
-person on a store's team can do.
+Use Mercur to decide who can sell on your marketplace and what each person on a store’s team can do.
-Governing your sellers starts here. The Store domain decides who may sell,
-enforces role-based access so every member acts only within their store, and
-keeps each store's data isolated from the rest. On top of that control layer, a
-store carries its own team, a governed account lifecycle, and the business
-details used to settle payouts. Every offer, order, payout, and storefront page
-belongs to a store, and all of it is exposed directly through the Admin and
-Vendor APIs.
+A store is the account a seller trades under. Offers, orders, payouts, and storefront pages all link back to it, and its team works only inside it. The Seller module holds the store record, its business details, its members and invites, and its status. Other marketplace modules attach to a store through module links, never through direct references.
+
+<img className="block dark:hidden" src="/images/figures/store-overview-light.svg" alt="A Stores list from the Seller module showing four stores, each with its status, currency, member count, and premium flag, in front of the Team panel for acme-supplies with three members and their seller roles." />
+<img className="hidden dark:block" src="/images/figures/store-overview-dark.svg" alt="A Stores list from the Seller module showing four stores, each with its status, currency, member count, and premium flag, in front of the Team panel for acme-supplies with three members and their seller roles." />
<Note>
- A store is the `Seller` entity. The Admin and Vendor panels call it a "Store".
- The API and core modules call the same record a `Seller` (id prefix `sel`). You
- never need to know Medusa to work with stores.
+ The Admin and Vendor panels call it a store. The code calls the same record a `Seller` (id prefix `sel`), and you resolve its module with `MercurModules.SELLER` from `@mercurjs/types`.
</Note>
## Key features
-- **Role-based access control:** many-to-many members, roles resolved per store, and a store switcher for users who belong to several stores.
-- **Store isolation:** each store sees and acts on only its own data.
-- **Governed lifecycle:** a four-state account model with operator-only transitions.
-- **Self-service onboarding:** create stores yourself, or let sellers register publicly.
-- **Scheduled closures:** temporary offline windows that don't change account status.
-- **Premium placement:** an operator-only flag the storefront uses for featured curation.
-- **Single-currency accounts:** each store settles in exactly one currency.
+The Seller module covers the full life of a store account:
+
+- **Many-to-many teams**: a member can belong to several stores and picks the active one per request
+- **Owner protection**: the store’s owner membership can’t be removed or have its role changed
+- **Seller roles**: each membership stores one of five `SellerRole` values, from administration to support
+- **Token-based invites**: signed invite tokens that expire after 7 days by default
+- **Governed lifecycle**: four statuses, each transition run by its own workflow with a hook and an event
+- **Scheduled closures**: a `closed_from` and `closed_to` window that hides a store from the Store API without changing its status
+- **Premium flag**: an `is_premium` boolean the operator sets for featured placement
+- **Region assignment**: every store links to one or more regions, starting with the default region
+
+## How it works
+
+A store moves from creation to trading in a fixed order:
+
+1. A seller registers, or your code runs `createSellersWorkflow`, and the store starts in `pending_approval`
+2. The workflow links the store to the default region and to any `region_ids` you pass
+3. The first member joins as owner, either at registration or by accepting the invite the workflow sends
+4. The operator runs `approveSellerWorkflow`, and the store becomes `open`
+5. The Store API lists the store and its offers while it’s `open` and outside a closure window
## Get started
-Learn how the domain fits together.
+Learn how stores, teams, and statuses fit together.
<CardGroup cols={2}>
<Card title="The store" icon="store" href="/platform/store/concepts/store-entity">
- The seller entity, its profile, currency, and business identity.
+ The seller record, its currency, regions, and business details.
</Card>
<Card title="Team & members" icon="users" href="/platform/store/concepts/team">
- Multi-user stores, roles, invites, and the store switcher.
+ Members, owners, roles, invites, and the active store.
</Card>
<Card title="Lifecycle" icon="arrows-rotate" href="/platform/store/concepts/lifecycle">
Statuses, transitions, scheduled closures, and premium.
@@ -49,38 +56,38 @@ Learn how the domain fits together.
## Examples
-Build against the Store domain in your own code.
+Build against stores in your own server code.
<CardGroup cols={2}>
<Card title="Create a store" icon="plus" href="/platform/store/guides/create-a-store">
- Run `createSellersWorkflow` from a route or seed script.
+ Run `createSellersWorkflow` from a route or a seed script.
</Card>
<Card title="Moderate stores" icon="gavel" href="/platform/store/guides/moderate-a-store">
- Approve, suspend, and terminate stores in code.
+ Approve, suspend, terminate, and reinstate stores in code.
</Card>
<Card title="Manage the team" icon="user-plus" href="/platform/store/guides/manage-the-team">
- Invite and add members programmatically.
+ Invite, add, re-role, and remove members.
</Card>
</CardGroup>
## Resources
-Data models, workflows, service methods, and events for the Store domain.
+The data models, links, workflows, service methods, and events behind stores.
<CardGroup cols={2}>
<Card title="Data models" icon="table" href="/platform/store/reference/data-models">
- The `Seller`, `Member`, and related entities.
+ `Seller`, `Member`, `SellerMember`, `MemberInvite`, and the satellite records.
</Card>
<Card title="Links" icon="link" href="/platform/store/reference/links">
- How the Store domain links to other modules.
+ How a store connects to orders, offers, payouts, regions, and more.
</Card>
<Card title="Workflows" icon="diagram-project" href="/platform/store/reference/workflows">
- Seller and member lifecycle workflows.
+ Store, lifecycle, and team workflows with their hooks.
</Card>
<Card title="Service" icon="gear" href="/platform/store/reference/service">
- Module service methods for working with records directly.
+ Seller module service methods for direct reads and writes.
</Card>
<Card title="Events" icon="bell" href="/platform/store/reference/events">
- Events emitted as stores and members change.
+ Events emitted as stores, members, and invites change.
</Card>
</CardGroup>
diff --git a/apps/docs/platform/store/reference/data-models.mdx b/apps/docs/platform/store/reference/data-models.mdx
index bf0523d7d..56bb13b94 100644
--- a/apps/docs/platform/store/reference/data-models.mdx
+++ b/apps/docs/platform/store/reference/data-models.mdx
@@ -1,89 +1,164 @@
---
-title: "Data models"
+title: "Seller module data models"
sidebarTitle: "Data models"
-description: "The data models owned by the Store (Seller) domain."
+description: "Every data model in the Seller module, with fields, types, defaults, indexes, and relations."
---
-The Store domain is owned by the **Seller module**. This reference lists its data
-models and their fields. For the full module overview, see the
-[Store overview](/platform/store/overview).
+The Seller module (`MercurModules.SELLER`) owns the store, its business details, and its team. Every model also has the standard `created_at`, `updated_at`, and `deleted_at` columns, which the tables below leave out.
## Seller
-Table `seller`, id prefix `sel`. The store account and profile.
+The store account and its public profile. Table `seller`, id prefix `sel`.
-| Field | Type | Notes |
+| Field | Type | Description |
| --- | --- | --- |
-| `id` | text | Primary key |
-| `name` | text | Unique, searchable |
-| `handle` | text | Unique; auto-generated from `name` when omitted |
-| `email` | text | Unique, searchable |
-| `phone` | text | Nullable |
-| `description` | text | Nullable |
-| `logo` / `banner` | text | Nullable |
-| `website_url` | text | Nullable |
-| `external_id` | text | Nullable; unique when set |
-| `currency_code` | text | The store's single operating currency |
-| `status` | enum | `SellerStatus`, default `pending_approval` |
-| `status_reason` | text | Nullable |
-| `approved_at` / `rejected_at` | dateTime | Nullable |
-| `is_premium` | boolean | Default `false`; operator-set only |
-| `closed_from` / `closed_to` | dateTime | Nullable; scheduled closure window |
-| `closure_note` | text | Nullable |
-| `metadata` | json | Nullable |
-
-Relations: `professional_details`, `address`, `payment_details` (one-to-one,
-deleted with the seller), `members` (many-to-many through `SellerMember`),
-`member_invites` (one-to-many, deleted with the seller).
+| `id` | `text` | Primary key |
+| `name` | `text` | Searchable, unique |
+| `handle` | `text` | Searchable, unique, generated from `name` when omitted |
+| `email` | `text` | Searchable, unique |
+| `phone` | `text` | Nullable |
+| `description` | `text` | Nullable |
+| `logo` | `text` | Nullable, image URL |
+| `banner` | `text` | Nullable, image URL |
+| `website_url` | `text` | Searchable, nullable |
+| `external_id` | `text` | Searchable, nullable, unique when set |
+| `currency_code` | `text` | The store’s settlement currency |
+| `status` | `enum` | `SellerStatus`, default `pending_approval` |
+| `status_reason` | `text` | Nullable, set by suspend and terminate |
+| `approved_at` | `dateTime` | Nullable, set on first approval |
+| `rejected_at` | `dateTime` | Nullable, set on first suspension |
+| `is_premium` | `boolean` | Default `false` |
+| `default_leadtime_to_ship` | `number` | Default `2`, in days |
+| `closed_from` | `dateTime` | Nullable, start of a scheduled closure |
+| `closed_to` | `dateTime` | Nullable, end of a scheduled closure |
+| `closure_note` | `text` | Nullable |
+| `metadata` | `json` | Nullable |
+
+Unique indexes on `name`, `handle`, `email`, and `external_id` apply only to rows that aren’t deleted. An extra index on `(status, closed_from, closed_to)` serves the Store API visibility filter.
+
+Relations:
+
+- **`professional_details`**: has one `ProfessionalDetails`, deleted with the seller
+- **`address`**: has one `SellerAddress`, deleted with the seller
+- **`payment_details`**: has one `PaymentDetails`, deleted with the seller
+- **`members`**: many-to-many with `Member` through `SellerMember`, detached when the seller is deleted
+- **`member_invites`**: has many `MemberInvite`, deleted with the seller
+
+## SellerStatus
+
+The enum in `@mercurjs/types` that types `Seller.status`.
+
+| Key | Value |
+| --- | --- |
+| `OPEN` | `open` |
+| `PENDING_APPROVAL` | `pending_approval` |
+| `SUSPENDED` | `suspended` |
+| `TERMINATED` | `terminated` |
## ProfessionalDetails
-Table `professional_details`, id prefix `selprodet`. Presence marks the store as
-a registered business.
+A store’s registered business identity. Table `professional_details`, id prefix `selprodet`.
-| Field | Type |
-| --- | --- |
-| `corporate_name` | text, nullable |
-| `registration_number` | text, nullable |
-| `tax_id` | text, nullable |
+| Field | Type | Description |
+| --- | --- | --- |
+| `corporate_name` | `text` | Nullable |
+| `registration_number` | `text` | Nullable |
+| `tax_id` | `text` | Nullable |
+| `seller_id` | `text` | Belongs to `Seller` |
## SellerAddress
-Table `seller_address`, id prefix `seladdr`. Fields: `name`, `company`,
-`first_name`, `last_name`, `address_1`, `address_2`, `city`, `country_code`,
-`province`, `postal_code`, `phone`, and `metadata`. All are nullable.
+A store’s postal address. Table `seller_address`, id prefix `seladdr`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name` | `text` | Searchable, nullable |
+| `company` | `text` | Searchable, nullable |
+| `first_name` | `text` | Searchable, nullable |
+| `last_name` | `text` | Searchable, nullable |
+| `address_1` | `text` | Searchable, nullable |
+| `address_2` | `text` | Searchable, nullable |
+| `city` | `text` | Searchable, nullable |
+| `country_code` | `text` | Nullable |
+| `province` | `text` | Searchable, nullable |
+| `postal_code` | `text` | Searchable, nullable |
+| `phone` | `text` | Nullable |
+| `metadata` | `json` | Nullable |
+| `seller_id` | `text` | Belongs to `Seller` |
## PaymentDetails
-Table `payment_details`, id prefix `selpaydet`. Fields: `country_code`,
-`holder_name`, `bank_name`, `iban`, `bic`, `routing_number`, and
-`account_number`. All are nullable.
+A store’s bank account details. Table `payment_details`, id prefix `selpaydet`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `country_code` | `text` | Nullable |
+| `holder_name` | `text` | Nullable |
+| `bank_name` | `text` | Nullable |
+| `iban` | `text` | Nullable |
+| `bic` | `text` | Nullable |
+| `routing_number` | `text` | Nullable |
+| `account_number` | `text` | Nullable |
+| `seller_id` | `text` | Belongs to `Seller` |
## Member
-Table `member`, id prefix `mem`. A dashboard user that can belong to one or more
-stores.
+A person who can work for one or more stores. Table `member`, id prefix `mem`.
-| Field | Type | Notes |
+| Field | Type | Description |
| --- | --- | --- |
-| `email` | text | Unique, searchable |
-| `first_name` / `last_name` | text | Nullable |
-| `locale` | text | Nullable |
-| `is_active` | boolean | Default `true` |
-| `metadata` | json | Nullable |
+| `id` | `text` | Primary key |
+| `email` | `text` | Searchable, unique across the marketplace |
+| `first_name` | `text` | Searchable, nullable |
+| `last_name` | `text` | Searchable, nullable |
+| `locale` | `text` | Nullable |
+| `is_active` | `boolean` | Default `true` |
+| `metadata` | `json` | Nullable |
+
+Relations: `sellers`, many-to-many with `Seller` through `SellerMember`.
## SellerMember
-Table `seller_member`, id prefix `selmem`. Pivot between `Seller` and `Member`,
-unique on `(seller_id, member_id)`.
+One member’s membership in one store. Table `seller_member`, id prefix `selmem`, unique on `(seller_id, member_id)`.
-| Field | Type | Notes |
+| Field | Type | Description |
| --- | --- | --- |
-| `role_id` | text | Nullable; resolved against the RBAC roles module |
-| `is_owner` | boolean | Default `false` |
-| `metadata` | json | Nullable |
+| `id` | `text` | Primary key |
+| `seller_id` | `text` | Belongs to `Seller` |
+| `member_id` | `text` | Belongs to `Member` |
+| `role_id` | `text` | Nullable, a `SellerRole` value |
+| `is_owner` | `boolean` | Default `false` |
+| `metadata` | `json` | Nullable |
+
+## SellerRole
+
+The enum in `@mercurjs/types` whose values go in `role_id`.
+
+| Key | Value |
+| --- | --- |
+| `SELLER_ADMINISTRATION` | `role_seller_administration` |
+| `INVENTORY_MANAGEMENT` | `role_seller_inventory_management` |
+| `ORDER_MANAGEMENT` | `role_seller_order_management` |
+| `ACCOUNTING` | `role_seller_accounting` |
+| `SUPPORT` | `role_seller_support` |
## MemberInvite
-Table `member_invite`, id prefix `meminv`. A pending team invitation, carrying
-the invited `email`, target `seller_id`, `role_id`, and an expiry.
+A pending invitation to join a store. Table `member_invite`, id prefix `meminv`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `text` | Primary key |
+| `email` | `text` | Searchable, the invited address |
+| `token` | `text` | Signed JWT, indexed |
+| `accepted` | `boolean` | Default `false` |
+| `expires_at` | `dateTime` | Set by the service, 7 days out by default |
+| `role_id` | `text` | The `SellerRole` the member gets on accept |
+| `seller_id` | `text` | Belongs to `Seller` |
+| `metadata` | `json` | Nullable |
+
+A unique index on `(email, seller_id)` covers invites that aren’t accepted or deleted, so a store has one open invite per email.
+
+## OrderGroup
+
+The Seller module also holds the `OrderGroup` model, which groups the per-store orders split from one cart. See the [order group data models](/platform/order-group/reference/data-models) for its fields.
diff --git a/apps/docs/platform/store/reference/events.mdx b/apps/docs/platform/store/reference/events.mdx
index 8d9364648..92aaaa827 100644
--- a/apps/docs/platform/store/reference/events.mdx
+++ b/apps/docs/platform/store/reference/events.mdx
@@ -1,22 +1,23 @@
---
-title: "Event reference"
+title: "Seller module events"
sidebarTitle: "Events"
-description: "Events emitted by the Store domain, for subscribers and side effects."
+description: "Every event the store and team workflows emit, when each fires, and its payload."
---
-The Store domain emits events as stores and members change. Subscribe to them to
-run side effects such as sending notifications, syncing external systems, or
-kicking off follow-up workflows, instead of polling.
+The Seller module workflows emit events after they write. Subscribe to them to send notifications, sync an outside system, or start follow-up work without polling. The event names are exported from `@mercurjs/core/workflows` as `SellerWorkflowEvents`, `SellerMemberWorkflowEvents`, and `MemberInviteWorkflowEvents`.
```ts title="src/subscribers/store-approved.ts"
import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+import { MercurModules } from "@mercurjs/types"
-export default async function storeApprovedHandler({
+export default async function storeApproved({
event,
container,
}: SubscriberArgs<{ id: string }>) {
- const sellerId = event.data.id
- // ...send a welcome email, provision resources, etc.
+ const sellerService = container.resolve(MercurModules.SELLER)
+ const seller = await sellerService.retrieveSeller(event.data.id)
+
+ container.resolve("logger").info(`${seller.name} is open`)
}
export const config: SubscriberConfig = {
@@ -24,20 +25,44 @@ export const config: SubscriberConfig = {
}
```
+This subscriber loads the store when it’s approved. Store events carry only the id, so retrieve the record when you need more.
+
## Store events
+`SellerWorkflowEvents` covers creation, updates, and every status transition.
+
| Event | Emitted when | Payload |
| --- | --- | --- |
-| `seller.created` | A store is created | `{ id }` |
-| `seller.updated` | A store's profile changes | `{ id }` |
-| `seller.approved` | A store is approved (`→ open`) | `{ id }` |
-| `seller.suspended` | A store is suspended | `{ id }` |
-| `seller.terminated` | A store is terminated | `{ id }` |
+| `seller.created` | `createSellersWorkflow` or `createSellerAccountWorkflow` creates a store, once per store | `{ id }` |
+| `seller.updated` | `updateSellersWorkflow` updates a store, once per store | `{ id }` |
+| `seller.deleted` | `deleteSellersWorkflow` soft deletes a store, once per store | `{ id }` |
+| `seller.approved` | `approveSellerWorkflow` opens a pending store | `{ id }` |
+| `seller.suspended` | `suspendSellerWorkflow` suspends a store | `{ id }` |
+| `seller.unsuspended` | `unsuspendSellerWorkflow` reopens a suspended store | `{ id }` |
+| `seller.terminated` | `terminateSellerWorkflow` terminates a store | `{ id }` |
+| `seller.unterminated` | `unterminateSellerWorkflow` returns a terminated store to `suspended` | `{ id }` |
-## Member events
+The address, professional details, payment details, and region workflows don’t emit events.
+
+## Membership events
+
+`SellerMemberWorkflowEvents` covers memberships changed directly. Accepting an invite emits `member_invite.accepted` instead of `seller_member.created`.
| Event | Emitted when | Payload |
| --- | --- | --- |
-| `member_invite.created` | A team invite is sent | `{ id }` |
-| `member_invite.accepted` | An invite is accepted | `{ id }` |
-| `seller_member.created` | A member is added to a store | `{ id }` |
+| `seller_member.created` | `addSellerMemberWorkflow` adds a member to a store | `{ seller_id, member_id }` |
+| `seller_member.updated` | `updateMemberRoleWorkflow` changes a membership’s role | `{ seller_member_id }` |
+| `seller_member.deleted` | `removeSellerMemberWorkflow` removes a membership | `{ seller_id, seller_member_id }` |
+
+## Invite events
+
+`MemberInviteWorkflowEvents` covers team invites. The created payload includes the signed token, so a subscriber can build the invite link.
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `member_invite.created` | `createMemberInvitesWorkflow`, `resendMemberInviteWorkflow`, or `createSellersWorkflow` creates an invite, once per invite | `{ id, token, expires_at }` |
+| `member_invite.accepted` | `acceptMemberInviteWorkflow` turns an invite into a membership | `{ seller_id, member_id }` |
+
+<Warning>
+ The `member_invite.created` payload carries a working invite token. Don’t log it or forward it to systems that shouldn’t grant store access.
+</Warning>
diff --git a/apps/docs/platform/store/reference/links.mdx b/apps/docs/platform/store/reference/links.mdx
index c5cfc730c..a8681570c 100644
--- a/apps/docs/platform/store/reference/links.mdx
+++ b/apps/docs/platform/store/reference/links.mdx
@@ -1,71 +1,89 @@
---
-title: "Links to other modules"
+title: "Seller module links"
sidebarTitle: "Links"
-description: "How the Store (Seller) domain links to other modules across the marketplace."
+description: "Every module link that connects the Seller module to other modules, with cardinality, source file, and query.graph aliases."
---
-Modules in Mercur never reference each other directly. They connect through
-**module links**. The Seller module is the most linked domain in the marketplace,
-and almost every other module attaches to a store. Once a link is defined, you
-retrieve related records with `query.graph` using the link alias.
+Mercur modules never reference each other directly: they connect through module links defined in `packages/core/src/links`. The `seller` entity is the most linked record in the marketplace. Once a link exists, `query.graph` resolves the other side through the link’s alias.
```ts
-const { data: stores } = await query.graph({
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
+
+const query = container.resolve(ContainerRegistrationKeys.QUERY)
+
+const { data: [seller] } = await query.graph({
entity: "seller",
- fields: ["id", "name", "offers.*", "payout_account.*"],
+ fields: ["id", "name", "regions.*", "payout_account.*"],
+ filters: { id: "sel_01JD8Q1234567" },
})
```
-## Commerce
+The tables below list the alias on each side. Read the “From seller” column as a field on `seller`, and the “From the other side” column as a field on the linked entity.
+
+## Catalog and offers
+
+These links decide what a store sells and where it’s listed.
+
+| Link | Cardinality | From seller | From the other side | File |
+| --- | --- | --- | --- | --- |
+| Product | many-to-many, table `product_seller` | `products` | `product.sellers` | `product-seller-link.ts` |
+| Product category | many-to-many | `product_categories` | `product_category.sellers` | `category-seller-link.ts` |
+| Offer | many offers to one seller, read-only | none | `offer.seller` | `offer-seller-link.ts` |
+
+The offer link is read-only and built on the `offer.seller_id` column, so you can’t create or dismiss it through the Link API. Query it from the offer side.
+
+## Orders and payouts
+
+These links attach a store’s sales and settlements.
+
+| Link | Cardinality | From seller | From the other side | File |
+| --- | --- | --- | --- | --- |
+| Order | many orders to one seller | `orders` | `order.seller` | `order-seller-link.ts` |
+| Payout | many payouts to one seller | `payouts` | `payout.seller` | `payout-seller-link.ts` |
+| Payout account | one-to-one | `payout_account` | `payout_account.seller` | `seller-payout-account-link.ts` |
+
+## Regions and customers
+
+These links set where a store trades and who it serves.
+
+| Link | Cardinality | From seller | From the other side | File |
+| --- | --- | --- | --- | --- |
+| Region | many-to-many, table `region_seller` | `regions` | `region.sellers` | `region-seller-link.ts` |
+| Customer | many-to-many | `customers` | `customer.sellers` | `seller-customer-link.ts` |
+| Customer group | many groups to one seller | `customer_groups` | `customer_group.seller` | `seller-customer-group-link.ts` |
-| Linked module | Relationship |
-| --- | --- |
-| **Offer** | A store has many offers (`offer.seller_id`, read-only). Offers are how a store sells against a master product. |
-| **Product** | Many-to-many allowlist (`product_seller`) that controls which stores may sell a given master product. |
-| **Product category** | Many-to-many link to the categories a store is associated with. |
-| **Order** | Each order belongs to one store; a store has many orders. |
+`createSellersWorkflow` and `createSellerAccountWorkflow` create the region links. `linkSellerRegionsWorkflow` changes them later.
-## Payouts
+## Fulfillment and inventory
-| Linked module | Relationship |
-| --- | --- |
-| **Payout** | A store has many payouts. |
-| **Payout account** | A store has one payout account (its provider onboarding record). |
+These links scope fulfillment setup and stock to a store.
-## Customers
+| Link | Cardinality | From seller | From the other side | File |
+| --- | --- | --- | --- | --- |
+| Fulfillment set | many sets to one seller | `fulfillment_sets` | `fulfillment_set.seller` | `fulfillment-set-seller-link.ts` |
+| Service zone | many zones to one seller | `service_zones` | `service_zone.seller` | `service-zone-seller-link.ts` |
+| Shipping option | many options to one seller | `shipping_options` | `shipping_option.seller` | `shipping-option-seller-link.ts` |
+| Stock location | many locations to one seller | `stock_locations` | `stock_location.seller` | `stock-location-seller-link.ts` |
+| Inventory item | many items to one seller | `inventory_items` | `inventory_item.seller` | `inventory-item-seller-link.ts` |
-| Linked module | Relationship |
-| --- | --- |
-| **Customer** | Many-to-many link to the customers associated with a store. |
-| **Customer group** | A customer group is owned by exactly one store; a store owns many groups. |
+## Pricing and promotions
-## Fulfillment & inventory
+These links scope a store’s own pricing and marketing.
-| Linked module | Relationship |
-| --- | --- |
-| **Shipping profile** | A store has many shipping profiles. |
-| **Shipping option** | A store has many shipping options. |
-| **Service zone** | A store has many service zones. |
-| **Fulfillment set** | A store has many fulfillment sets. |
-| **Stock location** | A store has many stock locations. |
-| **Inventory item** | A store has many inventory items. |
+| Link | Cardinality | From seller | From the other side | File |
+| --- | --- | --- | --- | --- |
+| Price list | many lists to one seller | `price_lists` | `price_list.seller` | `price-list-seller-link.ts` |
+| Promotion | many promotions to one seller | `promotions` | `promotion.seller` | `promotion-seller-link.ts` |
+| Campaign | many campaigns to one seller | `campaigns` | `campaign.seller` | `campaign-seller-link.ts` |
-## Pricing & promotions
+## Reviews
-| Linked module | Relationship |
-| --- | --- |
-| **Price list** | A store has many price lists. |
-| **Promotion** | A store has many promotions. |
-| **Campaign** | A store has many campaigns. |
+This link attaches customer reviews of a store.
-## Access & reviews
+| Link | Cardinality | From seller | From the other side | File |
+| --- | --- | --- | --- | --- |
+| Review | many reviews to one seller | `reviews` | `review.seller` | `seller-review.ts` |
-| Linked module | Relationship |
-| --- | --- |
-| **RBAC role** | A member's role on a store (`seller_member.role_id`, read-only) resolves against the roles module. |
-| **Review** | A store has many reviews. |
+## Order groups
-<Note>
- Read-only links (Offer, RBAC role) are resolved from the field on the owning
- record and can't be written through the link itself.
-</Note>
+The order group links start from `OrderGroup`, which lives in the Seller module, not from `Seller`. See the [order group links](/platform/order-group/reference/links) for `order-group-order-link.ts` and `order-group-cart-link.ts`.
diff --git a/apps/docs/platform/store/reference/service.mdx b/apps/docs/platform/store/reference/service.mdx
index db8e76a1a..4f134408a 100644
--- a/apps/docs/platform/store/reference/service.mdx
+++ b/apps/docs/platform/store/reference/service.mdx
@@ -1,51 +1,123 @@
---
-title: "Service reference"
+title: "Seller module service"
sidebarTitle: "Service"
-description: "The Seller module service and its methods for working with records directly."
+description: "Resolve the Seller module service, and the generated and custom methods it exposes for direct reads and writes."
---
-The Seller module exposes a service you can resolve from the Medusa container to
-read and write records directly, without going through a workflow. Use it inside
-custom services, subscribers, or scheduled jobs.
+The Seller module service reads and writes the module’s records directly, without a workflow. Use it for reads in subscribers, scheduled jobs, and custom steps. Its writes don’t emit events, run hooks, or roll back, so prefer the [workflows](/platform/store/reference/workflows) for changes.
+
+## Resolve the service
+
+Resolve the service from the Medusa container with the `MercurModules.SELLER` key from `@mercurjs/types`.
```ts
-import { MercurModules } from "@mercurjs/types"
+import { MercurModules, SellerStatus } from "@mercurjs/types"
-const sellerModuleService = container.resolve(MercurModules.SELLER)
+const sellerService = container.resolve(MercurModules.SELLER)
-const [sellers, count] = await sellerModuleService.listAndCountSellers({
- status: "open",
-})
+const [sellers, count] = await sellerService.listAndCountSellers(
+ { status: SellerStatus.OPEN, is_premium: true },
+ { take: 20, order: { created_at: "DESC" } }
+)
```
+This lists the 20 newest open premium stores and the total count of matches.
+
## Generated methods
-Each data model gets a standard set of auto-generated methods. For `Seller`:
+The service extends Medusa’s `MedusaService`, which generates the same eight methods for every model. For `Seller` they are:
| Method | Description |
| --- | --- |
-| `createSellers(data)` | Create one or more stores |
-| `retrieveSeller(id, config?)` | Retrieve a store by id |
-| `listSellers(filters?, config?)` | List stores matching filters |
-| `listAndCountSellers(filters?, config?)` | List stores with a total count |
-| `updateSellers(data)` | Update one or more stores |
-| `deleteSellers(ids)` | Delete one or more stores |
+| `retrieveSeller(id, config?)` | Retrieve one store by id |
+| `listSellers(filters?, config?)` | List stores that match filters |
+| `listAndCountSellers(filters?, config?)` | List stores and return the total count |
+| `createSellers(data)` | Create one store or an array of stores |
+| `updateSellers(data)` | Update one store or an array of stores by id |
+| `deleteSellers(ids)` | Hard delete stores |
+| `softDeleteSellers(ids)` | Soft delete stores |
+| `restoreSellers(ids)` | Restore soft deleted stores |
-The same set exists for every model in the module, such as `Member`, `SellerMember`,
-`MemberInvite`, `ProfessionalDetails`, `SellerAddress`, and `PaymentDetails`
-(e.g. `createMembers`, `listMemberInvites`, `updatePaymentDetails`).
+Each model gets the same set under its own name:
-## Team methods
-
-| Method | Description |
+| Model | Method names |
| --- | --- |
-| `addSellerMember(data)` | Attach a member to a store |
-| `removeSellerMember(sellerId, memberId)` | Detach a member from a store |
-| `createMemberInvites(data)` | Create pending team invitations |
-| `updateMember(data)` | Update a member record |
-
-<Warning>
- Prefer [workflows](/platform/store/reference/workflows) for anything with side
- effects (status changes, invites, payouts). The service writes records
- directly and does **not** emit events or run compensation.
-</Warning>
+| `Member` | `retrieveMember`, `listMembers`, `createMembers`, `updateMembers`, … |
+| `SellerMember` | `retrieveSellerMember`, `listSellerMembers`, `createSellerMembers`, … |
+| `MemberInvite` | `retrieveMemberInvite`, `listMemberInvites`, `deleteMemberInvites`, … |
+| `SellerAddress` | `listSellerAddresses`, `createSellerAddresses`, `updateSellerAddresses`, … |
+| `ProfessionalDetails` | `listProfessionalDetails`, `createProfessionalDetails`, … |
+| `PaymentDetails` | `listPaymentDetails`, `createPaymentDetails`, `updatePaymentDetails`, … |
+| `OrderGroup` | `retrieveOrderGroup`, `listOrderGroups`, `listAndCountOrderGroups`, … |
+
+## Custom methods
+
+The service overrides some generated methods and adds a few of its own.
+
+### createSellers and updateSellers
+
+```ts
+createSellers(
+ data: CreateSellerDTO | CreateSellerDTO[]
+): Promise<SellerDTO | SellerDTO[]>
+
+updateSellers(
+ data: UpdateSellerDTO | UpdateSellerDTO[]
+): Promise<SellerDTO | SellerDTO[]>
+```
+
+Both validate `handle` and throw `INVALID_DATA` when it isn’t URL safe. When `handle` is missing and `name` is present, both set the handle from the name.
+
+### upsertMembers
+
+```ts
+upsertMembers(
+ data: {
+ email: string
+ first_name?: string | null
+ last_name?: string | null
+ }[]
+): Promise<MemberDTO[]>
+```
+
+Matches members by `email` and creates the missing ones. For existing members, it fills `first_name` and `last_name` only when they’re empty. It returns the members in input order.
+
+### createMemberInvites
+
+```ts
+createMemberInvites(
+ data: CreateMemberInviteDTO | CreateMemberInviteDTO[]
+): Promise<MemberInviteDTO | MemberInviteDTO[]>
+```
+
+Throws `INVALID_DATA` if an email already belongs to the target store. For each invite, it signs a JWT with the module’s `jwt_secret`, stores it in `token`, and sets `expires_at` from `invite_valid_duration`.
+
+### validateMemberInviteToken
+
+```ts
+validateMemberInviteToken(token: string): Promise<MemberInviteDTO>
+```
+
+Verifies the token’s signature and returns its invite. Throws `INVALID_DATA` for a bad signature, and `NOT_ALLOWED` when the invite is accepted or expired.
+
+### getStatistics
+
+```ts
+getStatistics(): Promise<SellerStatisticsOutput>
+```
+
+Counts stores by status and returns `{ total, premium, by_status }`, where `by_status` has a key for every `SellerStatus` value.
+
+### Order group reads
+
+`listOrderGroups`, `listAndCountOrderGroups`, and `retrieveOrderGroup` go through a custom repository that computes `seller_count` and `total`. See the [order group service](/platform/order-group/reference/service).
+
+## Module options
+
+The service reads these options from its module registration, typed by `SellerModuleOptions`:
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `invite_valid_duration` | `604800` | Invite lifetime in seconds, 7 days |
+| `jwt_secret` | `projectConfig.http.jwtSecret` | Secret used to sign and verify invite tokens |
+| `vendor_url` | `MERCUR_VENDOR_URL`, or `""` | Base URL of the Vendor panel |
diff --git a/apps/docs/platform/store/reference/workflows.mdx b/apps/docs/platform/store/reference/workflows.mdx
index 870358d3a..87abd27db 100644
--- a/apps/docs/platform/store/reference/workflows.mdx
+++ b/apps/docs/platform/store/reference/workflows.mdx
@@ -1,35 +1,315 @@
---
-title: "Workflows"
+title: "Seller module workflows"
sidebarTitle: "Workflows"
-description: "Seller and member workflows, service methods, and events."
+description: "Every store, lifecycle, business-detail, and team workflow in the Seller module, with inputs, hooks, and events."
---
-This reference lists the workflows, service methods, and events for the Store
-domain. Import workflows from `@mercurjs/core/workflows` and run them against the
-Medusa container.
+This reference lists every workflow that writes Seller module data. Import them from `@mercurjs/core/workflows` and run them against the Medusa container: `await workflow(container).run({ input })`. Workflows roll back their completed steps when a later step fails.
-## Seller workflows
+```ts
+import { approveSellerWorkflow } from "@mercurjs/core/workflows"
-| Workflow | Input | Purpose |
+await approveSellerWorkflow(container).run({
+ input: { seller_id: "sel_01JD8Q1234567" },
+})
+```
+
+Workflows that take `additional_data` pass it to their hooks. Register a hook handler with `workflow.hooks.<hookName>(handler)`.
+
+## createSellersWorkflow
+
+Creates one or more stores, links each to the default region plus `region_ids`, and invites one member per store with `role_seller_administration`. Returns `SellerDTO[]`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `sellers` | `CreateSellerDTO & { member, region_ids? }[]` | Store fields; `status` defaults to `pending_approval` |
+| `sellers[].member` | `{ email: string }` | Required, the address that gets the invite |
+| `sellers[].region_ids` | `string[]` | Optional, regions besides the default one |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `validate` (`{ input }`), `sellersCreated` (`{ sellers, additional_data }`)
+- **Events**: `seller.created` per store, `member_invite.created` per invite
+
+## createSellerAccountWorkflow
+
+Creates one store in `pending_approval` and adds a member as its owner with `role_seller_administration`. Returns `SellerDTO`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `auth_identity_id` | `string` | The auth identity to attach the member to |
+| `seller` | `CreateSellerDTO` | Store fields; `status` is forced to `pending_approval` |
+| `member_id` | `string` | Optional, an existing member to make owner |
+| `member_email` | `string` | Used when `member_id` is absent to upsert a member |
+| `first_name`, `last_name` | `string` | Optional, set on a new member |
+| `address` | `UpdateSellerAddressDTO` | Optional, written through `updateSellerAddressWorkflow` |
+| `professional_details` | `UpdateProfessionalDetailsDTO` | Optional |
+| `payment_details` | `UpdatePaymentDetailsDTO` | Optional |
+| `region_ids` | `string[]` | Optional, regions besides the default one |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `validate` (`{ input }`), `sellerAccountCreated` (`{ seller, member_id, additional_data }`)
+- **Events**: `seller.created`
+
+## updateSellersWorkflow
+
+Updates every store that matches `selector` with the same `update`. Returns `SellerDTO[]`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `selector` | `Record<string, unknown>` | Filters, such as `{ id: "sel_01JD8Q1234567" }` |
+| `update` | `UpdateSellerDTO` | Fields to set |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `sellersUpdated` (`{ sellers, additional_data }`)
+- **Events**: `seller.updated` per store
+
+## deleteSellersWorkflow
+
+Soft deletes stores by id. Compensation restores them.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `ids` | `string[]` | Seller ids |
+
+- **Hooks**: none
+- **Events**: `seller.deleted` per store
+
+## approveSellerWorkflow
+
+Moves a `pending_approval` store to `open`, clears `status_reason`, and sets `approved_at` if it’s empty.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `seller_id` | `string` | The store to approve |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `sellerApproved` (`{ seller_id, additional_data }`)
+- **Events**: `seller.approved`
+
+## suspendSellerWorkflow
+
+Moves a `pending_approval` or `open` store to `suspended`, saves `reason` in `status_reason`, and sets `rejected_at` if it’s empty.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `seller_id` | `string` | The store to suspend |
+| `reason` | `string` | Optional |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `sellerSuspended` (`{ seller_id, additional_data }`)
+- **Events**: `seller.suspended`
+
+## unsuspendSellerWorkflow
+
+Moves a `suspended` store to `open` and clears `status_reason`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `seller_id` | `string` | The store to reopen |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `sellerUnsuspended` (`{ seller_id, additional_data }`)
+- **Events**: `seller.unsuspended`
+
+## terminateSellerWorkflow
+
+Moves a `pending_approval` or `suspended` store to `terminated` and saves `reason` in `status_reason`. Fails for an `open` store.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `seller_id` | `string` | The store to terminate |
+| `reason` | `string` | Optional |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `sellerTerminated` (`{ seller_id, additional_data }`)
+- **Events**: `seller.terminated`
+
+## unterminateSellerWorkflow
+
+Moves a `terminated` store to `suspended` and clears `status_reason`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `seller_id` | `string` | The store to restore |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `sellerUnterminated` (`{ seller_id, additional_data }`)
+- **Events**: `seller.unterminated`
+
+## linkSellerRegionsWorkflow
+
+Adds and removes store region links in one run. Fails if a region or seller doesn’t exist, or if a store would be left with no region.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `add` | `{ seller_id, region_id }[]` | Optional, links to create |
+| `remove` | `{ seller_id, region_id }[]` | Optional, links to dismiss |
+
+- **Hooks**: none
+- **Events**: none
+
+## updateSellerAddressWorkflow
+
+Creates or updates a store’s `SellerAddress`. Returns `SellerAddressDTO`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `seller_id` | `string` | The store |
+| `data` | `UpdateSellerAddressDTO` | Address fields |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `addressUpdated` (`{ address, additional_data }`)
+- **Events**: none
+
+## updateSellerProfessionalDetailsWorkflow
+
+Creates or updates a store’s `ProfessionalDetails`. Returns `ProfessionalDetailsDTO`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `seller_id` | `string` | The store |
+| `data` | `UpdateProfessionalDetailsDTO` | `corporate_name`, `registration_number`, `tax_id` |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `professionalDetailsUpdated` (`{ professional_details, additional_data }`)
+- **Events**: none
+
+## deleteSellerProfessionalDetailsWorkflow
+
+Deletes a store’s `ProfessionalDetails`, if it has any.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `seller_id` | `string` | The store |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `professionalDetailsDeleted` (`{ seller_id, additional_data }`)
+- **Events**: none
+
+## updateSellerPaymentDetailsWorkflow
+
+Creates or updates a store’s `PaymentDetails`. Returns `PaymentDetailsDTO`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `seller_id` | `string` | The store |
+| `data` | `UpdatePaymentDetailsDTO` | Bank account fields |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `paymentDetailsUpdated` (`{ payment_details, additional_data }`)
+- **Events**: none
+
+## inviteSellerWorkflow
+
+Sends an email that invites someone to register a new store. It creates a notification with the template `newSellerInvitation` on the `email` channel, and writes no Seller module records.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `email` | `string` | The prospective seller |
+| `registration_url` | `string` | Optional, the link in the email’s button |
+
+- **Hooks**: none
+- **Events**: none
+
+## createMemberInvitesWorkflow
+
+Creates team invites with signed tokens. Fails if an email already belongs to the store. Returns `MemberInviteDTO[]`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `[].seller_id` | `string` | The store |
+| `[].email` | `string` | The invitee |
+| `[].role_id` | `string` | A `SellerRole` value |
+
+The input is an array of invites, not an object.
+
+- **Hooks**: none
+- **Events**: `member_invite.created` per invite
+
+## resendMemberInviteWorkflow
+
+Deletes an invite and creates a replacement with the same email and role, a new token, and a new expiry. Returns `MemberInviteDTO[]`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `invite_id` | `string` | The invite to replace |
+| `seller_id` | `string` | The store that owns it |
+
+- **Hooks**: none
+- **Events**: `member_invite.created`
+
+## deleteMemberInviteWorkflow
+
+Deletes an invite.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `invite_id` | `string` | The invite to delete |
+
+- **Hooks**: none
+- **Events**: none
+
+## acceptMemberInviteWorkflow
+
+Validates an invite token, upserts the member by email, creates the membership with the invite’s role, and deletes the invite. The member becomes owner when the store has no owner yet. Returns `MemberDTO`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `invite_token` | `string` | The token from the invite |
+| `auth_identity_id` | `string` | The invitee’s auth identity |
+| `member_id` | `string` | Optional; when set, the auth identity isn’t updated |
+| `first_name`, `last_name` | `string` | Optional, set on a new member |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `validate` (`{ input, invite }`), `memberInviteAccepted` (`{ member, invite, additional_data }`)
+- **Events**: `member_invite.accepted`
+
+## addSellerMemberWorkflow
+
+Adds an existing member to a store. Returns the `SellerMember`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `seller_id` | `string` | The store |
+| `member_id` | `string` | The existing member |
+| `role_id` | `string` | A `SellerRole` value |
+
+- **Hooks**: none
+- **Events**: `seller_member.created`
+
+## updateMemberRoleWorkflow
+
+Changes the role on a membership. Fails for the owner membership.
+
+| Input | Type | Description |
| --- | --- | --- |
-| `createSellersWorkflow` | `{ sellers[], additional_data? }` | Create stores with defaults |
-| `updateSellersWorkflow` | `{ selector, update }` | Update store fields |
-| `deleteSellersWorkflow` | `{ ids[] }` | Delete stores |
-| `approveSellerWorkflow` | `{ seller_id, additional_data? }` | `pending_approval` → `open` |
-| `suspendSellerWorkflow` | `{ seller_id }` | `open` → `suspended` |
-| `unsuspendSellerWorkflow` | `{ seller_id }` | `suspended` → `open` |
-| `terminateSellerWorkflow` | `{ seller_id }` | → `terminated` (irreversible) |
+| `seller_member_id` | `string` | The membership id (`selmem_…`) |
+| `role_id` | `string` | A `SellerRole` value |
+
+- **Hooks**: none
+- **Events**: `seller_member.updated`
+
+## removeSellerMemberWorkflow
+
+Deletes a membership and keeps the `Member` record. Fails for the owner membership.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `seller_member_id` | `string` | The membership id |
+| `seller_id` | `string` | The store, included in the event payload |
+
+- **Hooks**: none
+- **Events**: `seller_member.deleted`
+
+## updateMemberWorkflow
-## Member workflows
+Updates the profile of every member that matches `selector`. Returns `MemberDTO[]`.
-| Workflow | Input | Purpose |
+| Input | Type | Description |
| --- | --- | --- |
-| `inviteSellerWorkflow` | `{ email, seller_id }` | Create + send a member invite |
-| `acceptMemberInviteWorkflow` | `{ token }` | Accept an invite, link the member |
-| `addSellerMemberWorkflow` | `{ seller_id, member }` | Add a member directly |
-| `removeSellerMemberWorkflow` | `{ seller_id, member_id }` | Revoke access |
-| `updateMemberRoleWorkflow` | `{ id, role_id }` | Change a member's role |
+| `selector` | `Record<string, unknown>` | Filters, such as `{ id: "mem_01JD8Q1234567" }` |
+| `update` | `{ first_name?, last_name?, locale? }` | Profile fields |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
-To work with records directly instead of through a workflow, see the
-[Service reference](/platform/store/reference/service). To run side effects when
-a store changes, see the [Event reference](/platform/store/reference/events).
+- **Hooks**: `membersUpdated` (`{ members, additional_data }`)
+- **Events**: none