Shipment Notification

wbhk

orderShipmentNotification

Once the order is fulfilled, ShipMonk can notify the 3rd party software of such event via webhook or Marketplace via direct integration. The payload consists of tracking and packing information.

Triggers for sending notification are:

once regular order is packed
batch is completed
wholesale order is picked up

Notification is sent with delay which can be set per each store in ShipMonk OMS.

Your endpoint URL can be set up in the store detail in ShipMonk OMS. Please note that Basic Auth (username and password) is supported only.

We expect the status code 200 in response. When we receive another status call, we will be re-trying it for the next 3 days.

To test it, place the order and submit it for fulfilment. You have to make sure the inventory is available and order is all right first (it has set the shipping service and the address is valid). In production the order is shipped by our warehouse employees, while for testing you will have to call our complete-order endpoint.

Edge cases:

If the order is big and cannot fit into a single packaging, we will send out multiple packages. Each package has its own tracking number inside of packages array.
If the inventory of any SKU is not available, it is possible to manually split the order in the ShipMonk app and then we send Shipment Notification per each shipment.
If the order is split and send out within multiple days, we send the Shipment Notification just once (when the first package is sent out)

fulfilled_quantity vs ordered_quantity: The value of these two fields might differ in case of partially fulfilled Orders. If a Product consists of 1x Item A and 1x Item B, when the customer orders 2 Products and the Shipment contains 1 piece of Item A and 2 pieces of Item B, then ordered_quantity = 2 but fulfilled_quantity = 1.

The list of carriers as we return them via webhook as carrier:

#	Carrier
1	CanadaPost
2	Cirro
3	DHL eCommerce
4	DHL Express
5	DPD
6	ePost
7	FedEx
8	Global-E
9	OnTrac
10	Passport
11	Royal Mail
12	ShipMonk
13	SpeedX
14	UPS
15	USPS

The above carriers cover standard shipments. In cases involving custom labels or freight shipments, the carrier field may contain values outside of this list.

Payload

order_key

string

required

Client-supplied order key (external order identifier) of the shipped order.

parent_order_key

string | null

required

Key of the parent order when this order is part of a split or partial shipment; null for standalone orders.

order_number

string

required

ShipMonk internal order number of the shipped order.

warehouse

string

required

Code of the warehouse that fulfilled and shipped the order.

items

array of objects

required

Order line items included in the shipment, each with the product lots allocated to fulfill it.

items*

store_id

string

required

Identifier of the store (sales channel or integration) the order belongs to.

carrier

string

required

Name of the shipping carrier (tracking company) used for the shipment.

service

string | null

required

Carrier service level used for the shipment (e.g. Ground, Express); null when not applicable.

master_tracking_number

string

required

Primary tracking number of the shipment.

tracking_link

string | null

required

ShipMonk tracking page URL for the shipment; null when unavailable.

estimated_shipping_cost

double | null

required

Estimated shipping cost of the shipment in the account currency; null when not calculated.

custom_data

array of objects

required

Arbitrary name and value pairs supplied by the client integration on the order.

custom_data*

carrier_tracking_url

string | null

required

Tracking page URL hosted by the carrier for the shipment; null when unavailable.

carrier_alpha_code

string | null

required

Carrier SCAC (Standard Carrier Alpha Code); null when unknown.

carrier_trans_method_code

string | null

required

Carrier transportation method code describing the mode of transport; null when not provided.

bill_of_lading_number

string | null

required

Bill of Lading (BOL) number for the shipment; null when not applicable.

master_bill_of_lading_number

string | null

required

Master Bill of Lading (MBOL) number grouping multiple bills of lading; null when not applicable.

load_number

string | null

required

Freight load number assigned to the shipment; null for non-freight shipments.

authorization_number

string | null

required

Routing or freight authorization number for the shipment; null when none was assigned.

order_parts

object

required

Main order together with any partial orders it was split into.

serial_numbers

array of objects

required

Serial numbers captured during fulfillment, grouped per order line.

serial_numbers*

order_size

string

enum

required

Size category of the order. One of: unknown, regular, oversized_item, large, extra_large.

Allowed:

extra_data

array of objects

required

Additional carrier and shipment metadata as label and value pairs.

extra_data*

routing

Routing Output | null

required

Routing information for the shipment; null when the order has no routing.

ordered_at

Date Time Output | string

required

Time the order was placed. Returned as an ISO 8601 string for most stores, or as a structured date object for selected legacy integrations.

shipped_at

Date Time Output | string

required

Time the order shipped. Returned as an ISO 8601 string for most stores, or as a structured date object for selected legacy integrations.

packages

array of objects

required

Packages (boxes) that make up the shipment.

packages*

pallets

array of objects

required

Pallets consolidating the shipment packages; empty when the shipment is not palletized.

pallets*

ship_from

Ship From Address Output | null

required

Origin (sender) address of the shipment; null when not provided.

ship_to

object

required

Destination (recipient) address of the shipment.

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 for the next 3 days.