---
title: "Shipment Notification"
method: POST
path: "orderShipmentNotification"
tags: ["Webhooks"]
---

# Shipment Notification

`POST orderShipmentNotification` (webhook)

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`.

## Payload

- ShipMonkOMSNotificationApiResourceShipmentNotificationOutput
  - `order_key` string, required — Client-supplied order key (external order identifier) of the shipped order.
  - `parent_order_key` string, nullable, 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` ShipMonkOMSNotificationApiResourceShipmentNotificationItemWithProductLotOutput[], required — Order line items included in the shipment, each with the product lots allocated to fulfill it.
    - `line_key` string, nullable, required — Client-supplied key identifying this order line; null when the line has no key.
    - `quantity` integer, required — Ordered quantity of this line. Deprecated alias of ordered_quantity, kept for backwards compatibility.
    - `ordered_quantity` integer, required — Quantity of this line that was ordered.
    - `sku` string, required — SKU of the ordered product or bundle on this line.
    - `name` string, nullable, required — Human-readable name of the product; null when unavailable.
    - `source` 'imported' | 'manual' | 'inserted' | 'packaging' | 'claim_reship', required
    - `products` ShipMonkOMSNotificationApiResourceShipmentNotificationProductLotOutput[], required — Products allocated to fulfill this line, including bundle components, each with its lot data.
      - `sku` string, required — SKU of the product allocated to fulfill the line.
      - `quantity` integer, required — Allocated quantity of this product. Deprecated alias of ordered_quantity, kept for backwards compatibility.
      - `ordered_quantity` integer, required — Quantity of this product allocated to the line.
      - `lot` ShipMonkOMSNotificationApiResourceShipmentNotificationLotOutput, required
        - `number` string, nullable, required — Lot or batch number; null when the product has no lot number.
        - `expiration_date` string, date, nullable, required — Expiration date of the lot in ISO 8601 format (YYYY-MM-DD); null when the lot does not expire or is unknown.
      - `other_potential_lots` ShipMonkOMSNotificationApiResourceShipmentNotificationLotOutput[], required — Additional lots that could fulfill this product when the primary lot is insufficient.
        - `number` string, nullable, required — Lot or batch number; null when the product has no lot number.
        - `expiration_date` string, date, nullable, required — Expiration date of the lot in ISO 8601 format (YYYY-MM-DD); null when the lot does not expire or is unknown.
    - `fulfilled_quantity` integer, required — Quantity of this line that was actually fulfilled and shipped.
  - `store_id` string, required — Identifier of the store (sales channel or integration) the order belongs to.
  - `carrier` union, required — Name of the shipping carrier (tracking company) used for the shipment. For standard shipments it is one value from the list. In cases involving custom labels or freight shipments, the field may contain values outside of this list.
    - 'CanadaPost' | 'Cirro' | 'DHL eCommerce' | 'DHL Express' | 'DPD' | 'FedEx' | 'Global-E' | 'International Bridge' | 'OnTrac' | 'Passport' | 'Royal Mail' | 'ShipMonk' | 'SpeedX' | 'UPS' | 'USPS'
    - string
  - `service` string, nullable, 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, nullable, required — ShipMonk tracking page URL for the shipment; null when unavailable.
  - `estimated_shipping_cost` number, double, nullable, required — Estimated shipping cost of the shipment in the account currency; null when not calculated.
  - `custom_data` ShipMonkOMSNotificationApiResourceCustomDataOutput[], required — Arbitrary name and value pairs supplied by the client integration on the order.
    - `name` string, required — Name (key) of the custom data field supplied by the client integration.
    - `value` object, required — Value of the custom data field; its type depends on what the integration supplied.
  - `carrier_tracking_url` string, nullable, required — Tracking page URL hosted by the carrier for the shipment; null when unavailable.
  - `carrier_alpha_code` string, nullable, required — Carrier SCAC (Standard Carrier Alpha Code); null when unknown.
  - `carrier_trans_method_code` string, nullable, required — Carrier transportation method code describing the mode of transport; null when not provided.
  - `bill_of_lading_number` string, nullable, required — Bill of Lading (BOL) number for the shipment; null when not applicable.
  - `master_bill_of_lading_number` string, nullable, required — Master Bill of Lading (MBOL) number grouping multiple bills of lading; null when not applicable.
  - `load_number` string, nullable, required — Freight load number assigned to the shipment; null for non-freight shipments.
  - `authorization_number` string, nullable, required — Routing or freight authorization number for the shipment; null when none was assigned.
  - `order_parts` ShipMonkOMSNotificationApiResourceOrderPartsOutput, required
    - `main_order` ShipMonkOMSNotificationApiResourceMainOrderOutput, required
      - `order_number` string, required — Order number of the main order.
      - `parts` ShipMonkOMSNotificationApiResourceOrderPartOutput[], required — Partial orders this main order was split into; empty when the order was not split.
        - `order_number` string, required — Order number of the split order.
  - `serial_numbers` ShipMonkOMSNotificationApiResourceSerialNumbersOutput[], required — Serial numbers captured during fulfillment, grouped per order line.
    - `line_key` string, nullable, required — Client-supplied key of the order line these serial numbers belong to; null when the line has no key.
    - `serial_numbers` ShipMonkOMSNotificationApiResourceSerialNumberItemOutput[], required — Serial numbers scanned for the products on this line.
      - `sku` string, required — SKU of the product the serial number belongs to.
      - `serial_number` string, required — Serial number scanned for the product unit.
  - `order_size` 'unknown' | 'regular' | 'oversized_item' | 'large' | 'extra_large', required
  - `extra_data` ShipMonkOMSNotificationApiResourceShipmentNotificationExtraDataOutput[], required — Additional carrier and shipment metadata as label and value pairs.
    - `label` 'carrierShippingMethod', required
    - `value` string, required — Value associated with the label.
  - `routing` ShipMonkOMSNotificationApiResourceRoutingOutput, required
    - `routing_key` string, nullable, required — Client-supplied routing key for the shipment; null when not provided.
  - `ordered_at` union, 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.
    - ShipMonkOMSNotificationApiResourceDateTimeOutput
      - `date` string, required — Local date and time formatted as "Y-m-d H:i:s.u".
      - `timezone` string, required — Name of the timezone the date is expressed in (e.g. America/New_York).
      - `timezone_type` integer, required — PHP timezone type identifier describing how the timezone is represented (3 = timezone name).
    - string
  - `shipped_at` union, required — Time the order shipped. Returned as an ISO 8601 string for most stores, or as a structured date object for selected legacy integrations.
    - ShipMonkOMSNotificationApiResourceDateTimeOutput
      - `date` string, required — Local date and time formatted as "Y-m-d H:i:s.u".
      - `timezone` string, required — Name of the timezone the date is expressed in (e.g. America/New_York).
      - `timezone_type` integer, required — PHP timezone type identifier describing how the timezone is represented (3 = timezone name).
    - string
  - `packages` ShipMonkOMSNotificationApiResourcePackageOutput[], required — Packages (boxes) that make up the shipment.
    - `tracking_number` string, nullable, required — Tracking number of this package; null when not yet assigned.
    - `tracking_link` string, nullable, required — ShipMonk tracking page URL for this package; null when unavailable.
    - `carrier_tracking_url` string, nullable, required — Tracking page URL hosted by the carrier for this package; null when unavailable.
    - `weight_lb` number, double, nullable, required — Weight of the package in pounds (lb); null when unknown.
    - `packed_products` object[], nullable, required — Products packed into this package, each with sku, quantity and lot details (lot_number, expiration_date); null when packed products are not tracked for this package.
      - `sku` string, required
      - `quantity` integer, required
      - `lots` object[], required
        - `lot_number` string, nullable, required
        - `expiration_date` string, nullable, required
      - `line_key` string, nullable, required
    - `box_number` integer, nullable, required — Sequential number of this box within the shipment; null when not applicable.
    - `pallet_number` integer, nullable, required — Number of the pallet this package is placed on; null when the package is not on a pallet.
    - `carton_labels` ShipMonkOMSNotificationApiResourcePackingLabelOutput[], nullable, required — Labels (e.g. carton or GS1 labels) attached to this package; null when none.
      - `type` string, required — Type of the label. One of: shipmonk_pack_list_order_level, shipmonk_pack_list_carton_level, retailer_packing_slip_order_level, shipmonk_carton_label, shipmonk_pallet_label, gs1_label, shipmonk_gs1, customized_carton_labels, custom_pack_list_order_level, special_instructions.
      - `identifier` string, nullable, required — Identifier (e.g. barcode value) printed on the label; null when none.
    - `pallet_weight_lb` number, double, nullable, required — Total weight of the pallet this package belongs to, in pounds (lb); null when not palletized.
    - `packing_group` FulfillmentIntegrationsBundleCrateNotifyShipmentPackingConfigurationPackingGroupOutput, required
      - `key` string, required
      - `name` string, nullable, required
    - `packed_items` ShipMonkOMSNotificationApiResourcePackedOrderItemOutput[], nullable, required — Order items packed into this package with quantities; null when not tracked at item level.
      - `sku` string, required — Marketplace SKU of the packed order item.
      - `line_key` string, nullable, required — Client-supplied key of the order line this item belongs to; null when the line has no key.
      - `quantity` integer, required — Quantity of this item packed into the package.
  - `pallets` ShipMonkOMSNotificationApiResourcePalletOutput[], required — Pallets consolidating the shipment packages; empty when the shipment is not palletized.
    - `number` integer, required — Sequential number of the pallet within the shipment.
    - `weight` ShipMonkMeasurementOutputWeightOutput, required
      - `value` number, double, required — Numeric weight value, expressed in the unit given by the unit field.
      - `unit` 'kg' | 'g' | 'lb' | 'oz', required
    - `dimensions` ShipMonkMeasurementOutputDimensionsOutput, required
      - `length` number, double, required — Length in the unit specified by the sibling "unit" field.
      - `width` number, double, required — Width in the unit specified by the sibling "unit" field.
      - `height` number, double, required — Height in the unit specified by the sibling "unit" field.
      - `unit` 'm' | 'cm' | 'mm' | 'ft' | 'in', required
    - `labels` ShipMonkOMSNotificationApiResourcePackingLabelOutput[], required — Labels (e.g. pallet or GS1 labels) attached to the pallet.
      - `type` string, required — Type of the label. One of: shipmonk_pack_list_order_level, shipmonk_pack_list_carton_level, retailer_packing_slip_order_level, shipmonk_carton_label, shipmonk_pallet_label, gs1_label, shipmonk_gs1, customized_carton_labels, custom_pack_list_order_level, special_instructions.
      - `identifier` string, nullable, required — Identifier (e.g. barcode value) printed on the label; null when none.
  - `ship_from` ShipMonkOMSNotificationApiResourceShipFromAddressOutput, required
    - `name` string, nullable, required — Full name of the sender; null when not provided.
    - `company` string, nullable, required — Company name of the sender; null when not provided.
    - `street1` string, nullable, required — First line of the sender street address; null when not provided.
    - `street2` string, nullable, required — Second line of the sender street address; null when not provided.
    - `state` string, nullable, required — State, province or region of the sender; null when not provided.
    - `city` string, nullable, required — City of the sender; null when not provided.
    - `zip` string, nullable, required — Postal or ZIP code of the sender; null when not provided.
    - `country_code` string, nullable, required — ISO 3166-1 alpha-2 country code of the sender; null when not provided.
    - `phone` string, nullable, required — Phone number of the sender; null when not provided.
    - `email` string, nullable, required — Email address of the sender; null when not provided.
    - `residential` boolean, required — Whether the sender address is residential.
  - `ship_to` ShipMonkOMSNotificationApiResourceShipToAddressOutput, required
    - `name` string, nullable, required — Full name of the recipient; null when not provided.
    - `company` string, nullable, required — Company name of the recipient; null when not provided.
    - `street1` string, nullable, required — First line of the recipient street address; null when not provided.
    - `street2` string, nullable, required — Second line of the recipient street address; null when not provided.
    - `state` string, nullable, required — State, province or region of the recipient; null when not provided.
    - `city` string, nullable, required — City of the recipient; null when not provided.
    - `zip` string, nullable, required — Postal or ZIP code of the recipient; null when not provided.
    - `country_code` string, nullable, required — ISO 3166-1 alpha-2 country code of the recipient; null when not provided.
    - `phone` string, nullable, required — Phone number of the recipient; null when not provided.
    - `email` string, nullable, required — Email address of the recipient; null when not provided.
    - `residential` boolean, required — Whether the recipient address is residential.

## Acknowledgement `200`

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

## Other responses

- `default` — For a 4xx status, ShipMonk will retry the webhook delivery for the next 3 days.

---

[API](https://skmtc.net/shipmonk/apis/shipmonk-api.md) · [All operations](https://skmtc.net/shipmonk/apis/shipmonk-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shipmonk/shipmonk-api/revisions/5dc3234a38a5/schema)