Today Express API
A public API for marketplaces, online stores, WMS and ERP systems. Create delivery orders from your own system and receive statuses via webhooks: server to server, no panel login. This page is the complete and only documentation: everything a developer needs is here.
{base_url})We give it to you together with the API key. Every path in this documentation is relative to it.Overview
The integration is built around a single entity — the delivery order (order). A typical flow:
- A customer places an order with you → you call
POST /orders/and receive atracking_code. - The courier picks the parcel up from your warehouse, sets the delivery price at pickup based on actual weight and dimensions, and delivers it to the recipient; on every status change we send you a webhook.
- The customer tracks the parcel via
tracking_urlon our site (you pass the link to them yourself) — fewer “where is my order” questions.
tracking_code is the only order identifier in the API: it is used to fetch, update and cancel the order, and it is what arrives in webhooks. Responses contain no internal numeric id.price is null: the final price is set by the courier at pickup and arrives in the order.status_changed webhook with status 2 and in GET /orders/{tracking_code}/. Delivery billing is handled under the contract, outside the API.Quick start
Two requests from zero to a created order. Start with the test key.
# 1. Find the recipient city id
curl -s {base_url}/reference/locations/ \
-H "X-Api-Key: YOUR_TEST_KEY"
# 2. Create the order (save tracking_code — the order identifier —
# and info_qr_url — a ready QR to print on the parcel)
curl -s -X POST {base_url}/orders/ \
-H "X-Api-Key: YOUR_TEST_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: order-5567" \
-d '{
"external_id": "order-5567",
"to_location_id": 2,
"to_full_name": "Aibek Asanov",
"to_contact": "996700123456",
"to_address": "Vostok-5, bldg 12, apt 3"
}'Authentication
Every request requires the header:
X-Api-Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx- Keys are issued by Today Express. There are two kinds: test (sandbox) and live. The environment is not visible from the key itself — do not mix them up, store them separately.
- The key determines your company, environment and permissions. Permissions are “read” (
GETonly) or “read and write”. - Only a hash of the key is stored in the database. The full key is shown once, at issue time — save it.
- You see only your own orders and only those of your environment: a test key cannot see live orders, a live key cannot see test ones.
- Revoking or reissuing a key and your sender profile are changed by Today Express — message us and we will do it.
Conventions
| Rule | Type | Required | Description |
|---|---|---|---|
| Trailing slash | — | yes | All paths end with /. Without it → 404. |
| Content-Type | — | yes | For POST/PATCH — application/json, body in UTF-8. |
| Idempotency-Key | header | no | Header on POST /orders/, up to 128 characters: a repeat with the same value and the same body returns the same order instead of creating a duplicate. The same key with a different body → 409 idempotency_mismatch. |
| Phones | — | yes | +996 numbers only. Accepted input: 996700123456, +996 700 123 456, 0700123456; stored and returned as 996XXXXXXXXX. Another country → 400 invalid_phone. |
| Identifier | — | — | An order is addressed by tracking_code, e.g. /orders/TEKG-202610-3A5361D1ARDW/. |
| Field lengths | — | — | Address up to 256 characters, name and company up to 128, comment up to 1000, external_id up to 128. Longer → 400. |
| Price | — | — | Not sent: a price field in the input is ignored. On creation price is null; the courier sets the final price at pickup. |
| Dates | — | — | In responses — ISO-8601 with timezone. In filters — YYYY-MM-DD. |
Reference data
Cities and value codes. Cache them on your side — they rarely change.
City list
/reference/locations/Returns the company's cities. id is used in to_location_id.
[
{ "id": 2, "name": "Ош", "name_en": "Osh", "latitude": 40.53, "longitude": 72.80 }
]Enum reference
/reference/enums/Codes for package types, weight bands and statuses (see the sections below).
Orders
Create an order
/orders/Creates an order in the “Pending” status without a price. Send the Idempotency-Key header.
| Field | Type | Required | Description |
|---|---|---|---|
external_id | string | no | your order id — returned in responses and webhooks |
to_location_id | integer | yes | recipient city id (/reference/locations/) |
to_contact | string | yes | recipient phone +996, e.g. 996700123456 or +996 700 123 456 |
to_full_name | string | no | recipient name |
to_address | string | yes | recipient address |
to_company | string | no | recipient company |
view | integer | no | package type 1–5 (default 5 — Other) |
weight | integer | no | weight band 1–5 (default 5) |
amount | integer | no | number of parcels in the order (default 1) |
comment | string | no | order comment |
+996 numbers are accepted. Spaces, brackets, the plus sign and a leading 0 are stripped by us; in responses and webhooks the number is always 996XXXXXXXXX. A number from another country → 400 with code invalid_phone. Unknown fields in the body (including price) are ignored.Response (201 Created; a repeat with the same Idempotency-Key → 200 OK and the same order):
HTTP 201 Created
{
"tracking_code": "TEKG-202610-3A5361D1ARDW",
"external_id": "order-5567",
"status": 1,
"status_name": "Ожидание",
"from_location": "Бишкек",
"from_address": "Дордой, проход 2, ангар 6",
"from_contact": "996999666777",
"to_location": "Ош",
"to_address": "Vostok-5, bldg 12, apt 3",
"to_full_name": "Aibek Asanov",
"to_contact": "996700123456",
"view": 5,
"weight": 2,
"amount": 1,
"price": null,
"comment": null,
"is_sandbox": true,
"info_qr_url": "https://aircore.fra1.cdn.digitaloceanspaces.com/qr/TEKG-202610-3A5361D1ARDW.png",
"label_data_url": "{base_url}/orders/TEKG-202610-3A5361D1ARDW/label/",
"tracking_url": "https://todayexpress.kg/track/TEKG-202610-3A5361D1ARDW/",
"created_date": "2026-10-16T11:31:12+06:00",
"last_status_date": null
}price is always null. At pickup the courier weighs and inspects the parcel and sets the final price. It arrives in the order.status_changed webhook with status 2 (“Picked up”) in data.price and is returned by GET /orders/{tracking_code}/ from then on. Until then the order has no price.There is no bulk endpoint: create orders one by one, each with its own Idempotency-Key. That way every order gets its own response and its own error, and a retry after a failure is safe.
List orders
/orders/Paginated. Query filters: status (1–9), external_id, from_date, to_date (YYYY-MM-DD), page. An invalid filter value → 400.
GET /orders/?status=1&from_date=2026-10-01&page=1
{
"count": 42,
"next": "{base_url}/orders/?page=2",
"previous": null,
"results": [ { /* order object, same as in the create response */ } ]
}Order by tracking code
/orders/{tracking_code}/Returns the same order object as the create call. Someone else's order or an order from another environment → 404.
Update an order (before a courier is assigned)
/orders/{tracking_code}/Until our operator assigns a courier you can correct the recipient and parcel parameters. Editable fields: to_address, to_full_name, to_contact, comment, view, weight, amount.
Cancel an order
/orders/{tracking_code}/cancel/Possible only until our operator assigns a courier: after that the courier may already be on the way to you. The status becomes “Cancelled” (9). To cancel later, message us.
Label data
/orders/{tracking_code}/label/Returns fields as JSON and a link to a ready QR. info_qr_url is a PNG with the tracking-code QR and the Today Express logo: print it on the parcel, the warehouse and couriers find the order by it. The link is returned immediately in the create response; the file itself appears at that link within a few seconds. If you lay out the label yourself, qr_value = tracking_code — encode it into the QR. The link to this endpoint arrives in the create response as label_data_url.
{ "tracking_code": "TEKG-202610-3A5361D1ARDW", "qr_value": "TEKG-202610-3A5361D1ARDW",
"info_qr_url": "https://aircore.fra1.cdn.digitaloceanspaces.com/qr/TEKG-202610-3A5361D1ARDW.png",
"to_location": "Ош", "to_address": "…", "to_full_name": "…",
"to_contact": "996700123456", "from_location": "Бишкек",
"weight": 2, "amount": 1 }Webhooks
Instead of polling, we send a POST to your URL on events. Register a subscription, verify the signature, respond with 2xx.
Register a subscription
/webhooks/POST /webhooks/
{
"url": "https://your-store.kg/api/te-webhook",
"secret": "a_random_string_only_you_know",
"events": [] // [] = all events; or ["order.status_changed"]
}
// url — https:// only and a public address only (not localhost, not 10.x/192.168.x)
// secret — at least 16 characters; an unknown event in events → 400
HTTP 201 Created
{ "id": 3, "url": "...", "events": [], "is_active": true, "created_date": "..." }Management: GET /webhooks/ — list, PATCH /webhooks/{id}/ — change url, secret or events without recreating, DELETE /webhooks/{id}/ — disable (the delivery log is kept), GET /webhooks/deliveries/?status=failed — delivery log (tracking code, status pending / success / failed / dead, attempts, response code, error, next retry time).
Events we send
| Event | Type | Required | Description |
|---|---|---|---|
order.created | — | — | order created |
order.status_changed | — | — | status changed; the specific status is in data.status (1–9) and data.status_name. With status 2 (“Picked up”) the final data.price arrives |
order.price_changed | — | — | the price changed without a status change (e.g. an operator corrected it after pickup); new price in data.price, previous in data.previous_price |
Event body and headers
POST to your URL
Content-Type: application/json
X-TE-Event: order.status_changed
X-TE-Delivery: 445e217b-d052-4ac2-a75c-f5161b0af563
X-TE-Timestamp: 1760602930
X-TE-Signature: sha256=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b...
{
"event_id": "445e217b-d052-4ac2-a75c-f5161b0af563",
"type": "order.status_changed",
"created_at": "2026-10-16T14:22:10+06:00",
"data": {
"tracking_code": "TEKG-202610-3A5361D1ARDW",
"external_id": "order-5567",
"status": 2,
"status_name": "Забрал",
"price": 350.0,
"from_location": "Бишкек",
"to_location": "Ош",
"info_qr_url": "https://aircore.fra1.cdn.digitaloceanspaces.com/qr/TEKG-202610-3A5361D1ARDW.png",
"last_status_date": "2026-10-16T14:22:09+06:00"
}
}X-TE-Signature—sha256=+ HMAC-SHA256 with yoursecretof the string<X-TE-Timestamp>.<raw body>.X-TE-Timestamp— send time, Unix seconds. Reject requests older than 5 minutes so an intercepted webhook cannot be replayed later.X-TE-Event— event type,X-TE-Delivery— same asevent_id.- Deduplicate by
event_id: on retries the same event may arrive again.
Signature verification
// Node.js (Express). Important: the signature is computed over the RAW request body.
const crypto = require("crypto");
const SECRET = process.env.TE_WEBHOOK_SECRET;
app.post("/api/te-webhook",
express.raw({ type: "application/json" }), // get a Buffer, do not parse beforehand
(req, res) => {
const ts = req.header("X-TE-Timestamp") || "";
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.status(401).end();
const expected = "sha256=" +
crypto.createHmac("sha256", SECRET).update(ts + ".").update(req.body).digest("hex");
const got = req.header("X-TE-Signature") || "";
const ok = expected.length === got.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(got));
if (!ok) return res.status(401).end();
const event = JSON.parse(req.body.toString("utf8"));
// TODO: dedupe by event.event_id, then process
res.status(200).json({ ok: true });
});<?php // PHP
$secret = getenv('TE_WEBHOOK_SECRET');
$raw = file_get_contents('php://input'); // raw body
$ts = $_SERVER['HTTP_X_TE_TIMESTAMP'] ?? '';
if (abs(time() - (int)$ts) > 300) { http_response_code(401); exit; }
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $raw, $secret);
$got = $_SERVER['HTTP_X_TE_SIGNATURE'] ?? '';
if (!hash_equals($expected, $got)) { http_response_code(401); exit; }
$event = json_decode($raw, true);
// TODO: dedupe by $event['event_id'], then process
http_response_code(200);
echo json_encode(['ok' => true]);# Python (Flask). Compute the HMAC over request.get_data() — the raw body.
import hmac, hashlib, os, time
from flask import request, abort
SECRET = os.environ["TE_WEBHOOK_SECRET"].encode()
@app.post("/api/te-webhook")
def te_webhook():
raw = request.get_data()
ts = request.headers.get("X-TE-Timestamp", "")
if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
abort(401)
expected = "sha256=" + hmac.new(SECRET, ts.encode() + b"." + raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get("X-TE-Signature", "")):
abort(401)
event = request.get_json()
# TODO: dedupe by event["event_id"], then process
return {"ok": True}, 200Retries and reliability
- Respond with
2xxwithin 10 seconds — otherwise the delivery is considered failed. - Up to 6 attempts with increasing delays:
1m → 5m → 30m → 2h → 6h. After that the status isdeadand we stop sending. - The event is written to the log in the same transaction as the status change: if the queue or the network is down, the delivery stays
pendingand a background process sends it within a couple of minutes. If your receiver fails all 6 attempts (about 9.5 hours), the event gets thedeadstatus and will not arrive again — it is visible in the delivery log. Ordering between close events is not guaranteed — rely ondata.status, not on arrival order. - Make your handler idempotent (by
event_id) and fast; do heavy work in your own background queue. - Attempt history is visible in
GET /webhooks/deliveries/. - Missed an event (your receiver was down)? There is no separate event feed or on-demand redelivery yet — restore the current state by polling
GET /orders/(filtersstatus,from_date).
Order statuses
Arrive as status (code) and status_name. Rely on the code — names are for display.
| Code | Type | Required | Description |
|---|---|---|---|
| 1 | Pending | — | order created, waiting for a courier |
| 2 | Picked up | — | courier picked up from the sender and set the delivery price |
| 3 | At warehouse | — | accepted at the warehouse |
| 4 | Dispatched | — | sent to the destination city |
| 5 | Received | — | arrived / received in the destination city |
| 6 | Ready for delivery | — | ready to be handed to the recipient |
| 7 | Completed | — | handed over, order closed |
| 8 | Returned | — | the parcel came back to your warehouse. Intermediate statuses of the return trip are not sent: until then the order stays in its last status before the return, then goes straight to 8 with the final price |
| 9 | Cancelled | — | cancelled by you, an operator or the system: an order not picked up during the day is cancelled at 05:00 the next day (Bishkek time) |
Enum values
Package type (view)
| Code | Type | Required | Description |
|---|---|---|---|
| 1 | Document | — | |
| 2 | Envelope | — | |
| 3 | Box | — | |
| 4 | Bag | — | |
| 5 | Other | — |
Weight (weight)
| Code | Type | Required | Description |
|---|---|---|---|
| 1 | up to 1 kg | — | |
| 2 | up to 5 kg | — | |
| 3 | up to 10 kg | — | by agreement |
| 4 | up to 15 kg | — | by agreement |
| 5 | Other | — | by agreement |
The weight band is a hint for the courier and the warehouse. The courier sets the delivery price at pickup from the parcel's actual weight and dimensions.
Errors
Every error uses the same envelope. code is a machine-readable code for branching in your code, message is text for logs, fields holds per-field errors (only on 400).
HTTP 400 Bad Request
{
"error": {
"code": "invalid_phone",
"message": "Нужен номер в формате +996XXXXXXXXX",
"fields": { "to_contact": ["Нужен номер в формате +996XXXXXXXXX"] }
}
}
// Several different errors at once → code: "validation_error", all fields in fields.
// 401 / 403 / 404 / 429 come without fields.| HTTP | Type | Required | Description |
|---|---|---|---|
| 400 | validation_error | — | the body or a filter failed validation; details in fields |
| 400 | invalid_phone | — | the phone is not +996 — in fields.to_contact |
| 400 | unknown_location | — | no such to_location_id; the current list is at /reference/locations/ |
| 401 | missing_api_key | — | no X-Api-Key header |
| 401 | invalid_api_key | — | the key is wrong or revoked |
| 403 | permission_denied | — | the key has no write permission |
| 404 | not_found | — | order, subscription or path not found (including someone else's order and an order from another environment) |
| 409 | idempotency_mismatch | — | this Idempotency-Key was already used for an order with different data |
| 429 | rate_limited | — | limit exceeded; wait Retry-After seconds |
| 500 | internal_error | — | our error; retry later, we already see it in the logs |
Limits and test mode
Rate limiting
The request limit is per key (120 requests per minute by default) and shared across all our servers. When exceeded → 429 with a Retry-After header (seconds until the next attempt). Requests without a key or with an invalid key are limited separately by IP. Request body up to 2 MB, a larger request is rejected. Need a higher limit — message us.
Sandbox (test key)
The test key uses the same API, but orders are marked is_sandbox: true and never reach real couriers and operators. Test tracking codes start with TEST-, they are not shown on public tracking, and info_qr_url points to a QR rendered by our API. Test webhooks are retried 2 times instead of 6. Environments are isolated: the test key cannot see or change live orders, the live key cannot see test ones. Once everything is verified, tell us “ready” and switch to the live key.
Since sandbox orders are not moved by operators, you change their statuses yourself via the test endpoint to verify that the order.status_changed webhook arrives:
/orders/{tracking_code}/test/advance/POST /orders/TEKG-202610-3A5361D1ARDW/test/advance/ { "status": 2, "price": 350 }
→ status “Picked up” with price 350, the order.status_changed webhook arrivesWorks only for test orders; with a live key it returns 400. Walk the order through the statuses (2 → 3 → 4 → 5 → 6 → 7) and make sure the webhooks arrive and the signature matches. There is no courier in the sandbox: to test the price, pass it together with status 2, as in the example.
Get a key and support
- How do I get API access?
- Message us on WhatsApp — we will set you up as a partner and issue two keys: test (sandbox) and live. The key determines your company, environment and permissions; nothing else is needed from you.
- Do I need to poll order statuses?
- No. Register a webhook — we send a POST to your URL on every status change. Every webhook is signed (HMAC) so you can be sure the request is from us.
- Can I test before going live?
- Yes. The test (sandbox) key uses the same API, but orders are marked as test (is_sandbox=true) and never reach real couriers or operators. You move sandbox order statuses yourself via POST /orders/{tracking_code}/test/advance/ — that is how you verify order.status_changed webhooks before going live.
- Who specifies the sender address?
- We do. Your warehouse (city, address, phone) is stored in your partner profile. In the create request you send only the recipient and the parcel — we fill in the pickup address ourselves.
- Who sets the delivery price?
- The courier at pickup, from the parcel's actual weight and dimensions. In the create response price = null; the final price arrives in the order.status_changed webhook with status 2 and in GET /orders/{tracking_code}/. The price is never sent through the API.
- Will the customer get tracking notifications from Today Express?
- By default no: for API orders we do not send the recipient a tracking link — you show statuses yourself in your system (via webhooks). This is configurable: on request we can enable sending a WhatsApp tracking link directly to the recipient. For regular orders (not via the API) recipient notifications work as before.
Ready to integrate?
Message us — we will set you up as a partner and issue test and live keys. You can start with the sandbox, no commitment.
Message us on WhatsApp
