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.

addressLinestringnullable

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
codestringnullable

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

messagestringnullable

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

statusinteger (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.

traceIdstringnullable

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

PublicApiKeyDtoObject#

The API key behind a key-authenticated call.

FieldTypeDescription
idstring (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
idstring (uuid)

Branch id.

namestringnullable

Branch name.

codestringnullable

Branch code.

citystringnullable

City name as entered on the branch.

phonestringnullable

Branch phone, when set.

latitudenumber (double)nullable

Latitude, when set.

longitudenumber (double)nullable

Longitude, when set.

isActiveboolean

Whether the branch is active.

PublicBranchDtoPublicPageObject#

Standard paged response of every public list endpoint.

FieldTypeDescription
itemsarray<PublicBranchDto>nullable

Items of the requested page.

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.

PublicBranchRefObject#

A branch reference.

FieldTypeDescription
idstring (uuid)

Branch id.

namestringnullable

Branch name.

PublicCancelShipmentRequestObject#

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

FieldTypeDescription
reasonstringnullable

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
cityPublicGeoNodeDto

A resolved geography node (id and both names).

deliveryboolean

True when the company delivers to the city.

pickupboolean

True when the company picks up from the city.

PublicCityDtoObject#

City item of the public geography endpoints.

FieldTypeDescription
idstring (uuid)

City id.

nameArstringnullable

Arabic name.

nameEnstringnullable

English name.

codestringnullable

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

countryIdstring (uuid)

Id of the country the city belongs to.

pendingboolean

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
itemsarray<PublicCityDto>nullable

Items of the requested page.

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.

PublicColdChainRangeEnum#

Temperature range of cold-chain goods.

Values: frozenchilledambient

PublicCompanyDtoObject#

Company identity shown by the public auth/me endpoint.

FieldTypeDescription
idstring (uuid)

Company id.

namestringnullable

Company name.

slugstringnullable

Company slug.

PublicCountryDtoObject#

Country item of the public geography endpoints.

FieldTypeDescription
idstring (uuid)

Country id.

nameArstringnullable

Arabic name.

nameEnstringnullable

English name.

codestringnullable

ISO 3166-1 alpha-2 code.

PublicCountryDtoPublicPageObject#

Standard paged response of every public list endpoint.

FieldTypeDescription
itemsarray<PublicCountryDto>nullable

Items of the requested page.

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.

PublicCoveredCityDtoObject#

A city the company covers.

FieldTypeDescription
idstring (uuid)

City id.

nameArstringnullable

Arabic name.

nameEnstringnullable

English name.

codestringnullable

City code, when defined.

countryIdstring (uuid)

Country id.

deliveryboolean

True when the company delivers to the city.

pickupboolean

True when the company picks up from the city.

PublicCoveredCityDtoPublicPageObject#

Standard paged response of every public list endpoint.

FieldTypeDescription
itemsarray<PublicCoveredCityDto>nullable

Items of the requested page.

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.

PublicCreateMerchantAddressRequestObject#

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

FieldTypeDescription
label
required
stringnullable

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
stringnullable

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
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, 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
stringnullable

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
stringnullable

Contact email. Required; unique across the platform.

Example: orders@noor-electronics.example

commercialRegNo
required
stringnullable

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

addressPublicMerchantAddressInput

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.

parcelPublicParcelInput

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
urlstringnullable

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

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

eventsarray<string>nullable

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
allowOpenPackageboolean

The recipient may open the package.

requireSignatureboolean

Signature required.

requireIdVerificationboolean

ID check required.

allowNeighborDeliveryboolean

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
idstring (uuid)

District id.

nameArstringnullable

Arabic name.

nameEnstringnullable

English name.

codestringnullable

District code, when defined.

cityIdstring (uuid)

Id of the city the district belongs to.

pendingboolean

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
itemsarray<PublicDistrictDto>nullable

Items of the requested page.

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.

PublicGeoNodeDtoObject#

A resolved geography node (id and both names).

FieldTypeDescription
idstring (uuid)

Resolved id.

nameArstringnullable

Arabic name.

nameEnstringnullable

English name.

PublicLoginRequestObject#

Credentials of a user of the shipping company.

FieldTypeDescription
usernamestringnullable

Username or e-mail address.

passwordstringnullable

Password.

PublicMerchantAddressDtoObject#

A saved pickup address of a merchant.

FieldTypeDescription
idstring (uuid)

Address id.

labelstringnullable

Short label.

contactNamestringnullable

Contact person at the address.

contactPhonestringnullable

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.

addressLinestringnullable

Street, building and landmark.

shortAddressstringnullable

Saudi national short address.

latitudenumber (double)nullable

Latitude.

longitudenumber (double)nullable

Longitude.

isPrimaryboolean

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
stringnullable

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
stringnullable

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
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, 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
idstring (uuid)

Merchant id.

namestringnullable

Account name.

contactNamestringnullable

Contact person.

contactPhonestringnullable

Contact phone.

contactEmailstringnullable

Contact email.

isActiveboolean

Whether the merchant can book shipments.

createdAtstring (date-time)

Creation time (UTC).

primaryAddressPublicMerchantAddressDto

A saved pickup address of a merchant.

PublicMerchantDtoPublicPageObject#

Standard paged response of every public list endpoint.

FieldTypeDescription
itemsarray<PublicMerchantDto>nullable

Items of the requested page.

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.

PublicMerchantRefObject#

A merchant reference.

FieldTypeDescription
idstring (uuid)

Merchant id.

namestringnullable

Merchant account name.

PublicMeResponseObject#

Identity and permissions of the current caller.

FieldTypeDescription
authMethodstringnullable

password or api_key.

companyPublicCompanyDto

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.

scopesarray<string>nullable

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

permissionsarray<string>nullable

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.

nameArstringnullable

Arabic name.

nameEnstringnullable

English name.

PublicOrderSourceEnum#

How the order reached the system.

Values: dashboardexcelImportmerchantPortalapiintegrationinviteLinkpublicWebsitephonewhatsAppsocialMediawalkInother

PublicParcelDtoObject#

Parcel data of a shipment.

FieldTypeDescription
weightKgnumber (double)

Actual weight.

lengthCmnumber (double)

Length.

widthCmnumber (double)

Width.

heightCmnumber (double)

Height.

chargeableWeightKgnumber (double)

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

piecesinteger (int32)

Number of pieces.

descriptionstringnullable

What is inside.

declaredValuenumber (double)

Declared value.

fragileboolean

Fragile.

requiresColdChainboolean

Needs cold chain.

coldChainRangeenum

Temperature range of cold-chain goods.

Values: frozenchilledambient

flammableboolean

Flammable.

hazardousboolean

Hazardous.

containsAlcoholboolean

Contains alcohol.

liquidboolean

Liquid.

highValueboolean

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
codAmountnumber (double)

Cash to collect from the recipient.

shippingFeenumber (double)

Shipping fee computed from the rate card.

freightOnDeliveryboolean

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

branchstringnullable

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

PublicPieceDtoObject#

One piece of a shipment.

FieldTypeDescription
barcodestringnullable

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

PublicQuoteDtoObject#

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

FieldTypeDescription
deliverableboolean

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.

breakdownarray<PublicQuoteLineDto>nullable

Price lines; they add up to total.

PublicQuoteLineDtoObject#

One line of a price.

FieldTypeDescription
codestringnullable

baseShipping, handling, codFee or reverseAdjustment.

labelstringnullable

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

amountnumber (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
stringnullable

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

pickupPublicQuoteLocationInput

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

recipientPublicQuoteLocationInput

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

parcelPublicParcelInput

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
namestringnullable

Recipient name.

phonestringnullable

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.

addressLinestringnullable

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

name
required
stringnullable

Recipient name. Required, up to 200 characters.

Example: Khaled Alotaibi

phone
required
stringnullable

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
refreshTokenstringnullable

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
typeenum

Who sends the shipment.

Values: merchantcustom

namestringnullable

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

pickupPublicAddressDto

A resolved address.

recipientPublicRecipientDto

The recipient.

parcelPublicParcelDto

Parcel data of a shipment.

deliveryPublicDeliveryOptionsDto

Handover rules.

paymentPublicPaymentDto

Payment data of a shipment.

piecesarray<PublicPieceDto>nullable

The pieces.

branchPublicBranchRef

A branch reference.

canCancelboolean

True while the shipment can still be cancelled.

isEditableboolean

True while the shipment can still be edited.

PublicShipmentSummaryDtoObject#

A shipment row of the list endpoint.

FieldTypeDescription
trackingNumberstringnullable

Tracking number.

referencestringnullable

Your order reference.

statusstringnullable

Status key.

statusLabelArstringnullable

Arabic status label.

statusLabelEnstringnullable

English status label.

merchantPublicMerchantRef

A merchant reference.

senderNamestringnullable

Sender name.

recipientNamestringnullable

Recipient name.

recipientPhonestringnullable

Recipient phone.

cityPublicNamedRef

A catalog entry shown in both languages.

districtPublicNamedRef

A catalog entry shown in both languages.

codAmountnumber (double)

Cash on delivery amount.

shippingFeenumber (double)

Shipping fee.

createdAtstring (date-time)

Creation time (UTC).

estimatedDeliveryDatestring (date)nullable

Estimated delivery date.

PublicShipmentSummaryDtoPublicPageObject#

Standard paged response of every public list endpoint.

FieldTypeDescription
itemsarray<PublicShipmentSummaryDto>nullable

Items of the requested page.

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.

PublicStatusDtoObject#

A shipment status of the catalog.

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

PublicTokenResponseObject#

Token pair returned by login and refresh.

FieldTypeDescription
accessTokenstringnullable

JWT to send as Authorization: Bearer ....

refreshTokenstringnullable

Single-use refresh token.

tokenTypestringnullable

Always Bearer.

expiresIninteger (int32)

Lifetime of the access token in seconds.

PublicTrackingDtoObject#

Tracking of one shipment.

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.

PublicTrackingEventDtoObject#

One step of the status timeline.

FieldTypeDescription
statusstringnullable

Status key.

statusLabelArstringnullable

Arabic label.

statusLabelEnstringnullable

English label.

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

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
idstring (uuid)

User id.

namestringnullable

Full name.

PublicWebhookCreatedDtoObject#

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

FieldTypeDescription
idstring (uuid)

Subscription id.

merchantIdstring (uuid)

The merchant whose shipments trigger the events.

urlstringnullable

The receiving URL.

eventsarray<string>nullable

Subscribed event types.

descriptionstringnullable

Description.

isActiveboolean

Whether it is active.

createdAtstring (date-time)

Creation time (UTC).

secretstringnullable

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

PublicWebhookDtoObject#

A webhook subscription of a merchant.

FieldTypeDescription
idstring (uuid)

Subscription id.

merchantIdstring (uuid)

The merchant whose shipments trigger the events.

urlstringnullable

The receiving URL.

eventsarray<string>nullable

Subscribed event types.

descriptionstringnullable

Description.

isActiveboolean

False when the subscription is paused.

createdAtstring (date-time)

Creation time (UTC).

PublicWebhookEventDtoObject#

An event type that can be subscribed to.

FieldTypeDescription
typestringnullable

Event type, e.g. shipment.delivered.

descriptionstringnullable

When the event is sent.

examplePayloadanynullable

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
secretstringnullable

The new signing secret.

PublicWebhookTestDtoObject#

Result of a test delivery request.

FieldTypeDescription
queuedboolean

True when a signed ping event was queued for delivery.

eventTypestringnullable

The event type sent (ping).

PublicZoneRefObject#

A pricing zone.

FieldTypeDescription
idstring (uuid)

Zone id.

namestringnullable

Zone name.