Starting with API version 2026-04, 3PLs and shipping apps can report fulfillment order progress via fulfillmentOrderReportProgress. They can signal that work has begun, optionally with a short status note. Merchants gain visibility into the shipping pipeline.
fulfillmentOrderReportProgress mutation lets 3PLs and shipping apps notify Shopify that work has started, making the progress visible to merchants.
After handing off an order, merchants had no standard API-based way to know whether the 3PL had actually started work or hadn't touched it yet.
The shipping side reports progress via the mutation → the status is updated and a webhook fires. An optional note (reasonNotes) can also be attached.
fulfillmentOrder.supportedActions returns REPORT_PROGRESS an action.The progress statuses you can report differ depending on whether the order is "3PL-managed" or "merchant-managed."
| Item | 3PL-managed fulfillment order | Merchant-managed fulfillment order |
|---|---|---|
| Reportable statuses | IN_PROGRESS | OPEN or IN_PROGRESS |
| Required scope | Not listed (intended for fulfillment services) | write_merchant_managed_fulfillment_orders |
| reasonNotes | Optional A supplementary note of up to 256 characters can be attached | |
Intended to return progress on orders that have already been handed off to a fulfillment service and are in progress (IN_PROGRESS).
You can report progress even while the order is still OPEN, transitioning it to IN_PROGRESS. However, a write scope is required.
fulfillment_orders/progress_reportedFires when progress is reported on a fulfillment order.
Included in the payload:
fulfillment_orders/manually_reported_progress_stoppedWhen progress was manually reported (fulfillmentOrderReportProgress via)merchant-managedfulfillment order is subsequently marked as "ready for fulfillment,"moving back from IN_PROGRESS to OPENthe webhook fires.
= The app can detect that the merchant has "undone/cancelled" the previously reported "in progress" state.
You can attach a short note describing the situation, such as "picking started" or "awaiting stock." It gives merchants a clue about the current state of their shipping pipeline. It is also reflected in the webhook's reason_notes .
On orders where progress reporting is possible, fulfillmentOrder.supportedActions returns REPORT_PROGRESS . By checking for this action in advance before firing the mutation, you can avoid unnecessary errors.
This mutation, webhooks, andREPORT_PROGRESS action are available from API version 2026-04 onward. Apps still hitting older versions need to upgrade.
3PL-managed orders require IN_PROGRESS only; merchant-managed orders accept either OPEN/IN_PROGRESS . Check the target order's type and status before sending.
Reporting on merchant-managed orders requires the write_merchant_managed_fulfillment_orders scope. Review your OAuth scope configuration.
progress_reported detects the start of work, andmanually_reported_progress_stopped detects a rollback to OPEN. The latter fires only when a merchant-managed order is returned to "ready."
progress_reported The webhook payload includes attribution data for the reporting app/user and initial_status(the status before the update).Useful for audit logs and tracking "which 3PL started work and when,"especially in environments where multiple shipping apps coexist.
fulfillmentOrderReportProgress and attaches details like "picking started" to reasonNotes .supportedActions contains REPORT_PROGRESS before invoking it.fulfillment_orders/progress_reported and manually_reported_progress_stopped , and fire notifications when received.initial_status and progress_report to format state transitions and notes into the notification body.progress_reported Store the webhook's attribution data (reporting app/user) along with the timestamp, building a per-order progress log.reason_notes tied to the order ID in chronological order. Cross-referencing with completion events also lets you compute start-to-completion lead time.