Dirise Delivery API

1. Get a key

We open a client account for you and create an API key on our admin page (you can make more keys yourself after logging in, under API). The key looks like dk_live_… and is shown once. Keep it on your server only: never in a web page or mobile app.

2. Basics

If your server can't send a path after v1.php, use ?path=orders/AAA111 instead.

3. Endpoints

Create an order

curl -X POST https://dirisecompany.com/order/v1.php/orders \
  -H "Authorization: Bearer dk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "SHOP-10045",
    "recipient": {
      "name": "Sara",
      "phone": "+96550000000",
      "area": "Salmiya",
      "address": "Block 10, Street 5, House 12",
      "location_url": "https://maps.google.com/?q=29.33,48.07"
    },
    "details": "2 boxes",
    "cash_on_delivery": 12.5,
    "delivery_date": "2026-10-25",
    "pickup": { "outside_warehouse": false }
  }'

Required: recipient.phone, recipient.area. If your goods are not stored with us, send "pickup": {"outside_warehouse": true, "phone": "…", "area": "…"} and our driver collects from you first.

cash_on_delivery (KWD, optional): the amount our driver collects from the recipient. Leave it out or send 0 when the order is already paid.

{
  "ok": true,
  "duplicate": false,
  "order": {
    "code": "AAB 204",
    "reference": "SHOP-10045",
    "status": "pending",
    "status_name": "Pending",
    "status_ar": "جديد",
    "created_at": "2026-10-23 21:14:07",
    "updated_at": "2026-10-23 21:14:07",
    "delivery_date": "2026-10-25",
    "pickup": { "outside_warehouse": false, "phone": "", "area": "" },
    "recipient": { "name": "Sara", "phone": "+96550000000", "area": "Salmiya", "address": "Block 10, Street 5, House 12", "location_url": "…" },
    "details": "2 boxes",
    "cash_on_delivery": 12.5,
    "driver": null,
    "source": "api"
  }
}

Sending the same reference again returns the existing order with "duplicate": true, so retries never create two orders.

Edit or cancel

curl -X PATCH https://dirisecompany.com/order/v1.php/orders/AAB204 \
  -H "Authorization: Bearer dk_live_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"recipient": {"address": "Block 11, Street 2, House 7"}, "delivery_date": "2026-10-26"}'

curl -X PATCH https://dirisecompany.com/order/v1.php/orders/AAB204 \
  -H "Authorization: Bearer dk_live_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"action": "cancel", "reason": "customer changed mind"}'

Edits are allowed while the status is pending, on_hold or processing; cancel until it is with a driver. After that you get 409 not_allowed: call us.

History

GET /orders/AAB204/events
{"ok": true, "code": "AAB 204", "events": [
  {"at": "2026-10-23 21:14:07", "from": "", "to": "pending", "note": "طلب جديد عن طريق API", "origin": "api", "by": "Your Store"},
  {"at": "2026-10-24 09:02:41", "from": "pending", "to": "in_delivery", "note": "السواق: HBM01", "origin": "dirisecompany", "by": "Ali (عامل المخزن)"},
  {"at": "2026-10-24 11:37:05", "from": "in_delivery", "to": "delivered", "note": "", "origin": "diriseapp", "by": "HBM01"}
]}

4. Statuses

5. Webhooks (we call you)

Set a webhook URL (on the admin page or with PUT /webhook). Every time one of your orders changes (status, driver, date, edits by our team), we POST this to your URL within about a minute. Your own API changes are not sent back to you.

POST https://your-site.com/dirise-webhook
Content-Type: application/json
X-Dirise-Event: order.updated
X-Dirise-Signature: 5b1f…  (hex HMAC-SHA256 of the raw body with your webhook secret)

{"event": "order.updated", "id": 8812,
 "order": { …same shape as above… },
 "change": {"at": "2026-10-24 11:37:05", "from": "in_delivery", "to": "delivered", "note": "", "origin": "diriseapp", "by": "HBM01"}}

Reply with any 2xx. If you don't, we retry after 1, 2, 4 … up to 60 minutes. Use id to ignore repeats.

Check the signature

// PHP
$body = file_get_contents('php://input');
$ok = hash_equals(hash_hmac('sha256', $body, $WEBHOOK_SECRET), $_SERVER['HTTP_X_DIRISE_SIGNATURE'] ?? '');

// Node.js
const crypto = require("crypto");
const ok = crypto.timingSafeEqual(
  Buffer.from(crypto.createHmac("sha256", WEBHOOK_SECRET).update(rawBody).digest("hex")),
  Buffer.from(req.headers["x-dirise-signature"] || ""));

6. Errors

7. Shopify, WooCommerce, Zid, Salla

Any platform that can send a webhook or run a small script can call POST /orders when an order is paid, and read our webhooks to update the order on its side. Tell us your platform and we help you set it up.