RapidXpk Integration API

Overview

Every request goes to https://api.rapidxpk.com/v1/… with your key in a header. You send each order with your own reference in external_id. RapidXpk answers with its order number (RXK-123456) and a public tracking link you can share with your customer.

Sending the same external_id twice never makes a second parcel: you get the first order back. That makes retries after a timeout safe.

curl https://api.rapidxpk.com/v1/health

Keys and auth

Send your key in the X-API-Key header on every call. RapidXpk issues two kinds of key when you are onboarded:

Keep keys on your server. Never put them in a website or mobile app. If a key leaks, ask RapidXpk to revoke it and issue a new one.

Order statuses

Charges follow attempts at the door. An order cancelled before it went out costs nothing.

Create an order

curl -X POST https://api.rapidxpk.com/v1/orders \
  -H "X-API-Key: rxp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "SHOP-10482",
    "customer": {
      "name": "Sana Malik",
      "phone": "03001234567",
      "address": "House 12, Street 5, DHA Phase 6, Karachi"
    },
    "items": [{ "sku": "VC-30", "name": "Vitamin C Serum 30ml", "qty": 2 }],
    "payment_method": "cod",
    "cod_amount": 4900,
    "notes": "Call on arrival"
  }'

{
  "order_id": "RXK-482915",
  "external_id": "SHOP-10482",
  "status": "received",
  "mode": "live",
  "tracking_url": "https://rapidxpk.com/track.html?tn=RXK-482915",
  "created_at": "2026-10-22T07:15:02Z"
}

Create in bulk

{ "orders": [ { "external_id": "SHOP-10483", … }, { "external_id": "SHOP-10484", … } ] }

{
  "count": 2,
  "results": [
    { "index": 0, "ok": true,  "result": { "order_id": "RXK-482916", … } },
    { "index": 1, "ok": false, "result": { "error": "invalid_phone", "field": "customer.phone", … } }
  ]
}

Resend only the ones with "ok": false after fixing them. The others are already in.

Get one order

{
  "order_id": "RXK-482915",
  "external_id": "SHOP-10482",
  "status": "failed_attempt",
  "reason": "Customer not home",
  "attempts": 1,
  "packed_at": "2026-10-22T08:02:11Z",
  "dispatched_at": "2026-10-22T10:40:05Z",
  "delivered_at": null,
  "returned_at": null,
  "updated_at": "2026-10-22T13:21:47Z",
  "cod": { "amount": 4900, "collected": false, "settled": false },
  "tracking_url": "https://rapidxpk.com/track.html?tn=RXK-482915"
}

cod.collected turns true when the rider's cash reaches RapidXpk. cod.settled turns true when it is paid out to you.

Sync changes

If you cannot receive webhooks, poll for every order that changed since your last call.

{
  "orders": [ { /* same shape as Get one order */ } ],
  "count": 200,
  "next_since": "2026-10-22T09:14:03.551210Z",
  "next_id": 48211,
  "has_more": true
}

Call again with updated_since=next_since and after_id=next_id while has_more is true. Save both values for your next poll. Every five minutes is plenty.

Cancel an order

Webhooks

Give us one public HTTPS address and we post every status change to it, normally within a few minutes.

The address must be https:// on port 443 and reachable from the internet. Local and private addresses are refused.

Events

order.received, order.packed, order.dispatched, order.delivered, order.failed_attempt, order.rto, order.returned, order.cancelled.

{
  "event": "order.delivered",
  "order_id": "RXK-482915",
  "external_id": "SHOP-10482",
  "status": "delivered",
  "previous_status": "dispatched",
  "reason": null,
  "attempts": 2,
  "occurred_at": "2026-10-23T12:05:40Z",
  "packed_at": "2026-10-22T08:02:11Z",
  "dispatched_at": "2026-10-23T10:12:09Z",
  "delivered_at": "2026-10-23T12:05:40Z",
  "returned_at": null,
  "cod": { "amount": 4900, "collected": false, "settled": false },
  "tracking_url": "https://rapidxpk.com/track.html?tn=RXK-482915"
}

Answer quickly

Reply with any 2xx within 12 seconds, then do your own work. Anything else counts as a failure and we try again after 1, 2, 4, 8 minutes and so on, up to every 6 hours, for 12 attempts in all. GET /v1/webhooks shows the last error, and you can always catch up with Sync changes.

Verify a delivery

Check the signature against the raw request body before you trust it, and refuse anything signed more than 5 minutes ago.

const crypto = require('crypto');

// rawBody: the exact bytes we sent, before JSON parsing
function isFromRapidXpk(headers, rawBody, secret) {
  const ts = headers['x-rapidxpk-timestamp'];
  const sig = headers['x-rapidxpk-signature'] || '';
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(ts + '.' + rawBody).digest('hex');
  return sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

$raw = file_get_contents('php://input');
$ts  = $_SERVER['HTTP_X_RAPIDXPK_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_RAPIDXPK_SIGNATURE'] ?? '';
$ok  = abs(time() - (int)$ts) <= 300
    && hash_equals('sha256=' . hash_hmac('sha256', $ts . '.' . $raw, $secret), $sig);
if (!$ok) { http_response_code(401); exit; }
http_response_code(200);   // then process $raw

Shopify

No code needed. Your RapidXpk portal gives you a personal webhook address under Connect orders → Shopify.

1. In Shopify admin open Settings → Notifications → Webhooks and choose Create webhook.
2. Event: Order creation. Format: JSON. Paste the address from your portal.
3. Copy the signing secret Shopify shows under the webhooks list into the portal (Connect orders → Store settings). We use it to check every order really came from your store.
4. Place a test order. It appears in the portal under Connect orders → Incoming orders, with product pictures, ready for RapidXpk to confirm.

Odoo 18

Odoo's built-in webhook action cannot send headers, so it uses an address with your key in the path:

Odoo sends only the sale order number. Save an Odoo API user in the portal (Connect orders → Odoo) and we read the full order from your Odoo and create the delivery. Without it the call is accepted with 202 and the answer explains the next step. Your RapidXpk contact has the full Odoo setup guide.

Errors

Every error has the same shape, and message is written to be shown to a person:

{ "error": "missing_field", "field": "customer.name", "message": "customer.name is required." }

Limits