Couriers API: Fleet Management and Delivery Tracking

The Couriers API provides full fleet lifecycle management — registering couriers, updating their operational status, assigning and responding to order offers, and paginating delivery history. Assignment logic respects the MAX_ACTIVE_ORDERS_PER_COURIER and ORDER_ASSIGNMENT_TIMEOUT_SECONDS environment variables, ensuring dispatch stays within safe capacity bounds.

Environment Variables

Variable	Default	Description
`MAX_ACTIVE_ORDERS_PER_COURIER`	`1`	Maximum concurrent active orders a courier can hold. Assignment is rejected when this limit is reached.
`ORDER_ASSIGNMENT_TIMEOUT_SECONDS`	`60`	Seconds a courier has to accept or reject an order offer before it expires and is re-queued.

Permissions

Permission	Description
`couriers.read`	List couriers, view profiles, delivery history, and performance metrics
`couriers.manage`	Register, update, and delete couriers; manage fleet status and blocks
`couriers.settlements`	View courier discrepancies, close-outs, and liquidation records
`orders.assign`	Assign orders to couriers and process accept/reject offers

GET /api/v1/couriers

Returns a paginated list of couriers with optional status and date-range filters. Permission required: couriers.read

Query Parameters

page

integer

default:"1"

Page number (1-indexed).

page_size

integer

default:"20"

Number of results per page.

status

string

Filter by courier status. Common values: active, inactive, blocked.

active_only

boolean

default:"false"

When true (also accepts 1, yes, si), returns only couriers currently on shift.

start_date

string

ISO 8601 date (YYYY-MM-DD) — lower bound for registration or activity date.

end_date

string

ISO 8601 date (YYYY-MM-DD) — upper bound for registration or activity date.

curl -X GET "https://api.zippi.co/api/v1/couriers?active_only=true&status=active&page=1" \
  -H "Authorization: Bearer <token>"

Response

success

boolean

Whether the request succeeded.

data

object

Paginated courier list.

data.items

array

Array of courier profile objects.

data.total

integer

Total matching couriers.

data.page

integer

Current page number.

data.page_size

integer

Page size used.

POST /api/v1/couriers

Registers a new courier. If a courier with the same identifying info already exists, the service returns 200 OK with created: false; a genuinely new record returns 201 Created with created: true. Permission required: couriers.manage

Body

name

string

required

Full name of the courier.

phone

string

required

Mobile phone number in E.164 format (e.g. "+573001234567").

vehicle_type

string

Vehicle type. E.g. bicycle, motorcycle, car.

vehicle_plate

string

Vehicle plate number (if applicable).

city_id

integer

City ID the courier is assigned to.

notes

string

Internal notes or background check references.

curl -X POST https://api.zippi.co/api/v1/couriers \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Carlos Mejia",
    "phone": "+573001234567",
    "vehicle_type": "motorcycle",
    "vehicle_plate": "ABC123",
    "city_id": 11001
  }'

Response

success

boolean

Always true on success.

data

object

Courier record with courier_id, name, phone, status, and created flag.

data.created

boolean

true if a new record was created; false if an existing record was matched.

GET /api/v1/couriers/by-phone/

Retrieves a single courier profile by their mobile phone number. Useful for onboarding flows where the courier ID is unknown. Permission required: couriers.read

Path Parameters

phone

string

required

Phone number to look up (URL-encoded E.164, e.g. %2B573001234567).

curl -X GET "https://api.zippi.co/api/v1/couriers/by-phone/%2B573001234567" \
  -H "Authorization: Bearer <token>"

Response

success

boolean

Whether the request succeeded.

data

object

Courier profile object or null if not found.

GET /api/v1/couriers/

Retrieves the full profile and performance summary of a single courier, optionally scoped to a date window. Permission required: couriers.read

Path Parameters

courier_id

integer

required

Numeric courier ID.

Query Parameters

start_date

string

ISO 8601 date — start of performance window.

end_date

string

ISO 8601 date — end of performance window.

curl -X GET "https://api.zippi.co/api/v1/couriers/7?start_date=2024-01-01&end_date=2024-01-31" \
  -H "Authorization: Bearer <token>"

Response

success

boolean

Whether the request succeeded.

data

object

Full courier profile including courier_id, name, phone, status, vehicle_type, vehicle_plate, city_id, and optional performance metrics for the requested date window.

PATCH /api/v1/couriers/

Partially updates a courier record. Commonly used to toggle operational status (active ↔ blocked) or update vehicle details. Permission required: couriers.manage

Path Parameters

courier_id

integer

required

Numeric courier ID.

Body

status

string

New status value. Accepted values: active, inactive, blocked.

name

string

Updated display name.

phone

string

Updated phone number in E.164 format.

vehicle_type

string

Updated vehicle type.

vehicle_plate

string

Updated plate number.

notes

string

Updated internal notes.

curl -X PATCH https://api.zippi.co/api/v1/couriers/7 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"status": "blocked", "notes": "Suspended pending ID verification"}'

Response

success

boolean

Always true on success.

data

object

Updated courier record.

DELETE /api/v1/couriers/

Soft-deletes a courier from the fleet. The record is retained for audit and history purposes but the courier will no longer appear in active lists. Permission required: couriers.manage

Path Parameters

courier_id

integer

required

Numeric courier ID.

curl -X DELETE https://api.zippi.co/api/v1/couriers/7 \
  -H "Authorization: Bearer <token>"

Response

success

boolean

Always true on success.

data

object

Confirmation payload including the deleted courier’s ID and deleted_at timestamp.

POST /api/v1/couriers//assignments

Assigns an order directly to a courier. The system enforces MAX_ACTIVE_ORDERS_PER_COURIER (default 1) — if the courier is already at capacity the call returns an error. Returns 201 Created on successful assignment. Permission required: orders.assign

Path Parameters

courier_id

integer

required

Numeric ID of the courier to assign the order to.

Body

order_id

integer

required

ID of the order to assign.

note

string

Optional dispatcher note attached to the assignment event.

curl -X POST https://api.zippi.co/api/v1/couriers/7/assignments \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"order_id": 1023}'

Response

success

boolean

Always true on success.

data

object

Assignment record including assignment_id, courier_id, order_id, and assigned_at.

POST /api/v1/couriers//offers//accept

The courier (or dispatcher on their behalf) accepts a pending order offer. Once accepted the order moves to the courier’s active delivery queue. Permission required: orders.assign

Path Parameters

courier_id

integer

required

Courier ID.

order_id

integer

required

Order ID of the pending offer.

curl -X POST https://api.zippi.co/api/v1/couriers/7/offers/1023/accept \
  -H "Authorization: Bearer <token>"

Response

success

boolean

Always true on success.

data

object

Updated order and assignment state.

POST /api/v1/couriers//offers//reject

The courier (or dispatcher on their behalf) rejects a pending order offer. The order is returned to the dispatch queue for reassignment. Permission required: orders.assign

After rejection the order offer timer (ORDER_ASSIGNMENT_TIMEOUT_SECONDS, default 60) is reset and the order becomes eligible for the next available courier.

Path Parameters

courier_id

integer

required

Courier ID.

order_id

integer

required

Order ID of the pending offer.

curl -X POST https://api.zippi.co/api/v1/couriers/7/offers/1023/reject \
  -H "Authorization: Bearer <token>"

Response

success

boolean

Always true on success.

data

object

Updated order state indicating the offer was rejected and the order returned to queue.

GET /api/v1/couriers//history

Returns a paginated delivery history for a courier, optionally filtered by date range. Useful for generating courier performance reports and settlement calculations. Permission required: couriers.read

Path Parameters

courier_id

integer

required

Numeric courier ID.

Query Parameters

page

integer

default:"1"

Page number (1-indexed).

page_size

integer

default:"20"

Number of results per page.

start_date

string

ISO 8601 date — earliest delivery date to include.

end_date

string

ISO 8601 date — latest delivery date to include.

curl -X GET "https://api.zippi.co/api/v1/couriers/7/history?start_date=2024-01-01&end_date=2024-01-31&page=1" \
  -H "Authorization: Bearer <token>"

Response

success

boolean

Whether the request succeeded.

data

object

Paginated history object.

data.items

array

Array of delivery records, each with order ID, status, timestamps, and delivery fee in centavos.

data.total

integer

Total number of matching deliveries.

data.page

integer

Current page.

data.page_size

integer

Page size used.

Authentication

Marketplace & Customer

Business Portal

Operations

Documentation Index

​Environment Variables

​Permissions

​GET /api/v1/couriers

​Query Parameters

​Response

​POST /api/v1/couriers

​Body

​Response

​GET /api/v1/couriers/by-phone/

​Path Parameters

​Response

​GET /api/v1/couriers/

​Path Parameters

​Query Parameters

​Response

​PATCH /api/v1/couriers/

​Path Parameters

​Body

​Response

​DELETE /api/v1/couriers/

​Path Parameters

​Response

​POST /api/v1/couriers//assignments

​Path Parameters

​Body

​Response

​POST /api/v1/couriers//offers//accept

​Path Parameters

​Response

​POST /api/v1/couriers//offers//reject

​Path Parameters

​Response

​GET /api/v1/couriers//history

​Path Parameters

​Query Parameters

​Response

Build docs developers (and LLMs) love

Environment Variables

Permissions

GET /api/v1/couriers

Query Parameters

Response

POST /api/v1/couriers

Body

Response

GET /api/v1/couriers/by-phone/

Path Parameters

Response

GET /api/v1/couriers/

Path Parameters

Query Parameters

Response

PATCH /api/v1/couriers/

Path Parameters

Body

Response

DELETE /api/v1/couriers/

Path Parameters

Response

POST /api/v1/couriers//assignments

Path Parameters

Body

Response

POST /api/v1/couriers//offers//accept

Path Parameters

Response

POST /api/v1/couriers//offers//reject

Path Parameters

Response

GET /api/v1/couriers//history

Path Parameters

Query Parameters

Response