Conventions
The rules below apply to every endpoint, so you only learn them once.
Every endpoint lives under /api/public/v1. The version is part of the path. The generated OpenAPI document is also served live at /api/public/v1/openapi.json. Write clients that ignore response fields they do not know, so that new optional fields never break them.
- Requests and responses are JSON, encoded as UTF-8. Send
Content-Type: application/jsonon requests with a body. The only exception is the shipping label, which is a PDF. - Field names are
camelCase. - Enums are strings, never numbers:
"serviceType": "delivery","serviceTier": "sameDay","status": "outForDelivery". The allowed values of every enum are listed in the schemas and in the field tables of the reference. - Identifiers are UUIDs, except the shipment tracking number, which is a string that identifies a shipment in every route.
- Names exist in both languages: place and status objects carry
nameArandnameEn(orstatusLabelArandstatusLabelEn). Pick whichever fits your interface; you do not needAccept-Languagefor that.
- Moments are ISO 8601 in UTC, for example
2026-01-15T09:30:00Z. Convert to the local time zone in your own interface. estimatedDeliveryDateis a date without time,yyyy-MM-dd.- Date filters such as
createdFromandcreatedTotake the same ISO 8601 form.
List endpoints take page (starting at 1, default 1) and pageSize (default 25, at most 100; larger values are clamped to 100) and return the same envelope:
{
"items": [],
"page": 1,
"pageSize": 25,
"totalCount": 0,
"totalPages": 0
}Loop until page reaches totalPages. A few endpoints that return a short, complete list (statuses, webhook events, a merchant's addresses) return a plain array instead; the reference shows which.
Accept-Language decides the language of the error message: Arabic by default, English when the header prefers English (Accept-Language: en). When the message is English, the Arabic text is kept in details.messageAr. The code never changes, so branch on the code, not on the text.
Limits work in two stages:
- Per client IP address, before authentication: by default 600 requests per minute. IPv6 addresses are grouped by their /64 prefix, so rotating addresses inside one prefix does not give a fresh allowance. The platform can change this ceiling.
- Per verified caller, after authentication: by default 120 requests per minute, counted per API key, or per user for password logins. Only a verified identity selects this bucket: an
X-API-Keyheader that fails verification never does.
Sign-in is limited separately: 30 requests per minute for login and 10 for refresh, per IP address (IPv6 by /64).
Both stages answer the same way. Over the limit the API answers 429 rate_limited with a Retry-After header (seconds) and details.retryAfterSeconds:
{
"code": "rate_limited",
"message": "Too many requests. Retry after the time given in the Retry-After header.",
"status": 429,
"details": {
"retryAfterSeconds": 23,
"messageAr": "طلبات كثيرة جداً. أعد المحاولة بعد المدة الموضحة في ترويسة Retry-After."
},
"traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}Wait for the time given, then retry. To stay well below the limit: cache lists that rarely change (countries, cities, districts, statuses), prefer webhooks over polling, and spread bulk jobs over time.
Numbers have upper bounds that match what the system can store; a larger value is refused with 400 validation_failed and a message such as Weight is too large. on that field:
| Field | Allowed |
|---|---|
parcel.weightKg |
greater than 0, at most 9,999,999 |
parcel.lengthCm, widthCm, heightCm |
greater than 0, each at most 100,000 |
parcel.pieces |
1 to 1000 |
parcel.declaredValue, payment.codAmount |
0 or more, at most 999,999,999,999 |
POST /shipments, POST /merchants and POST /merchants/{id}/addresses accept an optional Idempotency-Key header (X-Idempotency-Key is accepted as an alias). It makes a retry safe: if a request times out and you do not know whether it was created, send it again with the same key.
- The key is 1 to 128 printable characters without spaces. Use something stable that comes from your own data, such as
order-1001, not a fresh random value on every attempt. - The same key with the same request within 24 hours returns the first response, with the header
Idempotent-Replayed: true. No second shipment is created. - The same key with a different body answers
409 idempotency_key_reused. - Keys are scoped to your company and to the credential (API key or user). Only successful (2xx) responses are remembered, so a request that failed can be corrected and sent again with the same key.
- If the idempotency store is briefly unavailable, the request runs without that protection rather than failing.
{
"code": "idempotency_key_reused",
"message": "This Idempotency-Key was already used with a different request body.",
"status": 409,
"details": {
"messageAr": "تم استخدام مفتاح منع التكرار مع طلب مختلف."
},
"traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}Every response that is not 2xx has the same body:
{
"code": "validation_failed",
"message": "One or more fields are invalid.",
"status": 400,
"details": { "errors": { "recipient.phone": ["Recipient phone is required."] } },
"traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}| Field | Meaning |
|---|---|
code |
A stable code for programs. Generic codes such as unauthorized, or business codes in the form area.reason such as shipment.not_found |
message |
A readable text in the language described above. Show it to a developer, not blindly to an end customer |
status |
The HTTP status, repeated |
details |
Extra data that depends on the code, or null |
traceId |
Quote it when you contact support |
| Status | When |
|---|---|
400 |
The body or query is invalid: validation_failed, with details.errors mapping each field path (for example recipient.phone) to its messages. Also ambiguous_credentials when a request carries both a bearer token and an API key |
401 |
Credentials missing or wrong: unauthorized |
403 |
The credential lacks a scope (forbidden, with details.requiredScope), the API channel is off (channel_disabled), or the company is suspended (tenant_blocked) |
404 |
The resource does not exist, for example shipment.not_found |
409 |
A conflict, for example idempotency_key_reused or merchant.possible_duplicate |
422 |
The request is well formed but a business rule or a place failed, for example shipment.cannot_cancel or geo_city_not_found |
429 |
Too many requests: rate_limited |
500 |
An unexpected error: internal_error |
| Code | What to do |
|---|---|
unauthorized |
Check both headers (or the bearer token). Create a new key if it was revoked or expired |
ambiguous_credentials |
Send either Authorization: Bearer or X-API-Key with X-API-Secret, never both |
forbidden |
Add the scope named in details.requiredScope to the key |
channel_disabled |
Ask the platform to grant the channel and a company admin to switch it on |
validation_failed |
Fix every field in details.errors and resend |
rate_limited |
Wait for Retry-After, then retry |
idempotency_key_reused |
Use a new key for a new request |
geo_*_not_found, geo_*_ambiguous |
Let the user choose from details.candidates, see Places by name |
business_rule_violation |
Read message; the data breaks a rule that has no code of its own |
The full catalogue is in the error reference.
Retry network errors, 429 (after Retry-After) and 5xx, with a growing delay and always with the same Idempotency-Key on creates. Do not retry other 4xx responses unchanged: the request itself has to change first.