Sign in

v3

latestOpenAPI 3.1.02026-08-0619186200.1 KB
Webhooks

Order status change

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.

postWebhookorderStatusChange

Payload

order_keystring required

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

order_numberstring required

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

order_type'direct_to_consumer' | 'retail' | 'amazon' | 'transfer' | 'internal_warehouse_transfer' | 'removal_liquidation' | 'disposal' | 'bonded_inventory_clearance' | 'work_order' required
ordered_atstring date-time required

ISO 8601 timestamp indicating when the order was originally placed.

customer_emailstring nullable required

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

requested_shipping_servicestring nullable required

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

shipping_paidnumber double required

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

tax_paidnumber double required

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

order_status'unfulfilled' | 'fulfilled' | 'onHold' | 'cancelled' required
processing_status'backorder' | 'unable_to_submit' | 'queued_to_submit' | 'subscription' | 'package_forwarding' | 'awaiting_self_fulfillment' | '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' required
currency_codestring required

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

master_tracking_numberstring nullable required

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

tracking_urlstring nullable required

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

shipped_atstring date-time nullable required

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

updated_atstring date-time nullable required

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

order_size'unknown' | 'regular' | 'oversized_item' | 'large' | 'extra_large' required
gift_messagestring nullable required

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

gift_fromstring nullable required

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

customer_notesstring nullable required

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

order_detail_urlstring required

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

Response

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