Create a shipment
shipments:writeيدعم Idempotency-KeyBooks a shipment through the same engine as the dashboard: coverage, quota, rate-card pricing, estimated
delivery date, tracking number, and the shipment.created webhook event are all identical.
The fee is computed from the rate card; it cannot be sent.
Sender. sender.type = "merchant" takes sender.merchant (an id, or the exact account name; ambiguous
names answer 422 merchant.ambiguous with details.candidates). When pickup is omitted the merchant's
primary saved address is the pickup. sender.type = "custom" books a one-off sender on the company's shared
walk-in account and requires sender.name, sender.phone and pickup. A merchant login always sends as its
own merchant and cannot use custom.
Places. country, city and district of pickup and recipient accept an id, a code or a name in
Arabic or English. They are matched strictly and nothing is ever created: failures answer 422 with
geo_country_not_found, geo_city_not_found, geo_district_not_found, geo_city_ambiguous or
geo_district_ambiguous; details.field is pickup or recipient and details.candidates lists suggestions.
For addresses in Saudi Arabia shortAddress (4 letters + 4 digits) is required.
Pickup branch. Chosen from the pickup district's branch coverage unless pickup.branch names one.
Retries. Send Idempotency-Key to make a retry safe.
المعاملات
| الاسم | الموضع | النوع | الوصف |
|---|---|---|---|
Idempotency-Key | header | string | Optional key (up to 128 characters, no spaces; |
جسم الطلب · PublicCreateShipmentRequestapplication/json
The shipment.
| الحقل | النوع | الوصف |
|---|---|---|
reference | stringيقبل null | Your own order reference (shown on the label and searchable). Up to 100 characters. مثال: |
serviceType | enum | Kind of service requested for a shipment. القيم: |
serviceTier | enum | Speed of the service; it drives the estimated delivery date. القيم: |
sender | PublicSenderInput | The sender of a shipment. |
typesender.type | enum | Who sends the shipment. القيم: |
merchantsender.merchant | stringيقبل null | For مثال: |
namesender.name | stringيقبل null | For مثال: |
phonesender.phone | stringيقبل null | For مثال: |
emailsender.email | stringيقبل null | For مثال: |
pickup | PublicPickupInput | The pickup address. |
countrypickup.country | stringيقبل null | Country id, ISO code or name. Optional when the city name is unambiguous. مثال: |
citypickup.city مطلوب | stringيقبل null | City id, code or name. Required. مثال: |
districtpickup.district مطلوب | stringيقبل null | District id, code or name. Required. Unknown districts are never created: you get مثال: |
addressLinepickup.addressLine مطلوب | stringيقبل null | Street, building and landmark. Required, up to 500 characters. مثال: |
shortAddresspickup.shortAddress مشروط | stringيقبل null | Saudi national short address: 4 letters and 4 digits. Required when the city is in Saudi Arabia. مثال: |
latitudepickup.latitude | number (double)يقبل null | Latitude, -90 to 90 (optional). مثال: |
longitudepickup.longitude | number (double)يقبل null | Longitude, -180 to 180 (optional). مثال: |
branchpickup.branch | stringيقبل null | Branch that handles the pickup: branch id, code or name. Optional; by default the branch covering the pickup
district is chosen automatically ( مثال: |
recipient | PublicRecipientInput | The recipient and the delivery address. |
countryrecipient.country | stringيقبل null | Country id, ISO code or name. Optional when the city name is unambiguous. مثال: |
cityrecipient.city مطلوب | stringيقبل null | City id, code or name. Required. مثال: |
districtrecipient.district مطلوب | stringيقبل null | District id, code or name. Required. Unknown districts are never created: you get مثال: |
addressLinerecipient.addressLine مطلوب | stringيقبل null | Street, building and landmark. Required, up to 500 characters. مثال: |
shortAddressrecipient.shortAddress مشروط | stringيقبل null | Saudi national short address: 4 letters and 4 digits. Required when the city is in Saudi Arabia. مثال: |
latituderecipient.latitude | number (double)يقبل null | Latitude, -90 to 90 (optional). مثال: |
longituderecipient.longitude | number (double)يقبل null | Longitude, -180 to 180 (optional). مثال: |
namerecipient.name مطلوب | stringيقبل null | Recipient name. Required, up to 200 characters. مثال: |
phonerecipient.phone مطلوب | stringيقبل null | Recipient phone. Required; digits, spaces, +, - and brackets. مثال: |
secondaryPhonerecipient.secondaryPhone | stringيقبل null | Second phone (optional). مثال: |
parcel | PublicParcelInput | The parcel. Weight and dimensions describe the whole shipment. |
weightKgparcel.weightKg مطلوب | number (double) | Actual weight in kilograms, greater than 0. مثال: |
lengthCmparcel.lengthCm مطلوب | number (double) | Length in centimetres, greater than 0. مثال: |
widthCmparcel.widthCm مطلوب | number (double) | Width in centimetres, greater than 0. مثال: |
heightCmparcel.heightCm مطلوب | number (double) | Height in centimetres, greater than 0. مثال: |
piecesparcel.pieces | integer (int32)يقبل null | Number of pieces (default 1). مثال: |
descriptionparcel.description | stringيقبل null | What is inside (optional, shown on the label). مثال: |
declaredValueparcel.declaredValue | number (double)يقبل null | Declared value of the goods (default 0). مثال: |
fragileparcel.fragile | boolean | Fragile goods. مثال: |
requiresColdChainparcel.requiresColdChain مشروط | boolean | Needs cold chain; then مثال: |
coldChainRangeparcel.coldChainRange | enum | Temperature range of cold-chain goods. القيم: |
flammableparcel.flammable | boolean | Flammable goods. مثال: |
hazardousparcel.hazardous | boolean | Hazardous goods. مثال: |
containsAlcoholparcel.containsAlcohol | boolean | Contains alcohol. مثال: |
liquidparcel.liquid | boolean | Liquid goods. مثال: |
highValueparcel.highValue | boolean | High-value goods. مثال: |
payment | PublicPaymentInput | Cash on delivery and freight payment. |
codAmountpayment.codAmount | number (double)يقبل null | Amount the courier collects from the recipient (cash on delivery). Default 0. Must be 0 for مثال: |
freightOnDeliverypayment.freightOnDelivery | booleanيقبل null | True when the recipient pays the shipping fee on delivery. مثال: |
delivery | PublicDeliveryOptionsInput | Handover rules at the recipient's door. Omitted values use the system defaults shown. |
allowOpenPackagedelivery.allowOpenPackage | booleanيقبل null | The recipient may open the package before accepting. Default false. مثال: |
requireSignaturedelivery.requireSignature مشروط | booleanيقبل null | A signature is required on delivery. Default true. مثال: |
requireIdVerificationdelivery.requireIdVerification | booleanيقبل null | The courier must verify the recipient's ID. Default false. مثال: |
allowNeighborDeliverydelivery.allowNeighborDelivery | booleanيقبل null | A neighbour may accept the parcel. Default true. مثال: |
وثيقة OpenAPI لا تعلّم الحقول المطلوبة رسمياً، لذلك تُقرأ كلمة «مطلوب» من وصف كل حقل. تسرد الأدلة الحقول المطلوبة لكل طلب.
مثال طلب
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())تستخدم الأمثلة مفتاح API؛ استبدل القيم النائبة. لاستخدام رمز Bearer أرسل Authorization: Bearer <accessToken>.
الاستجابات
201The created shipment.
الاستجابات · الحقل
| الحقل | النوع | الوصف |
|---|---|---|
trackingNumber | stringيقبل null | Tracking number; identifies the shipment in every route. |
reference | stringيقبل null | Your order reference. |
status | stringيقبل null | Status key, e.g. |
statusCode | integer (int32) | Numeric status code. |
statusLabelAr | stringيقبل null | Arabic status label. |
statusLabelEn | stringيقبل null | English status label. |
isFinal | boolean | True when the shipment reached a final status. |
serviceType | enum | Kind of service requested for a shipment. القيم: |
serviceTier | enum | Speed of the service; it drives the estimated delivery date. القيم: |
source | enum | How the order reached the system. القيم: |
createdAt | string (date-time) | Creation time (UTC). |
estimatedDeliveryDate | string (date)يقبل null | Estimated delivery date (yyyy-MM-dd), when known. |
sender | PublicSenderDto | The sender of a shipment. |
typesender.type | enum | Who sends the shipment. القيم: |
namesender.name | stringيقبل null | Sender name. |
phonesender.phone | stringيقبل null | Sender phone. |
emailsender.email | stringيقبل null | Sender email. |
merchantsender.merchant | PublicMerchantRef | A merchant reference. |
idsender.merchant.id | string (uuid) | Merchant id. |
namesender.merchant.name | stringيقبل null | Merchant account name. |
pickup | PublicAddressDto | A resolved address. |
countrypickup.country | PublicNamedRef | A catalog entry shown in both languages. |
idpickup.country.id | string (uuid)يقبل null | Catalog id, or null for legacy shipments that only stored a name. |
nameArpickup.country.nameAr | stringيقبل null | Arabic name. |
nameEnpickup.country.nameEn | stringيقبل null | English name. |
citypickup.city | PublicNamedRef | A catalog entry shown in both languages. |
idpickup.city.id | string (uuid)يقبل null | Catalog id, or null for legacy shipments that only stored a name. |
nameArpickup.city.nameAr | stringيقبل null | Arabic name. |
nameEnpickup.city.nameEn | stringيقبل null | English name. |
districtpickup.district | PublicNamedRef | A catalog entry shown in both languages. |
idpickup.district.id | string (uuid)يقبل null | Catalog id, or null for legacy shipments that only stored a name. |
nameArpickup.district.nameAr | stringيقبل null | Arabic name. |
nameEnpickup.district.nameEn | stringيقبل null | English name. |
addressLinepickup.addressLine | stringيقبل null | Street, building and landmark. |
shortAddresspickup.shortAddress | stringيقبل null | Saudi national short address. |
latitudepickup.latitude | number (double)يقبل null | Latitude. |
longitudepickup.longitude | number (double)يقبل null | Longitude. |
recipient | PublicRecipientDto | The recipient. |
namerecipient.name | stringيقبل null | Recipient name. |
phonerecipient.phone | stringيقبل null | Recipient phone. |
secondaryPhonerecipient.secondaryPhone | stringيقبل null | Second phone. |
countryrecipient.country | PublicNamedRef | A catalog entry shown in both languages. |
idrecipient.country.id | string (uuid)يقبل null | Catalog id, or null for legacy shipments that only stored a name. |
nameArrecipient.country.nameAr | stringيقبل null | Arabic name. |
nameEnrecipient.country.nameEn | stringيقبل null | English name. |
cityrecipient.city | PublicNamedRef | A catalog entry shown in both languages. |
idrecipient.city.id | string (uuid)يقبل null | Catalog id, or null for legacy shipments that only stored a name. |
nameArrecipient.city.nameAr | stringيقبل null | Arabic name. |
nameEnrecipient.city.nameEn | stringيقبل null | English name. |
districtrecipient.district | PublicNamedRef | A catalog entry shown in both languages. |
idrecipient.district.id | string (uuid)يقبل null | Catalog id, or null for legacy shipments that only stored a name. |
nameArrecipient.district.nameAr | stringيقبل null | Arabic name. |
nameEnrecipient.district.nameEn | stringيقبل null | English name. |
addressLinerecipient.addressLine | stringيقبل null | Street, building and landmark. |
shortAddressrecipient.shortAddress | stringيقبل null | Saudi national short address. |
latituderecipient.latitude | number (double)يقبل null | Latitude. |
longituderecipient.longitude | number (double)يقبل null | Longitude. |
parcel | PublicParcelDto | Parcel data of a shipment. |
weightKgparcel.weightKg | number (double) | Actual weight. |
lengthCmparcel.lengthCm | number (double) | Length. |
widthCmparcel.widthCm | number (double) | Width. |
heightCmparcel.heightCm | number (double) | Height. |
chargeableWeightKgparcel.chargeableWeightKg | number (double) | Weight used for pricing: the larger of actual and volumetric weight. |
piecesparcel.pieces | integer (int32) | Number of pieces. |
descriptionparcel.description | stringيقبل null | What is inside. |
declaredValueparcel.declaredValue | number (double) | Declared value. |
fragileparcel.fragile | boolean | Fragile. |
requiresColdChainparcel.requiresColdChain | boolean | Needs cold chain. |
coldChainRangeparcel.coldChainRange | enum | Temperature range of cold-chain goods. القيم: |
flammableparcel.flammable | boolean | Flammable. |
hazardousparcel.hazardous | boolean | Hazardous. |
containsAlcoholparcel.containsAlcohol | boolean | Contains alcohol. |
liquidparcel.liquid | boolean | Liquid. |
highValueparcel.highValue | boolean | High value. |
delivery | PublicDeliveryOptionsDto | Handover rules. |
allowOpenPackagedelivery.allowOpenPackage | boolean | The recipient may open the package. |
requireSignaturedelivery.requireSignature | boolean | Signature required. |
requireIdVerificationdelivery.requireIdVerification | boolean | ID check required. |
allowNeighborDeliverydelivery.allowNeighborDelivery | boolean | Neighbour delivery allowed. |
payment | PublicPaymentDto | Payment data of a shipment. |
codAmountpayment.codAmount | number (double) | Cash to collect from the recipient. |
shippingFeepayment.shippingFee | number (double) | Shipping fee computed from the rate card. |
freightOnDeliverypayment.freightOnDelivery | boolean | True when the recipient pays the fee. |
pieces | array<PublicPieceDto>يقبل null | The pieces. |
barcodepieces[].barcode | stringيقبل null | Piece barcode (the tracking number followed by |
branch | PublicBranchRef | A branch reference. |
idbranch.id | string (uuid) | Branch id. |
namebranch.name | stringيقبل null | Branch name. |
canCancel | boolean | True while the shipment can still be cancelled. |
isEditable | boolean | True while the shipment can still be edited. |
{
"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
}| الحالة | الوصف |
|---|---|
400 | The request is invalid (code |
401 | Authentication is missing or invalid (code |
403 | Scope missing, or a merchant login named another merchant or a custom sender. |
404 | Merchant or branch not found ( |
409 | The Idempotency-Key was used with a different body ( |
422 | A business rule or a location could not be satisfied (codes such as |
429 | Too many requests (code |
تشترك أخطاء الواجهة في جسم واحد موصوف في مرجع الأخطاء. مرجع الأخطاء