Cancellations and refunds
What you can cancel at each status, what happens at the courier, and where the money goes back.
- Product
- APIShipping Engine API
- Section
- Core concepts
- Reading time
- 5 min read
In short
- You can cancel a shipment until the courier has it. After pickup, the courier usually refuses. Delivered and returning shipments can't be cancelled.
- Cancel one shipment with
cancelShipment, or every shipment in an order withcancelOrder. - The refund goes back to the pocket that paid, straight away, and you receive
shipment.cancelled.
What can be cancelled
Shipment status | Can cancel? | What happens | Refund |
|---|---|---|---|
WAITING_FOR_PAYMENT | Yes | Cancelled locally. | None: nothing was paid. |
CONFIRMED | Yes | Cancelled locally. No courier was booked yet. | Yes |
PENDING_PICKUP | Yes | Shipping Engine asks the courier to cancel first. | Yes, once the courier accepts |
PENDING_DROPOFF | Yes | Same as above. | Yes, once the courier accepts |
IN_TRANSIT | Request only | The courier is asked, and most refuse once they have the parcel. | Only if the courier accepts |
PROBLEM_SHIPMENT | Request only | As above. | Only if the courier accepts |
CANCELLED | Already done | Returns success again. Nothing changes. | No second refund |
DELIVERED | No | 400 Shipment 'SHP-…' is delivered and cannot be cancelled. | — |
RTS_CONFIRMED, RTS_TRANSIT, RTS_PROBLEM_SHIPMENT, RTS_DELIVERED | No | A return can't be cancelled. | — |
Shipment cancel vs order cancel
POST /b2b/shipments/cancel/{shipmentCode} | POST /b2b/orders/{orderCode}/cancel | |
|---|---|---|
| Cancels | One shipment | Every shipment in the order that isn't cancelled yet |
| Success | 200 Shipment successfully cancelled. | 200 Order successfully cancelled. |
| Order status | Unchanged. Use the shipment status. | Becomes CANCELLED when every shipment is cancelled |
| Refuses when | That shipment is delivered or returning | Any shipment in the order is delivered: 400 Order 'FSO-…' cannot be cancelled because shipment 'SHP-…' is already delivered. |
| Permission | CANCEL_ORDER | READ_ORDER |
| Use it for | Most cases, including one shipment of a multi-shipment order | Cleaning up a whole order, including a DRAFT order whose payment failed |
An order cancel is not all-or-nothing
Shipments are cancelled one by one. If a courier refuses partway, the request fails, but the
shipments cancelled before it stay cancelled and refunded. Check each shipment's status with
retrieveShipment after an error.
Before and after courier booking
A shipment is booked once it has an airwayBill. That decides who has to agree to the
cancellation.
Before booking (no airwayBill) | After booking (has airwayBill) | |
|---|---|---|
| Statuses | WAITING_FOR_PAYMENT, CONFIRMED | PENDING_PICKUP, PENDING_DROPOFF, and later |
| Who decides | Shipping Engine | The courier, first |
| Can it fail? | No | Yes, if the courier refuses or can't be reached. The error comes back and nothing changes. |
| Result | CANCELLED, refunded | CANCELLED, refunded, after the courier confirms |
If the courier refuses, the shipment keeps its status and you keep the airway bill. Try again later, or contact support if the parcel must not ship.
Cancellations you didn't request
A shipment can also become CANCELLED without a call from you:
| Cause | Example |
|---|---|
| The courier rejected the booking during order creation | The order response shows the shipment as CANCELLED. |
| The courier cancelled it | The pickup window passed, or an instant courier found no driver and gave up. |
You get the same refund and the same shipment.cancelled webhook.
Refunds
The amount paid for the shipment goes back to the pocket it came from. For API orders that is always your shipping credit.
| Paid with | Refunded to | Balance log description |
|---|---|---|
| Shipping credit (all API orders) | Shipping credit | Cancel shipment <shipment> for order <order> (wallet refund) |
| Payout or QRIS (dashboard orders) | Payout balance | … (payout refund) |
| Points (dashboard orders) | Points | … (point refund) |
| COD | — (nothing was paid upfront) | COD proceeds already credited for the shipment are reversed: … (COD reversal) |
| Question | Answer |
|---|---|
| How much? | The full totalPrice paid for that shipment, including insurance and tax. |
| When? | Straight away, as part of the cancellation. |
| What about later charges? | Price adjustments and return fees are separate. They are not part of this refund. |
| Can it be refunded twice? | No. Cancelling again returns success without another refund. |
See Balance and charges for every balance movement.
Webhooks
Every cancellation, by you or by the courier, sends shipment.cancelled:
{
"booking_id": "FSO-261120-B4TQ9P",
"awb": "JX1234567890",
"courier_code": "jnt",
"shipment_code": "SHP-261120-K7M2QX",
"data": {
"timestamp": "2026-11-20 04:10:12",
"status": "CANCELLED",
"desc": "Shipment cancelled after dispatch.",
"note": null,
"mapping_code": null,
"driver_name": null,
"driver_phone": null,
"driver_license_plate": null,
"proof_image": null,
"receiver_name": null,
"receiver_relation": null,
"tracking_link": null
}
}data.timestamp is in UTC without an offset. See the event catalog.
Common mistakes
Cancelling the order to cancel one parcel
cancelOrder cancels every shipment in the order. To cancel one, use cancelShipment with its
SHP-… code.
Passing the airway bill to cancelShipment
The path parameter is the shipment code (SHP-…), not the airway bill.
Treating a courier refusal as final
An error from cancelShipment after booking usually means the courier refused or was busy. The
shipment keeps its status. Check it, and stop the parcel physically if it hasn't been handed over.
Was this page helpful?