KunozDrop

Developers

API reference

Send an order the moment a customer checks out on your store. We confirm it by phone, ship it, collect the cash and settle your profit — you just make the call below.

Base URL

https://kunozdrop.com/api/v1/

Authentication

Create a key in your portal and send it on every request. The key is shown once — store it as an environment variable, never in client-side code.

Authorization: Api-Key kd_live_xxxxxxxxxxxxxxxx

Check your key works

curl https://kunozdrop.com/api/v1/ping/ \
  -H "Authorization: Api-Key kd_live_xxx"

{
  "ok": true,
  "seller": "Nomad Picks",
  "message": "Your API key is working."
}

Create an order

POST /api/v1/orders/create/

curl -X POST https://kunozdrop.com/api/v1/orders/create/ \
  -H "Authorization: Api-Key kd_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "KD-1001",
    "quantity": 2,
    "customer_name": "Ahmed Hassan",
    "phone": "+971501234567",
    "address": "Flat 12, Al Barsha 1",
    "city": "Dubai",
    "country": "AE",
    "selling_price": "199.00",
    "reference": "SHOP-4821"
  }'

Field	Required	Notes
`sku`	yes	Product or variant SKU. Use `items` for multiple lines.
`customer_name`	yes
`phone`	yes	Include the country code. We call this number.
`address`	yes
`city`	yes
`quantity`	no	Defaults to 1.
`country`	no	Two-letter code. Defaults to your account country.
`selling_price`	no	Defaults to your listed price. Must be at or above your cost.
`alt_phone`	no	A second number noticeably improves the confirmation rate.
`reference`	no	Your own order number. Send it — see idempotency below.
`note`	no	Passed to the courier.

Multiple products in one order:

"items": [
  { "sku": "KD-1001", "quantity": 1 },
  { "sku": "KD-1003", "quantity": 2, "selling_price": "89.00" }
]

201 Created

{
  "ok": true,
  "order": {
    "reference": "KD-260726-4F2A",
    "external_reference": "SHOP-4821",
    "status": "new",
    "total": "413.00",
    "your_profit": "148.50",
    "currency": "SAR"
  }
}

Idempotency

Send reference with your own order number. If the same reference arrives twice — a retry, a duplicated webhook, a re-run script — we return the original order instead of creating a second one. Without it, two calls make two orders and your customer gets two parcels.

A new order returns 201 with "duplicate": false. A repeat returns 200 with "duplicate": true and the original order, so your code can tell the difference without guessing.

Check an order

GET /api/v1/orders/{reference}/

Works with our reference or yours.

curl https://kunozdrop.com/api/v1/orders/SHOP-4821/ \
  -H "Authorization: Api-Key kd_live_xxx"

Returns the order with its items, status history and — once dispatched — the courier and tracking number.

List your orders

GET /api/v1/orders/?status=delivered&page=2

50 per page.

List products

GET /api/v1/products/?country=AE&winning=1

Your cost, suggested price, margin and live stock status. Sync this to keep your storefront in step with what we can actually ship.

Storefront webhooks

If you sell on Shopify or WooCommerce you do not need to write any code. Paste one URL into your store settings and orders arrive here automatically. The token in the URL is your API key — revoking the key disconnects the store.

Platform	URL to paste
Shopify	`/api/v1/hooks/shopify/YOUR_KEY/`
WooCommerce	`/api/v1/hooks/woocommerce/YOUR_KEY/`
Custom site	`/api/v1/hooks/website/YOUR_KEY/`

Step-by-step setup for each platform is in your portal under Connect my store.

Match your SKUs. Set each product's SKU in your store to the same SKU we use, for example KD-1001. That field is how we know what to ship. Lines with no matching SKU are skipped rather than failing the whole order — useful if you also sell your own items alongside ours.

Webhook endpoints answer 200 even when an order is rejected, with "ok": false and the reason. Shopify and WooCommerce retry non-2xx responses for days, and retrying will not fix a SKU that does not exist — so the failure is reported without asking for a retry. Check rejected orders in your portal.

Order statuses

`new`	Received, waiting to be called
`confirming`	Our agent is calling the customer
`confirmed`	Customer confirmed, ready to pack
`no_answer`	Could not reach them yet — we retry
`packed`	Picked and packed
`dispatched`	Handed to the courier
`out_for_delivery`	With the driver today
`delivered`	Cash collected, your wallet credited
`returned`	Came back to the warehouse
`cancelled`	Cancelled before dispatch

Errors

Every failure returns {"ok": false, "error": "..."}. The message is written to be shown to a human.

`401`	Key missing, wrong or revoked
`403`	Seller account not approved yet
`404`	No such order on your account
`422`	Order rejected — out of stock, price below cost, bad country

{
  "ok": false,
  "error": "Only 3 left of 'KD-1001', you asked for 5"
}

Stuck on something? Every call you make is logged, so send us the timestamp and we can tell you exactly what we received.