Pricing

A price is calculated from the pickup and dropoff coordinates, adjusted for cargo size, by the tariff of the city the pickup is in. When the pickup is outside every Govza city, the first dropoff inside one decides.

curl -X POST https://api.govza.app/v1/delivery/quotes \
  -H "Authorization: Bearer $GOVZA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pickup":   { "latitude": 43.342439, "longitude": 45.693597 },
    "dropoffs": [{ "latitude": 43.320872, "longitude": 45.691756 }],
    "cargo_size": "M"
  }'

{
  "success": true,
  "data": {
    "quote_id": "…",
    "price": 250,
    "distance": 2400,
    "duration": 600,
    "expires_at": "2026-08-11T12:05:00.000Z",
    "dropoffs": [
      {
        "route_id": "…",
        "distance": 2400,
        "duration": 600,
        "cargo_size": "M",
        "price": 250,
        "cargo_surcharge": 50
      }
    ]
  }
}

distance is in metres and duration in seconds. A dropoff’s price is its distance price plus cargo_surcharge: here 200 for 2.4 km and 50 for size M.

The tariff table

GET /pricing returns the distance bands every price is built from — the same table the Govza app shows. Each city has its own tariff; /pricing returns the one of your company’s city.

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

{
  "success": true,
  "data": {
    "base_price": 200,
    "first_threshold_km": 3,
    "band_width_km": 2,
    "band_step": 50,
    "max_threshold_km": 15,
    "per_km_over": 35,
    "cargo_size_step_fee": 50,
    "bands": [
      { "min_km": 0,  "max_km": 3,  "price": 200, "per_km_over": null },
      { "min_km": 3,  "max_km": 5,  "price": 250, "per_km_over": null },
      { "min_km": 5,  "max_km": 7,  "price": 300, "per_km_over": null },
      { "min_km": 7,  "max_km": 9,  "price": 350, "per_km_over": null },
      { "min_km": 9,  "max_km": 11, "price": 400, "per_km_over": null },
      { "min_km": 11, "max_km": 13, "price": 450, "per_km_over": null },
      { "min_km": 13, "max_km": 15, "price": 500, "per_km_over": null },
      { "min_km": 15, "max_km": null, "price": 550, "per_km_over": 35 }
    ]
  }
}

A distance belongs to a band when it is at least min_km and less than max_km. The last band has max_km: null: beyond max_threshold_km the price is the band’s price plus per_km_over for each kilometre started. Render the table in your interface or check a quote against it, and price a concrete trip with POST /quotes: a trip picked up in another city is priced by that city’s tariff, not by your company’s table.

Cargo size

Every dropoff has a size, and each size above S adds a fixed surcharge to that dropoff’s price:

Size	What it is	Up to
`S`	Fits the courier’s thermal bag: documents, food, small items; a box with no side over 40 cm	10 kg
`M`	The thermal bag and up to two bags; a box up to 60 cm on its longest side	20 kg
`L`	The thermal bag and up to four bags	40 kg
`XL`	Larger or heavier cargo, arranged with the courier	no limit

GET /cargo-sizes returns each size with its surcharge in your company’s city:

curl https://api.govza.app/v1/delivery/cargo-sizes \
  -H "Authorization: Bearer $GOVZA_KEY"

{
  "success": true,
  "data": {
    "cargo_sizes": [
      { "cargo_size": "S",  "surcharge": 0,   "max_weight_kg": 10 },
      { "cargo_size": "M",  "surcharge": 50,  "max_weight_kg": 20 },
      { "cargo_size": "L",  "surcharge": 100, "max_weight_kg": 40 },
      { "cargo_size": "XL", "surcharge": 150, "max_weight_kg": null }
    ]
  }
}

Use it to map your own parcels to a size and to show the difference at checkout. The surcharge is the same at any distance, and discounts never reduce it: a discount applies to the distance price alone.

In a request:

a top-level cargo_size applies to every dropoff;
a dropoff may set its own cargo_size, which takes precedence;
the default is S.

The surcharge is charged per dropoff, not per order: two M dropoffs add it twice. Each leg of a quote shows its surcharge as cargo_surcharge, its price already includes it, and the quote’s price is the sum of the dropoffs. A trip picked up in another city carries that city’s surcharge.

Several dropoffs

routing_mode decides how the trip is routed:

sequential (default) — one chained trip through every dropoff in order;
parallel — each dropoff is priced independently from the pickup.

For sequential, dropoff_order can arrange the dropoffs into the shortest route, and the quote is priced along it. The default is given, the order you sent. dropoffs in the response still follow your order, and the order of visits comes back in visit_order. See Dropoff order.

How long a quote lasts

Five minutes. Pass quote_id to POST /orders to hold the price.