Orders

1. General

All requests are sent to {BASE_URL}/api/v2/orders/.... The base URL and token are provided by Starex.

Authorization: Bearer {TOKEN}
Content-Type: application/json
Accept: application/json
Accept-Language: en

Methods:

2. Delivery type

The service field defines where the shipment is delivered and which other fields become required.

District and branch IDs come from the Dictionaries section.

3. Price calculation

Lets you check the delivery price before creating an order.

POST {BASE_URL}/api/v2/orders/calculate

Request parameters

Request example

POST {BASE_URL}/api/v2/orders/calculate
Authorization: Bearer {TOKEN}
Content-Type: application/json

{
  "sender_district_id": 12,
  "sender_address": "Amir Temur street, 1",
  "receiver_district_id": 45,
  "receiver_address": "Mustaqillik street, 20",
  "weight": 1.5,
  "service": 1
}

Response (200)

{
  "success": true,
  "data": {
    "price": 4500000,
    "from_town": { "code": 3922, "name": "TASHKENT" },
    "to_town": { "code": 3969, "name": "SAMARKAND" },
    "mass": 1.5,
    "service": { "code": 1, "name": "Courier delivery" }
  }
}

4. Creating an order

Creates a new shipment and returns its barcode.

POST {BASE_URL}/api/v2/orders/create

Request parameters

^* Technically the field may be omitted, but then the shipment goes out without a destination — always send 1 or 2.

^** At least one of receiver_person or receiver_company must be provided.

Request example (to the door)

POST {BASE_URL}/api/v2/orders/create
Authorization: Bearer {TOKEN}
Content-Type: application/json

{
  "sender_district_id": 12,
  "sender_person": "Ali Valiyev",
  "sender_phone": "998901234567",
  "sender_address": "Amir Temur street, 1",
  "receiver_district_id": 45,
  "receiver_person": "Vali Aliyev",
  "receiver_phone": "998907654321",
  "receiver_address": "Mustaqillik street, 20",
  "weight": 1.5,
  "service": 1
}

Request example (to a pickup point)

{
  "sender_district_id": 12,
  "sender_person": "Ali Valiyev",
  "sender_phone": "998901234567",
  "receiver_branch_id": 7,
  "receiver_person": "Vali Aliyev",
  "receiver_phone": "998907654321",
  "weight": 1.5,
  "service": 2
}

Response (200)

{
  "success": true,
  "data": {
    "order_code": "AB123456789UZ",
    "price": 4500000,
    "api_response": {
      "orderNo": "123456",
      "barcode": "AB123456789UZ",
      "error": 0,
      "errorMessage": null,
      "errorMessageRu": null,
      "orderPrice": 45000
    }
  }
}

Example of a failed creation:

{
  "success": true,
  "data": {
    "order_code": null,
    "price": null,
    "api_response": {
      "orderNo": null,
      "barcode": null,
      "error": 1,
      "errorMessage": "Wrong town code",
      "errorMessageRu": "Неверный код города",
      "orderPrice": null
    }
  }
}

5. Shipment statuses

Returns the status history of a single shipment by its barcode.

GET {BASE_URL}/api/v2/orders/trace

GET {BASE_URL}/api/v2/orders/trace?barcode=AB123456789UZ
Authorization: Bearer {TOKEN}
Accept: application/json

Response (200)

{
  "success": true,
  "data": {
    "barcode": "AB123456789UZ",
    "date": "2026-06-10 09:00:00",
    "weight": 1.5,
    "recipient": "Vali Aliyev",
    "trace": [
      { "code": 1, "name": "Новый",     "advanced": "NEW",      "statetime": "2026-06-10 09:00:00", "branch": "Tashkent central warehouse", "description": "Order accepted" },
      { "code": 9, "name": "Доставлен", "advanced": "COMPLETE", "statetime": "2026-06-15 14:30:00", "branch": "Samarkand branch",           "description": "Delivered to the recipient" }
    ]
  }
}

If the barcode is not found:

{
  "success": false,
  "error": {
    "code": -404,
    "message": "Data not found"
  }
}

6. Status codes

Every shipment status is identified by a numeric code. The same codes are used in three places:

• trace[].code in the shipment statuses response;
• state inside the webhook payload;
• code in the status dictionary.

The dictionary request resolves the codes:

GET {BASE_URL}/api/v2/dictionaries/states

{
  "success": true,
  "data": [
    { "code": 0, "name": "Ожидает синхронизации", "advanced": "AWAITING_SYNC" },
    { "code": 1, "name": "Новый",                  "advanced": "NEW" },
    { "code": 9, "name": "Доставлен",              "advanced": "COMPLETE" }
  ]
}

7. Errors

On failure the response contains success = false and an error object:

{
  "success": false,
  "error": {
    "code": -2006,
    "message": "District is required"
  }
}