GROperator

Schemas

Every data type used in requests and responses. Each name is a link target, so a field type in the operation pages jumps here.

PublicAddressDtoObject#

A resolved address.

FieldTypeDescription
countryPublicNamedRef

A catalog entry shown in both languages.

cityPublicNamedRef

A catalog entry shown in both languages.

districtPublicNamedRef

A catalog entry shown in both languages.

addressLine
required
string

Street, building and landmark.

shortAddressstringnullable

Saudi national short address.

latitudenumber (double)nullable

Latitude.

longitudenumber (double)nullable

Longitude.

PublicApiErrorObject#

Error envelope returned for every non-2xx response of the public API (/api/public/v1).

FieldTypeDescription
code
required
string

Stable machine-readable code, e.g. shipment.not_found or validation_failed.

message
required
string

Human readable message. Arabic by default; English when Accept-Language prefers English.

status
required
integer (int32)

HTTP status code, repeated in the body.

detailsobjectnullable

Extra data: errors (field to messages) for validation_failed; level, input and candidates for geo errors; messageAr when the message is English.

traceId
required
string

Correlation id of the request, quote it when contacting support.

PublicApiKeyDtoObject#

The API key behind a key-authenticated call.

FieldTypeDescription
id
required
string (uuid)

API key id.

namestringnullable

Label given to the key.

PublicBranchDtoObject#

Public-safe view of a branch (no manager, capacity, counters or other internal fields).

FieldTypeDescription
id
required
string (uuid)

Branch id.

name
required
string

Branch name.

code
required
string

Branch code.

city
required
string

City name as entered on the branch.

phonestringnullable

Branch phone, when set.

latitudenumber (double)nullable

Latitude, when set.

longitudenumber (double)nullable

Longitude, when set.

isActive
required
boolean

Whether the branch is active.

PublicBranchDtoPublicPageObject#

Standard paged response of every public list endpoint.

FieldTypeDescription
items
required
array<PublicBranchDto>

Items of the requested page.

page
required
integer (int32)

Current page number, starting at 1.

pageSize
required
integer (int32)

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

totalCount
required
integer (int32)

Total number of items across all pages.

totalPages
required
integer (int32)

Total number of pages.

PublicBranchRefObject#

A branch reference.

FieldTypeDescription
id
required
string (uuid)

Branch id.

name
required
string

Branch name.

PublicCancelShipmentRequestObject#

Body of POST /shipments/{trackingNumber}/cancel.

FieldTypeDescription
reason
required
string

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

Example: Customer cancelled the order

PublicCityCoverageDtoObject#

Whether the company delivers to / picks up from a city.

FieldTypeDescription
city
required
PublicGeoNodeDto

A resolved geography node (id and both names).

delivery
required
boolean

True when the company delivers to the city.

pickup
required
boolean

True when the company picks up from the city.

PublicCityDtoObject#

City item of the public geography endpoints.

FieldTypeDescription
id
required
string (uuid)

City id.

nameAr
required
string

Arabic name.

nameEn
required
string

English name.

codestringnullable

City code (unique within its country), when defined.

countryId
required
string (uuid)

Id of the country the city belongs to.

pending
required
boolean

True for a city created by your company that the platform has not approved yet.

PublicCityDtoPublicPageObject#

Standard paged response of every public list endpoint.

FieldTypeDescription
items
required
array<PublicCityDto>

Items of the requested page.

page
required
integer (int32)

Current page number, starting at 1.

pageSize
required
integer (int32)

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

totalCount
required
integer (int32)

Total number of items across all pages.

totalPages
required
integer (int32)

Total number of pages.

PublicColdChainRangeEnum#

Temperature range of cold-chain goods.

Values: frozenchilledambient

PublicCompanyDtoObject#

Company identity shown by the public auth/me endpoint.

FieldTypeDescription
id
required
string (uuid)

Company id.

name
required
string

Company name.

slug
required
string

Company slug.

PublicCountryDtoObject#

Country item of the public geography endpoints.

FieldTypeDescription
id
required
string (uuid)

Country id.

nameAr
required
string

Arabic name.

nameEn
required
string

English name.

code
required
string

ISO 3166-1 alpha-2 code.

PublicCountryDtoPublicPageObject#

Standard paged response of every public list endpoint.

FieldTypeDescription
items
required
array<PublicCountryDto>

Items of the requested page.

page
required
integer (int32)

Current page number, starting at 1.

pageSize
required
integer (int32)

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

totalCount
required
integer (int32)

Total number of items across all pages.

totalPages
required
integer (int32)

Total number of pages.

PublicCoveredCityDtoObject#

A city the company covers.

FieldTypeDescription
id
required
string (uuid)

City id.

nameAr
required
string

Arabic name.

nameEn
required
string

English name.

codestringnullable

City code, when defined.

countryId
required
string (uuid)

Country id.

delivery
required
boolean

True when the company delivers to the city.

pickup
required
boolean

True when the company picks up from the city.

PublicCoveredCityDtoPublicPageObject#

Standard paged response of every public list endpoint.

FieldTypeDescription
items
required
array<PublicCoveredCityDto>

Items of the requested page.

page
required
integer (int32)

Current page number, starting at 1.

pageSize
required
integer (int32)

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

totalCount
required
integer (int32)

Total number of items across all pages.

totalPages
required
integer (int32)

Total number of pages.

PublicCreateMerchantAddressRequestObject#

Body of POST /merchants/{id}/addresses.

FieldTypeDescription
label
required
string

Short label of the address, for example "Main warehouse". Required, up to 100 characters.

Example: Main warehouse

contactNamestringnullable

Person to contact at this address (defaults to the merchant name).

Example: Omar Hassan

contactPhone
required
string

Phone at this address. Required.

Example: 0501234567

countrystringnullable

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

Example: SA

city
required
string

City id, code or name. Required.

Example: Riyadh

district
required
string

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

Example: Al Olaya

addressLine
required
string

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

Example: King Fahd Road, Warehouse 4

shortAddress
conditional
stringnullable

Saudi national short address (4 letters and 4 digits). Required for addresses in Saudi Arabia.

Example: RNBA6769

latitudenumber (double)nullable

Latitude (optional).

Example: 24.7136

longitudenumber (double)nullable

Longitude (optional).

Example: 46.6753

makePrimaryboolean

Make this the primary address (the first address of a merchant is always primary).

Example: false

PublicCreateMerchantRequestObject#

Body of POST /merchants.

FieldTypeDescription
name
required
string

Account (store) name. Not unique, but a name that matches another merchant on the platform needs confirmPossibleDuplicate. Required, up to 200 characters.

Example: Noor Electronics

contactNamestringnullable

Contact person.

Example: Omar Hassan

contactPhonestringnullable

Contact phone.

Example: 0501234567

contactEmail
required
string

Contact email. Required; unique across the platform.

Example: orders@noor-electronics.example

commercialRegNo
required
string

Commercial registration number (or freelance licence number). Required.

Example: 1010123456

taxId
conditional
stringnullable

VAT number. Required unless notVatRegistered is true.

Example: 300123456700003

notVatRegisteredboolean

True when the merchant is not registered for VAT.

Example: false

address
required
PublicMerchantAddressInput

A saved pickup address of a merchant, given by names. Country, city and district each accept an id, a code or a name in Arabic or English.

confirmPossibleDuplicateboolean

Confirm that this is a different store even though its registration number, VAT number or name matches another merchant on the platform. Without it such a request is refused with 409 merchant.possible_duplicate.

Example: false

PublicCreateShipmentRequestObject#

Body of POST /shipments. Prices are computed from the company's rate card; never send a fee.

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.

pickupPublicPickupInput

The pickup address.

recipientPublicRecipientInput

The recipient and the delivery address.

parcel
required
PublicParcelInput

The parcel. Weight and dimensions describe the whole shipment.

paymentPublicPaymentInput

Cash on delivery and freight payment.

deliveryPublicDeliveryOptionsInput

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

PublicCreateWebhookRequestObject#

Body of POST /merchants/{merchantId}/webhooks.

FieldTypeDescription
url
required
string

HTTPS URL that receives the events. Private and local addresses are refused.

Example: https://shop.example.com/hooks/lastmile

events
required
array<string>

Event types to receive, from GET /webhooks/events. Wildcards: shipment.* (all shipment events) or * (everything). At least one.

Example: ["shipment.created","shipment.delivered"]

descriptionstringnullable

Free text to recognise the subscription (optional, up to 200 characters).

Example: Order system

PublicDeliveryOptionsDtoObject#

Handover rules.

FieldTypeDescription
allowOpenPackage
required
boolean

The recipient may open the package.

requireSignature
required
boolean

Signature required.

requireIdVerification
required
boolean

ID check required.

allowNeighborDelivery
required
boolean

Neighbour delivery allowed.

PublicDeliveryOptionsInputObject#

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

FieldTypeDescription
allowOpenPackagebooleannullable

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

Example: false

requireSignature
conditional
booleannullable

A signature is required on delivery. Default true.

Example: true

requireIdVerificationbooleannullable

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

Example: false

allowNeighborDeliverybooleannullable

A neighbour may accept the parcel. Default true.

Example: true

PublicDistrictDtoObject#

District item of the public geography endpoints.

FieldTypeDescription
id
required
string (uuid)

District id.

nameAr
required
string

Arabic name.

nameEn
required
string

English name.

codestringnullable

District code, when defined.

cityId
required
string (uuid)

Id of the city the district belongs to.

pending
required
boolean

True for a district created by your company that the platform has not approved yet.

PublicDistrictDtoPublicPageObject#

Standard paged response of every public list endpoint.

FieldTypeDescription
items
required
array<PublicDistrictDto>

Items of the requested page.

page
required
integer (int32)

Current page number, starting at 1.

pageSize
required
integer (int32)

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

totalCount
required
integer (int32)

Total number of items across all pages.

totalPages
required
integer (int32)

Total number of pages.

PublicGeoNodeDtoObject#

A resolved geography node (id and both names).

FieldTypeDescription
id
required
string (uuid)

Resolved id.

nameAr
required
string

Arabic name.

nameEn
required
string

English name.

PublicLoginRequestObject#

Credentials of a user of the shipping company.

FieldTypeDescription
username
required
string

Username or e-mail address.

password
required
string

Password.

PublicMerchantAddressDtoObject#

A saved pickup address of a merchant.

FieldTypeDescription
id
required
string (uuid)

Address id.

label
required
string

Short label.

contactNamestringnullable

Contact person at the address.

contactPhone
required
string

Phone at the address.

countryPublicNamedRef

A catalog entry shown in both languages.

cityPublicNamedRef

A catalog entry shown in both languages.

districtPublicNamedRef

A catalog entry shown in both languages.

addressLine
required
string

Street, building and landmark.

shortAddressstringnullable

Saudi national short address.

latitudenumber (double)nullable

Latitude.

longitudenumber (double)nullable

Longitude.

isPrimary
required
boolean

True for the primary address (used by default as the pickup of the merchant's shipments).

PublicMerchantAddressInputObject#

A saved pickup address of a merchant, given by names. Country, city and district each accept an id, a code or a name in Arabic or English.

FieldTypeDescription
label
required
string

Short label of the address, for example "Main warehouse". Required, up to 100 characters.

Example: Main warehouse

contactNamestringnullable

Person to contact at this address (defaults to the merchant name).

Example: Omar Hassan

contactPhone
required
string

Phone at this address. Required.

Example: 0501234567

countrystringnullable

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

Example: SA

city
required
string

City id, code or name. Required.

Example: Riyadh

district
required
string

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

Example: Al Olaya

addressLine
required
string

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

Example: King Fahd Road, Warehouse 4

shortAddress
conditional
stringnullable

Saudi national short address (4 letters and 4 digits). Required for addresses in Saudi Arabia.

Example: RNBA6769

latitudenumber (double)nullable

Latitude (optional).

Example: 24.7136

longitudenumber (double)nullable

Longitude (optional).

Example: 46.6753

PublicMerchantDtoObject#

A merchant of the company (no banking, commission, API keys or pricing details).

FieldTypeDescription
id
required
string (uuid)

Merchant id.

name
required
string

Account name.

contactNamestringnullable

Contact person.

contactPhonestringnullable

Contact phone.

contactEmailstringnullable

Contact email.

isActive
required
boolean

Whether the merchant can book shipments.

createdAt
required
string (date-time)

Creation time (UTC).

primaryAddressPublicMerchantAddressDto

A saved pickup address of a merchant.

PublicMerchantDtoPublicPageObject#

Standard paged response of every public list endpoint.

FieldTypeDescription
items
required
array<PublicMerchantDto>

Items of the requested page.

page
required
integer (int32)

Current page number, starting at 1.

pageSize
required
integer (int32)

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

totalCount
required
integer (int32)

Total number of items across all pages.

totalPages
required
integer (int32)

Total number of pages.

PublicMerchantRefObject#

A merchant reference.

FieldTypeDescription
id
required
string (uuid)

Merchant id.

name
required
string

Merchant account name.

PublicMeResponseObject#

Identity and permissions of the current caller.

FieldTypeDescription
authMethod
required
string

password or api_key.

company
required
PublicCompanyDto

Company identity shown by the public auth/me endpoint.

userPublicUserDto

The user behind a password-authenticated call.

apiKeyPublicApiKeyDto

The API key behind a key-authenticated call.

scopes
required
array<string>

API scopes granted (for password callers: the scopes the user's permissions cover).

permissions
required
array<string>

Permission codes held by the caller.

PublicNamedRefObject#

A catalog entry shown in both languages.

FieldTypeDescription
idstring (uuid)nullable

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

nameAr
required
string

Arabic name.

nameEn
required
string

English name.

PublicOrderSourceEnum#

How the order reached the system.

Values: dashboardexcelImportmerchantPortalapiintegrationinviteLinkpublicWebsitephonewhatsAppsocialMediawalkInother

PublicParcelDtoObject#

Parcel data of a shipment.

FieldTypeDescription
weightKg
required
number (double)

Actual weight.

lengthCm
required
number (double)

Length.

widthCm
required
number (double)

Width.

heightCm
required
number (double)

Height.

chargeableWeightKg
required
number (double)

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

pieces
required
integer (int32)

Number of pieces.

descriptionstringnullable

What is inside.

declaredValue
required
number (double)

Declared value.

fragile
required
boolean

Fragile.

requiresColdChain
required
boolean

Needs cold chain.

coldChainRangeenum

Temperature range of cold-chain goods.

Values: frozenchilledambient

flammable
required
boolean

Flammable.

hazardous
required
boolean

Hazardous.

containsAlcohol
required
boolean

Contains alcohol.

liquid
required
boolean

Liquid.

highValue
required
boolean

High value.

PublicParcelInputObject#

The parcel. Weight and dimensions describe the whole shipment.

FieldTypeDescription
weightKg
required
number (double)

Actual weight in kilograms, greater than 0.

Example: 1.5

lengthCm
required
number (double)

Length in centimetres, greater than 0.

Example: 20

widthCm
required
number (double)

Width in centimetres, greater than 0.

Example: 15

heightCm
required
number (double)

Height in centimetres, greater than 0.

Example: 10

piecesinteger (int32)nullable

Number of pieces (default 1).

Example: 1

descriptionstringnullable

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

Example: Mobile phone case

declaredValuenumber (double)nullable

Declared value of the goods (default 0).

Example: 250

fragileboolean

Fragile goods.

Example: false

requiresColdChain
conditional
boolean

Needs cold chain; then coldChainRange is required.

Example: false

coldChainRangeenum

Temperature range of cold-chain goods.

Values: frozenchilledambient

flammableboolean

Flammable goods.

Example: false

hazardousboolean

Hazardous goods.

Example: false

containsAlcoholboolean

Contains alcohol.

Example: false

liquidboolean

Liquid goods.

Example: false

highValueboolean

High-value goods.

Example: false

PublicPaymentDtoObject#

Payment data of a shipment.

FieldTypeDescription
codAmount
required
number (double)

Cash to collect from the recipient.

shippingFee
required
number (double)

Shipping fee computed from the rate card.

freightOnDelivery
required
boolean

True when the recipient pays the fee.

PublicPaymentInputObject#

Cash on delivery and freight payment.

FieldTypeDescription
codAmountnumber (double)nullable

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

Example: 199.5

freightOnDeliverybooleannullable

True when the recipient pays the shipping fee on delivery.

Example: false

PublicPickupInputObject#

The pickup address.

FieldTypeDescription
countrystringnullable

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

Example: SA

city
required
string

City id, code or name. Required.

Example: Riyadh

district
required
string

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

Example: Al Olaya

addressLine
required
string

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

Example: King Fahd Road, Building 12, Floor 3

shortAddress
conditional
stringnullable

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

Example: RNBA6769

latitudenumber (double)nullable

Latitude, -90 to 90 (optional).

Example: 24.7136

longitudenumber (double)nullable

Longitude, -180 to 180 (optional).

Example: 46.6753

branchstringnullable

Leave this out: the system assigns the branch that covers the pickup address automatically. Send a branch id, code or name only to override that choice, which is needed when no branch or more than one branch covers the pickup area (branch_coverage.no_coverage_for_city, branch_coverage.ambiguous_coverage).

PublicPieceDtoObject#

One piece of a shipment.

FieldTypeDescription
barcode
required
string

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

PublicQuoteDtoObject#

A price quote. Nothing is created or consumed: no tracking number, no quota.

FieldTypeDescription
deliverable
required
boolean

False when the company does not cover the pickup or the destination (see reason).

reasonstringnullable

destination_not_covered, pickup_not_covered or rate_card_not_found when not deliverable.

shippingFeenumber (double)nullable

Shipping fee without the COD fee (weight price plus handling surcharges).

codFeenumber (double)nullable

Fee charged for collecting cash on delivery.

totalnumber (double)nullable

What the shipment will be charged: shippingFee + codFee. Equals payment.shippingFee of the created shipment.

chargeableWeightKgnumber (double)nullable

The larger of actual and volumetric weight.

zonePublicZoneRef

A pricing zone.

breakdown
required
array<PublicQuoteLineDto>

Price lines; they add up to total.

PublicQuoteLineDtoObject#

One line of a price.

FieldTypeDescription
code
required
string

baseShipping, handling, codFee or reverseAdjustment.

label
required
string

Readable label (the handling flag name for handling lines).

amount
required
number (double)

Amount of the line.

PublicQuoteLocationInputObject#

A place given by names for a quote. Each level accepts an id, a code or a name in Arabic or English.

FieldTypeDescription
countrystringnullable

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

Example: SA

city
required
string

City id, code or name. Required.

Example: Jeddah

districtstringnullable

District id, code or name. Optional for a quote; when sent it must exist.

Example: Al Rawdah

PublicQuoteRequestObject#

Body of POST /pricing/quote.

FieldTypeDescription
merchant
conditional
stringnullable

Merchant id or exact account name; the merchant's own rate card applies. Optional: without it the company's default pricing is used. A merchant login always quotes for itself. Required for return quotes.

Example: Noor Electronics

pickup
required
PublicQuoteLocationInput

A place given by names for a quote. Each level accepts an id, a code or a name in Arabic or English.

recipient
required
PublicQuoteLocationInput

A place given by names for a quote. Each level accepts an id, a code or a name in Arabic or English.

parcel
required
PublicParcelInput

The parcel. Weight and dimensions describe the whole shipment.

paymentPublicPaymentInput

Cash on delivery and freight payment.

serviceTypeenum

Kind of service requested for a shipment.

Values: deliveryexchangereturn

serviceTierenum

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

Values: standardexpresssameDay

PublicRecipientDtoObject#

The recipient.

FieldTypeDescription
name
required
string

Recipient name.

phone
required
string

Recipient phone.

secondaryPhonestringnullable

Second phone.

countryPublicNamedRef

A catalog entry shown in both languages.

cityPublicNamedRef

A catalog entry shown in both languages.

districtPublicNamedRef

A catalog entry shown in both languages.

addressLine
required
string

Street, building and landmark.

shortAddressstringnullable

Saudi national short address.

latitudenumber (double)nullable

Latitude.

longitudenumber (double)nullable

Longitude.

PublicRecipientInputObject#

The recipient and the delivery address.

FieldTypeDescription
countrystringnullable

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

Example: SA

city
required
string

City id, code or name. Required.

Example: Riyadh

district
required
string

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

Example: Al Olaya

addressLine
required
string

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

Example: King Fahd Road, Building 12, Floor 3

shortAddress
conditional
stringnullable

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

Example: RNBA6769

latitudenumber (double)nullable

Latitude, -90 to 90 (optional).

Example: 24.7136

longitudenumber (double)nullable

Longitude, -180 to 180 (optional).

Example: 46.6753

name
required
string

Recipient name. Required, up to 200 characters.

Example: Khaled Alotaibi

phone
required
string

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

Example: 0555123456

secondaryPhonestringnullable

Second phone (optional).

Example: 0555987654

PublicRefreshRequestObject#

Request to exchange a refresh token for a new token pair.

FieldTypeDescription
refreshToken
required
string

The refresh token returned by login or by a previous refresh (single use).

PublicResolvedLocationDtoObject#

Result of validating a location by names.

FieldTypeDescription
countryPublicGeoNodeDto

A resolved geography node (id and both names).

cityPublicGeoNodeDto

A resolved geography node (id and both names).

districtPublicGeoNodeDto

A resolved geography node (id and both names).

PublicSenderDtoObject#

The sender of a shipment.

FieldTypeDescription
type
required
enum

Who sends the shipment.

Values: merchantcustom

name
required
string

Sender name.

phonestringnullable

Sender phone.

emailstringnullable

Sender email.

merchantPublicMerchantRef

A merchant reference.

PublicSenderInputObject#

The sender of a shipment.

FieldTypeDescription
typeenum

Who sends the shipment.

Values: merchantcustom

merchantstringnullable

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

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

namestringnullable

For custom: sender name (required).

Example: Sara Ahmed

phonestringnullable

For custom: sender phone (required).

Example: 0501234567

emailstringnullable

For custom: sender email (optional).

Example: sara@example.com

PublicSenderTypeEnum#

Who sends the shipment.

Values: merchantcustom

PublicServiceTierEnum#

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

Values: standardexpresssameDay

PublicServiceTypeEnum#

Kind of service requested for a shipment.

Values: deliveryexchangereturn

PublicShipmentDtoObject#

A shipment as returned by the public API.

FieldTypeDescription
trackingNumber
required
string

Tracking number; identifies the shipment in every route.

reference
required
string

Your order reference.

status
required
string

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

statusCode
required
integer (int32)

Numeric status code.

statusLabelAr
required
string

Arabic status label.

statusLabelEn
required
string

English status label.

isFinal
required
boolean

True when the shipment reached a final status.

serviceType
required
enum

Kind of service requested for a shipment.

Values: deliveryexchangereturn

serviceTier
required
enum

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

Values: standardexpresssameDay

source
required
enum

How the order reached the system.

Values: dashboardexcelImportmerchantPortalapiintegrationinviteLinkpublicWebsitephonewhatsAppsocialMediawalkInother

createdAt
required
string (date-time)

Creation time (UTC).

estimatedDeliveryDatestring (date)nullable

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

sender
required
PublicSenderDto

The sender of a shipment.

pickup
required
PublicAddressDto

A resolved address.

recipient
required
PublicRecipientDto

The recipient.

parcel
required
PublicParcelDto

Parcel data of a shipment.

delivery
required
PublicDeliveryOptionsDto

Handover rules.

payment
required
PublicPaymentDto

Payment data of a shipment.

pieces
required
array<PublicPieceDto>

The pieces.

branch
required
PublicBranchRef

A branch reference.

canCancel
required
boolean

True while the shipment can still be cancelled.

isEditable
required
boolean

True while the shipment can still be edited.

PublicShipmentSummaryDtoObject#

A shipment row of the list endpoint.

FieldTypeDescription
trackingNumber
required
string

Tracking number.

reference
required
string

Your order reference.

status
required
string

Status key.

statusLabelAr
required
string

Arabic status label.

statusLabelEn
required
string

English status label.

merchantPublicMerchantRef

A merchant reference.

senderName
required
string

Sender name.

recipientName
required
string

Recipient name.

recipientPhone
required
string

Recipient phone.

cityPublicNamedRef

A catalog entry shown in both languages.

districtPublicNamedRef

A catalog entry shown in both languages.

codAmount
required
number (double)

Cash on delivery amount.

shippingFee
required
number (double)

Shipping fee.

createdAt
required
string (date-time)

Creation time (UTC).

estimatedDeliveryDatestring (date)nullable

Estimated delivery date.

PublicShipmentSummaryDtoPublicPageObject#

Standard paged response of every public list endpoint.

FieldTypeDescription
items
required
array<PublicShipmentSummaryDto>

Items of the requested page.

page
required
integer (int32)

Current page number, starting at 1.

pageSize
required
integer (int32)

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

totalCount
required
integer (int32)

Total number of items across all pages.

totalPages
required
integer (int32)

Total number of pages.

PublicStatusDtoObject#

A shipment status of the catalog.

FieldTypeDescription
code
required
integer (int32)

Numeric status code.

key
required
string

Status key used in the API.

nameAr
required
string

Arabic name.

nameEn
required
string

English name.

isFinal
required
boolean

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

PublicTokenResponseObject#

Token pair returned by login and refresh.

FieldTypeDescription
accessToken
required
string

JWT to send as Authorization: Bearer ....

refreshToken
required
string

Single-use refresh token.

tokenType
required
string

Always Bearer.

expiresIn
required
integer (int32)

Lifetime of the access token in seconds.

PublicTrackingDtoObject#

Tracking of one shipment.

FieldTypeDescription
trackingNumber
required
string

Tracking number.

status
required
string

Current status key.

statusLabelAr
required
string

Arabic label of the current status.

statusLabelEn
required
string

English label of the current status.

estimatedDeliveryDatestring (date)nullable

Estimated delivery date.

events
required
array<PublicTrackingEventDto>

Timeline, oldest first.

PublicTrackingEventDtoObject#

One step of the status timeline.

FieldTypeDescription
status
required
string

Status key.

statusLabelAr
required
string

Arabic label.

statusLabelEn
required
string

English label.

at
required
string (date-time)

When the status was set (UTC).

notestringnullable

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

locationstringnullable

Reserved; not populated yet.

PublicUpdateMerchantRequestObject#

Body of PUT /merchants/{id}. Only the fields you send change.

FieldTypeDescription
namestringnullable

New account name.

Example: Noor Electronics

contactNamestringnullable

New contact person.

Example: Omar Hassan

contactPhonestringnullable

New contact phone.

Example: 0501234567

contactEmailstringnullable

New contact email.

Example: orders@noor-electronics.example

PublicUpdateParcelInputObject#

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

FieldTypeDescription
weightKgnumber (double)nullable

Weight in kilograms.

Example: 2

lengthCmnumber (double)nullable

Length in centimetres.

Example: 20

widthCmnumber (double)nullable

Width in centimetres.

Example: 15

heightCmnumber (double)nullable

Height in centimetres.

Example: 10

piecesinteger (int32)nullable

Number of pieces.

Example: 1

declaredValuenumber (double)nullable

Declared value of the goods.

Example: 300

PublicUpdateRecipientInputObject#

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

FieldTypeDescription
countrystringnullable

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

Example: SA

city
required
stringnullable

City id, code or name. Required.

Example: Riyadh

district
required
stringnullable

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

Example: Al Olaya

addressLine
required
stringnullable

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

Example: King Fahd Road, Building 12, Floor 3

shortAddress
conditional
stringnullable

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

Example: RNBA6769

latitudenumber (double)nullable

Latitude, -90 to 90 (optional).

Example: 24.7136

longitudenumber (double)nullable

Longitude, -180 to 180 (optional).

Example: 46.6753

namestringnullable

Recipient name.

Example: Khaled Alotaibi

phonestringnullable

Recipient phone.

Example: 0555123456

secondaryPhonestringnullable

Second phone.

Example: 0555987654

PublicUpdateShipmentRequestObject#

Body of PUT /shipments/{trackingNumber}. Every field except reason is optional: only the fields you send change, everything else keeps its current value. At least one field is required.

FieldTypeDescription
reason
required
string

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

parcelPublicUpdateParcelInput

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

paymentPublicPaymentInput

Cash on delivery and freight payment.

PublicUserDtoObject#

The user behind a password-authenticated call.

FieldTypeDescription
id
required
string (uuid)

User id.

namestringnullable

Full name.

PublicWebhookCreatedDtoObject#

A newly created subscription. The signing secret is returned here once and cannot be read again.

FieldTypeDescription
id
required
string (uuid)

Subscription id.

merchantId
required
string (uuid)

The merchant whose shipments trigger the events.

url
required
string

The receiving URL.

events
required
array<string>

Subscribed event types.

descriptionstringnullable

Description.

isActive
required
boolean

Whether it is active.

createdAt
required
string (date-time)

Creation time (UTC).

secret
required
string

Signing secret: keep it safe, use it to verify the X-Signature header of every delivery.

PublicWebhookDtoObject#

A webhook subscription of a merchant.

FieldTypeDescription
id
required
string (uuid)

Subscription id.

merchantId
required
string (uuid)

The merchant whose shipments trigger the events.

url
required
string

The receiving URL.

events
required
array<string>

Subscribed event types.

descriptionstringnullable

Description.

isActive
required
boolean

False when the subscription is paused.

createdAt
required
string (date-time)

Creation time (UTC).

PublicWebhookEventDtoObject#

An event type that can be subscribed to.

FieldTypeDescription
type
required
string

Event type, e.g. shipment.delivered.

description
required
string

When the event is sent.

examplePayload
required
any

An example of the JSON body of the delivery (event, occurredAt, data).

PublicWebhookSecretDtoObject#

A rotated signing secret (shown once; the previous secret stops working immediately).

FieldTypeDescription
secret
required
string

The new signing secret.

PublicWebhookTestDtoObject#

Result of a test delivery request.

FieldTypeDescription
queued
required
boolean

True when a signed ping event was queued for delivery.

eventType
required
string

The event type sent (ping).

PublicZoneRefObject#

A pricing zone.

FieldTypeDescription
id
required
string (uuid)

Zone id.

name
required
string

Zone name.