Scheduled Order Cancellation API Documentation (v1.0.9)

1

What Is This API?

Use this API to cancel an existing scheduled order or shipment created in Jeebly. Once cancelled, the shipment will no longer be processed for delivery.

When a cancellation request is accepted, Jeebly immediately revokes the dispatch task from our logistics routing engine, unassigns the courier rider if one was already scheduled, and updates the consignment milestone state to Cancelled. This ensures no driver arrives at your pickup location for this consignment.

API Details & Environments

Property	Value	Action
Request URL (Demo)	`https://demo.jeebly.com/customer/cancel_shipment`
Request URL (Production)	`https://myjeebly.jeebly.com/customer/cancel_shipment`
HTTP Method	POST	—
Content-Type	`application/json`	—

Crucial Operational Rule: Pre-Pickup Cancellation Window

You must cancel BEFORE the shipment is physically picked up by the courier. Once the status is Pickup Completed, the consignment enters active warehouse transit and can no longer be cancelled via API. See Troubleshooting Matrix for details.

2

Authentication Headers

Every request submitted to the Order Cancellation API must include your valid merchant authentication headers. Requests submitted without valid credentials will return an immediate 400 Bad Request with an authentication error code.

Header Name	Description	Required
`X-API-KEY`	Your API security key assigned to your merchant account.	Yes
`client_key`	Your Jeebly customer account key.	Yes
`Content-Type`	Must always be set to `application/json`.	Yes

Need to obtain or regenerate your sandbox/production API keys?

Get Your Keys

3

Request Body

The cancellation payload is compact and requires exactly one field containing the unique shipment reference identifier:

Field Name	Type	Description	Example	Required
`reference_number`	String	The AWB / tracking number of the scheduled order you want to cancel.	`"JB304036"`	Yes

Where do I get the reference_number?

The reference_number is the official Jeebly AWB tracking identifier returned in the JSON response when you created the order via the Create Shipment API (e.g., "JB304036").

4

Sample Request

Below is a complete example request demonstrating how to invoke the Order Cancellation endpoint across multiple development stacks:

curl --location 'https://demo.jeebly.com/customer/cancel_shipment' \
--header 'X-API-KEY: YOUR_API_KEY' \
--header 'client_key: YOUR_CLIENT_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "reference_number": "JB304036"
}'

{
  "reference_number": "JB304036"
}

const myHeaders = new Headers();
myHeaders.append("X-API-KEY", "YOUR_API_KEY");
myHeaders.append("client_key", "YOUR_CLIENT_KEY");
myHeaders.append("Content-Type", "application/json");

const raw = JSON.stringify({
  "reference_number": "JB304036"
});

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow"
};

fetch("https://demo.jeebly.com/customer/cancel_shipment", requestOptions)
  .then((response) => response.json())
  .then((result) => {
    if (result.success === "true") {
      console.log("Success:", result.message);
    } else {
      console.error("Cancellation failed:", result.message);
    }
  })
  .catch((error) => console.error("Network error:", error));

import requests
import json

url = "https://demo.jeebly.com/customer/cancel_shipment"

payload = json.dumps({
  "reference_number": "JB304036"
})

headers = {
  'X-API-KEY': 'YOUR_API_KEY',
  'client_key': 'YOUR_CLIENT_KEY',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)
data = response.json()

if response.status_code == 200 and data.get("success") == "true":
    print("Order cancelled successfully:", data.get("message"))
else:
    print("Cancellation error:", data.get("message"))

<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo.jeebly.com/customer/cancel_shipment',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode(['reference_number' => 'JB304036']),
  CURLOPT_HTTPHEADER => array(
    'X-API-KEY: YOUR_API_KEY',
    'client_key: YOUR_CLIENT_KEY',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

$result = json_decode($response, true);
if ($httpCode === 200 && ($result['success'] ?? '') === 'true') {
    echo "Shipment cancelled: " . $result['message'];
} else {
    echo "Error: " . ($result['message'] ?? 'Unable to cancel shipment');
}

Send a live cancellation test request in the interactive console:

Test in API Console

5

Success Response (200 OK)

When the cancellation request is successfully executed, the API returns an HTTP 200 OK status code with a JSON confirmation object:

200 OK application/json

{
  "success": "true",
  "message": "Shipment Cancelled Successfully."
}

Consignment Status: Cancelled

Driver pickup manifest automatically cleared. Shipment marked void across all tracking endpoints.

Pickup Dispatch Voided

Field Name	Type	Returned Value	Description
`success`	String	`"true"`	Status indicator confirming the cancellation operation was completed.
`message`	String	`"Shipment Cancelled Successfully."`	Human-readable operational confirmation message.

6

Error Responses (400 Bad Request)

A 400 Bad Request response is returned whenever a cancellation cannot be performed. This may occur due to invalid syntax, missing authentication, non-existent AWB numbers, or because the package has already been collected by the courier.

400 1. If the format is wrong

Malformed JSON or syntax error

{
  "success": "false",
  "message": "Invalid JSON format"
}

400 2. If the API Key is not valid

X-API-KEY wrong, revoked, or missing

{
  "success": "false",
  "message": "Invalid API Token"
}

400 3. If the customer Key is not valid

client_key wrong or missing

{
  "success": "false",
  "message": "Invalid Customer Key"
}

400 4. If the consignment is already cancelled

Order was already voided previously

{
  "success": "false",
  "message": "Shipment already cancelled"
}

400 5. If the consignment is picked up

Pickup scan completed; courier in possession

{
  "success": "false",
  "message": "Shipment cannot be cancelled"
}

400 6. If the consignment number is incorrect

reference_number does not exist

{
  "success": "false",
  "message": "Invalid Shipment Number"
}

400 7. If the consignment is Out for delivery

Shipment on delivery vehicle

{
  "success": "false",
  "message": "Shipment cannot be cancelled"
}

7

Troubleshooting & Resolution Matrix

Use this official troubleshooting matrix to diagnose and resolve errors when cancelling a scheduled shipment:

Error Message	What It Means	How to Fix It
`Invalid JSON format`	The request body is not valid JSON.	Check the format of your request, closing brackets, and valid quotes around `"reference_number"`.
`Invalid API Token`	Your API key is wrong or missing.	Check your `X-API-KEY` header value and ensure no extra whitespace was added.
`Invalid Customer Key`	Your client key is wrong or missing.	Check your `client_key` header and confirm it matches your Jeebly account key.
`Shipment already cancelled`	This order was already cancelled before.	No action needed — it is already cancelled. Update your local store database status to void.
`Shipment cannot be cancelled`	The shipment has been picked up or is out for delivery.	Contact Jeebly customer support to handle this manually (e.g., arrange Return to Shipper / RTS).
`Invalid Shipment Number`	The AWB number you entered does not exist in the system.	Double-check the reference number from your order creation response. Ensure no missing prefixes or typo.

Official Cancellation Window Notice

Note: You must cancel BEFORE the shipment is picked up. Once the status is 'Pickup Completed', the order can no longer be cancelled via API. If emergency recall is required after pickup, please reach out to Jeebly Operations immediately via phone or support desk.

8

Cancellation Rules & Lifecycle Timing

To manage order modifications and customer cancellations smoothly, follow these operational timing rules:

Eligible for API Void

Shipment status is Order Created or Assigned to Driver. The rider has not yet arrived or scanned the package at your facility.

API Void Blocked

Status is Pickup Completed, In Hub Sorting, or Out for Delivery. Physical custody has transferred to Jeebly network.

Manual RTS Escalation

If a collected parcel must be recalled, contact Jeebly operations to trigger a Return to Shipper (RTS) workflow from the distribution hub.

9

Related APIs & Lifecycle Workflow

Order cancellation is part of the comprehensive Scheduled Delivery management suite:

Step 1

Create Shipment

Submit order payload to receive your unique AWB reference.

Order Guide

Step 2

Generate Label

Download and print the official AWB thermal barcode label.

Label Guide

Step 3 (Current)

Cancel Shipment

Void an order before pickup collection arrives.

Open Console

Step 4

Track Shipment

Query real-time delivery milestones from pickup to completion.

Track Guide

Order Cancellation
API Guide

Cancel Scheduled Order

What Is This API?

API Details & Environments

Crucial Operational Rule: Pre-Pickup Cancellation Window

Authentication Headers

Request Body

Where do I get the reference_number?

Sample Request

Success Response (200 OK)

Consignment Status: Cancelled

Error Responses (400 Bad Request)

Troubleshooting & Resolution Matrix

Official Cancellation Window Notice

Cancellation Rules & Lifecycle Timing

Eligible for API Void

API Void Blocked

Manual RTS Escalation

Order Cancellation API Guide

Cancel Scheduled Order

What Is This API?

API Details & Environments

Crucial Operational Rule: Pre-Pickup Cancellation Window

Authentication Headers

Request Body

Where do I get the reference_number?

Sample Request

Success Response (200 OK)

Consignment Status: Cancelled

Error Responses (400 Bad Request)

Troubleshooting & Resolution Matrix

Official Cancellation Window Notice

Cancellation Rules & Lifecycle Timing

Eligible for API Void

API Void Blocked

Manual RTS Escalation

Related APIs & Lifecycle Workflow

Create Shipment

Generate Label

Cancel Shipment

Track Shipment

Order Cancellation
API Guide