Shipments
A shipment is created through the same engine as the dashboard: coverage check, monthly quota, rate-card pricing, estimated delivery date, tracking number, and the shipment.created webhook event are all identical. This guide explains how to create shipments for a merchant or a one-off sender, how returns and exchanges work, how a shipment moves through its statuses, and how to track, print, update and cancel it.
Scopes: shipments:write to create, update and cancel; shipments:read to list, get, track and print. Writing does not include reading. For a password login the dashboard permission is checked exactly: orders:create to create, orders:update to update, orders:cancel to cancel. An API key needs only the scope.
Numbers have upper bounds (for example weight at most 9,999,999 kg and each dimension at most 100,000 cm); larger values answer 400 validation_failed. See Conventions.
POST /shipments returns 201 with the full shipment. The shipping fee is never sent: it is computed from your company's rate card. To show the fee before ordering, use a price quote.
sender.type = "merchant" books the shipment for one of your merchants. sender.merchant is the merchant id or the exact account name (case and Arabic letter variants are ignored). A name shared by two merchants answers 422 merchant.ambiguous with details.candidates: use the id. When pickup is omitted, the merchant's primary saved address is the pickup.
curl -X POST "https://api.goldrock.live/api/public/v1/shipments" \
-H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-API-Secret: YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1001" \
-d '{
"reference": "ORD-1001",
"serviceType": "delivery",
"serviceTier": "standard",
"sender": {
"type": "merchant",
"merchant": "Noor Electronics"
},
"recipient": {
"country": "SA",
"city": "Riyadh",
"district": "Al Olaya",
"addressLine": "King Fahd Road, Building 12, Floor 3",
"shortAddress": "RNBA6769",
"name": "Khaled Alotaibi",
"phone": "0555123456"
},
"parcel": {
"weightKg": 1.5,
"lengthCm": 20,
"widthCm": 15,
"heightCm": 10,
"pieces": 1,
"description": "Mobile phone case",
"declaredValue": 250,
"fragile": false
},
"payment": {
"codAmount": 199.5,
"freightOnDelivery": false
},
"delivery": {
"allowOpenPackage": false,
"requireSignature": true
}
}'const response = await fetch("https://api.goldrock.live/api/public/v1/shipments", {
method: "POST",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Content-Type": "application/json",
"Idempotency-Key": "order-1001"
},
body: JSON.stringify({
"reference": "ORD-1001",
"serviceType": "delivery",
"serviceTier": "standard",
"sender": {
"type": "merchant",
"merchant": "Noor Electronics"
},
"recipient": {
"country": "SA",
"city": "Riyadh",
"district": "Al Olaya",
"addressLine": "King Fahd Road, Building 12, Floor 3",
"shortAddress": "RNBA6769",
"name": "Khaled Alotaibi",
"phone": "0555123456"
},
"parcel": {
"weightKg": 1.5,
"lengthCm": 20,
"widthCm": 15,
"heightCm": 10,
"pieces": 1,
"description": "Mobile phone case",
"declaredValue": 250,
"fragile": false
},
"payment": {
"codAmount": 199.5,
"freightOnDelivery": false
},
"delivery": {
"allowOpenPackage": false,
"requireSignature": true
}
}),
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/shipments';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
'Content-Type: application/json',
'Idempotency-Key: order-1001',
],
CURLOPT_POSTFIELDS => json_encode([
'reference' => 'ORD-1001',
'serviceType' => 'delivery',
'serviceTier' => 'standard',
'sender' => [
'type' => 'merchant',
'merchant' => 'Noor Electronics',
],
'recipient' => [
'country' => 'SA',
'city' => 'Riyadh',
'district' => 'Al Olaya',
'addressLine' => 'King Fahd Road, Building 12, Floor 3',
'shortAddress' => 'RNBA6769',
'name' => 'Khaled Alotaibi',
'phone' => '0555123456',
],
'parcel' => [
'weightKg' => 1.5,
'lengthCm' => 20,
'widthCm' => 15,
'heightCm' => 10,
'pieces' => 1,
'description' => 'Mobile phone case',
'declaredValue' => 250,
'fragile' => false,
],
'payment' => [
'codAmount' => 199.5,
'freightOnDelivery' => false,
],
'delivery' => [
'allowOpenPackage' => false,
'requireSignature' => true,
],
], JSON_UNESCAPED_UNICODE),
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"POST",
"https://api.goldrock.live/api/public/v1/shipments",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Idempotency-Key": "order-1001",
},
json={
"reference": "ORD-1001",
"serviceType": "delivery",
"serviceTier": "standard",
"sender": {
"type": "merchant",
"merchant": "Noor Electronics",
},
"recipient": {
"country": "SA",
"city": "Riyadh",
"district": "Al Olaya",
"addressLine": "King Fahd Road, Building 12, Floor 3",
"shortAddress": "RNBA6769",
"name": "Khaled Alotaibi",
"phone": "0555123456",
},
"parcel": {
"weightKg": 1.5,
"lengthCm": 20,
"widthCm": 15,
"heightCm": 10,
"pieces": 1,
"description": "Mobile phone case",
"declaredValue": 250,
"fragile": False,
},
"payment": {
"codAmount": 199.5,
"freightOnDelivery": False,
},
"delivery": {
"allowOpenPackage": False,
"requireSignature": True,
},
},
timeout=30,
)
print(response.status_code, response.json()){
"trackingNumber": "AWB-RUH-000123",
"reference": "ORD-1001",
"status": "created",
"statusCode": 1020,
"statusLabelAr": "تم إنشاء الطلب",
"statusLabelEn": "Order Created",
"isFinal": false,
"serviceType": "delivery",
"serviceTier": "standard",
"source": "api",
"createdAt": "2026-01-15T09:30:00Z",
"estimatedDeliveryDate": "2026-01-17",
"sender": {
"type": "merchant",
"name": "Noor Electronics",
"phone": "0501234567",
"email": "orders@noor-electronics.example",
"merchant": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Noor Electronics"
}
},
"pickup": {
"country": {
"id": "5a6f7c1c-1a3e-4c1f-9d5c-3f0d7d2a1b01",
"nameAr": "المملكة العربية السعودية",
"nameEn": "Saudi Arabia"
},
"city": {
"id": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b",
"nameAr": "الرياض",
"nameEn": "Riyadh"
},
"district": {
"id": "c2d3e4f5-0a1b-4c2d-8e3f-4a5b6c7d8e91",
"nameAr": "العليا",
"nameEn": "Al Olaya"
},
"addressLine": "King Fahd Road, Warehouse 4",
"shortAddress": "RNBA6769",
"latitude": null,
"longitude": null
},
"recipient": {
"name": "Khaled Alotaibi",
"phone": "0555123456",
"secondaryPhone": null,
"country": {
"id": "5a6f7c1c-1a3e-4c1f-9d5c-3f0d7d2a1b01",
"nameAr": "المملكة العربية السعودية",
"nameEn": "Saudi Arabia"
},
"city": {
"id": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b",
"nameAr": "الرياض",
"nameEn": "Riyadh"
},
"district": {
"id": "c2d3e4f5-0a1b-4c2d-8e3f-4a5b6c7d8e91",
"nameAr": "العليا",
"nameEn": "Al Olaya"
},
"addressLine": "King Fahd Road, Building 12, Floor 3",
"shortAddress": "RNBA6769",
"latitude": null,
"longitude": null
},
"parcel": {
"weightKg": 1.5,
"lengthCm": 20,
"widthCm": 15,
"heightCm": 10,
"chargeableWeightKg": 1.5,
"pieces": 1,
"description": "Mobile phone case",
"declaredValue": 250,
"fragile": false,
"requiresColdChain": false,
"coldChainRange": null,
"flammable": false,
"hazardous": false,
"containsAlcohol": false,
"liquid": false,
"highValue": false
},
"delivery": {
"allowOpenPackage": false,
"requireSignature": true,
"requireIdVerification": false,
"allowNeighborDelivery": true
},
"payment": {
"codAmount": 199.5,
"shippingFee": 30,
"freightOnDelivery": false
},
"pieces": [
{
"barcode": "AWB-RUH-000123-P1"
}
],
"branch": {
"id": "8d3c7f52-4b1e-4a90-b6d2-1e5f9a0c3b74",
"name": "Riyadh Hub"
},
"canCancel": true,
"isEditable": true
}sender.type = "custom" is for a person or business that is not one of your merchants, for example a customer of your website who ships a parcel. It needs sender.name, sender.phone and a pickup address. The shipment is booked on the company's shared walk-in account. Places here use Arabic names: the spelling variants are handled for you (Places by name).
curl -X POST "https://api.goldrock.live/api/public/v1/shipments" \
-H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-API-Secret: YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: web-order-58213" \
-d '{
"reference": "WEB-58213",
"serviceTier": "express",
"sender": {
"type": "custom",
"name": "Sara Ahmed",
"phone": "0501234567",
"email": "sara@example.com"
},
"pickup": {
"country": "SA",
"city": "الرياض",
"district": "حي العليا",
"addressLine": "طريق الملك فهد، مبنى 12",
"shortAddress": "RNBA6769",
"latitude": 24.7136,
"longitude": 46.6753
},
"recipient": {
"country": "SA",
"city": "جده",
"district": "حي البرية",
"addressLine": "شارع الأمير سلطان، عمارة 4",
"shortAddress": "JEDA2345",
"name": "خالد العتيبي",
"phone": "0555123456",
"secondaryPhone": "0555987654"
},
"parcel": {
"weightKg": 3,
"lengthCm": 40,
"widthCm": 30,
"heightCm": 20,
"description": "Clothes",
"declaredValue": 600
},
"payment": {
"codAmount": 0,
"freightOnDelivery": true
}
}'const response = await fetch("https://api.goldrock.live/api/public/v1/shipments", {
method: "POST",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Content-Type": "application/json",
"Idempotency-Key": "web-order-58213"
},
body: JSON.stringify({
"reference": "WEB-58213",
"serviceTier": "express",
"sender": {
"type": "custom",
"name": "Sara Ahmed",
"phone": "0501234567",
"email": "sara@example.com"
},
"pickup": {
"country": "SA",
"city": "الرياض",
"district": "حي العليا",
"addressLine": "طريق الملك فهد، مبنى 12",
"shortAddress": "RNBA6769",
"latitude": 24.7136,
"longitude": 46.6753
},
"recipient": {
"country": "SA",
"city": "جده",
"district": "حي البرية",
"addressLine": "شارع الأمير سلطان، عمارة 4",
"shortAddress": "JEDA2345",
"name": "خالد العتيبي",
"phone": "0555123456",
"secondaryPhone": "0555987654"
},
"parcel": {
"weightKg": 3,
"lengthCm": 40,
"widthCm": 30,
"heightCm": 20,
"description": "Clothes",
"declaredValue": 600
},
"payment": {
"codAmount": 0,
"freightOnDelivery": true
}
}),
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/shipments';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
'Content-Type: application/json',
'Idempotency-Key: web-order-58213',
],
CURLOPT_POSTFIELDS => json_encode([
'reference' => 'WEB-58213',
'serviceTier' => 'express',
'sender' => [
'type' => 'custom',
'name' => 'Sara Ahmed',
'phone' => '0501234567',
'email' => 'sara@example.com',
],
'pickup' => [
'country' => 'SA',
'city' => 'الرياض',
'district' => 'حي العليا',
'addressLine' => 'طريق الملك فهد، مبنى 12',
'shortAddress' => 'RNBA6769',
'latitude' => 24.7136,
'longitude' => 46.6753,
],
'recipient' => [
'country' => 'SA',
'city' => 'جده',
'district' => 'حي البرية',
'addressLine' => 'شارع الأمير سلطان، عمارة 4',
'shortAddress' => 'JEDA2345',
'name' => 'خالد العتيبي',
'phone' => '0555123456',
'secondaryPhone' => '0555987654',
],
'parcel' => [
'weightKg' => 3,
'lengthCm' => 40,
'widthCm' => 30,
'heightCm' => 20,
'description' => 'Clothes',
'declaredValue' => 600,
],
'payment' => [
'codAmount' => 0,
'freightOnDelivery' => true,
],
], JSON_UNESCAPED_UNICODE),
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"POST",
"https://api.goldrock.live/api/public/v1/shipments",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Idempotency-Key": "web-order-58213",
},
json={
"reference": "WEB-58213",
"serviceTier": "express",
"sender": {
"type": "custom",
"name": "Sara Ahmed",
"phone": "0501234567",
"email": "sara@example.com",
},
"pickup": {
"country": "SA",
"city": "الرياض",
"district": "حي العليا",
"addressLine": "طريق الملك فهد، مبنى 12",
"shortAddress": "RNBA6769",
"latitude": 24.7136,
"longitude": 46.6753,
},
"recipient": {
"country": "SA",
"city": "جده",
"district": "حي البرية",
"addressLine": "شارع الأمير سلطان، عمارة 4",
"shortAddress": "JEDA2345",
"name": "خالد العتيبي",
"phone": "0555123456",
"secondaryPhone": "0555987654",
},
"parcel": {
"weightKg": 3,
"lengthCm": 40,
"widthCm": 30,
"heightCm": 20,
"description": "Clothes",
"declaredValue": 600,
},
"payment": {
"codAmount": 0,
"freightOnDelivery": True,
},
},
timeout=30,
)
print(response.status_code, response.json())Required fields are marked. Everything else is optional.
| Field | Details |
|---|---|
reference |
Your own order reference, up to 100 characters. Printed on the label and searchable |
serviceType |
delivery (default), exchange or return |
serviceTier |
standard (default), express or sameDay. It drives the estimated delivery date |
sender |
Required for key and staff credentials. type is merchant or custom. A merchant login always sends as its own merchant and cannot use custom (403) |
sender.merchant |
Required for type: merchant: id or exact name |
sender.name, sender.phone |
Required for type: custom. sender.email is optional |
pickup |
Where the courier collects. Optional for a merchant sender (the primary address is used), required for a custom sender and for a return |
pickup.country |
Optional when the city name is unambiguous |
pickup.city, pickup.district |
Required when pickup is sent. Id, code or name |
pickup.addressLine |
Required, up to 500 characters: street, building, landmark |
pickup.shortAddress |
Saudi national short address, 4 letters then 4 digits. Required for pickups in Saudi Arabia |
pickup.latitude, pickup.longitude |
Optional, -90 to 90 and -180 to 180 |
pickup.branch |
Optional branch id, code or name. By default the branch covering the pickup district is chosen automatically; if none or several cover it you must name one (branch_coverage.no_coverage_for_city, branch_coverage.ambiguous_coverage) |
recipient |
Required except for returns. Same address fields as pickup, all of them required in the same way |
recipient.name |
Required, up to 200 characters |
recipient.phone |
Required, up to 30 characters: digits, spaces, +, - and brackets |
recipient.secondaryPhone |
Optional second phone, same format |
parcel.weightKg |
Required, greater than 0. The weight of the whole shipment |
parcel.lengthCm, widthCm, heightCm |
Required, greater than 0. Dimensions of the whole shipment |
parcel.pieces |
1 to 1000, default 1 |
parcel.description |
What is inside, up to 500 characters, shown on the label |
parcel.declaredValue |
Value of the goods, 0 or more, default 0 |
parcel.fragile, flammable, hazardous, containsAlcohol, liquid, highValue |
Handling flags, default false. They can add handling surcharges |
parcel.requiresColdChain |
Default false. When true, parcel.coldChainRange is required: frozen, chilled or ambient |
payment.codAmount |
Cash to collect from the recipient, 0 or more, default 0. Must be 0 for a return |
payment.freightOnDelivery |
true when the recipient pays the shipping fee at the door. Default false |
delivery.allowOpenPackage |
The recipient may open the parcel before accepting. Default false |
delivery.requireSignature |
A signature is required. Default true |
delivery.requireIdVerification |
The courier checks the recipient's ID. Default false |
delivery.allowNeighborDelivery |
A neighbour may accept the parcel. Default true |
parcel.chargeableWeightKg in the response is the larger of the actual and the volumetric weight; it is the weight your price is based on.
A return collects a parcel from a customer and sends it back to the merchant. Use serviceType: "return" with a merchant sender. pickup is the customer's address (the place the courier collects from) and is required. There is no recipient: the parcel goes to the merchant's primary saved address, and the receiver details are taken from it. A return cannot carry a COD amount (payment.codAmount must be 0).
curl -X POST "https://api.goldrock.live/api/public/v1/shipments" \
-H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-API-Secret: YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: return-ORD-1001" \
-d '{
"reference": "RET-1001",
"serviceType": "return",
"sender": {
"type": "merchant",
"merchant": "Noor Electronics"
},
"pickup": {
"country": "SA",
"city": "Riyadh",
"district": "Al Olaya",
"addressLine": "King Fahd Road, Building 12, Floor 3",
"shortAddress": "RNBA6769"
},
"parcel": {
"weightKg": 1.5,
"lengthCm": 20,
"widthCm": 15,
"heightCm": 10,
"description": "Returned phone case"
}
}'const response = await fetch("https://api.goldrock.live/api/public/v1/shipments", {
method: "POST",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Content-Type": "application/json",
"Idempotency-Key": "return-ORD-1001"
},
body: JSON.stringify({
"reference": "RET-1001",
"serviceType": "return",
"sender": {
"type": "merchant",
"merchant": "Noor Electronics"
},
"pickup": {
"country": "SA",
"city": "Riyadh",
"district": "Al Olaya",
"addressLine": "King Fahd Road, Building 12, Floor 3",
"shortAddress": "RNBA6769"
},
"parcel": {
"weightKg": 1.5,
"lengthCm": 20,
"widthCm": 15,
"heightCm": 10,
"description": "Returned phone case"
}
}),
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/shipments';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
'Content-Type: application/json',
'Idempotency-Key: return-ORD-1001',
],
CURLOPT_POSTFIELDS => json_encode([
'reference' => 'RET-1001',
'serviceType' => 'return',
'sender' => [
'type' => 'merchant',
'merchant' => 'Noor Electronics',
],
'pickup' => [
'country' => 'SA',
'city' => 'Riyadh',
'district' => 'Al Olaya',
'addressLine' => 'King Fahd Road, Building 12, Floor 3',
'shortAddress' => 'RNBA6769',
],
'parcel' => [
'weightKg' => 1.5,
'lengthCm' => 20,
'widthCm' => 15,
'heightCm' => 10,
'description' => 'Returned phone case',
],
], JSON_UNESCAPED_UNICODE),
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"POST",
"https://api.goldrock.live/api/public/v1/shipments",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Idempotency-Key": "return-ORD-1001",
},
json={
"reference": "RET-1001",
"serviceType": "return",
"sender": {
"type": "merchant",
"merchant": "Noor Electronics",
},
"pickup": {
"country": "SA",
"city": "Riyadh",
"district": "Al Olaya",
"addressLine": "King Fahd Road, Building 12, Floor 3",
"shortAddress": "RNBA6769",
},
"parcel": {
"weightKg": 1.5,
"lengthCm": 20,
"widthCm": 15,
"heightCm": 10,
"description": "Returned phone case",
},
},
timeout=30,
)
print(response.status_code, response.json())An exchange (serviceType: "exchange") delivers a replacement item to the recipient and comes with a linked return shipment for the item coming back. You create it like a normal delivery, with a recipient. Cancelling the exchange also cancels its pending return, and the service type of an exchange cannot be changed once its linked return exists.
curl -X POST "https://api.goldrock.live/api/public/v1/shipments" \
-H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-API-Secret: YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: exchange-ORD-1001" \
-d '{
"reference": "EXC-1001",
"serviceType": "exchange",
"sender": {
"type": "merchant",
"merchant": "Noor Electronics"
},
"recipient": {
"country": "SA",
"city": "Riyadh",
"district": "Al Olaya",
"addressLine": "King Fahd Road, Building 12, Floor 3",
"shortAddress": "RNBA6769",
"name": "Khaled Alotaibi",
"phone": "0555123456"
},
"parcel": {
"weightKg": 1.5,
"lengthCm": 20,
"widthCm": 15,
"heightCm": 10,
"description": "Replacement phone case"
}
}'const response = await fetch("https://api.goldrock.live/api/public/v1/shipments", {
method: "POST",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Content-Type": "application/json",
"Idempotency-Key": "exchange-ORD-1001"
},
body: JSON.stringify({
"reference": "EXC-1001",
"serviceType": "exchange",
"sender": {
"type": "merchant",
"merchant": "Noor Electronics"
},
"recipient": {
"country": "SA",
"city": "Riyadh",
"district": "Al Olaya",
"addressLine": "King Fahd Road, Building 12, Floor 3",
"shortAddress": "RNBA6769",
"name": "Khaled Alotaibi",
"phone": "0555123456"
},
"parcel": {
"weightKg": 1.5,
"lengthCm": 20,
"widthCm": 15,
"heightCm": 10,
"description": "Replacement phone case"
}
}),
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/shipments';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
'Content-Type: application/json',
'Idempotency-Key: exchange-ORD-1001',
],
CURLOPT_POSTFIELDS => json_encode([
'reference' => 'EXC-1001',
'serviceType' => 'exchange',
'sender' => [
'type' => 'merchant',
'merchant' => 'Noor Electronics',
],
'recipient' => [
'country' => 'SA',
'city' => 'Riyadh',
'district' => 'Al Olaya',
'addressLine' => 'King Fahd Road, Building 12, Floor 3',
'shortAddress' => 'RNBA6769',
'name' => 'Khaled Alotaibi',
'phone' => '0555123456',
],
'parcel' => [
'weightKg' => 1.5,
'lengthCm' => 20,
'widthCm' => 15,
'heightCm' => 10,
'description' => 'Replacement phone case',
],
], JSON_UNESCAPED_UNICODE),
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"POST",
"https://api.goldrock.live/api/public/v1/shipments",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Idempotency-Key": "exchange-ORD-1001",
},
json={
"reference": "EXC-1001",
"serviceType": "exchange",
"sender": {
"type": "merchant",
"merchant": "Noor Electronics",
},
"recipient": {
"country": "SA",
"city": "Riyadh",
"district": "Al Olaya",
"addressLine": "King Fahd Road, Building 12, Floor 3",
"shortAddress": "RNBA6769",
"name": "Khaled Alotaibi",
"phone": "0555123456",
},
"parcel": {
"weightKg": 1.5,
"lengthCm": 20,
"widthCm": 15,
"heightCm": 10,
"description": "Replacement phone case",
},
},
timeout=30,
)
print(response.status_code, response.json())Send an Idempotency-Key on every create, derived from your own order (for example order-1001). If a response is lost, send the same request again: the first answer is returned with Idempotent-Replayed: true and no second shipment is created. See Conventions.
A body that breaks a rule is rejected with 400 validation_failed, and details.errors maps every failing field path to its messages, so you can show all problems at once:
{
"code": "validation_failed",
"message": "One or more fields are invalid.",
"status": 400,
"details": {
"errors": {
"recipient.phone": [
"Recipient phone is required."
],
"parcel.weightKg": [
"Weight must be greater than 0."
],
"recipient.shortAddress": [
"Short address must be 4 letters followed by 4 digits, for example RNBA6769."
]
},
"messageAr": "بعض الحقول غير صالحة."
},
"traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}Saudi addresses need the short address. Here the pickup was in Saudi Arabia and the merchant sent none:
{
"code": "validation_failed",
"message": "One or more fields are invalid.",
"status": 400,
"details": {
"errors": {
"pickup.shortAddress": [
"Short address is required for a pickup in Saudi Arabia (e.g. RNBA6769)."
]
},
"messageAr": "بعض الحقول غير صالحة."
},
"traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}Every shipment has a status key (a string such as outForDelivery), its numeric statusCode, labels in both languages and an isFinal flag. The catalogue is the same for everyone and is served by GET /shipments/statuses; fetch it once and cache it. Use the key in your own code.
The stages and the usual path:
Pickup created → pickupScheduled → outForPickup → pickedUp
Linehaul arrivedAtOriginHub → inTransit → arrivedAtDestinationHub → sortedToShelf
Warehouse onHoldWarehouse → (holdExpiredPendingAction)
Delivery assignedToCourier → outForDelivery → delivered
↘ deliveryAttempted / postponedByCustomer / withCourier
(a new attempt returns to outForDelivery)
Exceptions rtoInitiated → rtoInTransit → returnedToSender
cancelled, lost, damaged, disposed, partiallyDeliveredA shipment does not have to touch every status, and the numeric codes group the stages rather than guarantee an order. Final statuses never change again: delivered, returnedToSender, cancelled, lost, disposed.
| Stage | Code | Key (status) | Name | Final |
|---|---|---|---|---|
| Pickup | 1010 | draft | Draft مسودة | |
| Pickup | 1020 | created | Order Created تم إنشاء الطلب | |
| Pickup | 1030 | pickupScheduled | Pickup Scheduled مجدول للاستلام | |
| Pickup | 1040 | outForPickup | Out For Pickup خرج للاستلام | |
| Pickup | 1050 | pickedUp | Picked Up تم الاستلام | |
| Sorting and linehaul | 2010 | arrivedAtOriginHub | Arrived at Origin Hub وصل مركز الفرز الأول | |
| Sorting and linehaul | 2020 | inTransit | In Transit جاري النقل بين المدن | |
| Sorting and linehaul | 2030 | arrivedAtDestinationHub | Arrived at Destination Hub وصل مركز التوزيع النهائي | |
| Sorting and linehaul | 2040 | sortedToShelf | Sorted to Shelf مفروز على الرف | |
| Warehouse hold | 3010 | onHoldWarehouse | On Hold in Warehouse مخزن بالمستودع | |
| Warehouse hold | 3020 | holdExpiredPendingAction | Hold Expired - Action Needed انتهت مهلة التخزين | |
| Last mile delivery | 4005 | assignedToCourier | Assigned to Courier مسندة للمندوب | |
| Last mile delivery | 4010 | outForDelivery | Out For Delivery خرج للتوصيل | |
| Last mile delivery | 4020 | deliveryAttempted | Delivery Attempted محاولة توصيل فاشلة | |
| Last mile delivery | 4030 | postponedByCustomer | Postponed by Customer مؤجل بطلب العميل | |
| Last mile delivery | 4040 | delivered | Delivered تم التسليم بنجاح | yes |
| Last mile delivery | 4050 | partiallyDelivered | Partially Delivered تسليم جزئي | |
| Last mile delivery | 4060 | withCourier | With courier (failed attempt) بعهدة المندوب (تعذّر التوصيل) | |
| Returns and exceptions | 5010 | rtoInitiated | RTO Initiated بدء الإرجاع للمرسل | |
| Returns and exceptions | 5020 | rtoInTransit | RTO In Transit المرتجع في الطريق | |
| Returns and exceptions | 5030 | returnedToSender | Returned to Sender تم الإرجاع للمرسل | yes |
| Returns and exceptions | 5040 | cancelled | Cancelled ملغاة | yes |
| Returns and exceptions | 5050 | lost | Lost مفقودة | yes |
| Returns and exceptions | 5060 | damaged | Damaged تالفة | |
| Returns and exceptions | 5070 | disposed | Disposed تم الإتلاف | yes |
Two flags on the shipment save you from guessing: canCancel (the shipment can still be cancelled) and isEditable (it can still be edited).
GET /shipments/{trackingNumber}/tracking returns the current status, the estimated delivery date and the timeline, oldest first. It carries no internal staff names. note is present only for failed attempts, postponements, cancellation, returns, loss and damage, and holds a reason you can show. location is reserved and not populated yet.
curl "https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/tracking" \
-H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-API-Secret: YOUR_API_SECRET"const response = await fetch("https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/tracking", {
method: "GET",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET"
},
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/tracking';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"GET",
"https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/tracking",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
timeout=30,
)
print(response.status_code, response.json()){
"trackingNumber": "AWB-RUH-000123",
"status": "outForDelivery",
"statusLabelAr": "خرج للتوصيل",
"statusLabelEn": "Out For Delivery",
"estimatedDeliveryDate": "2026-01-17",
"events": [
{
"status": "created",
"statusLabelAr": "تم إنشاء الطلب",
"statusLabelEn": "Order Created",
"at": "2026-01-15T09:30:00Z",
"note": null,
"location": null
},
{
"status": "pickedUp",
"statusLabelAr": "تم الاستلام",
"statusLabelEn": "Picked Up",
"at": "2026-01-15T14:05:00Z",
"note": null,
"location": null
},
{
"status": "outForDelivery",
"statusLabelAr": "خرج للتوصيل",
"statusLabelEn": "Out For Delivery",
"at": "2026-01-17T07:40:00Z",
"note": null,
"location": null
}
]
}To follow changes without polling, subscribe to webhooks.
GET /shipments/{trackingNumber} returns the full shipment shown above. A shipment that belongs to someone else answers 404 shipment.not_found.
GET /shipments lists shipments, newest first, paginated, with filters that combine with AND: status (one or several, comma separated, as keys or numeric codes), merchant (id or exact name), reference (exact, ignoring case), trackingNumber, recipientPhone (part of it), city (destination: id, code or name), createdFrom and createdTo (ISO 8601) and a free-text search.
curl -G "https://api.goldrock.live/api/public/v1/shipments" \
-H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-API-Secret: YOUR_API_SECRET" \
--data-urlencode 'status=created,outForDelivery' \
--data-urlencode 'createdFrom=2026-01-01T00:00:00Z' \
--data-urlencode 'page=1' \
--data-urlencode 'pageSize=25'const params = new URLSearchParams({
"status": "created,outForDelivery",
"createdFrom": "2026-01-01T00:00:00Z",
"page": "1",
"pageSize": "25"
});
const response = await fetch(`https://api.goldrock.live/api/public/v1/shipments?${params}`, {
method: "GET",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET"
},
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/shipments?' . http_build_query([
'status' => 'created,outForDelivery',
'createdFrom' => '2026-01-01T00:00:00Z',
'page' => '1',
'pageSize' => '25',
]);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"GET",
"https://api.goldrock.live/api/public/v1/shipments",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
params={
"status": "created,outForDelivery",
"createdFrom": "2026-01-01T00:00:00Z",
"page": "1",
"pageSize": "25",
},
timeout=30,
)
print(response.status_code, response.json()){
"items": [
{
"trackingNumber": "AWB-RUH-000123",
"reference": "ORD-1001",
"status": "outForDelivery",
"statusLabelAr": "خرج للتوصيل",
"statusLabelEn": "Out For Delivery",
"merchant": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Noor Electronics"
},
"senderName": "Noor Electronics",
"recipientName": "Khaled Alotaibi",
"recipientPhone": "0555123456",
"city": {
"id": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b",
"nameAr": "الرياض",
"nameEn": "Riyadh"
},
"district": {
"id": "c2d3e4f5-0a1b-4c2d-8e3f-4a5b6c7d8e91",
"nameAr": "العليا",
"nameEn": "Al Olaya"
},
"codAmount": 199.5,
"shippingFee": 30,
"createdAt": "2026-01-15T09:30:00Z",
"estimatedDeliveryDate": "2026-01-17"
}
],
"page": 1,
"pageSize": 25,
"totalCount": 1,
"totalPages": 1
}GET /shipments/{trackingNumber}/label returns the air waybill as a PDF (100 x 150 mm) with your company's branding. The response is binary: save it, do not parse it as JSON.
curl "https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/label" \
-H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-API-Secret: YOUR_API_SECRET" \
-o AWB-RUH-000123.pdfconst response = await fetch("https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/label", {
method: "GET",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET"
},
});
if (!response.ok) throw new Error(await response.text());
await require("node:fs/promises").writeFile("AWB-RUH-000123.pdf", Buffer.from(await response.arrayBuffer()));<?php
$url = 'https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/label';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
file_put_contents('AWB-RUH-000123.pdf', $result);import requests
response = requests.request(
"GET",
"https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/label",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
timeout=30,
)
response.raise_for_status()
with open("AWB-RUH-000123.pdf", "wb") as f:
f.write(response.content)PUT /shipments/{trackingNumber} changes only the fields you send. reason is required (up to 300 characters) and is kept in the shipment's audit trail. At least one other field is needed.
You can change: the order reference, the recipient (name, phones, address by names, coordinates), the parcel (weight, dimensions, pieces, declared value) and the payment (codAmount, freightOnDelivery). When you send address fields, the recipient address is resolved again. You may send only the district: it is then looked up inside the shipment's current city. If you send a city, you must send the district too (400 validation_failed). Places accept an id, a code or a name, as everywhere. The fee is recalculated when something that affects it changes.
You cannot change the sender, the pickup address, the service type and tier or the handling flags. Merchant logins cannot edit shipments.
Editing is allowed until the shipment reaches a final status. Once it is out for delivery, only contact details, the address and COD can change (shipment.field_locked_out_for_delivery).
curl -X PUT "https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123" \
-H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-API-Secret: YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"reason": "Customer changed the delivery address",
"recipient": {
"city": "Riyadh",
"district": "Al Malqa",
"addressLine": "Anas Bin Malik Road, Villa 7",
"shortAddress": "RMLA1234",
"phone": "0555000111"
},
"payment": {
"codAmount": 150
}
}'const response = await fetch("https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123", {
method: "PUT",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Content-Type": "application/json"
},
body: JSON.stringify({
"reason": "Customer changed the delivery address",
"recipient": {
"city": "Riyadh",
"district": "Al Malqa",
"addressLine": "Anas Bin Malik Road, Villa 7",
"shortAddress": "RMLA1234",
"phone": "0555000111"
},
"payment": {
"codAmount": 150
}
}),
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'reason' => 'Customer changed the delivery address',
'recipient' => [
'city' => 'Riyadh',
'district' => 'Al Malqa',
'addressLine' => 'Anas Bin Malik Road, Villa 7',
'shortAddress' => 'RMLA1234',
'phone' => '0555000111',
],
'payment' => [
'codAmount' => 150,
],
], JSON_UNESCAPED_UNICODE),
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"PUT",
"https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
json={
"reason": "Customer changed the delivery address",
"recipient": {
"city": "Riyadh",
"district": "Al Malqa",
"addressLine": "Anas Bin Malik Road, Villa 7",
"shortAddress": "RMLA1234",
"phone": "0555000111",
},
"payment": {
"codAmount": 150,
},
},
timeout=30,
)
print(response.status_code, response.json())POST /shipments/{trackingNumber}/cancel with an optional reason (up to 500 characters). It is possible while the shipment is a draft, created or scheduled for pickup. Later it answers 422 shipment.cannot_cancel. Check canCancel first. Merchant logins cannot cancel through the API.
curl -X POST "https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/cancel" \
-H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-API-Secret: YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"reason": "Customer cancelled the order"
}'const response = await fetch("https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/cancel", {
method: "POST",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Content-Type": "application/json"
},
body: JSON.stringify({
"reason": "Customer cancelled the order"
}),
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/cancel';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'reason' => 'Customer cancelled the order',
], JSON_UNESCAPED_UNICODE),
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"POST",
"https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/cancel",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
json={
"reason": "Customer cancelled the order",
},
timeout=30,
)
print(response.status_code, response.json()){
"code": "shipment.cannot_cancel",
"message": "The shipment can no longer be cancelled in its current status.",
"status": 422,
"details": {
"messageAr": "لا يمكن إلغاء الشحنة في حالتها الحالية."
},
"traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}| Code | Cause |
|---|---|
validation_failed |
A field is missing or malformed. Read details.errors |
geo_*_not_found, geo_*_ambiguous |
A place name did not match, see Places by name |
merchant.not_found, merchant.ambiguous |
The merchant id or name is wrong, or a name is shared by two merchants |
coverage.destination_not_covered, coverage.pickup_not_covered |
The company does not serve that city |
branch_coverage.no_coverage_for_city, branch_coverage.ambiguous_coverage |
Name the pickup branch explicitly |
quota.monthly_shipments_limit_reached |
The company's monthly shipment limit is reached |
pricing.default_rate_card_not_found |
The company has no rate card yet |
shipment.cannot_cancel, shipment.not_editable, shipment.field_locked_out_for_delivery |
The shipment is past the point of that action |
idempotency_key_reused |
The same Idempotency-Key was sent with a different body |
See the error reference for every code.