Create a delivery

POST

/orders

const url = 'https://api.govza.app/v1/delivery/orders';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"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 минут до приезда"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.govza.app/v1/delivery/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

apiKey

Request Body^required

application/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: S

Allowed values: S M L XL

routing_mode

string

default: sequential

Allowed values: parallel sequential

dropoff_order

The order the courier visits the dropoffs in. given, the default, keeps the order you sent. optimized reorders every dropoff into the shortest road route from the pickup, and the trip is priced along that route. optimized_keep_last does the same but keeps your last dropoff last. Your order stays when no other is shorter. Only for routing_mode: sequential; with parallel the request is refused.

string

default: given

Allowed values: given optimized optimized_keep_last

payment_type

Buyout payment method. 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.

string

default: cash

Allowed values: cash card

payment_amount

Item buyout amount in RUB. 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.

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

200

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

application/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. Expires 24 hours after the order is delivered or cancelled. 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, one per dropoff in your order, whatever order they are visited in. Null for a single-dropoff order or when unavailable.

Array<string>

nullable

visit_order

Zero-based positions in your dropoffs array, in the order the courier visits them. Everything else stays in your order: quote legs, tracking_urls and index in PATCH.

Array<integer>

Example

{
  "data": {
    "status": "new",
    "visit_order": [
      2,
      0,
      1
    ]
  }
}

201

The delivery was created.

application/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

string

nullable

tracking_urls

Individual tracking pages, one per dropoff in your order, whatever order they are visited in. Null for a single-dropoff order or when unavailable.

Array<string>

nullable

visit_order

Zero-based positions in your dropoffs array, in the order the courier visits them. Everything else stays in your order: quote legs, tracking_urls and index in PATCH.

Array<integer>

Example

{
  "data": {
    "status": "new",
    "visit_order": [
      2,
      0,
      1
    ]
  }
}

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.

application/json

object

success

boolean

error

object

string

code

string

message

string

details

string

Example

{
  "success": false,
  "error": {
    "id": "validation.delivery_payload_invalid",
    "message": "dropoffs.0.address.latitude: latitude is required",
    "details": "[{\"field\":\"dropoffs.0.address.latitude\",\"message\":\"latitude is required\"}]"
  }
}

401

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

application/json

object

success

boolean

error

object

string

code

string

message

string

details

string

Example

{
  "success": false
}

409

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

429

Too many requests for this key in the current minute.

application/json

object

success

boolean

error

object

string

code

string

message

string

details

string

Example

{
  "success": false
}

Create a delivery

Authorizations

Request Bodyrequired

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Responses

200

Example

201

Example

400

Example

401

Example

409

429

Example

Request Body^required