Orders

Creating

An order carries a pickup, one or more dropoffs, payment terms and your own identifier. The full field list is in the reference.

curl -X POST https://api.govza.app/v1/delivery/orders \
  -H "Authorization: Bearer $GOVZA_KEY" \
  -H "Content-Type: application/json" \
  -d @order.json

{
  "success": true,
  "data": {
    "external_order_id": "SHOP-10432",
    "order_code": "YB2072",
    "status": "new",
    "price": 300,
    "tracking_url": "https://track.govza.app/abc123",
    "tracking_urls": null,
    "delivered_at": null,
    "driver": null,
    "driver_location": null
  }
}

Once a driver is assigned and the order is underway, driver and driver_location are populated:

{
  "status": "in_progress",
  "delivered_at": null,
  "driver": {
    "name": "Isa",
    "phone": "+79280003396",
    "transport": { "type": "car", "make": "Toyota", "model": "Camry", "color": "white", "number": "A123BC" }
  },
  "driver_location": {
    "latitude": 43.2389,
    "longitude": 45.7127,
    "heading": 120,
    "updated_at": "2026-09-18T08:27:00.000Z"
  }
}

driver_location only appears for assigned and in_progress, and only when the position is under 30 minutes old. After delivery, delivered_at is the moment the order completed.

tracking_url is a public tracking page for the whole order. Keep it from the create response: reading an order or listing orders returns only links that already exist and never creates one. If you need a link later, ask for it explicitly:

curl -X POST https://api.govza.app/v1/delivery/orders/SHOP-10432/tracking_link \
  -H "Authorization: Bearer $GOVZA_KEY"

For a single dropoff, tracking_urls is null. For multiple dropoffs, it contains one link per dropoff, in dropoff order, or null when individual links are unavailable.

For a multi-dropoff order:

"tracking_urls": [
  "https://track.govza.app/abc123?route=8f3a1c2d",
  "https://track.govza.app/abc123?route=41b7e902"
]

Duplicate protection

external_order_id is your order identifier. Repeating a request with the same value does not create a duplicate order.

• 201 — the order was created;
• 200 — this external_order_id was already used; the original order is returned;
• 409 — a concurrent request is creating this order, retry shortly.

A retry after a network timeout is safe. Use an identifier from your own system and do not reuse one for a different delivery.

Reading status

List deliveries with:

curl 'https://api.govza.app/v1/delivery/orders?limit=20&offset=0' \
  -H "Authorization: Bearer $GOVZA_KEY"

Orders are returned newest first. limit is capped at 100 and defaults to 20.

For one order:

curl https://api.govza.app/v1/delivery/orders/SHOP-10432 \
  -H "Authorization: Bearer $GOVZA_KEY"

Statuses run:

new → assigned → in_progress → delivered

or cancelled at any point before delivery.

The response carries the current status, the price, the tracking URL, the assigned driver once there is one, and the status history.

Cancelling

curl -X POST https://api.govza.app/v1/delivery/orders/SHOP-10432/cancel \
  -H "Authorization: Bearer $GOVZA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "customer_changed_mind" }'

Editing

Use PUT /v1/delivery/orders/{external_order_id} to edit an order while its status is new or assigned. Send the same payload used to create it.

For a partial update, use PATCH and send only the fields to change:

curl -X PATCH https://api.govza.app/v1/delivery/orders/SHOP-10432 \
  -H "Authorization: Bearer $GOVZA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "comment": "Call 5 minutes ahead", "dropoffs": [{ "index": 1, "contact": { "name": "Zalina" } }] }'

Nested addresses and contacts are merged with the stored values. Send only the dropoffs that changed. index is the zero-based dropoff position; without it, the element’s position in the submitted array is used.

Changing coordinates, cargo size, or routing mode makes Govza verify the quote_id and calculate fresh routes when needed. Changing a name, contact, address text, comment, or buyout amount keeps the existing route and does not by itself change the delivery price.