Cancel a shipment
Cancel one shipment or a whole order, handle a courier's refusal, and confirm the refund.
- Product
- APIShipping Engine API
- Section
- Guides
- Reading time
- 5 min read
Goal: cancel a booking that is no longer needed (for example the customer cancelled the purchase) and get the shipping price back to your balance.
Before you start:
- You have the shipment code (
SHP-…) or the order code (FSO-…) from the booking response. - Your API key has
CANCEL_ORDER(andREAD_ORDERto check the status first).
Cancel before the courier has the parcel
Cancelling works reliably until the courier picks the parcel up or you drop it off. After that the request goes to the courier, which usually refuses. Cancel as early as you can.
Decide what to cancel
You want to… Call Effect Cancel one shipment POST /b2b/shipments/cancel/{shipmentCode}Only that shipment is cancelled and refunded. Other shipments in the order continue. Cancel everything in an order POST /b2b/orders/{orderCode}/cancelEvery shipment that isn't cancelled yet is cancelled and refunded, one after another. When all are cancelled, the order becomes CANCELLED.An order with only one shipment can be cancelled either way. With several shipments, cancel by shipment unless you really want to stop all of them.
Check the status first
Read the shipment with
GET /b2b/shipments/{code}/detailsand look atstatus:Status Can you cancel? CONFIRMED,PENDING_PICKUP,PENDING_DROPOFFYes. If the courier already issued an airway bill, Shipping Engine cancels it with the courier first. IN_TRANSIT,PROBLEM_SHIPMENTOnly if the courier accepts. Most refuse once the parcel is moving. DELIVEREDNo. Shipment 'SHP-…' is delivered and cannot be cancelled.RTS_CONFIRMED,RTS_TRANSIT,RTS_PROBLEM_SHIPMENT,RTS_DELIVEREDNo. The parcel is already being returned. See Returns (RTS). CANCELLEDAlready done. Calling cancel again is harmless and returns success. For an order cancel, if any shipment is
DELIVERED, the whole request is refused withOrder 'FSO-…' cannot be cancelled because shipment 'SHP-…' is already delivered.Cancel the other shipments one by one instead.Cancel
# One shipment curl -s -X POST "$FASTRAC_API/b2b/shipments/cancel/SHP-261120-D4E5F6" \ -H "Authorization: Bearer $FASTRAC_TOKEN" # A whole order curl -s -X POST "$FASTRAC_API/b2b/orders/FSO-261120-A1B2C3/cancel" \ -H "Authorization: Bearer $FASTRAC_TOKEN"Both calls take no request body and return 200:
InboundResponse { "statusCode": 200, "message": "Shipment successfully cancelled." }The order call returns
"message": "Order successfully cancelled.".Confirm the refund
For each cancelled shipment:
- The status becomes
CANCELLEDand the webhookshipment.cancelledis sent. - The amount you paid is credited back to where it came from, normally your
shippingCredit. - A balance log entry appears, for example:
{ "type": "CREDIT", "amount": 9099, "description": "Cancel shipment SHP-261120-D4E5F6 for order FSO-261120-A1B2C3 (wallet refund)" }Find it with
GET /b2b/user-balance/logs?shipmentId=SHP-261120-D4E5F6. See Reconcile your balance.COD shipments cost nothing upfront, so there is nothing to refund. See Ship with COD.
- The status becomes
When the cancellation is refused
| Response | What it means | What to do |
|---|---|---|
400 Shipment '…' is delivered and cannot be cancelled. | Too late. | Handle it as a return with your customer. |
400 Order '…' cannot be cancelled because shipment '…' is already delivered. | One shipment in the order is delivered. | Cancel the others by shipment code. |
404 Shipment with code '…' was not found. / Order with code '…' was not found. | Wrong code. | Use the SHP-… or FSO-… code from the booking, not the airway bill. |
403 You are not allowed to cancel order '…'. | The order belongs to another account. | Use the API key of the account that booked it. |
| Any other error | Usually the courier refused, for example because the parcel is already moving. The shipment keeps its status and nothing is refunded. | Check the status again. If the parcel must not be delivered, contact support with the shipment code. |
Order cancellation is not all-or-nothing
Shipments are cancelled one by one. If the courier refuses one of them, the shipments cancelled before it stay cancelled. After any error, read each shipment's status to see where you stand.
Checklist
- Cancel by shipment unless you want to stop the whole order.
- Check the status first; don't try to cancel
DELIVEREDor returning shipments. - Treat a repeated cancel of a cancelled shipment as success.
- After an error, re-read the status of every shipment in the order.
- Confirm with the
shipment.cancelledwebhook and the refund in your balance logs.
Was this page helpful?