Docs
Sign in

Cancel a shipment

Updated May 31, 20262 min read

A shipment is booked but hasn't shipped, and it needs to be called off. Cancelling it in Carriyo also cancels the booking with the carrier where the carrier supports that.

Scenario

You booked a shipment for an order. Before it's collected, the customer changes their mind and asks to cancel. The shipment is in booked status, no carrier pickup has happened yet. You cancel it.

If you use Carriyo Orders

This recipe cancels the shipment directly, the path for clients not using the Carriyo Order object. If you do use Carriyo Orders and the whole order is being called off, cancel the order instead: that cancels the shipment too (when it hasn't shipped yet), moves the fulfillment orders and line items to cancelled, and releases any reserved inventory. See Cancel an order.

Prerequisites

  • API credentials: see Getting started.
  • A shipment that hasn't shipped yet. Cancellation is allowed up to the point of shipping; once a shipment is shipped (or beyond), the cancel call returns 400.

Step 1, cancel the shipment

The body is optional, but supplying an update_reason_code records why it was cancelled:

curl -X POST 'https://api.carriyo.com/shipments/MPRC8K2NXVABD9/cancel' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'tenant-id: YOUR_TENANT_ID' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "update_reason_code": "cancelled_by_customer"
  }'

The path accepts either the Carriyo shipment_id or your partner_shipment_reference. The update_reason_code is one of Carriyo's standard reason codes or a custom code configured for your merchant.

Step 2, read the response

The shipment comes back in cancelled:

{
  "shipment_id": "MPRC8K2NXVABD9",
  "references": {
    "partner_order_reference": "YOUR_ORDER_REF",
    "partner_shipment_reference": "YOUR_ORDER_REF-1"
  },
  "post_shipping_info": {
    "status": "cancelled"
  },
  "...": "(other fields elided)"
}

Where the carrier supports cancellation, Carriyo also cancels the booking with the carrier as part of this call. For carriers that don't support it, the Carriyo record is cancelled but no carrier call is made. You may need to confirm cancellation on the carrier side separately.

Pitfalls

  • Only works before shipping. A shipment that's already shipped, delivered, returned, or cancelled can't be cancelled; the call returns 400. Check the status first.
  • Carrier cancellation is carrier-dependent. Carriyo cancels its own record always, and the carrier booking only when the carrier supports it.
  • Cancellation is distinct from a return. If the parcel has already shipped and needs to come back, that's a reverse shipment / return, not a cancel.