API reference

Quick start

Ask the delivery company for a test key, then create your first shipment. With a test key nothing is sent and no rider is involved.

curl https://api.ae.delivery/v1/shipments \
  -H "Authorization: Bearer $AED_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10042-create" \
  -H "AE-Version: 2026-09-25" \
  -d '{
    "merchant_reference": "ORDER-10042",
    "service": "next_day",
    "payment_type": "cod",
    "cod_amount": 24500,
    "receiver": { "name": "Test Receiver", "phone": "+971500000000", "language": "ar" },
    "address": { "text": "Villa 12, Street 4, Al Nahda", "emirate": "SHJ", "area": "shj-al-nahda" }
  }'

The response is the shipment, with its tracking number and tracking link. Send the same request again with the same Idempotency-Key and you get the same shipment back, not a second one.

Authentication

Send your key in the Authorization header on every request. Keys are shown once when they are made; store them like passwords.

Each key has scopes, listed with every endpoint below. A merchant key only ever sees that merchant's parcels.

Errors

Errors follow RFC 9457 (problem+json). Each has a stable code to branch on, a title in English and Arabic you can show to people, and a request id to quote to support.

HTTP/1.1 409 Conflict
Content-Type: application/problem+json
AE-Request-Id: req_4f2a91c07be3d58a6e1f

{
  "type": "https://docs.ae.delivery/errors/cancellation_window_closed",
  "title": "It is too late to cancel this parcel",
  "title_ar": "فات أوان إلغاء هذا الطرد",
  "status": 409,
  "code": "cancellation_window_closed",
  "request_id": "req_4f2a91c07be3d58a6e1f"
}

Branch on code, never on the title text. Validation errors (422) also list each field that failed in errors.

Idempotency

Send an Idempotency-Key header on POST requests so a retry never creates something twice.

• The same key with the same body returns the stored response, marked with Idempotent-Replayed: true.
• The same key with a different body is refused with idempotency_key_reused.
• The key is required on settlements; the endpoint list says where.
• Your merchant_reference is also unique per merchant, so an order can only become one shipment.

Money is integer fils

Every amount is a whole number of fils, the smallest unit of the dirham. There are no decimals anywhere in the API, and the currency is always AED.

Round in your own system before you send; a fractional amount is refused. Cash collected, fees and settlements all use the same unit, so statements add up to the fils.

Webhooks

Webhooks follow Standard Webhooks v1. Each endpoint has its own secret starting whsec_, shown once when you create the endpoint.

• Every request carries webhook-id, webhook-timestamp and webhook-signature headers.
• The signature is HMAC-SHA256 over id, timestamp and the raw body, joined by dots.
• Failed deliveries are retried for about 27.5 hours; an endpoint failing for 5 days is disabled.
• Payloads carry sequence and occurred_at, so you can put events in order and drop duplicates by webhook-id.
• Personal details of the receiver are left out unless the endpoint opts in to include_pii.

// Verify an ae.delivery webhook (Standard Webhooks v1) with Node's built-in crypto.
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWebhook(rawBody, headers, secret /* "whsec_…" */) {
  const id = headers["webhook-id"];
  const ts = headers["webhook-timestamp"];
  const sigs = String(headers["webhook-signature"] ?? "").split(" ");
  if (!id || !ts) throw new Error("missing webhook headers");
  // Reject anything older or newer than 5 minutes (replay protection).
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) throw new Error("timestamp outside tolerance");

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${ts}.${rawBody}`).digest();
  const ok = sigs.some((s) => {
    const [version, value] = s.split(",");
    if (version !== "v1" || !value) return false;
    const got = Buffer.from(value, "base64");
    return got.length === expected.length && timingSafeEqual(got, expected);
  });
  if (!ok) throw new Error("bad signature");
  return JSON.parse(rawBody); // then de-duplicate on webhook-id and order by "sequence"
}

Event catalogue (67 events)

• shipment.created
• shipment.confirmed
• shipment.updated
• shipment.status_changed
• shipment.pickup_assigned
• shipment.picked_up
• shipment.pickup_failed
• shipment.received_at_hub
• shipment.out_for_delivery
• shipment.arrived
• shipment.delivery_attempt_failed
• shipment.rescheduled
• shipment.address_changed
• shipment.on_hold
• shipment.released
• shipment.delivered
• shipment.return_initiated
• shipment.returned
• shipment.cancelled
• shipment.corrected
• pickup.created
• pickup.assigned
• pickup.completed
• pickup.failed
• pickup.cancelled
• pod.captured
• label.generated
• shipment.feedback_received
• complaint.created
• cod.collected
• cod.collection_failed
• cod.handed_over
• settlement.created
• settlement.voided
• statement.issued
• import.completed
• import.failed
• carrier.status_unmapped
• carrier.booking_failed
• webhook_endpoint.disabled
• api_key.created
• api_key.revoked
• ping
• eta.updated
• shipment.at_risk
• shipment.pickup_requested
• shipment.pickup_en_route
• shipment.pickup_arrived
• shipment.sorted
• shipment.transfer_departed
• shipment.transfer_arrived
• shipment.handed_to_carrier
• shipment.en_route
• shipment.partially_delivered
• shipment.reattempt_requested
• shipment.return_assigned
• shipment.return_out_for_delivery
• shipment.return_attempt_failed
• shipment.pieces_mismatch
• shipment.issue_reported
• shipment.exception_closed
• shipment.reopened
• shipment.exchange_created
• shipment.reverse_pickup_created
• cod.not_collected
• cod.reversed
• shipment.created_at_pickup

Merchant endpoints never receive company-only events such as cash handovers between riders and the company.

Test mode

With a test key, parcels move only when you move them. Advance a parcel one step, or run a whole scenario:

happy_path

Picked up, at the hub, out for delivery, delivered.

failed_then_delivered

The first delivery attempt fails with a reason, the second succeeds.

rto

Delivery fails and the parcel goes back to the sender.

cod_short

Delivered, but the rider collects less cash than asked, so the statement shows the difference.

curl -X POST https://api.ae.delivery/v1/test/shipments/shp_…/simulate \
  -H "Authorization: Bearer $AED_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scenario": "failed_then_delivered" }'

Scenarios are chosen by the request, never by special phone numbers. The simulator endpoints refuse live keys with test_mode_only.

Status model

A shipment has one status from this fixed set, plus a finer sub-status. The receiver wording is what the tracking page shows. The same list is served at GET /v1/meta/statuses.

A final status does not change again, except by a correction, which arrives as shipment.corrected.

Endpoints

Generated from the same route list as the OpenAPI document. Paths are relative to the base URL.