GROperator

Shipments

Every operation of the LastMile Public API, generated from the OpenAPI document. The reference text is in English in both languages.

POST

/api/public/v1/shipments

#

Create a shipment

API key + secret, or bearer tokenRequired scope: shipments:writeSupports Idempotency-Key

Books 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.

Parameters

NameInTypeDescription
Idempotency-Keyheaderstring

Optional key (up to 128 characters, no spaces; X-Idempotency-Key is accepted too) that makes a retry safe. The same key with the same body within 24 hours returns the first response (header Idempotent-Replayed: true); the same key with a different body answers 409 idempotency_key_reused. Scoped to your company and credential.

Request body · PublicCreateShipmentRequestapplication/json

The shipment.

FieldTypeDescription
referencestringnullable

Your own order reference (shown on the label and searchable). Up to 100 characters.

Example: ORD-1001

serviceTypeenum

Kind of service requested for a shipment.

Values: deliveryexchangereturn

serviceTierenum

Speed of the service; it drives the estimated delivery date.

Values: standardexpresssameDay

senderPublicSenderInput

The sender of a shipment.

type
sender.type
enum

Who sends the shipment.

Values: merchantcustom

merchant
sender.merchant
stringnullable

For merchant: the merchant id, or the exact account name (compared ignoring case and Arabic letter variants).

Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

name
sender.name
stringnullable

For custom: sender name (required).

Example: Sara Ahmed

phone
sender.phone
stringnullable

For custom: sender phone (required).

Example: 0501234567

email
sender.email
stringnullable

For custom: sender email (optional).

Example: sara@example.com

pickupPublicPickupInput

The pickup address.

country
pickup.country
stringnullable

Country id, ISO code or name. Optional when the city name is unambiguous.

Example: SA

city
pickup.city
required
stringnullable

City id, code or name. Required.

Example: Riyadh

district
pickup.district
required
stringnullable

District id, code or name. Required. Unknown districts are never created: you get geo_district_not_found.

Example: Al Olaya

addressLine
pickup.addressLine
required
stringnullable

Street, building and landmark. Required, up to 500 characters.

Example: King Fahd Road, Building 12, Floor 3

shortAddress
pickup.shortAddress
conditional
stringnullable

Saudi national short address: 4 letters and 4 digits. Required when the city is in Saudi Arabia.

Example: RNBA6769

latitude
pickup.latitude
number (double)nullable

Latitude, -90 to 90 (optional).

Example: 24.7136

longitude
pickup.longitude
number (double)nullable

Longitude, -180 to 180 (optional).

Example: 46.6753

branch
pickup.branch
stringnullable

Branch that handles the pickup: branch id, code or name. Optional; by default the branch covering the pickup district is chosen automatically (branch_coverage.no_coverage_for_city when none covers it).

Example: RUH-01

recipientPublicRecipientInput

The recipient and the delivery address.

country
recipient.country
stringnullable

Country id, ISO code or name. Optional when the city name is unambiguous.

Example: SA

city
recipient.city
required
stringnullable

City id, code or name. Required.

Example: Riyadh

district
recipient.district
required
stringnullable

District id, code or name. Required. Unknown districts are never created: you get geo_district_not_found.

Example: Al Olaya

addressLine
recipient.addressLine
required
stringnullable

Street, building and landmark. Required, up to 500 characters.

Example: King Fahd Road, Building 12, Floor 3

shortAddress
recipient.shortAddress
conditional
stringnullable

Saudi national short address: 4 letters and 4 digits. Required when the city is in Saudi Arabia.

Example: RNBA6769

latitude
recipient.latitude
number (double)nullable

Latitude, -90 to 90 (optional).

Example: 24.7136

longitude
recipient.longitude
number (double)nullable

Longitude, -180 to 180 (optional).

Example: 46.6753

name
recipient.name
required
stringnullable

Recipient name. Required, up to 200 characters.

Example: Khaled Alotaibi

phone
recipient.phone
required
stringnullable

Recipient phone. Required; digits, spaces, +, - and brackets.

Example: 0555123456

secondaryPhone
recipient.secondaryPhone
stringnullable

Second phone (optional).

Example: 0555987654

parcelPublicParcelInput

The parcel. Weight and dimensions describe the whole shipment.

weightKg
parcel.weightKg
required
number (double)

Actual weight in kilograms, greater than 0.

Example: 1.5

lengthCm
parcel.lengthCm
required
number (double)

Length in centimetres, greater than 0.

Example: 20

widthCm
parcel.widthCm
required
number (double)

Width in centimetres, greater than 0.

Example: 15

heightCm
parcel.heightCm
required
number (double)

Height in centimetres, greater than 0.

Example: 10

pieces
parcel.pieces
integer (int32)nullable

Number of pieces (default 1).

Example: 1

description
parcel.description
stringnullable

What is inside (optional, shown on the label).

Example: Mobile phone case

declaredValue
parcel.declaredValue
number (double)nullable

Declared value of the goods (default 0).

Example: 250

fragile
parcel.fragile
boolean

Fragile goods.

Example: false

requiresColdChain
parcel.requiresColdChain
conditional
boolean

Needs cold chain; then coldChainRange is required.

Example: false

coldChainRange
parcel.coldChainRange
enum

Temperature range of cold-chain goods.

Values: frozenchilledambient

flammable
parcel.flammable
boolean

Flammable goods.

Example: false

hazardous
parcel.hazardous
boolean

Hazardous goods.

Example: false

containsAlcohol
parcel.containsAlcohol
boolean

Contains alcohol.

Example: false

liquid
parcel.liquid
boolean

Liquid goods.

Example: false

highValue
parcel.highValue
boolean

High-value goods.

Example: false

paymentPublicPaymentInput

Cash on delivery and freight payment.

codAmount
payment.codAmount
number (double)nullable

Amount the courier collects from the recipient (cash on delivery). Default 0. Must be 0 for return.

Example: 199.5

freightOnDelivery
payment.freightOnDelivery
booleannullable

True when the recipient pays the shipping fee on delivery.

Example: false

deliveryPublicDeliveryOptionsInput

Handover rules at the recipient's door. Omitted values use the system defaults shown.

allowOpenPackage
delivery.allowOpenPackage
booleannullable

The recipient may open the package before accepting. Default false.

Example: false

requireSignature
delivery.requireSignature
conditional
booleannullable

A signature is required on delivery. Default true.

Example: true

requireIdVerification
delivery.requireIdVerification
booleannullable

The courier must verify the recipient's ID. Default false.

Example: false

allowNeighborDelivery
delivery.allowNeighborDelivery
booleannullable

A neighbour may accept the parcel. Default true.

Example: true

The OpenAPI document does not mark required fields formally, so “required” is read from each field’s description. The guides list the required fields of every request.

Request example

POST /shipments
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
  }
}'

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

201The created shipment.

Responses · Field
FieldTypeDescription
trackingNumberstringnullable

Tracking number; identifies the shipment in every route.

referencestringnullable

Your order reference.

statusstringnullable

Status key, e.g. created, outForDelivery, delivered. See GET /shipments/statuses.

statusCodeinteger (int32)

Numeric status code.

statusLabelArstringnullable

Arabic status label.

statusLabelEnstringnullable

English status label.

isFinalboolean

True when the shipment reached a final status.

serviceTypeenum

Kind of service requested for a shipment.

Values: deliveryexchangereturn

serviceTierenum

Speed of the service; it drives the estimated delivery date.

Values: standardexpresssameDay

sourceenum

How the order reached the system.

Values: dashboardexcelImportmerchantPortalapiintegrationinviteLinkpublicWebsitephonewhatsAppsocialMediawalkInother

createdAtstring (date-time)

Creation time (UTC).

estimatedDeliveryDatestring (date)nullable

Estimated delivery date (yyyy-MM-dd), when known.

senderPublicSenderDto

The sender of a shipment.

type
sender.type
enum

Who sends the shipment.

Values: merchantcustom

name
sender.name
stringnullable

Sender name.

phone
sender.phone
stringnullable

Sender phone.

email
sender.email
stringnullable

Sender email.

merchant
sender.merchant
PublicMerchantRef

A merchant reference.

id
sender.merchant.id
string (uuid)

Merchant id.

name
sender.merchant.name
stringnullable

Merchant account name.

pickupPublicAddressDto

A resolved address.

country
pickup.country
PublicNamedRef

A catalog entry shown in both languages.

id
pickup.country.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
pickup.country.nameAr
stringnullable

Arabic name.

nameEn
pickup.country.nameEn
stringnullable

English name.

city
pickup.city
PublicNamedRef

A catalog entry shown in both languages.

id
pickup.city.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
pickup.city.nameAr
stringnullable

Arabic name.

nameEn
pickup.city.nameEn
stringnullable

English name.

district
pickup.district
PublicNamedRef

A catalog entry shown in both languages.

id
pickup.district.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
pickup.district.nameAr
stringnullable

Arabic name.

nameEn
pickup.district.nameEn
stringnullable

English name.

addressLine
pickup.addressLine
stringnullable

Street, building and landmark.

shortAddress
pickup.shortAddress
stringnullable

Saudi national short address.

latitude
pickup.latitude
number (double)nullable

Latitude.

longitude
pickup.longitude
number (double)nullable

Longitude.

recipientPublicRecipientDto

The recipient.

name
recipient.name
stringnullable

Recipient name.

phone
recipient.phone
stringnullable

Recipient phone.

secondaryPhone
recipient.secondaryPhone
stringnullable

Second phone.

country
recipient.country
PublicNamedRef

A catalog entry shown in both languages.

id
recipient.country.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
recipient.country.nameAr
stringnullable

Arabic name.

nameEn
recipient.country.nameEn
stringnullable

English name.

city
recipient.city
PublicNamedRef

A catalog entry shown in both languages.

id
recipient.city.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
recipient.city.nameAr
stringnullable

Arabic name.

nameEn
recipient.city.nameEn
stringnullable

English name.

district
recipient.district
PublicNamedRef

A catalog entry shown in both languages.

id
recipient.district.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
recipient.district.nameAr
stringnullable

Arabic name.

nameEn
recipient.district.nameEn
stringnullable

English name.

addressLine
recipient.addressLine
stringnullable

Street, building and landmark.

shortAddress
recipient.shortAddress
stringnullable

Saudi national short address.

latitude
recipient.latitude
number (double)nullable

Latitude.

longitude
recipient.longitude
number (double)nullable

Longitude.

parcelPublicParcelDto

Parcel data of a shipment.

weightKg
parcel.weightKg
number (double)

Actual weight.

lengthCm
parcel.lengthCm
number (double)

Length.

widthCm
parcel.widthCm
number (double)

Width.

heightCm
parcel.heightCm
number (double)

Height.

chargeableWeightKg
parcel.chargeableWeightKg
number (double)

Weight used for pricing: the larger of actual and volumetric weight.

pieces
parcel.pieces
integer (int32)

Number of pieces.

description
parcel.description
stringnullable

What is inside.

declaredValue
parcel.declaredValue
number (double)

Declared value.

fragile
parcel.fragile
boolean

Fragile.

requiresColdChain
parcel.requiresColdChain
boolean

Needs cold chain.

coldChainRange
parcel.coldChainRange
enum

Temperature range of cold-chain goods.

Values: frozenchilledambient

flammable
parcel.flammable
boolean

Flammable.

hazardous
parcel.hazardous
boolean

Hazardous.

containsAlcohol
parcel.containsAlcohol
boolean

Contains alcohol.

liquid
parcel.liquid
boolean

Liquid.

highValue
parcel.highValue
boolean

High value.

deliveryPublicDeliveryOptionsDto

Handover rules.

allowOpenPackage
delivery.allowOpenPackage
boolean

The recipient may open the package.

requireSignature
delivery.requireSignature
boolean

Signature required.

requireIdVerification
delivery.requireIdVerification
boolean

ID check required.

allowNeighborDelivery
delivery.allowNeighborDelivery
boolean

Neighbour delivery allowed.

paymentPublicPaymentDto

Payment data of a shipment.

codAmount
payment.codAmount
number (double)

Cash to collect from the recipient.

shippingFee
payment.shippingFee
number (double)

Shipping fee computed from the rate card.

freightOnDelivery
payment.freightOnDelivery
boolean

True when the recipient pays the fee.

piecesarray<PublicPieceDto>nullable

The pieces.

barcode
pieces[].barcode
stringnullable

Piece barcode (the tracking number followed by -P1, -P2...).

branchPublicBranchRef

A branch reference.

id
branch.id
string (uuid)

Branch id.

name
branch.name
stringnullable

Branch name.

canCancelboolean

True while the shipment can still be cancelled.

isEditableboolean

True while the shipment can still be edited.

201 · Example response
{
  "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
}
StatusDescription
400

The request is invalid (code validation_failed, details.errors lists every field).

401

Authentication is missing or invalid (code unauthorized).

403

Scope missing, or a merchant login named another merchant or a custom sender.

404

Merchant or branch not found (merchant.not_found, branch.not_found).

409

The Idempotency-Key was used with a different body (idempotency_key_reused).

422

A business rule or a location could not be satisfied (codes such as geo_city_not_found, shipment.cannot_cancel).

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

GET

/api/public/v1/shipments

#

List shipments

API key + secret, or bearer tokenRequired scope: shipments:read

Newest first, paginated. All filters are optional and combine with AND. city filters by destination city (id, code or name; an unknown city answers 422 geo_city_not_found). search matches the tracking number, reference, recipient name and phone, and sender name.

Parameters

NameInTypeDescription
pagequeryinteger (int32)
Default: 1

Page number, starting at 1.

pageSizequeryinteger (int32)
Default: 25

Items per page, 1 to 100 (larger values are clamped to 100).

statusquerystring

One status or several separated by commas, as keys (delivered,outForDelivery) or numeric codes. See GET /shipments/statuses.

merchantquerystring

Merchant id or exact account name.

referencequerystring

Your order reference (exact match, ignoring case).

trackingNumberquerystring

Exact tracking number.

recipientPhonequerystring

Part of the recipient's phone.

cityquerystring

Destination city: id, code or name.

createdFromquerystring (date-time)

Created at or after this instant (ISO 8601, e.g. 2026-01-01T00:00:00Z).

createdToquerystring (date-time)

Created at or before this instant (ISO 8601).

searchquerystring

Free text.

Request example

GET /shipments
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'

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200A page of shipments.

Responses · Field
FieldTypeDescription
itemsarray<PublicShipmentSummaryDto>nullable

Items of the requested page.

trackingNumber
items[].trackingNumber
stringnullable

Tracking number.

reference
items[].reference
stringnullable

Your order reference.

status
items[].status
stringnullable

Status key.

statusLabelAr
items[].statusLabelAr
stringnullable

Arabic status label.

statusLabelEn
items[].statusLabelEn
stringnullable

English status label.

merchant
items[].merchant
PublicMerchantRef

A merchant reference.

id
items[].merchant.id
string (uuid)

Merchant id.

name
items[].merchant.name
stringnullable

Merchant account name.

senderName
items[].senderName
stringnullable

Sender name.

recipientName
items[].recipientName
stringnullable

Recipient name.

recipientPhone
items[].recipientPhone
stringnullable

Recipient phone.

city
items[].city
PublicNamedRef

A catalog entry shown in both languages.

id
items[].city.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
items[].city.nameAr
stringnullable

Arabic name.

nameEn
items[].city.nameEn
stringnullable

English name.

district
items[].district
PublicNamedRef

A catalog entry shown in both languages.

id
items[].district.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
items[].district.nameAr
stringnullable

Arabic name.

nameEn
items[].district.nameEn
stringnullable

English name.

codAmount
items[].codAmount
number (double)

Cash on delivery amount.

shippingFee
items[].shippingFee
number (double)

Shipping fee.

createdAt
items[].createdAt
string (date-time)

Creation time (UTC).

estimatedDeliveryDate
items[].estimatedDeliveryDate
string (date)nullable

Estimated delivery date.

pageinteger (int32)

Current page number, starting at 1.

pageSizeinteger (int32)

Requested page size (1 to 100, default 25).

totalCountinteger (int32)

Total number of items across all pages.

totalPagesinteger (int32)

Total number of pages.

200 · Example response
{
  "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
}
StatusDescription
400

The request is invalid (code validation_failed, details.errors lists every field).

401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

GET

/api/public/v1/shipments/statuses

#

List shipment statuses

API key + secret, or bearer tokenRequired scope: shipments:read

The catalog of statuses with their keys, codes, Arabic and English names and whether they are final. Use key to map statuses in your system; status of a shipment is one of these keys.

Request example

GET /shipments/statuses
curl "https://api.goldrock.live/api/public/v1/shipments/statuses" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET"

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200All statuses in code order.

Responses · Field
FieldTypeDescription
codeinteger (int32)

Numeric status code.

keystringnullable

Status key used in the API.

nameArstringnullable

Arabic name.

nameEnstringnullable

English name.

isFinalboolean

True when no further status follows (delivered, returned to sender, cancelled, lost, disposed).

200 · Example response
[
  {
    "code": 1,
    "isFinal": false
  }
]
StatusDescription
401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

GET

/api/public/v1/shipments/{trackingNumber}

#

Get a shipment

API key + secret, or bearer tokenRequired scope: shipments:read

Required scope (API key) or equivalent permission (password): shipments:read.

Parameters

NameInTypeDescription
trackingNumber
required
pathstring

Tracking number.

Request example

GET /shipments/AWB-RUH-000123
curl "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"

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200The shipment.

Responses · Field
FieldTypeDescription
trackingNumberstringnullable

Tracking number; identifies the shipment in every route.

referencestringnullable

Your order reference.

statusstringnullable

Status key, e.g. created, outForDelivery, delivered. See GET /shipments/statuses.

statusCodeinteger (int32)

Numeric status code.

statusLabelArstringnullable

Arabic status label.

statusLabelEnstringnullable

English status label.

isFinalboolean

True when the shipment reached a final status.

serviceTypeenum

Kind of service requested for a shipment.

Values: deliveryexchangereturn

serviceTierenum

Speed of the service; it drives the estimated delivery date.

Values: standardexpresssameDay

sourceenum

How the order reached the system.

Values: dashboardexcelImportmerchantPortalapiintegrationinviteLinkpublicWebsitephonewhatsAppsocialMediawalkInother

createdAtstring (date-time)

Creation time (UTC).

estimatedDeliveryDatestring (date)nullable

Estimated delivery date (yyyy-MM-dd), when known.

senderPublicSenderDto

The sender of a shipment.

type
sender.type
enum

Who sends the shipment.

Values: merchantcustom

name
sender.name
stringnullable

Sender name.

phone
sender.phone
stringnullable

Sender phone.

email
sender.email
stringnullable

Sender email.

merchant
sender.merchant
PublicMerchantRef

A merchant reference.

id
sender.merchant.id
string (uuid)

Merchant id.

name
sender.merchant.name
stringnullable

Merchant account name.

pickupPublicAddressDto

A resolved address.

country
pickup.country
PublicNamedRef

A catalog entry shown in both languages.

id
pickup.country.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
pickup.country.nameAr
stringnullable

Arabic name.

nameEn
pickup.country.nameEn
stringnullable

English name.

city
pickup.city
PublicNamedRef

A catalog entry shown in both languages.

id
pickup.city.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
pickup.city.nameAr
stringnullable

Arabic name.

nameEn
pickup.city.nameEn
stringnullable

English name.

district
pickup.district
PublicNamedRef

A catalog entry shown in both languages.

id
pickup.district.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
pickup.district.nameAr
stringnullable

Arabic name.

nameEn
pickup.district.nameEn
stringnullable

English name.

addressLine
pickup.addressLine
stringnullable

Street, building and landmark.

shortAddress
pickup.shortAddress
stringnullable

Saudi national short address.

latitude
pickup.latitude
number (double)nullable

Latitude.

longitude
pickup.longitude
number (double)nullable

Longitude.

recipientPublicRecipientDto

The recipient.

name
recipient.name
stringnullable

Recipient name.

phone
recipient.phone
stringnullable

Recipient phone.

secondaryPhone
recipient.secondaryPhone
stringnullable

Second phone.

country
recipient.country
PublicNamedRef

A catalog entry shown in both languages.

id
recipient.country.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
recipient.country.nameAr
stringnullable

Arabic name.

nameEn
recipient.country.nameEn
stringnullable

English name.

city
recipient.city
PublicNamedRef

A catalog entry shown in both languages.

id
recipient.city.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
recipient.city.nameAr
stringnullable

Arabic name.

nameEn
recipient.city.nameEn
stringnullable

English name.

district
recipient.district
PublicNamedRef

A catalog entry shown in both languages.

id
recipient.district.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
recipient.district.nameAr
stringnullable

Arabic name.

nameEn
recipient.district.nameEn
stringnullable

English name.

addressLine
recipient.addressLine
stringnullable

Street, building and landmark.

shortAddress
recipient.shortAddress
stringnullable

Saudi national short address.

latitude
recipient.latitude
number (double)nullable

Latitude.

longitude
recipient.longitude
number (double)nullable

Longitude.

parcelPublicParcelDto

Parcel data of a shipment.

weightKg
parcel.weightKg
number (double)

Actual weight.

lengthCm
parcel.lengthCm
number (double)

Length.

widthCm
parcel.widthCm
number (double)

Width.

heightCm
parcel.heightCm
number (double)

Height.

chargeableWeightKg
parcel.chargeableWeightKg
number (double)

Weight used for pricing: the larger of actual and volumetric weight.

pieces
parcel.pieces
integer (int32)

Number of pieces.

description
parcel.description
stringnullable

What is inside.

declaredValue
parcel.declaredValue
number (double)

Declared value.

fragile
parcel.fragile
boolean

Fragile.

requiresColdChain
parcel.requiresColdChain
boolean

Needs cold chain.

coldChainRange
parcel.coldChainRange
enum

Temperature range of cold-chain goods.

Values: frozenchilledambient

flammable
parcel.flammable
boolean

Flammable.

hazardous
parcel.hazardous
boolean

Hazardous.

containsAlcohol
parcel.containsAlcohol
boolean

Contains alcohol.

liquid
parcel.liquid
boolean

Liquid.

highValue
parcel.highValue
boolean

High value.

deliveryPublicDeliveryOptionsDto

Handover rules.

allowOpenPackage
delivery.allowOpenPackage
boolean

The recipient may open the package.

requireSignature
delivery.requireSignature
boolean

Signature required.

requireIdVerification
delivery.requireIdVerification
boolean

ID check required.

allowNeighborDelivery
delivery.allowNeighborDelivery
boolean

Neighbour delivery allowed.

paymentPublicPaymentDto

Payment data of a shipment.

codAmount
payment.codAmount
number (double)

Cash to collect from the recipient.

shippingFee
payment.shippingFee
number (double)

Shipping fee computed from the rate card.

freightOnDelivery
payment.freightOnDelivery
boolean

True when the recipient pays the fee.

piecesarray<PublicPieceDto>nullable

The pieces.

barcode
pieces[].barcode
stringnullable

Piece barcode (the tracking number followed by -P1, -P2...).

branchPublicBranchRef

A branch reference.

id
branch.id
string (uuid)

Branch id.

name
branch.name
stringnullable

Branch name.

canCancelboolean

True while the shipment can still be cancelled.

isEditableboolean

True while the shipment can still be edited.

200 · Example response
{
  "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
}
StatusDescription
401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

404

Code shipment.not_found (also when the shipment belongs to someone else).

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

PUT

/api/public/v1/shipments/{trackingNumber}

#

Update a shipment

API key + secret, or bearer tokenRequired scope: shipments:write

Changes the recipient (name, phones, address by names, coordinates), the order reference, COD amount, who pays the freight and the parcel (weight, dimensions, pieces, declared value). Only the fields you send change. The fee is recalculated when something that affects it changes. reason is required and goes to the shipment's audit trail. Allowed until the shipment reaches a final status; once it is out for delivery only contact details, address and COD can change (shipment.field_locked_out_for_delivery). Not editable through the API: sender, pickup address, service type and tier, handling flags. Merchant logins cannot edit shipments.

Parameters

NameInTypeDescription
trackingNumber
required
pathstring

Tracking number.

Request body · PublicUpdateShipmentRequestapplication/json

The changes.

FieldTypeDescription
reason
required
stringnullable

Why the shipment is edited (kept in the shipment's audit trail). Required, up to 300 characters.

Example: Customer changed the delivery address

referencestringnullable

New order reference.

Example: ORD-1001-B

recipientPublicUpdateRecipientInput

Recipient fields that can change. Sending any address field re-resolves the whole address (city and district are then required).

country
recipient.country
stringnullable

Country id, ISO code or name. Optional when the city name is unambiguous.

Example: SA

city
recipient.city
conditional
stringnullable

City id, code or name. Required.

Example: Riyadh

district
recipient.district
conditional
stringnullable

District id, code or name. Required. Unknown districts are never created: you get geo_district_not_found.

Example: Al Olaya

addressLine
recipient.addressLine
conditional
stringnullable

Street, building and landmark. Required, up to 500 characters.

Example: King Fahd Road, Building 12, Floor 3

shortAddress
recipient.shortAddress
conditional
stringnullable

Saudi national short address: 4 letters and 4 digits. Required when the city is in Saudi Arabia.

Example: RNBA6769

latitude
recipient.latitude
number (double)nullable

Latitude, -90 to 90 (optional).

Example: 24.7136

longitude
recipient.longitude
number (double)nullable

Longitude, -180 to 180 (optional).

Example: 46.6753

name
recipient.name
stringnullable

Recipient name.

Example: Khaled Alotaibi

phone
recipient.phone
stringnullable

Recipient phone.

Example: 0555123456

secondaryPhone
recipient.secondaryPhone
stringnullable

Second phone.

Example: 0555987654

parcelPublicUpdateParcelInput

Parcel fields that can change. Only the fields you send are changed.

weightKg
parcel.weightKg
number (double)nullable

Weight in kilograms.

Example: 2

lengthCm
parcel.lengthCm
number (double)nullable

Length in centimetres.

Example: 20

widthCm
parcel.widthCm
number (double)nullable

Width in centimetres.

Example: 15

heightCm
parcel.heightCm
number (double)nullable

Height in centimetres.

Example: 10

pieces
parcel.pieces
integer (int32)nullable

Number of pieces.

Example: 1

declaredValue
parcel.declaredValue
number (double)nullable

Declared value of the goods.

Example: 300

paymentPublicPaymentInput

Cash on delivery and freight payment.

codAmount
payment.codAmount
number (double)nullable

Amount the courier collects from the recipient (cash on delivery). Default 0. Must be 0 for return.

Example: 199.5

freightOnDelivery
payment.freightOnDelivery
booleannullable

True when the recipient pays the shipping fee on delivery.

Example: false

The OpenAPI document does not mark required fields formally, so “required” is read from each field’s description. The guides list the required fields of every request.

Request example

PUT /shipments/AWB-RUH-000123
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
  }
}'

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200The updated shipment.

Responses · Field
FieldTypeDescription
trackingNumberstringnullable

Tracking number; identifies the shipment in every route.

referencestringnullable

Your order reference.

statusstringnullable

Status key, e.g. created, outForDelivery, delivered. See GET /shipments/statuses.

statusCodeinteger (int32)

Numeric status code.

statusLabelArstringnullable

Arabic status label.

statusLabelEnstringnullable

English status label.

isFinalboolean

True when the shipment reached a final status.

serviceTypeenum

Kind of service requested for a shipment.

Values: deliveryexchangereturn

serviceTierenum

Speed of the service; it drives the estimated delivery date.

Values: standardexpresssameDay

sourceenum

How the order reached the system.

Values: dashboardexcelImportmerchantPortalapiintegrationinviteLinkpublicWebsitephonewhatsAppsocialMediawalkInother

createdAtstring (date-time)

Creation time (UTC).

estimatedDeliveryDatestring (date)nullable

Estimated delivery date (yyyy-MM-dd), when known.

senderPublicSenderDto

The sender of a shipment.

type
sender.type
enum

Who sends the shipment.

Values: merchantcustom

name
sender.name
stringnullable

Sender name.

phone
sender.phone
stringnullable

Sender phone.

email
sender.email
stringnullable

Sender email.

merchant
sender.merchant
PublicMerchantRef

A merchant reference.

id
sender.merchant.id
string (uuid)

Merchant id.

name
sender.merchant.name
stringnullable

Merchant account name.

pickupPublicAddressDto

A resolved address.

country
pickup.country
PublicNamedRef

A catalog entry shown in both languages.

id
pickup.country.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
pickup.country.nameAr
stringnullable

Arabic name.

nameEn
pickup.country.nameEn
stringnullable

English name.

city
pickup.city
PublicNamedRef

A catalog entry shown in both languages.

id
pickup.city.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
pickup.city.nameAr
stringnullable

Arabic name.

nameEn
pickup.city.nameEn
stringnullable

English name.

district
pickup.district
PublicNamedRef

A catalog entry shown in both languages.

id
pickup.district.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
pickup.district.nameAr
stringnullable

Arabic name.

nameEn
pickup.district.nameEn
stringnullable

English name.

addressLine
pickup.addressLine
stringnullable

Street, building and landmark.

shortAddress
pickup.shortAddress
stringnullable

Saudi national short address.

latitude
pickup.latitude
number (double)nullable

Latitude.

longitude
pickup.longitude
number (double)nullable

Longitude.

recipientPublicRecipientDto

The recipient.

name
recipient.name
stringnullable

Recipient name.

phone
recipient.phone
stringnullable

Recipient phone.

secondaryPhone
recipient.secondaryPhone
stringnullable

Second phone.

country
recipient.country
PublicNamedRef

A catalog entry shown in both languages.

id
recipient.country.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
recipient.country.nameAr
stringnullable

Arabic name.

nameEn
recipient.country.nameEn
stringnullable

English name.

city
recipient.city
PublicNamedRef

A catalog entry shown in both languages.

id
recipient.city.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
recipient.city.nameAr
stringnullable

Arabic name.

nameEn
recipient.city.nameEn
stringnullable

English name.

district
recipient.district
PublicNamedRef

A catalog entry shown in both languages.

id
recipient.district.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
recipient.district.nameAr
stringnullable

Arabic name.

nameEn
recipient.district.nameEn
stringnullable

English name.

addressLine
recipient.addressLine
stringnullable

Street, building and landmark.

shortAddress
recipient.shortAddress
stringnullable

Saudi national short address.

latitude
recipient.latitude
number (double)nullable

Latitude.

longitude
recipient.longitude
number (double)nullable

Longitude.

parcelPublicParcelDto

Parcel data of a shipment.

weightKg
parcel.weightKg
number (double)

Actual weight.

lengthCm
parcel.lengthCm
number (double)

Length.

widthCm
parcel.widthCm
number (double)

Width.

heightCm
parcel.heightCm
number (double)

Height.

chargeableWeightKg
parcel.chargeableWeightKg
number (double)

Weight used for pricing: the larger of actual and volumetric weight.

pieces
parcel.pieces
integer (int32)

Number of pieces.

description
parcel.description
stringnullable

What is inside.

declaredValue
parcel.declaredValue
number (double)

Declared value.

fragile
parcel.fragile
boolean

Fragile.

requiresColdChain
parcel.requiresColdChain
boolean

Needs cold chain.

coldChainRange
parcel.coldChainRange
enum

Temperature range of cold-chain goods.

Values: frozenchilledambient

flammable
parcel.flammable
boolean

Flammable.

hazardous
parcel.hazardous
boolean

Hazardous.

containsAlcohol
parcel.containsAlcohol
boolean

Contains alcohol.

liquid
parcel.liquid
boolean

Liquid.

highValue
parcel.highValue
boolean

High value.

deliveryPublicDeliveryOptionsDto

Handover rules.

allowOpenPackage
delivery.allowOpenPackage
boolean

The recipient may open the package.

requireSignature
delivery.requireSignature
boolean

Signature required.

requireIdVerification
delivery.requireIdVerification
boolean

ID check required.

allowNeighborDelivery
delivery.allowNeighborDelivery
boolean

Neighbour delivery allowed.

paymentPublicPaymentDto

Payment data of a shipment.

codAmount
payment.codAmount
number (double)

Cash to collect from the recipient.

shippingFee
payment.shippingFee
number (double)

Shipping fee computed from the rate card.

freightOnDelivery
payment.freightOnDelivery
boolean

True when the recipient pays the fee.

piecesarray<PublicPieceDto>nullable

The pieces.

barcode
pieces[].barcode
stringnullable

Piece barcode (the tracking number followed by -P1, -P2...).

branchPublicBranchRef

A branch reference.

id
branch.id
string (uuid)

Branch id.

name
branch.name
stringnullable

Branch name.

canCancelboolean

True while the shipment can still be cancelled.

isEditableboolean

True while the shipment can still be edited.

200 · Example response
{
  "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
}
StatusDescription
400

The request is invalid (code validation_failed, details.errors lists every field).

401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

404

Code shipment.not_found.

422

Not editable in this state, no change, or an unresolved location.

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

POST

/api/public/v1/shipments/{trackingNumber}/cancel

#

Cancel a shipment

API key + secret, or bearer tokenRequired scope: shipments:write

Possible while the shipment is a draft, created or scheduled for pickup; later it answers 422 shipment.cannot_cancel. A pending return created with an exchange is cancelled with it. Merchant logins cannot cancel through the API.

Parameters

NameInTypeDescription
trackingNumber
required
pathstring

Tracking number.

Request body · PublicCancelShipmentRequestapplication/json

The reason.

FieldTypeDescription
reasonstringnullable

Why the shipment is cancelled (kept in the shipment history). Up to 500 characters.

Example: Customer cancelled the order

The OpenAPI document does not mark required fields formally, so “required” is read from each field’s description. The guides list the required fields of every request.

Request example

POST /shipments/AWB-RUH-000123/cancel
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"
}'

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200The cancelled shipment.

Responses · Field
FieldTypeDescription
trackingNumberstringnullable

Tracking number; identifies the shipment in every route.

referencestringnullable

Your order reference.

statusstringnullable

Status key, e.g. created, outForDelivery, delivered. See GET /shipments/statuses.

statusCodeinteger (int32)

Numeric status code.

statusLabelArstringnullable

Arabic status label.

statusLabelEnstringnullable

English status label.

isFinalboolean

True when the shipment reached a final status.

serviceTypeenum

Kind of service requested for a shipment.

Values: deliveryexchangereturn

serviceTierenum

Speed of the service; it drives the estimated delivery date.

Values: standardexpresssameDay

sourceenum

How the order reached the system.

Values: dashboardexcelImportmerchantPortalapiintegrationinviteLinkpublicWebsitephonewhatsAppsocialMediawalkInother

createdAtstring (date-time)

Creation time (UTC).

estimatedDeliveryDatestring (date)nullable

Estimated delivery date (yyyy-MM-dd), when known.

senderPublicSenderDto

The sender of a shipment.

type
sender.type
enum

Who sends the shipment.

Values: merchantcustom

name
sender.name
stringnullable

Sender name.

phone
sender.phone
stringnullable

Sender phone.

email
sender.email
stringnullable

Sender email.

merchant
sender.merchant
PublicMerchantRef

A merchant reference.

id
sender.merchant.id
string (uuid)

Merchant id.

name
sender.merchant.name
stringnullable

Merchant account name.

pickupPublicAddressDto

A resolved address.

country
pickup.country
PublicNamedRef

A catalog entry shown in both languages.

id
pickup.country.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
pickup.country.nameAr
stringnullable

Arabic name.

nameEn
pickup.country.nameEn
stringnullable

English name.

city
pickup.city
PublicNamedRef

A catalog entry shown in both languages.

id
pickup.city.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
pickup.city.nameAr
stringnullable

Arabic name.

nameEn
pickup.city.nameEn
stringnullable

English name.

district
pickup.district
PublicNamedRef

A catalog entry shown in both languages.

id
pickup.district.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
pickup.district.nameAr
stringnullable

Arabic name.

nameEn
pickup.district.nameEn
stringnullable

English name.

addressLine
pickup.addressLine
stringnullable

Street, building and landmark.

shortAddress
pickup.shortAddress
stringnullable

Saudi national short address.

latitude
pickup.latitude
number (double)nullable

Latitude.

longitude
pickup.longitude
number (double)nullable

Longitude.

recipientPublicRecipientDto

The recipient.

name
recipient.name
stringnullable

Recipient name.

phone
recipient.phone
stringnullable

Recipient phone.

secondaryPhone
recipient.secondaryPhone
stringnullable

Second phone.

country
recipient.country
PublicNamedRef

A catalog entry shown in both languages.

id
recipient.country.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
recipient.country.nameAr
stringnullable

Arabic name.

nameEn
recipient.country.nameEn
stringnullable

English name.

city
recipient.city
PublicNamedRef

A catalog entry shown in both languages.

id
recipient.city.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
recipient.city.nameAr
stringnullable

Arabic name.

nameEn
recipient.city.nameEn
stringnullable

English name.

district
recipient.district
PublicNamedRef

A catalog entry shown in both languages.

id
recipient.district.id
string (uuid)nullable

Catalog id, or null for legacy shipments that only stored a name.

nameAr
recipient.district.nameAr
stringnullable

Arabic name.

nameEn
recipient.district.nameEn
stringnullable

English name.

addressLine
recipient.addressLine
stringnullable

Street, building and landmark.

shortAddress
recipient.shortAddress
stringnullable

Saudi national short address.

latitude
recipient.latitude
number (double)nullable

Latitude.

longitude
recipient.longitude
number (double)nullable

Longitude.

parcelPublicParcelDto

Parcel data of a shipment.

weightKg
parcel.weightKg
number (double)

Actual weight.

lengthCm
parcel.lengthCm
number (double)

Length.

widthCm
parcel.widthCm
number (double)

Width.

heightCm
parcel.heightCm
number (double)

Height.

chargeableWeightKg
parcel.chargeableWeightKg
number (double)

Weight used for pricing: the larger of actual and volumetric weight.

pieces
parcel.pieces
integer (int32)

Number of pieces.

description
parcel.description
stringnullable

What is inside.

declaredValue
parcel.declaredValue
number (double)

Declared value.

fragile
parcel.fragile
boolean

Fragile.

requiresColdChain
parcel.requiresColdChain
boolean

Needs cold chain.

coldChainRange
parcel.coldChainRange
enum

Temperature range of cold-chain goods.

Values: frozenchilledambient

flammable
parcel.flammable
boolean

Flammable.

hazardous
parcel.hazardous
boolean

Hazardous.

containsAlcohol
parcel.containsAlcohol
boolean

Contains alcohol.

liquid
parcel.liquid
boolean

Liquid.

highValue
parcel.highValue
boolean

High value.

deliveryPublicDeliveryOptionsDto

Handover rules.

allowOpenPackage
delivery.allowOpenPackage
boolean

The recipient may open the package.

requireSignature
delivery.requireSignature
boolean

Signature required.

requireIdVerification
delivery.requireIdVerification
boolean

ID check required.

allowNeighborDelivery
delivery.allowNeighborDelivery
boolean

Neighbour delivery allowed.

paymentPublicPaymentDto

Payment data of a shipment.

codAmount
payment.codAmount
number (double)

Cash to collect from the recipient.

shippingFee
payment.shippingFee
number (double)

Shipping fee computed from the rate card.

freightOnDelivery
payment.freightOnDelivery
boolean

True when the recipient pays the fee.

piecesarray<PublicPieceDto>nullable

The pieces.

barcode
pieces[].barcode
stringnullable

Piece barcode (the tracking number followed by -P1, -P2...).

branchPublicBranchRef

A branch reference.

id
branch.id
string (uuid)

Branch id.

name
branch.name
stringnullable

Branch name.

canCancelboolean

True while the shipment can still be cancelled.

isEditableboolean

True while the shipment can still be edited.

200 · Example response
{
  "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
}
StatusDescription
400

The request is invalid (code validation_failed, details.errors lists every field).

401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

404

Code shipment.not_found.

422

Code shipment.cannot_cancel or another state-machine code.

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

GET

/api/public/v1/shipments/{trackingNumber}/label

#

Print the shipping label

API key + secret, or bearer tokenRequired scope: shipments:read

The label (air waybill, 100x150 mm) as a PDF, with the company's branding.

Parameters

NameInTypeDescription
trackingNumber
required
pathstring

Tracking number.

Request example

GET /shipments/AWB-RUH-000123/label
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.pdf

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200The PDF file.Binary file (PDF)

StatusDescription
401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

404

Code shipment.not_found.

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

GET

/api/public/v1/shipments/{trackingNumber}/tracking

#

Track a shipment

API key + secret, or bearer tokenRequired scope: shipments:read

The status timeline (oldest first) with Arabic and English labels, the current status and the estimated delivery date. It carries no internal user names; note is present only for failed attempts, postponements, cancellation, returns, loss and damage.

Parameters

NameInTypeDescription
trackingNumber
required
pathstring

Tracking number.

Request example

GET /shipments/AWB-RUH-000123/tracking
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"

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200The tracking timeline.

Responses · Field
FieldTypeDescription
trackingNumberstringnullable

Tracking number.

statusstringnullable

Current status key.

statusLabelArstringnullable

Arabic label of the current status.

statusLabelEnstringnullable

English label of the current status.

estimatedDeliveryDatestring (date)nullable

Estimated delivery date.

eventsarray<PublicTrackingEventDto>nullable

Timeline, oldest first.

status
events[].status
stringnullable

Status key.

statusLabelAr
events[].statusLabelAr
stringnullable

Arabic label.

statusLabelEn
events[].statusLabelEn
stringnullable

English label.

at
events[].at
string (date-time)

When the status was set (UTC).

note
events[].note
stringnullable

Reason, only for failed attempts, postponements, cancellation, returns, loss and damage.

location
events[].location
stringnullable

Reserved; not populated yet.

200 · Example response
{
  "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
    }
  ]
}
StatusDescription
401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

404

Code shipment.not_found.

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference