September 22, 2026 · Ahmed · More by Ahmed
Ending Fulfillment's IN_PROGRESS Black Box
Shopify's new fulfillmentOrderReportProgress mutation lets 3PLs post status updates mid-fulfillment, plus two webhooks and stricter cancel/move errors.
Until API version 2026-04, a fulfillment order sitting in IN_PROGRESS status was largely opaque to the merchant watching it: work had started somewhere in a 3PL's warehouse or a fulfillment app's pipeline, but nothing surfaced until a shipment appeared. The new fulfillmentOrderReportProgress mutation gives 3PLs and fulfillment apps a way to post a status update onto the fulfillment order while it's still being worked, with an optional short note for the merchant to read.
This isn't a general observability platform bolted onto fulfillment — it's a narrow, specific mutation with documented eligibility rules, and any automation pipeline that wants to expose real fulfillment-stage visibility to ops teams needs to know exactly where it applies.
Eligibility and the reasonNotes Field
The mutation's scope depends on who manages the fulfillment order. For 3PL-managed fulfillment orders, it works only when the order is already in IN_PROGRESS status. For merchant-managed fulfillment orders, it works on orders in either OPEN or IN_PROGRESS status, but calling it requires the write_merchant_managed_fulfillment_orders scope — a merchant-managed integration without that scope can't use it.
An optional reasonNotes field, capped at 256 characters, carries a short human-readable note alongside the status — enough for "picked, awaiting carrier pickup," not a full audit log. Before calling the mutation, an integration can check fulfillmentOrder.supportedActions for the REPORT_PROGRESS action to confirm eligibility rather than calling blind and handling a rejection.
Two New Webhooks
Two webhook topics ship alongside the mutation. fulfillment_orders/progress_reported fires whenever progress is reported, and its payload carries the fulfillment order's ID and status, the initial_status before the update, and a progress_report object with the reason_notes text and attribution data for which app or user reported it. fulfillment_orders/manually_reported_progress_stopped fires specifically for merchant-managed orders: when a merchant who had manually reported progress marks the order "ready for fulfillment" again, moving it from IN_PROGRESS back to OPEN, this webhook tells any listening app that the merchant undid the in-progress status.
Cancel and Move Now Fail Differently
The same release changed error handling on two related mutations specifically because progress reporting now exists. fulfillmentOrderCancel returns a specific fulfillmentOrderCancelError type, with a code field, instead of a generic userError, built to let integrations programmatically detect when a cancellation is restricted because the order has reported progress. fulfillmentOrderMove similarly now returns fulfillmentOrderMoveUserError with its own code field, since moving a fulfillment order that has reported progress is restricted. Automation that cancels or reroutes fulfillment orders should expect these typed errors rather than the older generic shape, and should treat a reported-progress order as one that needs different handling before it can be cancelled or moved.