Skip to Content
FastracDocs

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 (and READ_ORDER to 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.

  1. Decide what to cancel

    You want to…CallEffect
    Cancel one shipmentPOST /b2b/shipments/cancel/{shipmentCode}Only that shipment is cancelled and refunded. Other shipments in the order continue.
    Cancel everything in an orderPOST /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.

  2. Check the status first

    Read the shipment with GET /b2b/shipments/{code}/details and look at status:

    StatusCan 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 with Order 'FSO-…' cannot be cancelled because shipment 'SHP-…' is already delivered. Cancel the other shipments one by one instead.

  3. 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.".

  4. Confirm the refund

    For each cancelled shipment:

    • The status becomes CANCELLED and the webhook shipment.cancelled is 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.

When the cancellation is refused

ResponseWhat it meansWhat 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 errorUsually 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 DELIVERED or 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.cancelled webhook and the refund in your balance logs.

Was this page helpful?

On this page