Check availability

POST

/availability

curl --request POST \
  --url https://api.govza.app/v1/delivery/availability \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "pickup": { "latitude": 43.342439, "longitude": 45.693597 }, "dropoffs": [ { "latitude": 43.320872, "longitude": 45.691756 } ] }'

Answers whether Govza can take a delivery from this pickup right now: whether the points are in the service area, and whether a courier is free near the pickup and how soon they would reach it. Nothing is created or reserved. Call it at checkout to decide whether to offer Govza delivery.

The courier status reflects this moment and changes minute to minute; it is not a promise, and POST /orders does not consult it.

Authorizations

• apiKey

Request Body^required

Media typeapplication/json

Coordinates only, like POST /quotes: you can check before the customer has typed an address.

object

pickup

required

object

latitude

required

number

>= -90 <= 90

longitude

required

number

>= -180 <= 180

dropoffs

Optional. Checked against the service area only.

Array<object>

default: <= 10 items

object

latitude

required

number

>= -90 <= 90

longitude

required

number

>= -180 <= 180

Example

{
  "pickup": {
    "latitude": 43.342439,
    "longitude": 45.693597
  },
  "dropoffs": [
    {
      "latitude": 43.320872,
      "longitude": 45.691756
    }
  ]
}

Responses

200

Availability was checked.

Media typeapplication/json

object

success

boolean

data

object

available

true when an order would be accepted and a courier is free near the pickup — reasons is empty exactly when this is true. limited still counts as available.

boolean

pickup

object

in_service_area

boolean

dropoffs

One entry per requested dropoff, in the same order.

Array<object>

object

in_service_area

boolean

couriers

object

status

• available — free couriers near the pickup outnumber the orders already waiting there.
• limited — someone is free, but the orders already waiting could take every one of them first; expect a longer wait.
• unavailable — no courier is free near the pickup. An order can still be created and will wait for one.

string

Allowed values: available limited unavailable

pickup_eta

Estimated minutes until a courier reaches the pickup if the order is created now: the nearest free courier’s driving time plus the usual time to accept. null when the status is unavailable.

integer

nullable

reasons

Why available is false. Empty otherwise.

Array<string>

Allowed values: outside_service_area no_couriers_nearby

checked_at

string format: date-time

Example

{
  "data": {
    "available": true,
    "pickup": {
      "in_service_area": true
    },
    "dropoffs": [
      {
        "in_service_area": true
      }
    ],
    "couriers": {
      "status": "available",
      "pickup_eta": 6
    },
    "reasons": [],
    "checked_at": "2026-10-05T12:00:00.000Z"
  }
}

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.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.

Media typeapplication/json

object

success

boolean

error

object

id

string

code

string

message

string

details

string

Example

{
  "success": false
}

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
}