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,
    "visit_order": [0],
    "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. It stops working 24 hours after the order is delivered or cancelled. 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 the order you sent the dropoffs, 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"
]

Dropoff order

By default the courier visits the dropoffs in the order you sent them. dropoff_order lets Govza arrange them into the shortest route:

given (default) — in the order sent;
optimized — every dropoff, in the order of the shortest route from the pickup;
optimized_keep_last — the same, but the last dropoff you sent stays last, for example a return to the warehouse.

{
  "external_order_id": "SHOP-10433",
  "routing_mode": "sequential",
  "dropoff_order": "optimized_keep_last",
  "pickup": { … },
  "dropoffs": [ … ]
}

The pickup always comes first. The route is chosen by road distance, and the delivery is priced along it. When no order is shorter than yours, the dropoffs stay as sent. The field works only with routing_mode: sequential: with parallel each dropoff is already routed from the pickup, and the request is refused with 400.

The order of visits comes back in visit_order: zero-based positions in the dropoffs array you sent, in the order the courier visits them:

"visit_order": [2, 0, 1]

Here the courier goes to the third dropoff you sent first, then to the first and the second. Everything else still follows your order: tracking_urls, dropoffs in the POST /quotes response, and index in PATCH. If you don’t specify which dropoff the buyout is for, it goes to the first dropoff in dropoffs: first in your order, not in the order of visits.

To hold a price, send POST /quotes the same dropoff_order as POST /orders: a quote made with another order does not fit the order, and the route is priced again.

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, routing mode, or dropoff_order makes Govza verify the quote_id and calculate fresh routes when needed, and the order of dropoffs with them. Once a courier has the order, the order of visits stays as it is while the number of dropoffs stays the same. Changing a name, contact, address text, comment, or buyout amount keeps the existing route and does not by itself change the delivery price.