Order status change

wbhk

orderStatusChange

As an order progresses from initial import to full fulfillment, it transitions through multiple statuses. ShipMonk can notify external systems of these status changes via webhooks.

Supported Order Webhooks

Currently ShipMonk supports these order-related webhooks.

Order being back-ordered (processing_status: back-order)
Order is unable to submit (processing_status: unable_to_submit)
Order is queued to submit (processing_status: queued_to_submit)
Order is subscription - Order (processing_status: subscription)
Order is package-forwarding - Order (processing_status: package_forwarding)
Order is put to on hold (processing_status: on_hold)
Order is submitted (processing_status: submitted)
Order is being picked (processing_status: pick_in_progress)
Order is being packed (processing_status: pack_in_progress)
Order is packed (processing_status: packed)
Order is awaiting pickup (processing_status: awaiting_pick_up)
Order is awaiting carrier processing (processing_status: awaiting_carrier_processing)
Order is en route (processing_status: en_route)
Order is delivered (processing_status: delivered)
Order is undeliverable (processing_status: undeliverable)
Order is shipped, but it’s untrackable (processing_status: shipped_untrackable)
Order cancellation requested (processing_status: cancellation_requested)
Order is cancelled (processing_status: cancelled)

All order-related webhooks are closely tied to the order’s processing-status. Each webhook is triggered by a change in the processing-status, reflecting key moments in the order lifecycle.

Payload Structure (JSON Schema)

All order-related webhooks share the same JSON schema, which matches the response of our GET endpoint for retrieving a single order.

Payload

order_key

string

required

Unique identifier from an external system used to associate an order. Must be unique per order and store.

order_number

string

required

Customer-facing identifier for an order. Uniqueness is recommended but not strictly enforced.

order_type

Order Type | null

required

Order classification (e.g. standard, wholesale, return). Null when not categorized.

store

object

required

Sales channel or storefront the order originated from.

warehouse

Warehouse Detail Output | null

required

Warehouse where the order is processed. Null if a warehouse has not yet been assigned.

trading_partner

Account Trading Partner Output | null

required

B2B trading partner (e.g. retailer or distributor) the order is destined for. Null for direct-to-consumer orders.

ordered_at

date-time

required

ISO 8601 timestamp indicating when the order was originally placed.

customer_email

required

Customer's email address. Null when not provided by the source system.

shipping_method

Shipping Method Detail Output | null

required

Carrier and service selected to ship the order. Null if no method has been resolved yet.

requested_shipping_service

string | null

required

Free-text shipping service originally requested by the customer or source system; null if none was specified.

shipping_paid

double

required

Amount the customer paid for shipping, expressed in the order's currency_code.

tax_paid

double

required

Amount the customer paid in taxes, expressed in the order's currency_code.

order_costs

object

required

Estimated fulfillment-service charges (shipping, packaging, pick & pack) for the order. These are estimates and may differ from final billed amounts.

ship_from

Shipping Order Detail Address Output | null

required

Origin address from which the order will ship. Null when not yet determined.

ship_to

Shipping Order Detail Address Output | null

required

Destination address the order will be shipped to. Null when not yet specified.

order_status

string

enum

required

High-level order state: unfulfilled (not yet shipped), fulfilled (shipped), onHold (paused), cancelled.

Allowed:

processing_status

string

enum

required

Fine-grained processing stage of the order. Values: backorder, unable_to_submit, queued_to_submit, subscription, package_forwarding, awaiting_label_request_from_merchant_facility, on_hold, submitted, pick_in_progress, pack_in_progress, packed, awaiting_pick_up, awaiting_carrier_processing, en_route, delivered, undeliverable, shipped_untrackable, fulfilled_by_3rd, cancellation_requested, cancelled, updating.

items

array of objects

required

Line items (SKUs and quantities) included in the order.

items*

attributes

array of objects

required

Custom key/value attributes attached to the order by the merchant or source system.

attributes*

currency_code

string

required

ISO 4217 currency code used for all monetary values on the order.

references

array of objects

required

Additional external reference identifiers attached to the order (e.g. PO number, marketplace reference).

references*

custom_data

array of objects

required

Custom key-value data associated with the order.

custom_data*

special_requirements

Special Requirements Output | null

required

Special handling requirements for the order, such as required documents, label dates, and pack list rules. Null when none apply.

actions_required

object

required

Boolean flags indicating issues that must be resolved before the order can be fulfilled.

master_tracking_number

string | null

required

Master tracking number that groups all packages of a multi-piece shipment; null when not applicable.

tracking_url

string | null

required

Carrier URL where the customer can track the shipment; null if not yet available.

returns

array of objects

required

Return Merchandise Authorizations (RMAs) created for this order.

returns*

packages

array of objects

required

Per-package fulfillment data, including tracking numbers, weights, and packed contents.

packages*

tax_id

Order Tax Id Output | null

required

deprecated

Deprecated: Use recipientTaxId Deprecated; use recipient_tax_id instead. Tax identifier associated with the recipient.

recipient_tax_id

Order Tax Id Output | null

required

Recipient tax identification (e.g. VAT or EIN); null when not provided. Used for customs clearance on international shipments.

shipment_data

Shipment Data Output | null

required

Carrier and tracking details once the order has shipped; null until shipment data is available.

order_parts

Order Part Output | null

required

Information about related orders when an order has been split into multiple parts; null if the order was not split.

shipped_at

date-time | null

required

ISO 8601 timestamp of when the order was shipped; null if not yet shipped.

updated_at

date-time | null

required

ISO 8601 timestamp of when the order was last updated; null if never updated since creation.

order_size

string

enum

required

Size classification of the order based on item dimensions: unknown, regular, oversized_item, large, or extra_large.

Allowed:

extra_data

array of objects

required

Additional key/value attributes attached to the shipment notification (e.g. carrier shipping method).

extra_data*

serial_numbers

array of objects

required

Serial numbers of items fulfilled in the order, grouped by order line.

serial_numbers*

gift_message

string | null

required

Gift message to include with the order; null if the order is not a gift.

gift_from

string | null

required

Name of the gift sender; null if the order is not a gift.

customer_notes

string | null

required

Customer-provided notes about the order; null if no notes were submitted.

order_detail_url

string

required

URL to view the order in the ShipMonk web application (requires sign-in).

Responses

200

Return a 2xx status to indicate that the data was received successfully

default

For a 4xx status, ShipMonk will retry the webhook delivery up to 100 times, with a 5-minute delay between attempts.