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.
| Field | Type | Description |
|---|---|---|
country | PublicNamedRef | A catalog entry shown in both languages. |
city | PublicNamedRef | A catalog entry shown in both languages. |
district | PublicNamedRef | A catalog entry shown in both languages. |
addressLine | stringnullable | Street, building and landmark. |
shortAddress | stringnullable | Saudi national short address. |
latitude | number (double)nullable | Latitude. |
longitude | number (double)nullable | Longitude. |
PublicApiErrorObject#
Error envelope returned for every non-2xx response of the public API (/api/public/v1).
| Field | Type | Description |
|---|---|---|
code | stringnullable | Stable machine-readable code, e.g. |
message | stringnullable | Human readable message. Arabic by default; English when Accept-Language prefers English. |
status | integer (int32) | HTTP status code, repeated in the body. |
details | objectnullable | Extra data: |
traceId | stringnullable | Correlation id of the request, quote it when contacting support. |
PublicApiKeyDtoObject#
The API key behind a key-authenticated call.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | API key id. |
name | stringnullable | Label given to the key. |
PublicBranchDtoObject#
Public-safe view of a branch (no manager, capacity, counters or other internal fields).
| Field | Type | Description |
|---|---|---|
id | string (uuid) | Branch id. |
name | stringnullable | Branch name. |
code | stringnullable | Branch code. |
city | stringnullable | City name as entered on the branch. |
phone | stringnullable | Branch phone, when set. |
latitude | number (double)nullable | Latitude, when set. |
longitude | number (double)nullable | Longitude, when set. |
isActive | boolean | Whether the branch is active. |
PublicBranchDtoPublicPageObject#
Standard paged response of every public list endpoint.
| Field | Type | Description |
|---|---|---|
items | array<PublicBranchDto>nullable | Items of the requested page. |
page | integer (int32) | Current page number, starting at 1. |
pageSize | integer (int32) | Requested page size (1 to 100, default 25). |
totalCount | integer (int32) | Total number of items across all pages. |
totalPages | integer (int32) | Total number of pages. |
PublicBranchRefObject#
A branch reference.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | Branch id. |
name | stringnullable | Branch name. |
PublicCancelShipmentRequestObject#
Body of POST /shipments/{trackingNumber}/cancel.
| Field | Type | Description |
|---|---|---|
reason | stringnullable | Why the shipment is cancelled (kept in the shipment history). Up to 500 characters. Example: |
PublicCityCoverageDtoObject#
Whether the company delivers to / picks up from a city.
| Field | Type | Description |
|---|---|---|
city | PublicGeoNodeDto | A resolved geography node (id and both names). |
delivery | boolean | True when the company delivers to the city. |
pickup | boolean | True when the company picks up from the city. |
PublicCityDtoObject#
City item of the public geography endpoints.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | City id. |
nameAr | stringnullable | Arabic name. |
nameEn | stringnullable | English name. |
code | stringnullable | City code (unique within its country), when defined. |
countryId | string (uuid) | Id of the country the city belongs to. |
pending | 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.
| Field | Type | Description |
|---|---|---|
items | array<PublicCityDto>nullable | Items of the requested page. |
page | integer (int32) | Current page number, starting at 1. |
pageSize | integer (int32) | Requested page size (1 to 100, default 25). |
totalCount | integer (int32) | Total number of items across all pages. |
totalPages | 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.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | Company id. |
name | stringnullable | Company name. |
slug | stringnullable | Company slug. |
PublicCountryDtoObject#
Country item of the public geography endpoints.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | Country id. |
nameAr | stringnullable | Arabic name. |
nameEn | stringnullable | English name. |
code | stringnullable | ISO 3166-1 alpha-2 code. |
PublicCountryDtoPublicPageObject#
Standard paged response of every public list endpoint.
| Field | Type | Description |
|---|---|---|
items | array<PublicCountryDto>nullable | Items of the requested page. |
page | integer (int32) | Current page number, starting at 1. |
pageSize | integer (int32) | Requested page size (1 to 100, default 25). |
totalCount | integer (int32) | Total number of items across all pages. |
totalPages | integer (int32) | Total number of pages. |
PublicCoveredCityDtoObject#
A city the company covers.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | City id. |
nameAr | stringnullable | Arabic name. |
nameEn | stringnullable | English name. |
code | stringnullable | City code, when defined. |
countryId | string (uuid) | Country id. |
delivery | boolean | True when the company delivers to the city. |
pickup | boolean | True when the company picks up from the city. |
PublicCoveredCityDtoPublicPageObject#
Standard paged response of every public list endpoint.
| Field | Type | Description |
|---|---|---|
items | array<PublicCoveredCityDto>nullable | Items of the requested page. |
page | integer (int32) | Current page number, starting at 1. |
pageSize | integer (int32) | Requested page size (1 to 100, default 25). |
totalCount | integer (int32) | Total number of items across all pages. |
totalPages | integer (int32) | Total number of pages. |
PublicCreateMerchantAddressRequestObject#
Body of POST /merchants/{id}/addresses.
| Field | Type | Description |
|---|---|---|
labelrequired | stringnullable | Short label of the address, for example "Main warehouse". Required, up to 100 characters. Example: |
contactName | stringnullable | Person to contact at this address (defaults to the merchant name). Example: |
contactPhonerequired | stringnullable | Phone at this address. Required. Example: |
country | stringnullable | Country id, ISO code or name. Optional when the city name is unambiguous. Example: |
cityrequired | stringnullable | City id, code or name. Required. Example: |
districtrequired | stringnullable | District id, code or name. Required. Unknown districts are never created: you get Example: |
addressLinerequired | stringnullable | Street, building and landmark. Required, up to 500 characters. Example: |
shortAddressconditional | stringnullable | Saudi national short address (4 letters and 4 digits). Required for addresses in Saudi Arabia. Example: |
latitude | number (double)nullable | Latitude (optional). Example: |
longitude | number (double)nullable | Longitude (optional). Example: |
makePrimary | boolean | Make this the primary address (the first address of a merchant is always primary). Example: |
PublicCreateMerchantRequestObject#
Body of POST /merchants.
| Field | Type | Description |
|---|---|---|
namerequired | stringnullable | Account (store) name. Not unique, but a name that matches another merchant on the platform needs Example: |
contactName | stringnullable | Contact person. Example: |
contactPhone | stringnullable | Contact phone. Example: |
contactEmailrequired | stringnullable | Contact email. Required; unique across the platform. Example: |
commercialRegNorequired | stringnullable | Commercial registration number (or freelance licence number). Required. Example: |
taxIdconditional | stringnullable | VAT number. Required unless Example: |
notVatRegistered | boolean | True when the merchant is not registered for VAT. Example: |
address | 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. |
confirmPossibleDuplicate | boolean | 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 Example: |
PublicCreateShipmentRequestObject#
Body of POST /shipments. Prices are computed from the company's rate card; never send a fee.
| Field | Type | Description |
|---|---|---|
reference | stringnullable | Your own order reference (shown on the label and searchable). Up to 100 characters. Example: |
serviceType | enum | Kind of service requested for a shipment. Values: |
serviceTier | enum | Speed of the service; it drives the estimated delivery date. Values: |
sender | PublicSenderInput | The sender of a shipment. |
pickup | PublicPickupInput | The pickup address. |
recipient | PublicRecipientInput | The recipient and the delivery address. |
parcel | PublicParcelInput | The parcel. Weight and dimensions describe the whole shipment. |
payment | PublicPaymentInput | Cash on delivery and freight payment. |
delivery | PublicDeliveryOptionsInput | Handover rules at the recipient's door. Omitted values use the system defaults shown. |
PublicCreateWebhookRequestObject#
Body of POST /merchants/{merchantId}/webhooks.
| Field | Type | Description |
|---|---|---|
url | stringnullable | HTTPS URL that receives the events. Private and local addresses are refused. Example: |
events | array<string>nullable | Event types to receive, from Example: |
description | stringnullable | Free text to recognise the subscription (optional, up to 200 characters). Example: |
PublicDeliveryOptionsDtoObject#
Handover rules.
| Field | Type | Description |
|---|---|---|
allowOpenPackage | boolean | The recipient may open the package. |
requireSignature | boolean | Signature required. |
requireIdVerification | boolean | ID check required. |
allowNeighborDelivery | boolean | Neighbour delivery allowed. |
PublicDeliveryOptionsInputObject#
Handover rules at the recipient's door. Omitted values use the system defaults shown.
| Field | Type | Description |
|---|---|---|
allowOpenPackage | booleannullable | The recipient may open the package before accepting. Default false. Example: |
requireSignatureconditional | booleannullable | A signature is required on delivery. Default true. Example: |
requireIdVerification | booleannullable | The courier must verify the recipient's ID. Default false. Example: |
allowNeighborDelivery | booleannullable | A neighbour may accept the parcel. Default true. Example: |
PublicDistrictDtoObject#
District item of the public geography endpoints.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | District id. |
nameAr | stringnullable | Arabic name. |
nameEn | stringnullable | English name. |
code | stringnullable | District code, when defined. |
cityId | string (uuid) | Id of the city the district belongs to. |
pending | 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.
| Field | Type | Description |
|---|---|---|
items | array<PublicDistrictDto>nullable | Items of the requested page. |
page | integer (int32) | Current page number, starting at 1. |
pageSize | integer (int32) | Requested page size (1 to 100, default 25). |
totalCount | integer (int32) | Total number of items across all pages. |
totalPages | integer (int32) | Total number of pages. |
PublicGeoNodeDtoObject#
A resolved geography node (id and both names).
| Field | Type | Description |
|---|---|---|
id | string (uuid) | Resolved id. |
nameAr | stringnullable | Arabic name. |
nameEn | stringnullable | English name. |
PublicLoginRequestObject#
Credentials of a user of the shipping company.
| Field | Type | Description |
|---|---|---|
username | stringnullable | Username or e-mail address. |
password | stringnullable | Password. |
PublicMerchantAddressDtoObject#
A saved pickup address of a merchant.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | Address id. |
label | stringnullable | Short label. |
contactName | stringnullable | Contact person at the address. |
contactPhone | stringnullable | Phone at the address. |
country | PublicNamedRef | A catalog entry shown in both languages. |
city | PublicNamedRef | A catalog entry shown in both languages. |
district | PublicNamedRef | A catalog entry shown in both languages. |
addressLine | stringnullable | Street, building and landmark. |
shortAddress | stringnullable | Saudi national short address. |
latitude | number (double)nullable | Latitude. |
longitude | number (double)nullable | Longitude. |
isPrimary | 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.
| Field | Type | Description |
|---|---|---|
labelrequired | stringnullable | Short label of the address, for example "Main warehouse". Required, up to 100 characters. Example: |
contactName | stringnullable | Person to contact at this address (defaults to the merchant name). Example: |
contactPhonerequired | stringnullable | Phone at this address. Required. Example: |
country | stringnullable | Country id, ISO code or name. Optional when the city name is unambiguous. Example: |
cityrequired | stringnullable | City id, code or name. Required. Example: |
districtrequired | stringnullable | District id, code or name. Required. Unknown districts are never created: you get Example: |
addressLinerequired | stringnullable | Street, building and landmark. Required, up to 500 characters. Example: |
shortAddressconditional | stringnullable | Saudi national short address (4 letters and 4 digits). Required for addresses in Saudi Arabia. Example: |
latitude | number (double)nullable | Latitude (optional). Example: |
longitude | number (double)nullable | Longitude (optional). Example: |
PublicMerchantDtoObject#
A merchant of the company (no banking, commission, API keys or pricing details).
| Field | Type | Description |
|---|---|---|
id | string (uuid) | Merchant id. |
name | stringnullable | Account name. |
contactName | stringnullable | Contact person. |
contactPhone | stringnullable | Contact phone. |
contactEmail | stringnullable | Contact email. |
isActive | boolean | Whether the merchant can book shipments. |
createdAt | string (date-time) | Creation time (UTC). |
primaryAddress | PublicMerchantAddressDto | A saved pickup address of a merchant. |
PublicMerchantDtoPublicPageObject#
Standard paged response of every public list endpoint.
| Field | Type | Description |
|---|---|---|
items | array<PublicMerchantDto>nullable | Items of the requested page. |
page | integer (int32) | Current page number, starting at 1. |
pageSize | integer (int32) | Requested page size (1 to 100, default 25). |
totalCount | integer (int32) | Total number of items across all pages. |
totalPages | integer (int32) | Total number of pages. |
PublicMerchantRefObject#
A merchant reference.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | Merchant id. |
name | stringnullable | Merchant account name. |
PublicMeResponseObject#
Identity and permissions of the current caller.
| Field | Type | Description |
|---|---|---|
authMethod | stringnullable |
|
company | PublicCompanyDto | Company identity shown by the public |
user | PublicUserDto | The user behind a password-authenticated call. |
apiKey | PublicApiKeyDto | The API key behind a key-authenticated call. |
scopes | array<string>nullable | API scopes granted (for password callers: the scopes the user's permissions cover). |
permissions | array<string>nullable | Permission codes held by the caller. |
PublicNamedRefObject#
A catalog entry shown in both languages.
| Field | Type | Description |
|---|---|---|
id | string (uuid)nullable | Catalog id, or null for legacy shipments that only stored a name. |
nameAr | stringnullable | Arabic name. |
nameEn | stringnullable | English name. |
PublicOrderSourceEnum#
How the order reached the system.
Values: dashboardexcelImportmerchantPortalapiintegrationinviteLinkpublicWebsitephonewhatsAppsocialMediawalkInother
PublicParcelDtoObject#
Parcel data of a shipment.
| Field | Type | Description |
|---|---|---|
weightKg | number (double) | Actual weight. |
lengthCm | number (double) | Length. |
widthCm | number (double) | Width. |
heightCm | number (double) | Height. |
chargeableWeightKg | number (double) | Weight used for pricing: the larger of actual and volumetric weight. |
pieces | integer (int32) | Number of pieces. |
description | stringnullable | What is inside. |
declaredValue | number (double) | Declared value. |
fragile | boolean | Fragile. |
requiresColdChain | boolean | Needs cold chain. |
coldChainRange | enum | Temperature range of cold-chain goods. Values: |
flammable | boolean | Flammable. |
hazardous | boolean | Hazardous. |
containsAlcohol | boolean | Contains alcohol. |
liquid | boolean | Liquid. |
highValue | boolean | High value. |
PublicParcelInputObject#
The parcel. Weight and dimensions describe the whole shipment.
| Field | Type | Description |
|---|---|---|
weightKgrequired | number (double) | Actual weight in kilograms, greater than 0. Example: |
lengthCmrequired | number (double) | Length in centimetres, greater than 0. Example: |
widthCmrequired | number (double) | Width in centimetres, greater than 0. Example: |
heightCmrequired | number (double) | Height in centimetres, greater than 0. Example: |
pieces | integer (int32)nullable | Number of pieces (default 1). Example: |
description | stringnullable | What is inside (optional, shown on the label). Example: |
declaredValue | number (double)nullable | Declared value of the goods (default 0). Example: |
fragile | boolean | Fragile goods. Example: |
requiresColdChainconditional | boolean | Needs cold chain; then Example: |
coldChainRange | enum | Temperature range of cold-chain goods. Values: |
flammable | boolean | Flammable goods. Example: |
hazardous | boolean | Hazardous goods. Example: |
containsAlcohol | boolean | Contains alcohol. Example: |
liquid | boolean | Liquid goods. Example: |
highValue | boolean | High-value goods. Example: |
PublicPaymentDtoObject#
Payment data of a shipment.
| Field | Type | Description |
|---|---|---|
codAmount | number (double) | Cash to collect from the recipient. |
shippingFee | number (double) | Shipping fee computed from the rate card. |
freightOnDelivery | boolean | True when the recipient pays the fee. |
PublicPaymentInputObject#
Cash on delivery and freight payment.
| Field | Type | Description |
|---|---|---|
codAmount | number (double)nullable | Amount the courier collects from the recipient (cash on delivery). Default 0. Must be 0 for Example: |
freightOnDelivery | booleannullable | True when the recipient pays the shipping fee on delivery. Example: |
PublicPickupInputObject#
The pickup address.
| Field | Type | Description |
|---|---|---|
country | stringnullable | Country id, ISO code or name. Optional when the city name is unambiguous. Example: |
cityrequired | stringnullable | City id, code or name. Required. Example: |
districtrequired | stringnullable | District id, code or name. Required. Unknown districts are never created: you get Example: |
addressLinerequired | stringnullable | Street, building and landmark. Required, up to 500 characters. Example: |
shortAddressconditional | stringnullable | Saudi national short address: 4 letters and 4 digits. Required when the city is in Saudi Arabia. Example: |
latitude | number (double)nullable | Latitude, -90 to 90 (optional). Example: |
longitude | number (double)nullable | Longitude, -180 to 180 (optional). Example: |
branch | stringnullable | Branch that handles the pickup: branch id, code or name. Optional; by default the branch covering the pickup
district is chosen automatically ( Example: |
PublicPieceDtoObject#
One piece of a shipment.
| Field | Type | Description |
|---|---|---|
barcode | stringnullable | Piece barcode (the tracking number followed by |
PublicQuoteDtoObject#
A price quote. Nothing is created or consumed: no tracking number, no quota.
| Field | Type | Description |
|---|---|---|
deliverable | boolean | False when the company does not cover the pickup or the destination (see |
reason | stringnullable |
|
shippingFee | number (double)nullable | Shipping fee without the COD fee (weight price plus handling surcharges). |
codFee | number (double)nullable | Fee charged for collecting cash on delivery. |
total | number (double)nullable | What the shipment will be charged: |
chargeableWeightKg | number (double)nullable | The larger of actual and volumetric weight. |
zone | PublicZoneRef | A pricing zone. |
breakdown | array<PublicQuoteLineDto>nullable | Price lines; they add up to |
PublicQuoteLineDtoObject#
One line of a price.
| Field | Type | Description |
|---|---|---|
code | stringnullable |
|
label | stringnullable | Readable label (the handling flag name for |
amount | 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.
| Field | Type | Description |
|---|---|---|
country | stringnullable | Country id, ISO code or name. Optional when the city name is unambiguous. Example: |
cityrequired | stringnullable | City id, code or name. Required. Example: |
district | stringnullable | District id, code or name. Optional for a quote; when sent it must exist. Example: |
PublicQuoteRequestObject#
Body of POST /pricing/quote.
| Field | Type | Description |
|---|---|---|
merchantconditional | 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 Example: |
pickup | PublicQuoteLocationInput | A place given by names for a quote. Each level accepts an id, a code or a name in Arabic or English. |
recipient | PublicQuoteLocationInput | A place given by names for a quote. Each level accepts an id, a code or a name in Arabic or English. |
parcel | PublicParcelInput | The parcel. Weight and dimensions describe the whole shipment. |
payment | PublicPaymentInput | Cash on delivery and freight payment. |
serviceType | enum | Kind of service requested for a shipment. Values: |
serviceTier | enum | Speed of the service; it drives the estimated delivery date. Values: |
PublicRecipientDtoObject#
The recipient.
| Field | Type | Description |
|---|---|---|
name | stringnullable | Recipient name. |
phone | stringnullable | Recipient phone. |
secondaryPhone | stringnullable | Second phone. |
country | PublicNamedRef | A catalog entry shown in both languages. |
city | PublicNamedRef | A catalog entry shown in both languages. |
district | PublicNamedRef | A catalog entry shown in both languages. |
addressLine | stringnullable | Street, building and landmark. |
shortAddress | stringnullable | Saudi national short address. |
latitude | number (double)nullable | Latitude. |
longitude | number (double)nullable | Longitude. |
PublicRecipientInputObject#
The recipient and the delivery address.
| Field | Type | Description |
|---|---|---|
country | stringnullable | Country id, ISO code or name. Optional when the city name is unambiguous. Example: |
cityrequired | stringnullable | City id, code or name. Required. Example: |
districtrequired | stringnullable | District id, code or name. Required. Unknown districts are never created: you get Example: |
addressLinerequired | stringnullable | Street, building and landmark. Required, up to 500 characters. Example: |
shortAddressconditional | stringnullable | Saudi national short address: 4 letters and 4 digits. Required when the city is in Saudi Arabia. Example: |
latitude | number (double)nullable | Latitude, -90 to 90 (optional). Example: |
longitude | number (double)nullable | Longitude, -180 to 180 (optional). Example: |
namerequired | stringnullable | Recipient name. Required, up to 200 characters. Example: |
phonerequired | stringnullable | Recipient phone. Required; digits, spaces, +, - and brackets. Example: |
secondaryPhone | stringnullable | Second phone (optional). Example: |
PublicRefreshRequestObject#
Request to exchange a refresh token for a new token pair.
| Field | Type | Description |
|---|---|---|
refreshToken | stringnullable | The refresh token returned by login or by a previous refresh (single use). |
PublicResolvedLocationDtoObject#
Result of validating a location by names.
| Field | Type | Description |
|---|---|---|
country | PublicGeoNodeDto | A resolved geography node (id and both names). |
city | PublicGeoNodeDto | A resolved geography node (id and both names). |
district | PublicGeoNodeDto | A resolved geography node (id and both names). |
PublicSenderDtoObject#
The sender of a shipment.
| Field | Type | Description |
|---|---|---|
type | enum | Who sends the shipment. Values: |
name | stringnullable | Sender name. |
phone | stringnullable | Sender phone. |
email | stringnullable | Sender email. |
merchant | PublicMerchantRef | A merchant reference. |
PublicSenderInputObject#
The sender of a shipment.
| Field | Type | Description |
|---|---|---|
type | enum | Who sends the shipment. Values: |
merchant | stringnullable | For Example: |
name | stringnullable | For Example: |
phone | stringnullable | For Example: |
email | stringnullable | For Example: |
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.
| Field | Type | Description |
|---|---|---|
trackingNumber | stringnullable | Tracking number; identifies the shipment in every route. |
reference | stringnullable | Your order reference. |
status | stringnullable | Status key, e.g. |
statusCode | integer (int32) | Numeric status code. |
statusLabelAr | stringnullable | Arabic status label. |
statusLabelEn | stringnullable | English status label. |
isFinal | boolean | True when the shipment reached a final status. |
serviceType | enum | Kind of service requested for a shipment. Values: |
serviceTier | enum | Speed of the service; it drives the estimated delivery date. Values: |
source | enum | How the order reached the system. Values: |
createdAt | string (date-time) | Creation time (UTC). |
estimatedDeliveryDate | string (date)nullable | Estimated delivery date (yyyy-MM-dd), when known. |
sender | PublicSenderDto | The sender of a shipment. |
pickup | PublicAddressDto | A resolved address. |
recipient | PublicRecipientDto | The recipient. |
parcel | PublicParcelDto | Parcel data of a shipment. |
delivery | PublicDeliveryOptionsDto | Handover rules. |
payment | PublicPaymentDto | Payment data of a shipment. |
pieces | array<PublicPieceDto>nullable | The pieces. |
branch | PublicBranchRef | A branch reference. |
canCancel | boolean | True while the shipment can still be cancelled. |
isEditable | boolean | True while the shipment can still be edited. |
PublicShipmentSummaryDtoObject#
A shipment row of the list endpoint.
| Field | Type | Description |
|---|---|---|
trackingNumber | stringnullable | Tracking number. |
reference | stringnullable | Your order reference. |
status | stringnullable | Status key. |
statusLabelAr | stringnullable | Arabic status label. |
statusLabelEn | stringnullable | English status label. |
merchant | PublicMerchantRef | A merchant reference. |
senderName | stringnullable | Sender name. |
recipientName | stringnullable | Recipient name. |
recipientPhone | stringnullable | Recipient phone. |
city | PublicNamedRef | A catalog entry shown in both languages. |
district | PublicNamedRef | A catalog entry shown in both languages. |
codAmount | number (double) | Cash on delivery amount. |
shippingFee | number (double) | Shipping fee. |
createdAt | string (date-time) | Creation time (UTC). |
estimatedDeliveryDate | string (date)nullable | Estimated delivery date. |
PublicShipmentSummaryDtoPublicPageObject#
Standard paged response of every public list endpoint.
| Field | Type | Description |
|---|---|---|
items | array<PublicShipmentSummaryDto>nullable | Items of the requested page. |
page | integer (int32) | Current page number, starting at 1. |
pageSize | integer (int32) | Requested page size (1 to 100, default 25). |
totalCount | integer (int32) | Total number of items across all pages. |
totalPages | integer (int32) | Total number of pages. |
PublicStatusDtoObject#
A shipment status of the catalog.
| Field | Type | Description |
|---|---|---|
code | integer (int32) | Numeric status code. |
key | stringnullable | Status key used in the API. |
nameAr | stringnullable | Arabic name. |
nameEn | stringnullable | English name. |
isFinal | boolean | True when no further status follows (delivered, returned to sender, cancelled, lost, disposed). |
PublicTokenResponseObject#
Token pair returned by login and refresh.
| Field | Type | Description |
|---|---|---|
accessToken | stringnullable | JWT to send as |
refreshToken | stringnullable | Single-use refresh token. |
tokenType | stringnullable | Always |
expiresIn | integer (int32) | Lifetime of the access token in seconds. |
PublicTrackingDtoObject#
Tracking of one shipment.
| Field | Type | Description |
|---|---|---|
trackingNumber | stringnullable | Tracking number. |
status | stringnullable | Current status key. |
statusLabelAr | stringnullable | Arabic label of the current status. |
statusLabelEn | stringnullable | English label of the current status. |
estimatedDeliveryDate | string (date)nullable | Estimated delivery date. |
events | array<PublicTrackingEventDto>nullable | Timeline, oldest first. |
PublicTrackingEventDtoObject#
One step of the status timeline.
| Field | Type | Description |
|---|---|---|
status | stringnullable | Status key. |
statusLabelAr | stringnullable | Arabic label. |
statusLabelEn | stringnullable | English label. |
at | string (date-time) | When the status was set (UTC). |
note | stringnullable | Reason, only for failed attempts, postponements, cancellation, returns, loss and damage. |
location | stringnullable | Reserved; not populated yet. |
PublicUpdateMerchantRequestObject#
Body of PUT /merchants/{id}. Only the fields you send change.
| Field | Type | Description |
|---|---|---|
name | stringnullable | New account name. Example: |
contactName | stringnullable | New contact person. Example: |
contactPhone | stringnullable | New contact phone. Example: |
contactEmail | stringnullable | New contact email. Example: |
PublicUpdateParcelInputObject#
Parcel fields that can change. Only the fields you send are changed.
| Field | Type | Description |
|---|---|---|
weightKg | number (double)nullable | Weight in kilograms. Example: |
lengthCm | number (double)nullable | Length in centimetres. Example: |
widthCm | number (double)nullable | Width in centimetres. Example: |
heightCm | number (double)nullable | Height in centimetres. Example: |
pieces | integer (int32)nullable | Number of pieces. Example: |
declaredValue | number (double)nullable | Declared value of the goods. Example: |
PublicUpdateRecipientInputObject#
Recipient fields that can change. Sending any address field re-resolves the whole address (city and district are then required).
| Field | Type | Description |
|---|---|---|
country | stringnullable | Country id, ISO code or name. Optional when the city name is unambiguous. Example: |
cityrequired | stringnullable | City id, code or name. Required. Example: |
districtrequired | stringnullable | District id, code or name. Required. Unknown districts are never created: you get Example: |
addressLinerequired | stringnullable | Street, building and landmark. Required, up to 500 characters. Example: |
shortAddressconditional | stringnullable | Saudi national short address: 4 letters and 4 digits. Required when the city is in Saudi Arabia. Example: |
latitude | number (double)nullable | Latitude, -90 to 90 (optional). Example: |
longitude | number (double)nullable | Longitude, -180 to 180 (optional). Example: |
name | stringnullable | Recipient name. Example: |
phone | stringnullable | Recipient phone. Example: |
secondaryPhone | stringnullable | Second phone. Example: |
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.
| Field | Type | Description |
|---|---|---|
reasonrequired | stringnullable | Why the shipment is edited (kept in the shipment's audit trail). Required, up to 300 characters. Example: |
reference | stringnullable | New order reference. Example: |
recipient | PublicUpdateRecipientInput | Recipient fields that can change. Sending any address field re-resolves the whole address (city and district are then required). |
parcel | PublicUpdateParcelInput | Parcel fields that can change. Only the fields you send are changed. |
payment | PublicPaymentInput | Cash on delivery and freight payment. |
PublicUserDtoObject#
The user behind a password-authenticated call.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | User id. |
name | stringnullable | Full name. |
PublicWebhookCreatedDtoObject#
A newly created subscription. The signing secret is returned here once and cannot be read again.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | Subscription id. |
merchantId | string (uuid) | The merchant whose shipments trigger the events. |
url | stringnullable | The receiving URL. |
events | array<string>nullable | Subscribed event types. |
description | stringnullable | Description. |
isActive | boolean | Whether it is active. |
createdAt | string (date-time) | Creation time (UTC). |
secret | stringnullable | Signing secret: keep it safe, use it to verify the |
PublicWebhookDtoObject#
A webhook subscription of a merchant.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | Subscription id. |
merchantId | string (uuid) | The merchant whose shipments trigger the events. |
url | stringnullable | The receiving URL. |
events | array<string>nullable | Subscribed event types. |
description | stringnullable | Description. |
isActive | boolean | False when the subscription is paused. |
createdAt | string (date-time) | Creation time (UTC). |
PublicWebhookEventDtoObject#
An event type that can be subscribed to.
| Field | Type | Description |
|---|---|---|
type | stringnullable | Event type, e.g. |
description | stringnullable | When the event is sent. |
examplePayload | anynullable | An example of the JSON body of the delivery ( |
PublicWebhookSecretDtoObject#
A rotated signing secret (shown once; the previous secret stops working immediately).
| Field | Type | Description |
|---|---|---|
secret | stringnullable | The new signing secret. |
PublicWebhookTestDtoObject#
Result of a test delivery request.
| Field | Type | Description |
|---|---|---|
queued | boolean | True when a signed |
eventType | stringnullable | The event type sent ( |
PublicZoneRefObject#
A pricing zone.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | Zone id. |
name | stringnullable | Zone name. |