Cancel Shipment

Cancels an existing shipment and requests a label refund from the carrier.

A shipment can only be canceled if it has not been picked up, scanned, or entered the carrier’s transportation network. Refund eligibility depends on the carrier’s cancellation policy.

Endpoint

POST /shipments/cancel

Request Body

Field	Type	Required	Description
trackingNumber	string	Yes	Tracking number of the shipment to cancel.

Example

{
  "trackingNumber": "794813797842"
}

Successful Response

HTTP 200 OK

Field	Type	Description
status	string	Current shipment status after cancellation.
trackingNumber	string	Tracking number of the canceled shipment.
carrier	string	Carrier responsible for the shipment.
service	string	Shipping service used for the shipment.
balanceRefunded	boolean	Indicates whether the shipping label cost was refunded.

Example

{
  "status": "Canceled",
  "trackingNumber": "794813797842",
  "carrier": "jtexpress",
  "service": "ground",
  "balanceRefunded": true
}

The balanceRefunded field indicates whether the shipping label cost was refunded after requesting the cancellation. If the value is true, the balance was refunded successfully. If the value is false, the shipment may have been canceled successfully, but the refund may still be pending or depend on the carrier’s policy.

Error Responses

HTTP 404 Not Found → Shipment not found

{
  "status": 404,
  "message": "Shipment not found"
}

HTTP 409 Conflict → Shipment cannot be canceled

{
  "status": 409,
  "error": "Invalid status transition"
}

HTTP 400 Bad Request → Invalid Request

{
  "status": 400,
  "message": "Validation error",
  "errors": [
    {
      "code": "invalid_type",
      "expected": "string",
      "received": "undefined",
      "path": [
        "trackingNumber"
      ],
      "message": "Required"
    }
  ]
}

Notes

• Refund processing times vary by carrier.
• Once a shipment has been scanned or picked up by the carrier, cancellation may no longer be possible.