Cancel Consignment

This API is used to cancel an existing consignment. Cancelled consignments are notified to the carrier and the label becomes invalid.

Endpoint Information

Property	Value
URL	`{{BASE_URL}}/api/v1/consignments/{idBarcodeOrReference}/cancel`
HTTP Method	`POST`
Content Type	`application/json`
Authentication	`APIKEY` header

Cancellable Statuses

Not all consignments can be cancelled. Consignments in the following statuses can be cancelled:

Status	Cancellable
Label created, not yet picked up	✅ Yes
Handed to carrier (in transit)	⚠️ Provider dependent
Delivered	❌ No
Already cancelled	❌ No

Important: After being handed to the carrier, cancellation depends on the provider's rules. Some providers do not support cancellation of in-transit shipments.

Request Parameters

URL Parameters

Parameter	Type	Required	Description
`idBarcodeOrReference`	String/Integer	REQUIRED	Consignment ID, barcode, or reference number

Flexible Search: You can cancel the consignment using ID, ComToHome barcode (C2H...), or your own reference number (reference_no).

Example Usage

Cancel by ID

curl -X POST "{{BASE_URL}}/api/v1/consignments/632236/cancel" \
  -H "Content-Type: application/json" \
  -H "APIKEY: {{APIKEY}}"

<?php
$client = new \GuzzleHttp\Client();

$consignmentId = 632236;

$response = $client->request('POST', "{{BASE_URL}}/api/v1/consignments/{$consignmentId}/cancel", [
    'headers' => [
        'Content-Type' => 'application/json',
        'APIKEY' => '{{APIKEY}}'
    ]
]);

$body = json_decode($response->getBody(), true);

if ($body['status']) {
    echo "Consignment successfully cancelled: " . $body['data']['consignment'];
}

<?php
$consignmentId = 632236;

$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => "{{BASE_URL}}/api/v1/consignments/{$consignmentId}/cancel",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'APIKEY: {{APIKEY}}'
    ]
]);

$response = curl_exec($ch);
$result = json_decode($response, true);

if ($result['status']) {
    echo "Consignment successfully cancelled";
} else {
    echo "Error: " . $result['errors'][0]['message'];
}

curl_close($ch);

Cancel by Barcode

curl -X POST "{{BASE_URL}}/api/v1/consignments/C2H07238640094/cancel" \
  -H "Content-Type: application/json" \
  -H "APIKEY: {{APIKEY}}"

Cancel by Reference Number

curl -X POST "{{BASE_URL}}/api/v1/consignments/ORDER-2024-001/cancel" \
  -H "Content-Type: application/json" \
  -H "APIKEY: {{APIKEY}}"

API Response

Successful Response

{
    "status": true,
    "message": "Cancelled by customer",
    "data": {
        "consignment": 632236
    }
}

Response Fields

Field	Type	Description
`status`	Boolean	Operation success status
`message`	String	Cancellation result message
`data.consignment`	Integer	Cancelled consignment ID

Error Responses

Consignment Not Found

{
    "status": false,
    "errors": [
        {
            "message": "Consignment not found"
        }
    ]
}

Cancellation Failed

{
    "status": false,
    "errors": [
        {
            "message": "Consignment cancel failed: Shipment already in transit"
        }
    ]
}

Common Error Scenarios

Error	Description	Solution
`Consignment not found`	Consignment not found	Check ID, barcode, or reference number
`Consignment cancel failed`	Cancellation failed	Check consignment status
`Shipment already delivered`	Shipment has been delivered	Delivered shipments cannot be cancelled
`Shipment already cancelled`	Shipment already cancelled	-

Delete Consignment (DELETE)

Unlike cancellation, you can use the DELETE method to completely delete the consignment:

Property	Value
URL	`{{BASE_URL}}/api/v1/consignments/{idBarcodeOrReference}`
HTTP Method	`DELETE`

curl -X DELETE "{{BASE_URL}}/api/v1/consignments/632236" \
  -H "APIKEY: {{APIKEY}}"

Difference: The cancel endpoint cancels the consignment and keeps it in records. The DELETE endpoint first cancels the consignment, then removes it from the system.

Next Steps

After cancelling the consignment:

Webhook: Cancellation status is notified via webhook (if configured)
New Consignment: You can create a new consignment with the same information if needed
Reporting: Cancelled consignments can be viewed in reports