Cancel before physical pickup
curl --request POST \
--url https://api-test.drop-hub.com/api/v2/external/shipments/{shipmentId}/cancel \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"reason": "MERCHANT_REQUESTED"
}
'import requests
url = "https://api-test.drop-hub.com/api/v2/external/shipments/{shipmentId}/cancel"
payload = { "reason": "MERCHANT_REQUESTED" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({reason: 'MERCHANT_REQUESTED'})
};
fetch('https://api-test.drop-hub.com/api/v2/external/shipments/{shipmentId}/cancel', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-test.drop-hub.com/api/v2/external/shipments/{shipmentId}/cancel",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'reason' => 'MERCHANT_REQUESTED'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-test.drop-hub.com/api/v2/external/shipments/{shipmentId}/cancel"
payload := strings.NewReader("{\n \"reason\": \"MERCHANT_REQUESTED\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-test.drop-hub.com/api/v2/external/shipments/{shipmentId}/cancel")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"reason\": \"MERCHANT_REQUESTED\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-test.drop-hub.com/api/v2/external/shipments/{shipmentId}/cancel")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"reason\": \"MERCHANT_REQUESTED\"\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"reference": "<string>",
"status": "CREATED",
"trackingUrl": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"version": 1,
"codAmount": 1,
"deliveryFeeAmount": 1,
"deliveryFeeCurrency": "SAR",
"eta": {
"target": "PICKUP",
"estimatedArrivalAt": "2023-11-07T05:31:56Z",
"estimatedMinutes": 123,
"calculatedAt": "2023-11-07T05:31:56Z",
"distanceMetres": 123
},
"proofAvailable": true,
"proofType": "PHOTO",
"deliveredAt": "2023-11-07T05:31:56Z",
"failureReasonCode": "<string>",
"cancellationReasonCode": "<string>",
"driver": {
"firstName": "<string>",
"vehicleType": "MOTORCYCLE",
"vehiclePlate": "<string>"
}
}{
"type": "https://api.drophub.example/problems/authentication-required",
"title": "Authentication required",
"status": 401,
"detail": "Authentication is required for this resource.",
"instance": "/api/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
"code": "AUTHENTICATION_REQUIRED",
"timestamp": "2026-08-22T18:30:00Z",
"correlationId": "018f2d8a-1f00-7000-8000-000000000207",
"requestId": "018f2d8a-1f00-7000-8000-000000000208"
}{
"type": "https://api.drophub.example/problems/access-denied",
"title": "Access denied",
"status": 403,
"detail": "Access to this resource is denied.",
"instance": "/api/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
"code": "ACCESS_DENIED",
"timestamp": "2026-08-22T18:30:00Z",
"correlationId": "018f2d8a-1f00-7000-8000-000000000207",
"requestId": "018f2d8a-1f00-7000-8000-000000000208"
}{
"type": "https://api.drophub.example/problems/access-denied",
"title": "Access denied",
"status": 403,
"detail": "Access to this resource is denied.",
"instance": "/api/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
"code": "ACCESS_DENIED",
"timestamp": "2026-08-22T18:30:00Z",
"correlationId": "018f2d8a-1f00-7000-8000-000000000207",
"requestId": "018f2d8a-1f00-7000-8000-000000000208"
}{
"type": "https://api.drophub.example/problems/access-denied",
"title": "Access denied",
"status": 403,
"detail": "Access to this resource is denied.",
"instance": "/api/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
"code": "ACCESS_DENIED",
"timestamp": "2026-08-22T18:30:00Z",
"correlationId": "018f2d8a-1f00-7000-8000-000000000207",
"requestId": "018f2d8a-1f00-7000-8000-000000000208"
}{
"type": "https://api.drophub.example/problems/access-denied",
"title": "Access denied",
"status": 403,
"detail": "Access to this resource is denied.",
"instance": "/api/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
"code": "ACCESS_DENIED",
"timestamp": "2026-08-22T18:30:00Z",
"correlationId": "018f2d8a-1f00-7000-8000-000000000207",
"requestId": "018f2d8a-1f00-7000-8000-000000000208"
}{
"type": "https://api.drophub.example/problems/access-denied",
"title": "Access denied",
"status": 403,
"detail": "Access to this resource is denied.",
"instance": "/api/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
"code": "ACCESS_DENIED",
"timestamp": "2026-08-22T18:30:00Z",
"correlationId": "018f2d8a-1f00-7000-8000-000000000207",
"requestId": "018f2d8a-1f00-7000-8000-000000000208"
}External Shipments
Cancel before physical pickup
Allows cancellation while pending, ready, without a driver, offered or accepted, atomically withdrawing live driver offers. Once the parcel is picked up, returns 409 with SHIPMENT_RETURN_REQUIRED; create a separate return shipment instead. Delivery and custody facts are preserved.
POST
/
api
/
v2
/
external
/
shipments
/
{shipmentId}
/
cancel
Cancel before physical pickup
curl --request POST \
--url https://api-test.drop-hub.com/api/v2/external/shipments/{shipmentId}/cancel \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"reason": "MERCHANT_REQUESTED"
}
'import requests
url = "https://api-test.drop-hub.com/api/v2/external/shipments/{shipmentId}/cancel"
payload = { "reason": "MERCHANT_REQUESTED" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({reason: 'MERCHANT_REQUESTED'})
};
fetch('https://api-test.drop-hub.com/api/v2/external/shipments/{shipmentId}/cancel', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-test.drop-hub.com/api/v2/external/shipments/{shipmentId}/cancel",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'reason' => 'MERCHANT_REQUESTED'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-test.drop-hub.com/api/v2/external/shipments/{shipmentId}/cancel"
payload := strings.NewReader("{\n \"reason\": \"MERCHANT_REQUESTED\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-test.drop-hub.com/api/v2/external/shipments/{shipmentId}/cancel")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"reason\": \"MERCHANT_REQUESTED\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-test.drop-hub.com/api/v2/external/shipments/{shipmentId}/cancel")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"reason\": \"MERCHANT_REQUESTED\"\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"reference": "<string>",
"status": "CREATED",
"trackingUrl": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"version": 1,
"codAmount": 1,
"deliveryFeeAmount": 1,
"deliveryFeeCurrency": "SAR",
"eta": {
"target": "PICKUP",
"estimatedArrivalAt": "2023-11-07T05:31:56Z",
"estimatedMinutes": 123,
"calculatedAt": "2023-11-07T05:31:56Z",
"distanceMetres": 123
},
"proofAvailable": true,
"proofType": "PHOTO",
"deliveredAt": "2023-11-07T05:31:56Z",
"failureReasonCode": "<string>",
"cancellationReasonCode": "<string>",
"driver": {
"firstName": "<string>",
"vehicleType": "MOTORCYCLE",
"vehiclePlate": "<string>"
}
}{
"type": "https://api.drophub.example/problems/authentication-required",
"title": "Authentication required",
"status": 401,
"detail": "Authentication is required for this resource.",
"instance": "/api/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
"code": "AUTHENTICATION_REQUIRED",
"timestamp": "2026-08-22T18:30:00Z",
"correlationId": "018f2d8a-1f00-7000-8000-000000000207",
"requestId": "018f2d8a-1f00-7000-8000-000000000208"
}{
"type": "https://api.drophub.example/problems/access-denied",
"title": "Access denied",
"status": 403,
"detail": "Access to this resource is denied.",
"instance": "/api/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
"code": "ACCESS_DENIED",
"timestamp": "2026-08-22T18:30:00Z",
"correlationId": "018f2d8a-1f00-7000-8000-000000000207",
"requestId": "018f2d8a-1f00-7000-8000-000000000208"
}{
"type": "https://api.drophub.example/problems/access-denied",
"title": "Access denied",
"status": 403,
"detail": "Access to this resource is denied.",
"instance": "/api/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
"code": "ACCESS_DENIED",
"timestamp": "2026-08-22T18:30:00Z",
"correlationId": "018f2d8a-1f00-7000-8000-000000000207",
"requestId": "018f2d8a-1f00-7000-8000-000000000208"
}{
"type": "https://api.drophub.example/problems/access-denied",
"title": "Access denied",
"status": 403,
"detail": "Access to this resource is denied.",
"instance": "/api/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
"code": "ACCESS_DENIED",
"timestamp": "2026-08-22T18:30:00Z",
"correlationId": "018f2d8a-1f00-7000-8000-000000000207",
"requestId": "018f2d8a-1f00-7000-8000-000000000208"
}{
"type": "https://api.drophub.example/problems/access-denied",
"title": "Access denied",
"status": 403,
"detail": "Access to this resource is denied.",
"instance": "/api/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
"code": "ACCESS_DENIED",
"timestamp": "2026-08-22T18:30:00Z",
"correlationId": "018f2d8a-1f00-7000-8000-000000000207",
"requestId": "018f2d8a-1f00-7000-8000-000000000208"
}{
"type": "https://api.drophub.example/problems/access-denied",
"title": "Access denied",
"status": 403,
"detail": "Access to this resource is denied.",
"instance": "/api/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206",
"code": "ACCESS_DENIED",
"timestamp": "2026-08-22T18:30:00Z",
"correlationId": "018f2d8a-1f00-7000-8000-000000000207",
"requestId": "018f2d8a-1f00-7000-8000-000000000208"
}Authorizations
OAuth 2.0 client-credentials flow for external machine-to-machine integrations.
Headers
Optional. Retry safety is handled for you: when this header is absent DropHub derives the key from the reference you already send — the order number on a shipment create, the shipment id on a cancel — scoped to your merchant account. Two calls naming the same order are treated as one submission and the second returns the original result. Send your own key only if you want to control the replay window yourself; an explicit key always wins.
Required string length:
16 - 128Example:
"merchant-order-20260822-0001"
Path Parameters
Body
application/json
Pattern:
^[A-Z][A-Z0-9_]{1,47}$Response
Minimal partner-safe shipment
ASSIGNED covers an offer awaiting the driver's acceptance and an accepted one. NO_DRIVER_AVAILABLE means the bounded driver search ended without a driver; the shipment can still be cancelled.
Available options:
CREATED, ASSIGNED, PICKED_UP, OUT_FOR_DELIVERY, DELIVERED, FAILED, NO_DRIVER_AVAILABLE, CANCELLED Required range:
x >= 0Required range:
x >= 0Required range:
x >= 0Example:
"SAR"
Show child attributes
Show child attributes
Available options:
PHOTO, SIGNATURE, null The driver who accepted the shipment, while it is still moving. Phone number, surname, licence and identifiers are not disclosed; contact goes through the shipment conversation.
Show child attributes
Show child attributes