@mercurjs/docs 2.2.0-canary.40

package/content/references/workflows/media/set-collection-images.mdx

@@ -0,0 +1,41 @@
+---
+title: "setCollectionImagesWorkflow"
+description: "Replace a collection's media gallery and icon, enforcing single thumbnail/banner."
+---
+
+Replaces a product collection's media. When `media` is provided, the entire existing gallery is swapped for the new list; when `icon` is provided, the existing icon image is swapped (pass `null` to clear it). Omitted fields are left untouched. At most one image keeps `is_thumbnail` and one keeps `is_banner` — the first flagged entry wins and later flags are silently dropped. Usually invoked through the `createProductCollectionWithImagesWorkflow`, `updateProductCollectionWithImagesWorkflow`, and `deleteProductCollectionWithImagesWorkflow` wrappers behind the `/admin/collections` routes.
+
+## Usage
+
+```ts
+import { setCollectionImagesWorkflow } from "@mercurjs/core/workflows"
+
+await setCollectionImagesWorkflow(container).run({
+  input: {
+    collection_id: "pcol_123",
+    media: [
+      { url: "https://cdn.example.com/hero.jpg", is_banner: true },
+      { url: "https://cdn.example.com/thumb.jpg", is_thumbnail: true },
+    ],
+    icon: "https://cdn.example.com/icon.svg",
+  },
+})
+```
+
+## Input
+
+<ParamField body="collection_id" type="string" required>The collection whose images are replaced.</ParamField>
+<ParamField body="media" type="CollectionMediaInput[]">
+  New gallery; replaces all existing non-icon images (pass `[]` to clear).
+  <Expandable title="properties">
+    <ParamField body="url" type="string" required>Public URL of the image.</ParamField>
+    <ParamField body="is_thumbnail" type="boolean">Mark as the thumbnail; only the first flagged image is honoured.</ParamField>
+    <ParamField body="is_banner" type="boolean">Mark as the banner; only the first flagged image is honoured.</ParamField>
+    <ParamField body="rank" type="number">Sort rank; defaults to the array index.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="icon" type="string | null">New icon URL; `null` removes the current icon, omit to keep it.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">No return value.</ResponseField>

package/content/references/workflows/member/accept-member-invite.mdx

@@ -0,0 +1,33 @@
+---
+title: "acceptMemberInviteWorkflow"
+description: "Redeem an invite token and join a seller's team."
+---
+
+Validates the invite token, upserts the member by the invited email, links them to the seller with the invited role (as owner if the seller has none yet), binds the auth identity when the member is new, and deletes the consumed invite. Triggered by `POST /vendor/members/invites/accept`. Emits `member_invite.accepted`.
+
+## Usage
+
+```ts
+import { acceptMemberInviteWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await acceptMemberInviteWorkflow(container).run({
+  input: {
+    invite_token: "eyJhbGciOi...",
+    auth_identity_id: "authid_123",
+    first_name: "Jane",
+    last_name: "Doe",
+  },
+})
+```
+
+## Input
+
+<ParamField body="invite_token" type="string" required>Signed invite token from the invitation link.</ParamField>
+<ParamField body="auth_identity_id" type="string" required>Auth identity of the accepting user.</ParamField>
+<ParamField body="member_id" type="string">Existing member id; when set, no auth metadata is written.</ParamField>
+<ParamField body="first_name" type="string">First name for a newly created member.</ParamField>
+<ParamField body="last_name" type="string">Last name for a newly created member.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="MemberDTO">The member linked to the seller.</ResponseField>

package/content/references/workflows/member/add-seller-member.mdx

@@ -0,0 +1,30 @@
+---
+title: "addSellerMemberWorkflow"
+description: "Attach an existing member to a seller with a role."
+---
+
+Creates a seller-member link between an existing member and a seller with the given role. Triggered by `POST /admin/sellers/:id/members` and `POST /vendor/sellers/:id/members`. Emits `seller_member.created`.
+
+## Usage
+
+```ts
+import { addSellerMemberWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await addSellerMemberWorkflow(container).run({
+  input: {
+    seller_id: "sel_123",
+    member_id: "mem_123",
+    role_id: "role_seller_support",
+  },
+})
+```
+
+## Input
+
+<ParamField body="seller_id" type="string" required>Id of the seller.</ParamField>
+<ParamField body="member_id" type="string" required>Id of the member to attach.</ParamField>
+<ParamField body="role_id" type="string" required>Role to assign, e.g. `role_seller_administration`, `role_seller_support`.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="SellerMemberDTO">The created seller-member link.</ResponseField>

package/content/references/workflows/member/create-member-invites.mdx

@@ -0,0 +1,34 @@
+---
+title: "createMemberInvitesWorkflow"
+description: "Create tokenized member invitations for sellers."
+---
+
+Creates invite records with a signed token and expiry for each entry. Triggered by `POST /admin/sellers/:id/members/invite` and the vendor invite routes; also run as a step by `createSellersWorkflow` for the initial member. Emits `member_invite.created` with `{ id, token, expires_at }` per invite, which typically drives the invitation email.
+
+## Usage
+
+```ts
+import { createMemberInvitesWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await createMemberInvitesWorkflow(container).run({
+  input: [
+    {
+      seller_id: "sel_123",
+      email: "teammate@acme.co",
+      role_id: "role_seller_support",
+    },
+  ],
+})
+```
+
+## Input
+
+The input is an array of invites.
+
+<ParamField body="[].seller_id" type="string" required>Seller the invite belongs to.</ParamField>
+<ParamField body="[].email" type="string" required>Email of the invitee.</ParamField>
+<ParamField body="[].role_id" type="string" required>Role the invitee receives on acceptance.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="MemberInviteDTO[]">The created invites, including `token` and `expires_at`.</ResponseField>

package/content/references/workflows/member/delete-member-invite.mdx

@@ -0,0 +1,24 @@
+---
+title: "deleteMemberInviteWorkflow"
+description: "Delete a pending member invite."
+---
+
+Deletes the invite so its token can no longer be redeemed. Triggered by `DELETE /admin/sellers/:id/members/invites/:invite_id` and the vendor equivalent.
+
+## Usage
+
+```ts
+import { deleteMemberInviteWorkflow } from "@mercurjs/core/workflows"
+
+await deleteMemberInviteWorkflow(container).run({
+  input: { invite_id: "meminv_123" },
+})
+```
+
+## Input
+
+<ParamField body="invite_id" type="string" required>Id of the invite to delete.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">Nothing is returned.</ResponseField>

package/content/references/workflows/member/remove-seller-member.mdx

@@ -0,0 +1,28 @@
+---
+title: "removeSellerMemberWorkflow"
+description: "Remove a member from a seller's team."
+---
+
+Validates the seller-member link can be removed (owners cannot be removed), then deletes it. Triggered by `DELETE /admin/sellers/:id/members/:member_id` and `DELETE /vendor/sellers/:id/members/:member_id`. Emits `seller_member.deleted`.
+
+## Usage
+
+```ts
+import { removeSellerMemberWorkflow } from "@mercurjs/core/workflows"
+
+await removeSellerMemberWorkflow(container).run({
+  input: {
+    seller_member_id: "selmem_123",
+    seller_id: "sel_123",
+  },
+})
+```
+
+## Input
+
+<ParamField body="seller_member_id" type="string" required>Id of the seller-member link to delete.</ParamField>
+<ParamField body="seller_id" type="string" required>Id of the seller, included in the emitted event.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">Nothing is returned.</ResponseField>

package/content/references/workflows/member/resend-member-invite.mdx

@@ -0,0 +1,28 @@
+---
+title: "resendMemberInviteWorkflow"
+description: "Re-issue a member invite with a fresh token."
+---
+
+Loads the existing invite, deletes it, and creates a new one with the same email and role — resetting the token and expiry. Triggered by `POST /admin/sellers/:id/members/invites/:invite_id/resend` and the vendor equivalent. Emits `member_invite.created` for the new invite.
+
+## Usage
+
+```ts
+import { resendMemberInviteWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await resendMemberInviteWorkflow(container).run({
+  input: {
+    invite_id: "meminv_123",
+    seller_id: "sel_123",
+  },
+})
+```
+
+## Input
+
+<ParamField body="invite_id" type="string" required>Id of the invite to re-issue; must belong to the seller.</ParamField>
+<ParamField body="seller_id" type="string" required>Seller the invite belongs to.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="MemberInviteDTO[]">The re-created invite (single-element array) with a new `token` and `expires_at`.</ResponseField>

package/content/references/workflows/member/update-member-role.mdx

@@ -0,0 +1,28 @@
+---
+title: "updateMemberRoleWorkflow"
+description: "Change a team member's role."
+---
+
+Validates the target is not the seller owner, then updates the seller-member link's role. Triggered by `POST /admin/sellers/:id/members/:member_id` and `POST /vendor/sellers/:id/members/:member_id`. Emits `seller_member.updated`.
+
+## Usage
+
+```ts
+import { updateMemberRoleWorkflow } from "@mercurjs/core/workflows"
+
+await updateMemberRoleWorkflow(container).run({
+  input: {
+    seller_member_id: "selmem_123",
+    role_id: "role_seller_order_management",
+  },
+})
+```
+
+## Input
+
+<ParamField body="seller_member_id" type="string" required>Id of the seller-member link to update; must not be the owner.</ParamField>
+<ParamField body="role_id" type="string" required>New role to assign.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">Nothing is returned.</ResponseField>

package/content/references/workflows/member/update-member.mdx

@@ -0,0 +1,35 @@
+---
+title: "updateMemberWorkflow"
+description: "Update member profile fields matching a selector."
+---
+
+Updates every member matching the selector — name and locale only. Triggered by `POST /vendor/members/me` when a member edits their own profile.
+
+## Usage
+
+```ts
+import { updateMemberWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await updateMemberWorkflow(container).run({
+  input: {
+    selector: { id: "mem_123" },
+    update: { first_name: "Jane", last_name: "Doe" },
+  },
+})
+```
+
+## Input
+
+<ParamField body="selector" type="object" required>Filter selecting the members to update, e.g. `{ id: "mem_123" }`.</ParamField>
+<ParamField body="update" type="object" required>
+  Fields to update.
+  <Expandable title="properties">
+    <ParamField body="first_name" type="string | null">First name.</ParamField>
+    <ParamField body="last_name" type="string | null">Last name.</ParamField>
+    <ParamField body="locale" type="string | null">Preferred locale.</ParamField>
+  </Expandable>
+</ParamField>
+
+## Result
+
+<ResponseField name="result" type="MemberDTO[]">The updated members.</ResponseField>

package/content/references/workflows/offer/batch-offer-inventory-items.mdx

@@ -0,0 +1,58 @@
+---
+title: "batchOfferInventoryItemsWorkflow"
+description: "Create, update, and delete an offer's inventory-item links in one call."
+---
+
+Manages the `offer ↔ inventory_item` links that define what stock an offer consumes. Validates the payload (no duplicates, no ID in more than one bucket, created items must exist, deleted items must already be linked), then batches the link changes — each link carries a `required_quantity` (default `1`). Emits `offer.updated`. Triggered by `POST /vendor/offers/:id/inventory-items/batch`.
+
+## Usage
+
+```ts
+import { batchOfferInventoryItemsWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await batchOfferInventoryItemsWorkflow(container).run({
+  input: {
+    offer_id: "offer_123",
+    create: [{ inventory_item_id: "iitem_1", required_quantity: 2 }],
+    update: [{ inventory_item_id: "iitem_2", required_quantity: 1 }],
+    delete: ["iitem_3"],
+  },
+})
+```
+
+## Input
+
+<ParamField body="offer_id" type="string" required>The offer whose inventory links are managed; fails if not found.</ParamField>
+<ParamField body="create" type="object[]">Links to create; the inventory items must exist and not appear in `update`/`delete`.
+  <Expandable title="properties">
+    <ParamField body="inventory_item_id" type="string" required>The inventory item to link.</ParamField>
+    <ParamField body="required_quantity" type="number">Units consumed per offer unit; defaults to `1`.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="update" type="object[]">Existing links to update.
+  <Expandable title="properties">
+    <ParamField body="inventory_item_id" type="string" required>The linked inventory item.</ParamField>
+    <ParamField body="required_quantity" type="number" required>New units consumed per offer unit.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="delete" type="string[]">Inventory item IDs to unlink; each must currently be linked or the workflow throws a 404.</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed through to the workflow hooks.</ParamField>
+
+## Result
+
+<ResponseField name="result.created" type="LinkDefinition[]">The created offer ↔ inventory-item links.</ResponseField>
+<ResponseField name="result.updated" type="LinkDefinition[]">The updated links.</ResponseField>
+<ResponseField name="result.deleted" type="string[]">Inventory item IDs that were unlinked.</ResponseField>
+
+## Hooks
+
+- `validate` — runs first with `{ input }`.
+- `offerInventoryItemsBatched` — runs after the batch with `{ offer_id, result, additional_data }`.
+
+```ts
+batchOfferInventoryItemsWorkflow.hooks.offerInventoryItemsBatched(
+  async ({ offer_id, result }) => {
+    // react to link changes
+  }
+)
+```

package/content/references/workflows/offer/create-offers.mdx

@@ -0,0 +1,63 @@
+---
+title: "createOffersWorkflow"
+description: "Create seller offers with inventory items and offer-scoped prices."
+---
+
+Creates one offer per entry: creates and links new inventory items (with optional starting stock levels) to the offer and the seller, ensures the master variant has a `PriceSet`, writes the offer's prices onto that shared set scoped by an `offer_id` price rule, and links the price rows to the offer. Emits `offer.created`. Triggered by `POST /vendor/offers` and the vendor/admin offer batch routes.
+
+## Usage
+
+```ts
+import { createOffersWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await createOffersWorkflow(container).run({
+  input: {
+    offers: [
+      {
+        seller_id: "sel_123",
+        created_by: "member_123",
+        variant_id: "variant_123",
+        shipping_profile_id: "sp_123",
+        sku: "ACME-TEE-M",
+        inventory_items: [
+          { stock_levels: [{ location_id: "sloc_123", stocked_quantity: 50 }] },
+        ],
+        prices: [{ amount: 1999, currency_code: "usd" }],
+      },
+    ],
+  },
+})
+```
+
+## Input
+
+<ParamField body="offers" type="object[]" required>Offers to create.
+  <Expandable title="properties">
+    <ParamField body="seller_id" type="string" required>The seller that owns the offer.</ParamField>
+    <ParamField body="created_by" type="string" required>ID of the member creating the offer.</ParamField>
+    <ParamField body="sku" type="string" required>The offer's SKU.</ParamField>
+    <ParamField body="variant_id" type="string" required>The master product variant the offer sells; fails if not found.</ParamField>
+    <ParamField body="shipping_profile_id" type="string" required>Shipping profile used to fulfill the offer.</ParamField>
+    <ParamField body="inventory_items" type="object[]" required>New inventory items to create and link; at least one entry. Each entry accepts `sku`, `title`, `required_quantity` (default `1`), and `stock_levels` (`{ location_id, stocked_quantity }[]`).</ParamField>
+    <ParamField body="prices" type="object[]" required>Offer price ladder; each row accepts `amount`, `currency_code`, `min_quantity`, `max_quantity`, and `rules`.</ParamField>
+    <ParamField body="ean" type="string | null">EAN; snapshotted from the variant when omitted.</ParamField>
+    <ParamField body="upc" type="string | null">UPC; snapshotted from the variant when omitted.</ParamField>
+    <ParamField body="metadata" type="object | null">Custom key-value data.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed through to the workflow hooks.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="OfferDTO[]">The created offers.</ResponseField>
+
+## Hooks
+
+- `validate` — runs first with `{ input }`.
+- `offersCreated` — runs after creation with `{ offers, additional_data }`.
+
+```ts
+createOffersWorkflow.hooks.offersCreated(async ({ offers, additional_data }) => {
+  // react to new offers
+})
+```

package/content/references/workflows/offer/delete-offers.mdx

@@ -0,0 +1,35 @@
+---
+title: "deleteOffersWorkflow"
+description: "Delete one or more offers."
+---
+
+Deletes the given offers and emits `offer.deleted` with each offer's `id` and `product_id`. Triggered by `DELETE /vendor/offers/:id`, `DELETE /admin/offers/:id`, and the offer batch routes.
+
+## Usage
+
+```ts
+import { deleteOffersWorkflow } from "@mercurjs/core/workflows"
+
+await deleteOffersWorkflow(container).run({
+  input: { ids: ["offer_123"] },
+})
+```
+
+## Input
+
+<ParamField body="ids" type="string[]" required>IDs of the offers to delete.</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed through to the workflow hooks.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">No return value; the offers are deleted.</ResponseField>
+
+## Hooks
+
+- `offersDeleted` — runs after deletion with `{ ids, additional_data }`.
+
+```ts
+deleteOffersWorkflow.hooks.offersDeleted(async ({ ids, additional_data }) => {
+  // react to deleted offers
+})
+```

package/content/references/workflows/offer/update-offers.mdx

@@ -0,0 +1,51 @@
+---
+title: "updateOffersWorkflow"
+description: "Update offer rows and rewrite their price ladders with replace semantics."
+---
+
+Applies partial updates to offer rows (`sku`, `shipping_profile_id`, `metadata`). When an entry sets `prices`, the offer's price ladder is rewritten with replace semantics: rows with `id` are updated in place, rows without `id` are added, and existing offer-owned prices omitted from the array are removed — all on the variant's shared `PriceSet`, scoped by the `offer_id` price rule. Price ownership is asserted so an offer can't touch another offer's rows. Emits `offer.updated`. Triggered by `POST /vendor/offers/:id` and the offer batch routes.
+
+## Usage
+
+```ts
+import { updateOffersWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await updateOffersWorkflow(container).run({
+  input: {
+    offers: [
+      {
+        id: "offer_123",
+        prices: [{ amount: 1799, currency_code: "usd" }],
+      },
+    ],
+  },
+})
+```
+
+## Input
+
+<ParamField body="offers" type="object[]" required>Offer updates, keyed by ID.
+  <Expandable title="properties">
+    <ParamField body="id" type="string" required>The offer to update; fails if not found.</ParamField>
+    <ParamField body="sku" type="string">New SKU.</ParamField>
+    <ParamField body="shipping_profile_id" type="string">New shipping profile.</ParamField>
+    <ParamField body="metadata" type="object | null">Custom key-value data.</ParamField>
+    <ParamField body="prices" type="object[]">Full replacement price ladder; each row accepts `id` (update in place when set), `amount`, `currency_code`, `min_quantity`, `max_quantity`, and `rules`. Omit the field to leave prices untouched.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed through to the workflow hooks.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="OfferDTO[]">The updated offers.</ResponseField>
+
+## Hooks
+
+- `validate` — runs first with `{ input }`.
+- `offersUpdated` — runs after the update with `{ offers, additional_data }`.
+
+```ts
+updateOffersWorkflow.hooks.offersUpdated(async ({ offers, additional_data }) => {
+  // react to updated offers
+})
+```

package/content/references/workflows/order/cancel-order-fulfillment.mdx

@@ -0,0 +1,34 @@
+---
+title: "cancelOrderFulfillmentWorkflow"
+description: "Cancel an unshipped fulfillment and restore reservations and stock."
+---
+
+Mercur's offer-aware replacement for Medusa's cancel-order-fulfillment flow. Validates that the fulfillment exists, is not shipped, and not already canceled, then cancels it on the order and at the provider, re-creates or tops up reservations, and adjusts inventory back up — dividing line quantities by each offer's `required_quantity` so bundle offers restock correctly. Triggered by `POST /vendor/orders/:id/fulfillments/:fulfillment_id/cancel`. Emits `order.fulfillment_canceled`.
+
+## Usage
+
+```ts
+import { cancelOrderFulfillmentWorkflow } from "@mercurjs/core/workflows"
+
+await cancelOrderFulfillmentWorkflow(container).run({
+  input: {
+    order_id: "order_123",
+    fulfillment_id: "ful_123",
+  },
+})
+```
+
+## Input
+
+<ParamField body="order_id" type="string" required>The order the fulfillment belongs to; must not be canceled.</ParamField>
+<ParamField body="fulfillment_id" type="string" required>The fulfillment to cancel; shipped or already-canceled fulfillments throw.</ParamField>
+<ParamField body="no_notification" type="boolean">Suppress customer notification for the cancellation.</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed through to the hooks.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">No return value.</ResponseField>
+
+## Hooks
+
+- `orderFulfillmentCanceled` — runs after cancellation with `{ fulfillment, additional_data }`.

package/content/references/workflows/order/confirm-claim-request.mdx

@@ -0,0 +1,25 @@
+---
+title: "confirmClaimRequestWorkflow"
+description: "Confirm a claim request and fix reservations for offer bundles."
+---
+
+Wraps Medusa's `confirmClaimRequestWorkflow` and then rewrites the reservations created for the claim's additional items when those items come from offers: single-link offers get their reservation quantity scaled by `required_quantity`, multi-link (bundle) offers have the default reservation replaced with one reservation per linked inventory item. Triggered by `POST /admin/claims/:id/request` and `POST /vendor/claims/:id/request`. Events are emitted by the wrapped Medusa workflow.
+
+## Usage
+
+```ts
+import { confirmClaimRequestWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await confirmClaimRequestWorkflow(container).run({
+  input: { claim_id: "claim_123", confirmed_by: "user_123" },
+})
+```
+
+## Input
+
+<ParamField body="claim_id" type="string" required>The claim whose pending request is confirmed.</ParamField>
+<ParamField body="confirmed_by" type="string">Id of the user confirming the claim.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="OrderPreviewDTO">Preview of the order with the confirmed claim applied.</ResponseField>

package/content/references/workflows/order/confirm-exchange-request.mdx

@@ -0,0 +1,25 @@
+---
+title: "confirmExchangeRequestWorkflow"
+description: "Confirm an exchange request and fix reservations for offer bundles."
+---
+
+Wraps Medusa's `confirmExchangeRequestWorkflow` and then rewrites the reservations created for the exchange's additional items when those items come from offers: single-link offers get their reservation quantity scaled by `required_quantity`, multi-link (bundle) offers have the default reservation replaced with one reservation per linked inventory item. Triggered by `POST /admin/exchanges/:id/request` and `POST /vendor/exchanges/:id/request`. Events are emitted by the wrapped Medusa workflow.
+
+## Usage
+
+```ts
+import { confirmExchangeRequestWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await confirmExchangeRequestWorkflow(container).run({
+  input: { exchange_id: "exchange_123", confirmed_by: "user_123" },
+})
+```
+
+## Input
+
+<ParamField body="exchange_id" type="string" required>The exchange whose pending request is confirmed.</ParamField>
+<ParamField body="confirmed_by" type="string">Id of the user confirming the exchange.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="OrderPreviewDTO">Preview of the order with the confirmed exchange applied.</ResponseField>

package/content/references/workflows/order/confirm-order-edit-request.mdx

@@ -0,0 +1,25 @@
+---
+title: "confirmOrderEditRequestWorkflow"
+description: "Confirm an order edit and reconcile offer-bundle reservations."
+---
+
+Wraps Medusa's `confirmOrderEditRequestWorkflow` and then reconciles reservations for every unfulfilled order item that comes from an offer with inventory links: desired quantities are computed as `(ordered - fulfilled) × required_quantity` per linked inventory item, and mismatching reservations are replaced with a correct set (one per linked item, bundle offers included). Triggered by `POST /admin/order-edits/:id/confirm` and `POST /vendor/order-edits/:id/confirm`. Events are emitted by the wrapped Medusa workflow.
+
+## Usage
+
+```ts
+import { confirmOrderEditRequestWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await confirmOrderEditRequestWorkflow(container).run({
+  input: { order_id: "order_123", confirmed_by: "user_123" },
+})
+```
+
+## Input
+
+<ParamField body="order_id" type="string" required>The order whose pending edit is confirmed.</ParamField>
+<ParamField body="confirmed_by" type="string">Id of the user confirming the edit.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="OrderPreviewDTO">Preview of the order with the confirmed edit applied.</ResponseField>

package/content/references/workflows/order/confirm-return-receive.mdx

@@ -0,0 +1,25 @@
+---
+title: "confirmReturnReceiveWorkflow"
+description: "Confirm a return receival, offer-aware restock included."
+---
+
+Mercur's offer-aware replacement for Medusa's confirm-return-receive flow. Applies the pending receive actions of the return's order change, updates return items' received/damaged quantities, marks the return `received` (or `partially_received`), restocks inventory — expanding offer bundle links by `required_quantity` — and refreshes the order payment collection. Throws when a bundle offer has no stock level at the return's location. Triggered by `POST /admin/returns/:id/receive/confirm` and `POST /vendor/returns/:id/receive/confirm`. Emits `order.return_received`.
+
+## Usage
+
+```ts
+import { confirmReturnReceiveWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await confirmReturnReceiveWorkflow(container).run({
+  input: { return_id: "return_123", confirmed_by: "user_123" },
+})
+```
+
+## Input
+
+<ParamField body="return_id" type="string" required>The return whose pending receival is confirmed.</ParamField>
+<ParamField body="confirmed_by" type="string">Id of the user confirming the receival.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="OrderPreviewDTO">Preview of the order with the confirmed changes applied.</ResponseField>