Tadalal Delivery API

How it works

A customer checks out on your website. Your server posts the delivery details to tadalal. We price it, charge the merchant’s Tadalal wallet when the driver collects, and dispatch. The order appears in the merchant’s Orders page exactly as if it had been typed there by hand.

1. 1 Your customer places an order Your site handles the products, the payment and the receipt. Tadalal never sees any of that.
2. 2 Your server calls POST /orders Send the recipient, their phone and where it is going. That is the whole required payload.
3. 3 We dispatch and you poll for status Use the returned id to show live progress on your own order-tracking page.

Before you start

Four things must be true, and three of them are set up by the merchant, not by you.

• An API key. The merchant creates it in their Tadalal portal under API keys and sends it to you privately. It is shown once and cannot be recovered.
• The branch has a map location. Orders are collected from a branch, and a branch with no pin cannot be a pickup point. Portal → Branches.
• The wallet has money in it. An order is refused with INSUFFICIENT_BALANCE if the balance will not cover the delivery fee.
• You call us from a server. Never from browser JavaScript, a mobile app, or anywhere a customer could read the key.

Authentication

Every request carries the key as a bearer token. Keys look like glk_live_3f9a2b71_… — the part before the last underscore identifies the key, the rest is the secret.

Authorization: Bearer glk_live_3f9a2b71_Kj8sQ2vX...
Content-Type: application/json

Every response has the same shape

{
  "success": true,
  "data": { /* … */ }
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "…"
  }
}

Branch on error.code, never on error.message — the wording may be improved at any time, the codes will not change.

Test your key

Run this first, before writing any order code. It confirms the key, the base URL and the pickup branch in one call — which is the answer to nearly every “it isn’t working” question.

curl https://api.tadalal.app/api/v1/ping \
  -H "Authorization: Bearer $TADALAL_API_KEY"

{
  "success": true,
  "data": {
    "authenticated": true,
    "merchant": { "id": "…", "name": "Sharq Sweets" },
    "api_key": {
      "name": "Main website",
      "scopes": ["orders:write", "orders:read"],
      "pickup_branch_id": "b3f1…"
    },
    "wallet": { "balance": 412.000, "currency": "KWD" },
    "branches": [
      { "id": "b3f1…", "name": "Sharq", "located": true }
    ],
    "server_time": "2026-09-03T09:14:02.881Z"
  }
}

If any branch shows "located": false, ask the merchant to set its map pin before you send orders that collect from it.

Create an order

The one endpoint you genuinely need. Three fields are required.

Fields

* required. Pickup is never sent — it comes from the branch.

Example

curl -X POST https://api.tadalal.app/api/v1/orders \
  -H "Authorization: Bearer $TADALAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: web-order-10482" \
  -d '{
    "recipient_name": "Fatima Al-Sabah",
    "recipient_phone": "50123456",
    "delivery_address": "Salmiya, Block 10, Street 1, Building 27",
    "delivery_lat": 29.3328,
    "delivery_lng": 48.0672,
    "city": "Salmiya",
    "notes": "Second floor, ring twice",
    "external_ref": "web-order-10482"
  }'

<?php
// Runs on your server. $_ENV['TADALAL_API_KEY'] is never sent to the browser.
$payload = [
  'recipient_name'   => $order->customer_name,
  'recipient_phone'  => $order->phone,
  'delivery_address' => $order->address,
  'delivery_lat'     => $order->lat,   // from your checkout map
  'delivery_lng'     => $order->lng,
  'external_ref'     => 'web-order-' . $order->id,
];

$ch = curl_init('https://api.tadalal.app/api/v1/orders');
curl_setopt_array($ch, [
  CURLOPT_POST           => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT        => 30,
  CURLOPT_HTTPHEADER     => [
    'Authorization: Bearer ' . $_ENV['TADALAL_API_KEY'],
    'Content-Type: application/json',
    // Same value if you ever retry this same order.
    'Idempotency-Key: web-order-' . $order->id,
  ],
  CURLOPT_POSTFIELDS => json_encode($payload),
]);

$body   = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$result = json_decode($body, true);

if ($status === 201) {
  $order->update(['tadalal_id' => $result['data']['id']]);
} elseif ($result['error']['code'] === 'INSUFFICIENT_BALANCE') {
  notify_shop_owner('Top up your Tadalal wallet');
} else {
  log_error($result['error']['code'], $result['error']['message']);
}

const res = await fetch('https://api.tadalal.app/api/v1/orders', {
  method: 'POST',
  headers: {
    'Authorization':   `Bearer ${process.env.TADALAL_API_KEY}`,
    'Content-Type':    'application/json',
    // Reuse this exact value on any retry of this same order.
    'Idempotency-Key': `web-order-${order.id}`,
  },
  body: JSON.stringify({
    recipient_name:   order.customerName,
    recipient_phone:  order.phone,
    delivery_address: order.address,
    delivery_lat:     order.lat,  // from your checkout map
    delivery_lng:     order.lng,
    external_ref:     `web-order-${order.id}`,
  }),
});

const body = await res.json();

if (res.status === 201) {
  await db.orders.update(order.id, { tadalalId: body.data.id });
} else if (body.error.code === 'INSUFFICIENT_BALANCE') {
  await notifyShopOwner('Top up your Tadalal wallet');
} else {
  logger.error(body.error.code, body.error.message);
}

{
  "success": true,
  "data": {
    "id": "7c1e4f8a-2b93-4d61-9f0a-55d2c1e77b31",
    "order_number": "ORD-260903-4821",
    "external_ref": "web-order-10482",
    "status": "pending",
    "recipient": { "name": "Fatima Al-Sabah", "phone": "50123456" },
    "delivery": {
      "address": "Salmiya, Block 10, Street 1, Building 27",
      "lat": 29.3328, "lng": 48.0672
    },
    "pickup": { "address": "Sharq, Ahmad Al Jaber St", "lat": 29.3759, "lng": 47.9774 },
    "distance_km": 8.42,
    "delivery_fee": 1.750,
    "currency": "KWD",
    "driver": null,
    "placed_at": "2026-09-03T09:14:02.881Z"
  }
}

Store data.id against your own order. It is what you poll with.

Addresses & coordinates

The delivery fee is calculated from the driving distance between the branch and the drop-off. A wrong coordinate is not a cosmetic problem — it produces a wrong fare and sends a driver to the wrong place.

When you send no coordinates we look the address up. That lookup is deliberately strict: a vague address is rejected with ADDRESS_NOT_RESOLVED rather than quietly resolved to the middle of the country — which is what produces a plausible-looking 53 km delivery across the street.

"Salmiya, Block 10, Street 1, Building 27"
"Sharq, Ahmad Al Jaber Street, Kuwait City"
"Hawally, Block 4, Tunis Street"

"Kuwait"
"near the big mosque"
"Salmiya"          // area alone

Deliveries are Kuwait-only. A coordinate outside the country is refused with INVALID_DELIVERY_COORDS.

Avoiding duplicates

This is the part worth reading twice. If your request times out you do not know whether the order was created — and retrying blindly is how one customer gets two drivers and the merchant pays two fees.

Send an Idempotency-Key

Put a value that is unique to that order — your own order id works perfectly — in an Idempotency-Key header. Reuse the same value on every retry of that order.

Idempotency-Key: web-order-10482

The first request does the work. Any repeat with the same key returns the original response, byte for byte, with an Idempotent-Replay: true header. No second order, no second charge.

Keys are remembered for 24 hours. After that the same value is treated as a new request, which is correct: a retry a day later is not a retry.

The second safety net

Send external_ref as well. It is unique per merchant, so even with no idempotency key at all, replaying the same website order is refused with DUPLICATE_EXTERNAL_REF. Use both and duplicates are effectively impossible.

Which branch the order is collected from

Pickup always comes from a branch — you never send a pickup address.

The simplest setup for a multi-branch merchant is one API key per branch, each bound to its own. Then your code never mentions a branch at all.

Order status

Six values, in the order a normal delivery passes through them. Treat any value you do not recognise as “in progress” — new ones may be added.

Read an order

{reference} can be any of three things, so you never have to store an identifier you did not choose:

curl https://api.tadalal.app/api/v1/orders/web-order-10482 \
  -H "Authorization: Bearer $TADALAL_API_KEY"

The response is the same order object as on create. Once a driver is assigned, driver carries their name and phone so you can show it to your customer.

{
  "success": true,
  "data": {
    "order_number": "ORD-260903-4821",
    "status": "in_transit",
    "driver": { "name": "Ahmed K.", "phone": "66554433" },
    "picked_up_at": "2026-09-03T09:41:20.115Z",
    "delivered_at": null
  }
}

List orders

Newest first. Useful for reconciliation, not for tracking a single order.

curl "https://api.tadalal.app/api/v1/orders?status=in_transit&limit=50" \
  -H "Authorization: Bearer $TADALAL_API_KEY"

Cancel an order

Works only while the order is pending or assigned. Once the driver has collected the parcel the fee has been charged and someone is carrying it, so cancellation becomes a support conversation rather than an API call — you get NOT_CANCELLABLE.

Cancelling an already-cancelled order returns 200, not an error, so a retry is safe.

Errors

Every failure carries a stable error.code. These are the ones worth handling explicitly; anything else can be logged and retried.

Rate limits

Standard RateLimit-* headers are returned on every response. Polling one active order every 30 seconds uses about two requests a minute — well inside the limit.

Go-live checklist

• GET /ping returns 200 from your production server, not just your laptop.
• The key is in an environment variable and is not in your Git history.
• Every create sends an Idempotency-Key and an external_ref.
• You store data.id against your own order record.
• INSUFFICIENT_BALANCE alerts the shop owner instead of failing silently. This is the most common real-world failure.
• A failed order is visible to someone. A delivery that never reached us should raise an alarm on your side, not sit in a log.
• One real order end to end — placed, collected, delivered — before you switch customers over.