Skip to main content
Mercur’s offer-aware replacement for Medusa’s create-order-fulfillment flow. Validates the order and items, creates the fulfillment, registers it on the order, links it, and consumes reservations / adjusts inventory — multiplying quantities by each offer’s required_quantity inventory links so bundle offers deduct the right stock. Triggered by POST /vendor/orders/:id/fulfillments. Emits order.fulfillment_created.

​
Usage

import { createOrderFulfillmentWorkflow } from "@mercurjs/core/workflows"

const { result } = await createOrderFulfillmentWorkflow(container).run({
  input: {
    order_id: "order_123",
    items: [{ id: "ordli_123", quantity: 1 }],
  },
})

​
Input

​
order_id
string
required
The order to fulfill.
​
items
{ id: string; quantity: number }[]
required
Order line items and quantities to fulfill; all items must either require shipping or not — mixed requests throw.
​
location_id
string
Stock location to fulfill from; defaults to the shipping option’s linked location.
​
shipping_option_id
string
Shipping option to fulfill with; defaults to the order’s first shipping method.
​
created_by
string
Id of the user creating the fulfillment.
​
labels
FulfillmentLabelDTO[]
Tracking labels to attach.
​
no_notification
boolean
Suppress customer notification for this fulfillment.
​
metadata
object | null
Custom key-value data on the fulfillment.
​
additional_data
object
Custom data passed through to the hooks.

​
Result

​
result
FulfillmentDTO
The created fulfillment.

​
Hooks

  • fulfillmentCreated — runs after creation with { fulfillment, additional_data }.
createOrderFulfillmentWorkflow.hooks.fulfillmentCreated(async ({ fulfillment }) => {
  // push to a 3PL
})