Get real-time event notifications for your Zonos integration.
This guide details the event types that Zonos can send as a webhook response. Each type returns a specific GraphQL object that contains the data relevant to the event.
The ORDER_STATUS_CHANGED event is triggered whenever an order status changes. It always returns an Order object. Possible statuses are found on the OrderStatus enum.
The ORDER_RETURN_CREATED event is triggered when a return is created on an order. The new return starts in the REQUESTED status.
Creating a return does not also send ORDER_RETURN_STATUS_CHANGED. Every status change after that one does.
1{
2"eventType":"ORDER_RETURN_CREATED",
3"orderReturnId":"order_return_[ID]"
4}
Get the return's details
Return events carry only the event type and the return's ID. To get the return's status, items, label, and history, query it with orderReturn, asking for the fields your integration needs. It returns an OrderReturn object.
1queryOrderReturn($id: ID!){
2 orderReturn(id:$id) {
3 id
4 status
5 order {
6 id
7 accountOrderNumber
8}
9 lines {
10 id
11 itemId
12 quantity
13 reason
14 disposition
15 note
16}
17 labelSource
18 carrier
19 trackingNumber
20 statusTransitions {
21 fromStatus
22 toStatus
23 actor
24 note
25 createdAt
26}
27 updatedAt
28}
29}
Note: The query returns the return as it is when you ask, not as it was when the event fired. If a return changes again quickly, it may already have moved past the status the event was about. Treat status as the return's current state, and use statusTransitions for its history. Entries in statusTransitions are not guaranteed to be in order, so sort them by createdAt.
The ORDER_RETURN_STATUS_CHANGED event is triggered whenever a return moves to a new status: approved, label issued, in transit, received, inspected, completed, rejected, or canceled.
The newest entry in the return's statusTransitions, by createdAt, shows the change: its fromStatus, its toStatus, who made it, and any note they left, such as the reason a return was rejected. To read it, query the return as shown under Get the return's details above.
The ORDER_RETURN_COMPLETED event is triggered when a return is completed and closed.
Completing a return also sends ORDER_RETURN_STATUS_CHANGED. If you only need to know when returns close, subscribe to ORDER_RETURN_COMPLETED alone instead of handling every status change. If you subscribe to both, expect two webhooks when a return completes.
ORDER_RETURN_COMPLETED is not sent for rejected or canceled returns. Those end with ORDER_RETURN_STATUS_CHANGED only.
1{
2"eventType":"ORDER_RETURN_COMPLETED",
3"orderReturnId":"order_return_[ID]"
4}
Note: Completing a return never refunds the shopper. A completed return's linkedRefunds lists refunds you issued on the order and linked to the return. It does not mean Zonos issued them.
Event types
Webhook event types
Get real-time event notifications for your Zonos integration.
This guide details the event types that Zonos can send as a webhook response. Each type returns a specific GraphQL object that contains the data relevant to the event.
ORDER_CREATED
The
ORDER_CREATEDevent is triggered when a new order is created. It always returns anOrderobject.{"data": {"order": {"status": "OPEN","createdAt": "2024-07-23T16:18:57.104Z","accountOrderNumber": null,"currencyCode": "HKD","organization": "organization_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","amountSubtotals": {"duties": 0,"fees": 0,"items": 9999.99,"shipping": 9999.99,"taxes": 0,"variance": -0.01},"root": {"exchangeRates": [{"sourceCurrencyCode": "USD","targetCurrencyCode": "HKD","rate": 9.99999,"type": "GUARANTEED"},{"sourceCurrencyCode": "USD","targetCurrencyCode": "HKD","rate": 9.9999,"type": "MID_MARKET"},{"sourceCurrencyCode": "USD","targetCurrencyCode": "HKD","rate": 9.9999,"type": "MID_MARKET"},{"sourceCurrencyCode": "USD","targetCurrencyCode": "HKD","rate": 9.9999,"type": "MID_MARKET"},{"sourceCurrencyCode": "HKD","targetCurrencyCode": "USD","rate": 0.9999999999999999,"type": "MID_MARKET"}]},"items": [{"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Discount","productId": "","amount": 0,"imageUrl": "","currencyCode": "USD","description": null,"hsCode": "9999.99","sku": "DISCOUNT_SKU","countryOfOrigin": "CN","measurements": [{"type": "WEIGHT","unitOfMeasure": "POUND","value": 0}],"quantity": 1,"attributes": null},{"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 1","productId": "","amount": 999.99,"imageUrl": "https://example.com/product1-image.jpg","currencyCode": "USD","description": "Product 1 Description","hsCode": "9999.99.99","sku": "PRODUCT1_SKU","countryOfOrigin": "US","measurements": [{"type": "HEIGHT","unitOfMeasure": "INCH","value": 99},{"type": "LENGTH","unitOfMeasure": "INCH","value": 99},{"type": "WIDTH","unitOfMeasure": "INCH","value": 99},{"type": "WEIGHT","unitOfMeasure": "OUNCE","value": 999}],"quantity": 1,"attributes": null},{"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 2","productId": "","amount": 999.99,"imageUrl": "https://example.com/product2-image.jpg","currencyCode": "USD","description": "Product 2 Description","hsCode": "9999.99.99","sku": "PRODUCT2_SKU","countryOfOrigin": "US","measurements": [{"type": "HEIGHT","unitOfMeasure": "INCH","value": 99},{"type": "LENGTH","unitOfMeasure": "INCH","value": 99},{"type": "WIDTH","unitOfMeasure": "INCH","value": 99},{"type": "WEIGHT","unitOfMeasure": "OUNCE","value": 99}],"quantity": 1,"attributes": null},{"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Insurance","productId": "","amount": 99.99,"imageUrl": "","currencyCode": "USD","description": null,"hsCode": "","sku": "INSURANCE_SKU","countryOfOrigin": "US","measurements": [{"type": "WEIGHT","unitOfMeasure": "POUND","value": 9.999}],"quantity": 1,"attributes": null}],"paymentDetail": {"chargeId": "ch_xxxxxxxxxxxxxxxxxxxxxxxxxx","refunds": []},"landedCosts": [{"method": "DDP","landedCostGuaranteeCode": "GUARANTEE_CODE","currencyCode": "USD","amountSubtotals": {"landedCostTotal": 0,"duties": 0,"fees": 0,"taxes": 0,"items": 999.99,"shipping": 999.99},"remittance": [],"shipmentRating": {"displayName": "Shipping Method","serviceLevelCode": "shipping.service_code","amount": 999.99,"currencyCode": "USD","details": [{"amount": 9999.99,"carrierCode": "Carrier api: standard rate (shipping_rate)","type": "PUBLISHED_RATE"},{"amount": 999.99,"carrierCode": "Carrier api: fuel surcharge (999)","type": "FUEL_SURCHARGE"},{"amount": -9999.99,"carrierCode": "negotiated_rate","type": "DISCOUNT"}],"appliedRules": []},"deMinimis": [{"type": "DUTY","threshold": "ABOVE"},{"type": "TAX","threshold": "ABOVE"}],"duties": [{"amount": 0,"currencyCode": "USD","description": "duty","type": "ITEM","formula": "0.0 % cif","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 1","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 1 Description"}},{"amount": 0,"currencyCode": "USD","description": "duty","type": "SHIPPING","formula": "0.0 % cif","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 1","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 1 Description"}},{"amount": 0,"currencyCode": "USD","description": "duty","type": "ITEM","formula": "0.0 % cif","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Discount","productId": "","amount": 0,"currencyCode": "USD","quantity": 1,"description": null}},{"amount": 0,"currencyCode": "USD","description": "duty","type": "SHIPPING","formula": "0.0 % cif","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Discount","productId": "","amount": 0,"currencyCode": "USD","quantity": 1,"description": null}},{"amount": 0,"currencyCode": "USD","description": "duty","type": "ITEM","formula": "0.0 % cif","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 2","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 2 Description"}},{"amount": 0,"currencyCode": "USD","description": "duty","type": "SHIPPING","formula": "0.0 % cif","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 2","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 2 Description"}}],"taxes": [{"amount": 0,"currencyCode": "USD","description": "Tax","type": "ITEM","formula": "0%","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Discount","productId": "","amount": 0,"currencyCode": "USD","quantity": 1,"description": null}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "SHIPPING","formula": "0%","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Discount","productId": "","amount": 0,"currencyCode": "USD","quantity": 1,"description": null}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "ITEM","formula": "0%","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 1","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 1 Description"}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "SHIPPING","formula": "0%","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 1","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 1 Description"}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "ITEM","formula": "0%","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 2","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 2 Description"}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "SHIPPING","formula": "0%","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 2","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 2 Description"}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "DUTY","formula": "0%","note": "Tax on the duty of the item","item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 1","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 1 Description"}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "DUTY","formula": "0%","note": "Tax on the duty of the shipping","item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 1","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 1 Description"}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "DUTY","formula": "0%","note": "Tax on the duty of the item","item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Discount","productId": "","amount": 0,"currencyCode": "USD","quantity": 1,"description": null}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "DUTY","formula": "0%","note": "Tax on the duty of the shipping","item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Discount","productId": "","amount": 0,"currencyCode": "USD","quantity": 1,"description": null}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "DUTY","formula": "0%","note": "Tax on the duty of the item","item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 2","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 2 Description"}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "DUTY","formula": "0%","note": "Tax on the duty of the shipping","item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 2","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 2 Description"}}],"fees": []}]}}}ORDER_CANCELED
The
ORDER_CANCELEDevent is triggered when an order is canceled. It always returns anOrderobject.{"data": {"order": {"status": "OPEN","createdAt": "2024-07-23T16:18:57.104Z","accountOrderNumber": null,"currencyCode": "HKD","organization": "organization_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","amountSubtotals": {"duties": 0,"fees": 0,"items": 9999.99,"shipping": 9999.99,"taxes": 0,"variance": -0.01},"root": {"exchangeRates": [{"sourceCurrencyCode": "USD","targetCurrencyCode": "HKD","rate": 9.99999,"type": "GUARANTEED"},{"sourceCurrencyCode": "USD","targetCurrencyCode": "HKD","rate": 9.9999,"type": "MID_MARKET"},{"sourceCurrencyCode": "USD","targetCurrencyCode": "HKD","rate": 9.9999,"type": "MID_MARKET"},{"sourceCurrencyCode": "USD","targetCurrencyCode": "HKD","rate": 9.9999,"type": "MID_MARKET"},{"sourceCurrencyCode": "HKD","targetCurrencyCode": "USD","rate": 0.9999999999999999,"type": "MID_MARKET"}]},"items": [{"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Discount","productId": "","amount": 0,"imageUrl": "","currencyCode": "USD","description": null,"hsCode": "9999.99","sku": "DISCOUNT_SKU","countryOfOrigin": "CN","measurements": [{"type": "WEIGHT","unitOfMeasure": "POUND","value": 0}],"quantity": 1,"attributes": null},{"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 1","productId": "","amount": 999.99,"imageUrl": "https://example.com/product1-image.jpg","currencyCode": "USD","description": "Product 1 Description","hsCode": "9999.99.99","sku": "PRODUCT1_SKU","countryOfOrigin": "US","measurements": [{"type": "HEIGHT","unitOfMeasure": "INCH","value": 99},{"type": "LENGTH","unitOfMeasure": "INCH","value": 99},{"type": "WIDTH","unitOfMeasure": "INCH","value": 99},{"type": "WEIGHT","unitOfMeasure": "OUNCE","value": 999}],"quantity": 1,"attributes": null},{"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 2","productId": "","amount": 999.99,"imageUrl": "https://example.com/product2-image.jpg","currencyCode": "USD","description": "Product 2 Description","hsCode": "9999.99.99","sku": "PRODUCT2_SKU","countryOfOrigin": "US","measurements": [{"type": "HEIGHT","unitOfMeasure": "INCH","value": 99},{"type": "LENGTH","unitOfMeasure": "INCH","value": 99},{"type": "WIDTH","unitOfMeasure": "INCH","value": 99},{"type": "WEIGHT","unitOfMeasure": "OUNCE","value": 99}],"quantity": 1,"attributes": null},{"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Insurance","productId": "","amount": 99.99,"imageUrl": "","currencyCode": "USD","description": null,"hsCode": "","sku": "INSURANCE_SKU","countryOfOrigin": "US","measurements": [{"type": "WEIGHT","unitOfMeasure": "POUND","value": 9.999}],"quantity": 1,"attributes": null}],"paymentDetail": {"chargeId": "ch_xxxxxxxxxxxxxxxxxxxxxxxxxx","refunds": []},"landedCosts": [{"method": "DDP","landedCostGuaranteeCode": "GUARANTEE_CODE","currencyCode": "USD","amountSubtotals": {"landedCostTotal": 0,"duties": 0,"fees": 0,"taxes": 0,"items": 999.99,"shipping": 999.99},"remittance": [],"shipmentRating": {"displayName": "Shipping Method","serviceLevelCode": "shipping.service_code","amount": 999.99,"currencyCode": "USD","details": [{"amount": 9999.99,"carrierCode": "Carrier api: standard rate (shipping_rate)","type": "PUBLISHED_RATE"},{"amount": 999.99,"carrierCode": "Carrier api: fuel surcharge (999)","type": "FUEL_SURCHARGE"},{"amount": -9999.99,"carrierCode": "negotiated_rate","type": "DISCOUNT"}],"appliedRules": []},"deMinimis": [{"type": "DUTY","threshold": "ABOVE"},{"type": "TAX","threshold": "ABOVE"}],"duties": [{"amount": 0,"currencyCode": "USD","description": "duty","type": "ITEM","formula": "0.0 % cif","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 1","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 1 Description"}},{"amount": 0,"currencyCode": "USD","description": "duty","type": "SHIPPING","formula": "0.0 % cif","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 1","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 1 Description"}},{"amount": 0,"currencyCode": "USD","description": "duty","type": "ITEM","formula": "0.0 % cif","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Discount","productId": "","amount": 0,"currencyCode": "USD","quantity": 1,"description": null}},{"amount": 0,"currencyCode": "USD","description": "duty","type": "SHIPPING","formula": "0.0 % cif","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Discount","productId": "","amount": 0,"currencyCode": "USD","quantity": 1,"description": null}},{"amount": 0,"currencyCode": "USD","description": "duty","type": "ITEM","formula": "0.0 % cif","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 2","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 2 Description"}},{"amount": 0,"currencyCode": "USD","description": "duty","type": "SHIPPING","formula": "0.0 % cif","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 2","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 2 Description"}}],"taxes": [{"amount": 0,"currencyCode": "USD","description": "Tax","type": "ITEM","formula": "0%","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Discount","productId": "","amount": 0,"currencyCode": "USD","quantity": 1,"description": null}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "SHIPPING","formula": "0%","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Discount","productId": "","amount": 0,"currencyCode": "USD","quantity": 1,"description": null}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "ITEM","formula": "0%","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 1","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 1 Description"}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "SHIPPING","formula": "0%","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 1","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 1 Description"}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "ITEM","formula": "0%","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 2","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 2 Description"}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "SHIPPING","formula": "0%","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 2","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 2 Description"}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "DUTY","formula": "0%","note": "Tax on the duty of the item","item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 1","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 1 Description"}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "DUTY","formula": "0%","note": "Tax on the duty of the shipping","item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 1","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 1 Description"}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "DUTY","formula": "0%","note": "Tax on the duty of the item","item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Discount","productId": "","amount": 0,"currencyCode": "USD","quantity": 1,"description": null}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "DUTY","formula": "0%","note": "Tax on the duty of the shipping","item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Discount","productId": "","amount": 0,"currencyCode": "USD","quantity": 1,"description": null}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "DUTY","formula": "0%","note": "Tax on the duty of the item","item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 2","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 2 Description"}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "DUTY","formula": "0%","note": "Tax on the duty of the shipping","item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 2","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 2 Description"}}],"fees": []}]}}}ORDER_STATUS_CHANGED
The
ORDER_STATUS_CHANGEDevent is triggered whenever an order status changes. It always returns anOrderobject. Possible statuses are found on theOrderStatusenum.{"data": {"order": {"status": "OPEN","createdAt": "2024-07-23T16:18:57.104Z","accountOrderNumber": null,"currencyCode": "HKD","organization": "organization_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","amountSubtotals": {"duties": 0,"fees": 0,"items": 9999.99,"shipping": 9999.99,"taxes": 0,"variance": -0.01},"root": {"exchangeRates": [{"sourceCurrencyCode": "USD","targetCurrencyCode": "HKD","rate": 9.99999,"type": "GUARANTEED"},{"sourceCurrencyCode": "USD","targetCurrencyCode": "HKD","rate": 9.9999,"type": "MID_MARKET"},{"sourceCurrencyCode": "USD","targetCurrencyCode": "HKD","rate": 9.9999,"type": "MID_MARKET"},{"sourceCurrencyCode": "USD","targetCurrencyCode": "HKD","rate": 9.9999,"type": "MID_MARKET"},{"sourceCurrencyCode": "HKD","targetCurrencyCode": "USD","rate": 0.9999999999999999,"type": "MID_MARKET"}]},"items": [{"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Discount","productId": "","amount": 0,"imageUrl": "","currencyCode": "USD","description": null,"hsCode": "9999.99","sku": "DISCOUNT_SKU","countryOfOrigin": "CN","measurements": [{"type": "WEIGHT","unitOfMeasure": "POUND","value": 0}],"quantity": 1,"attributes": null},{"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 1","productId": "","amount": 999.99,"imageUrl": "https://example.com/product1-image.jpg","currencyCode": "USD","description": "Product 1 Description","hsCode": "9999.99.99","sku": "PRODUCT1_SKU","countryOfOrigin": "US","measurements": [{"type": "HEIGHT","unitOfMeasure": "INCH","value": 99},{"type": "LENGTH","unitOfMeasure": "INCH","value": 99},{"type": "WIDTH","unitOfMeasure": "INCH","value": 99},{"type": "WEIGHT","unitOfMeasure": "OUNCE","value": 999}],"quantity": 1,"attributes": null},{"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 2","productId": "","amount": 999.99,"imageUrl": "https://example.com/product2-image.jpg","currencyCode": "USD","description": "Product 2 Description","hsCode": "9999.99.99","sku": "PRODUCT2_SKU","countryOfOrigin": "US","measurements": [{"type": "HEIGHT","unitOfMeasure": "INCH","value": 99},{"type": "LENGTH","unitOfMeasure": "INCH","value": 99},{"type": "WIDTH","unitOfMeasure": "INCH","value": 99},{"type": "WEIGHT","unitOfMeasure": "OUNCE","value": 99}],"quantity": 1,"attributes": null},{"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Insurance","productId": "","amount": 99.99,"imageUrl": "","currencyCode": "USD","description": null,"hsCode": "","sku": "INSURANCE_SKU","countryOfOrigin": "US","measurements": [{"type": "WEIGHT","unitOfMeasure": "POUND","value": 9.999}],"quantity": 1,"attributes": null}],"paymentDetail": {"chargeId": "ch_xxxxxxxxxxxxxxxxxxxxxxxxxx","refunds": []},"landedCosts": [{"method": "DDP","landedCostGuaranteeCode": "GUARANTEE_CODE","currencyCode": "USD","amountSubtotals": {"landedCostTotal": 0,"duties": 0,"fees": 0,"taxes": 0,"items": 999.99,"shipping": 999.99},"remittance": [],"shipmentRating": {"displayName": "Shipping Method","serviceLevelCode": "shipping.service_code","amount": 999.99,"currencyCode": "USD","details": [{"amount": 9999.99,"carrierCode": "Carrier api: standard rate (shipping_rate)","type": "PUBLISHED_RATE"},{"amount": 999.99,"carrierCode": "Carrier api: fuel surcharge (999)","type": "FUEL_SURCHARGE"},{"amount": -9999.99,"carrierCode": "negotiated_rate","type": "DISCOUNT"}],"appliedRules": []},"deMinimis": [{"type": "DUTY","threshold": "ABOVE"},{"type": "TAX","threshold": "ABOVE"}],"duties": [{"amount": 0,"currencyCode": "USD","description": "duty","type": "ITEM","formula": "0.0 % cif","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 1","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 1 Description"}},{"amount": 0,"currencyCode": "USD","description": "duty","type": "SHIPPING","formula": "0.0 % cif","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 1","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 1 Description"}},{"amount": 0,"currencyCode": "USD","description": "duty","type": "ITEM","formula": "0.0 % cif","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Discount","productId": "","amount": 0,"currencyCode": "USD","quantity": 1,"description": null}},{"amount": 0,"currencyCode": "USD","description": "duty","type": "SHIPPING","formula": "0.0 % cif","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Discount","productId": "","amount": 0,"currencyCode": "USD","quantity": 1,"description": null}},{"amount": 0,"currencyCode": "USD","description": "duty","type": "ITEM","formula": "0.0 % cif","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 2","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 2 Description"}},{"amount": 0,"currencyCode": "USD","description": "duty","type": "SHIPPING","formula": "0.0 % cif","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 2","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 2 Description"}}],"taxes": [{"amount": 0,"currencyCode": "USD","description": "Tax","type": "ITEM","formula": "0%","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Discount","productId": "","amount": 0,"currencyCode": "USD","quantity": 1,"description": null}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "SHIPPING","formula": "0%","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Discount","productId": "","amount": 0,"currencyCode": "USD","quantity": 1,"description": null}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "ITEM","formula": "0%","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 1","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 1 Description"}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "SHIPPING","formula": "0%","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 1","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 1 Description"}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "ITEM","formula": "0%","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 2","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 2 Description"}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "SHIPPING","formula": "0%","note": null,"item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 2","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 2 Description"}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "DUTY","formula": "0%","note": "Tax on the duty of the item","item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 1","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 1 Description"}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "DUTY","formula": "0%","note": "Tax on the duty of the shipping","item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 1","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 1 Description"}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "DUTY","formula": "0%","note": "Tax on the duty of the item","item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Discount","productId": "","amount": 0,"currencyCode": "USD","quantity": 1,"description": null}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "DUTY","formula": "0%","note": "Tax on the duty of the shipping","item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Discount","productId": "","amount": 0,"currencyCode": "USD","quantity": 1,"description": null}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "DUTY","formula": "0%","note": "Tax on the duty of the item","item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 2","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 2 Description"}},{"amount": 0,"currencyCode": "USD","description": "Tax","type": "DUTY","formula": "0%","note": "Tax on the duty of the shipping","item": {"id": "item_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name": "Product 2","productId": "","amount": 999.99,"currencyCode": "USD","quantity": 1,"description": "Product 2 Description"}}],"fees": []}]}}}ORDER_RETURN_CREATED
The
ORDER_RETURN_CREATEDevent is triggered when a return is created on an order. The new return starts in theREQUESTEDstatus.Creating a return does not also send
ORDER_RETURN_STATUS_CHANGED. Every status change after that one does.{"eventType": "ORDER_RETURN_CREATED","orderReturnId": "order_return_[ID]"}Get the return's details
Return events carry only the event type and the return's ID. To get the return's status, items, label, and history, query it with
orderReturn, asking for the fields your integration needs. It returns anOrderReturnobject.query OrderReturn($id: ID!) {orderReturn(id: $id) {idstatusorder {idaccountOrderNumber}lines {iditemIdquantityreasondispositionnote}labelSourcecarriertrackingNumberstatusTransitions {fromStatustoStatusactornotecreatedAt}updatedAt}}ORDER_RETURN_STATUS_CHANGED
The
ORDER_RETURN_STATUS_CHANGEDevent is triggered whenever a return moves to a new status: approved, label issued, in transit, received, inspected, completed, rejected, or canceled.The newest entry in the return's
statusTransitions, bycreatedAt, shows the change: itsfromStatus, itstoStatus, who made it, and any note they left, such as the reason a return was rejected. To read it, query the return as shown under Get the return's details above.{"eventType": "ORDER_RETURN_STATUS_CHANGED","orderReturnId": "order_return_[ID]"}ORDER_RETURN_COMPLETED
The
ORDER_RETURN_COMPLETEDevent is triggered when a return is completed and closed.Completing a return also sends
ORDER_RETURN_STATUS_CHANGED. If you only need to know when returns close, subscribe toORDER_RETURN_COMPLETEDalone instead of handling every status change. If you subscribe to both, expect two webhooks when a return completes.ORDER_RETURN_COMPLETEDis not sent for rejected or canceled returns. Those end withORDER_RETURN_STATUS_CHANGEDonly.{"eventType": "ORDER_RETURN_COMPLETED","orderReturnId": "order_return_[ID]"}SHIPMENT_CANCELED
The
SHIPMENT_CANCELEDevent is triggered whenever a shipment is voided. It always returns aShipmentobject.{"createdAt": 1758753664.363,"shipmentCartons": [],"createdBy": "organization_[ID]","level": "info","parties": [{"person": {"firstName": "[FIRST_NAME]","lastName": "[LAST_NAME]","email": "[EMAIL]"},"location": {"countryCode": "CA","postalCode": "[POSTAL_CODE]","locality": "[LOCALITY]","line1": "[ADDRESS_LINE1]"},"id": "party_[ID]","type": "PAYOR"},{"person": {"firstName": "[FIRST_NAME]","lastName": "[LAST_NAME]","email": "[EMAIL]"},"location": {"countryCode": "CA","postalCode": "[POSTAL_CODE]","locality": "[LOCALITY]","line1": "[ADDRESS_LINE1]"},"id": "party_[ID]","type": "DESTINATION"},{"location": {"countryCode": "US","postalCode": "[POSTAL_CODE]","locality": "[LOCALITY]","line2": "","line1": "[ADDRESS_LINE1]"},"id": "party_[ID]","type": "ORIGIN"},{"person": {"firstName": "[FIRST_NAME]","lastName": "[LAST_NAME]","email": "[EMAIL]"},"location": {"countryCode": "CA","postalCode": "[POSTAL_CODE]","locality": "[LOCALITY]","line1": "[ADDRESS_LINE1]"},"id": "party_[ID]","type": "DESTINATION"}],"id": "shipment_level_[ID]","trackingDetails": [],"serviceLevel": {"carrier": {"code": "ups","name": "UPS"},"name": "Worldwide Economy DDP","id": "service_level_[ID]"},"order": {"accountOrderNumber": "[ACCOUNT_NUMBER]","mode": "LIVE","references": [],"zonosOrderId": "zonos_order_[ID]","organization": "organization_[ID]","id": "order_[ID]"},"timestamp": "2025-09-24T22:41:04.904Z"}SHIPMENT_CREATED
The
SHIPMENT_CREATEDevent is triggered whenever a shipment is created. It always returns aShipmentobject.{"data": {"shipment": {"id": "shipment_[ID]","order": {"accountOrderNumber": "[ACCOUNT_NUMBER]","id": "order_[ID]"},"parties": [{"type": "ORIGIN","location": {"countryCode": "ID","administrativeArea": null,"administrativeAreaCode": "[AREA_CODE]","line1": "[ADDRESS_LINE1]","line2": "","line3": "","locality": "[LOCALITY]","postalCode": "[POSTAL_CODE]"},"person": {"firstName": "[FIRST_NAME]","lastName": "[LAST_NAME]","email": "[EMAIL]","phone": "[PHONE]","companyName": "[COMPANY_NAME]"}},{"type": "DESTINATION","location": {"countryCode": "US","administrativeArea": null,"administrativeAreaCode": "NY","line1": "[ADDRESS_LINE1]","line2": "[LINE2]","line3": null,"locality": "New York","postalCode": "[POSTAL_CODE]"},"person": {"firstName": "[FIRST_NAME]","lastName": "[LAST_NAME]","email": "[EMAIL]","phone": "[PHONE]","companyName": ""}}],"serviceLevel": {"carrier": {"name": "DHL"},"name": "DHL Express Worldwide","code": "dhl.express_worldwide"},"shipmentCartons": [{"id": "shipment_carton_[ID]","carton": {"length": 5.9055,"width": 7.874,"height": 3.937,"dimensionalUnit": "INCH","weight": 0.23,"weightUnit": "POUND","items": [{"quantity": 1,"item": {"id": "item_[ID]","sku": "","name": "Caraco Black - S / Black","description": null,"hsCode": "6109.10.0027","amount": 125,"currencyCode": "USD"}}]},"tracking": {"number": "[TRACKING_NUMBER]"},"label": {"labelAmounts": [{"amount": 22.71,"amountType": "QUOTE","currencyCode": "USD"}],"labelFileType": "PDF","url": "[URL]","statusTransitions": [{"changedAt": "[DATE_TIME]","status": "CREATED"}]}}],"createdAt": "[DATE_TIME]","status": "CREATED","customsDocuments": [{"documentType": "COMMERCIAL_INVOICE","fileUrl": "[URL]"}],"shipmentConsolidation": null}}}Was this page helpful?