Skip to content
Govza Partner API

Create a delivery

POST
/orders
curl --request POST \
  --url https://api.govza.app/v1/partner/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "external_order_id": "SHOP-GROZNY-20260811-001", "quote_id": "5c1f5b14-7915-4f3c-8544-9869b3f04f36", "pickup": { "address": { "latitude": 43.342439, "longitude": 45.693597, "area": "Грозный", "street": "А. А. Айдамирова", "building": "123" }, "contact": { "value": "+79280003396", "name": "Адам", "type": "phone" } }, "dropoffs": [ { "address": { "latitude": 43.320872, "longitude": 45.691756, "area": "Грозный", "street": "С. Ш. Лорсанова", "building": "12", "apartment": 18, "entrance": 2, "floor": 3, "instructions": "Позвонить за 10 минут" }, "contact": { "value": "+79280003396", "name": "Милана", "type": "phone" }, "cargo_size": "M", "payment_type": "cash", "payment_amount": 1500, "doorstep": false }, { "address": { "latitude": 43.351021, "longitude": 45.69154, "area": "Грозный", "street": "А. А. Айдамирова", "building": "147к3", "apartment": 7, "entrance": 1, "floor": 2 }, "contact": { "value": "+79280003396", "name": "Залина", "type": "whatsapp" }, "cargo_size": "S", "payment_type": "card", "doorstep": true } ], "cargo_size": "M", "routing_mode": "sequential", "delivery_time": "2026-08-12T12:00:00Z", "comment": "Позвонить за 10 минут до приезда" }'

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Unlike POST /quotes, creating a delivery needs full structured addresses and contact details — someone has to be found at the door.

object
external_order_id
required

Your identifier. Reusing one returns the original order.

string
<= 128 characters
quote_id

A quote_id from POST /quotes. Honoured only while the whole quote is still valid; otherwise the trip is re-priced and the response carries the new price.

string format: uuid
pickup
required
object
address
required
object
latitude
required

Required. Decides routing and price.

number
>= -90 <= 90
longitude
required
number
>= -180 <= 180
area
required

City or locality.

string
Example
Грозный
street
required
string
Example
проспект Путина
building
required

House or building number, as text.

string
Example
12к3
apartment

Whole number only. Put anything else in instructions.

integer
nullable
entrance
integer
nullable
floor
integer
nullable
intercom
string
nullable <= 64 characters
instructions

Free text shown to the courier.

string
nullable <= 1000 characters
Example
{
  "latitude": 43.342439,
  "longitude": 45.693597,
  "area": "Грозный",
  "street": "А. А. Айдамирова",
  "building": "123",
  "apartment": 12,
  "entrance": 2,
  "floor": 3,
  "instructions": "Позвонить при входе"
}
contact
required
object
value
required

Phone number or messaging handle. E.164 preferred for phone contacts.

string
Example
+79280003396
name
string
nullable
type
string
default: phone
Allowed values: phone whatsapp telegram
Example
{
  "value": "+79280003396",
  "name": "Адам",
  "type": "phone"
}
dropoffs
required
Array<object>
>= 1 items <= 10 items
object
address
required
object
latitude
required

Required. Decides routing and price.

number
>= -90 <= 90
longitude
required
number
>= -180 <= 180
area
required

City or locality.

string
Example
Грозный
street
required
string
Example
проспект Путина
building
required

House or building number, as text.

string
Example
12к3
apartment

Whole number only. Put anything else in instructions.

integer
nullable
entrance
integer
nullable
floor
integer
nullable
intercom
string
nullable <= 64 characters
instructions

Free text shown to the courier.

string
nullable <= 1000 characters
Example
{
  "latitude": 43.342439,
  "longitude": 45.693597,
  "area": "Грозный",
  "street": "А. А. Айдамирова",
  "building": "123",
  "apartment": 12,
  "entrance": 2,
  "floor": 3,
  "instructions": "Позвонить при входе"
}
contact
required
object
value
required

Phone number or messaging handle. E.164 preferred for phone contacts.

string
Example
+79280003396
name
string
nullable
type
string
default: phone
Allowed values: phone whatsapp telegram
Example
{
  "value": "+79280003396",
  "name": "Адам",
  "type": "phone"
}
cargo_size
string
Allowed values: S M L XL
payment_type

How the courier pays for the goods bought out at this door.

string
Allowed values: cash card
payment_amount

Item buyout amount in RUB for this dropoff. Omit or null when there is no buyout.

number
nullable
doorstep
boolean
cargo_size
string
default: M
Allowed values: S M L XL
routing_mode
string
default: sequential
Allowed values: parallel sequential
payment_type

Buyout payment method. Applied to the first dropoff when not set there.

string
default: cash
Allowed values: cash card
payment_amount

Item buyout amount in RUB. Applied to the first dropoff when not set there.

number
nullable
delivery_time

For a scheduled delivery. Omit for as-soon-as-possible.

string format: date-time
nullable
comment

Shown to the courier.

string
nullable <= 2000 characters
Example
{
  "external_order_id": "SHOP-GROZNY-20260811-001",
  "quote_id": "5c1f5b14-7915-4f3c-8544-9869b3f04f36",
  "pickup": {
    "address": {
      "latitude": 43.342439,
      "longitude": 45.693597,
      "area": "Грозный",
      "street": "А. А. Айдамирова",
      "building": "123"
    },
    "contact": {
      "value": "+79280003396",
      "name": "Адам",
      "type": "phone"
    }
  },
  "dropoffs": [
    {
      "address": {
        "latitude": 43.320872,
        "longitude": 45.691756,
        "area": "Грозный",
        "street": "С. Ш. Лорсанова",
        "building": "12",
        "apartment": 18,
        "entrance": 2,
        "floor": 3,
        "instructions": "Позвонить за 10 минут"
      },
      "contact": {
        "value": "+79280003396",
        "name": "Милана",
        "type": "phone"
      },
      "cargo_size": "M",
      "payment_type": "cash",
      "payment_amount": 1500,
      "doorstep": false
    },
    {
      "address": {
        "latitude": 43.351021,
        "longitude": 45.69154,
        "area": "Грозный",
        "street": "А. А. Айдамирова",
        "building": "147к3",
        "apartment": 7,
        "entrance": 1,
        "floor": 2
      },
      "contact": {
        "value": "+79280003396",
        "name": "Залина",
        "type": "whatsapp"
      },
      "cargo_size": "S",
      "payment_type": "card",
      "doorstep": true
    }
  ],
  "cargo_size": "M",
  "routing_mode": "sequential",
  "delivery_time": "2026-08-12T12:00:00Z",
  "comment": "Позвонить за 10 минут до приезда"
}

Responses

Section titled “Responses”

200

Section titled “200”

This external_order_id was already used; the original order is returned unchanged and nothing new was created.

Media typeapplication/json
object
success
boolean
data
object
external_order_id
string
order_code

The human-readable Govza order code.

string
status
string
Allowed values: new assigned in_progress delivered cancelled
price
number
nullable
tracking_url

Public tracking page, safe to forward to the recipient. Present on create; when reading or listing, null if the order has no link yet — reads never create one. Use POST /orders/{external_order_id}/tracking_link to issue one.

string
nullable
tracking_urls

Individual tracking pages in dropoff order. Null for a single-dropoff order or when unavailable.

Array<string>
nullable
Example
{
  "data": {
    "status": "new"
  }
}

201

Section titled “201”

The delivery was created.

Media typeapplication/json
object
success
boolean
data
object
external_order_id
string
order_code

The human-readable Govza order code.

string
status
string
Allowed values: new assigned in_progress delivered cancelled
price
number
nullable
tracking_url

Public tracking page, safe to forward to the recipient. Present on create; when reading or listing, null if the order has no link yet — reads never create one. Use POST /orders/{external_order_id}/tracking_link to issue one.

string
nullable
tracking_urls

Individual tracking pages in dropoff order. Null for a single-dropoff order or when unavailable.

Array<string>
nullable
Example
{
  "data": {
    "status": "new"
  }
}

400

Section titled “400”

The payload was rejected. error.details is a JSON array of { field, message } covering every offending field, not just the first, so one response is enough to fix the request.

Media typeapplication/json
object
success
boolean
error
object
id
string
code
string
message
string
details
string
Example
{
  "success": false,
  "error": {
    "id": "validation.partner_payload_invalid",
    "message": "dropoffs.0.address.latitude: latitude is required",
    "details": "[{\"field\":\"dropoffs.0.address.latitude\",\"message\":\"latitude is required\"}]"
  }
}

401

Section titled “401”

The key is missing, malformed, revoked, or its account can no longer create orders.

Media typeapplication/json
object
success
boolean
error
object
id
string
code
string
message
string
details
string
Example
{
  "success": false
}

409

Section titled “409”

A concurrent request is already creating this order. Retry shortly.

429

Section titled “429”

Too many requests for this key in the current minute.

Media typeapplication/json
object
success
boolean
error
object
id
string
code
string
message
string
details
string
Example
{
  "success": false
}