Deliveries API — assign riders and track shipments

The AgroPulse deliveries system connects orders to transporters and tracks every shipment from warehouse pickup through final drop-off. When a buyer places an order with a DELIVERY delivery type, a Delivery record is created and linked one-to-one to that order. Admins or dispatchers assign a transporter (rider), who then advances the delivery through a strict four-stage lifecycle — PENDING → PICKED_UP → IN_TRANSIT → DELIVERED — using dedicated action endpoints. On confirmation, the linked order is automatically marked COMPLETED and a RiderEarnings record is created at 10% of the order total. Every authenticated role (admin, farmer, buyer, transporter) sees only the deliveries relevant to them; admins see all.

Base path

/api/deliveries/

Endpoints

Method	Path	Description
`GET`	`/api/deliveries/`	List deliveries scoped to the authenticated user’s role
`POST`	`/api/deliveries/`	Create a new delivery for a `DELIVERY`-type order
`GET`	`/api/deliveries/{id}/`	Retrieve a single delivery with full order and transporter details
`PUT`	`/api/deliveries/{id}/`	Full update of a delivery record
`PATCH`	`/api/deliveries/{id}/`	Partial update of a delivery record
`DELETE`	`/api/deliveries/{id}/`	Delete a delivery record
`POST`	`/api/deliveries/{id}/assign_rider/`	Assign or reassign a transporter to a delivery
`POST`	`/api/deliveries/{id}/pickup_confirmation/`	Mark delivery as `PICKED_UP` and record the pickup timestamp
`POST`	`/api/deliveries/{id}/start_transit/`	Advance a picked-up delivery to `IN_TRANSIT`
`POST`	`/api/deliveries/{id}/delivery_confirmation/`	Confirm delivery, set `DELIVERED`, complete the order, and create rider earnings
`GET`	`/api/deliveries/available_riders/`	List all transporters with their current active delivery count and availability
`GET`	`/api/deliveries/my_deliveries/`	Return all deliveries assigned to the authenticated transporter
`GET`	`/api/deliveries/pending_deliveries/`	Return all deliveries with `PENDING` status (no auth required)
`GET`	`/api/deliveries/by_status/`	Filter deliveries by a specific status value (no auth required)

All endpoints except pending_deliveries and by_status require an Authorization: Bearer <token> header.

Create a delivery

The linked order must have delivery_type set to "DELIVERY". Attempting to create a delivery for a pickup order returns a 400 error.

POST /api/deliveries/

order

string

required

UUID of the order to associate with this delivery. The order must have delivery_type = "DELIVERY" and must not already have a delivery record.

transporter

string

required

UUID of the TransporterProfile to assign as the initial rider. The transporter must exist and must have fewer than 5 active deliveries.

delivery_address

string

required

Full delivery address for this shipment. Free-form text field.

delivery_status

string

default:"PENDING"

Initial status. One of PENDING, PICKED_UP, IN_TRANSIT, or DELIVERED. Defaults to PENDING when omitted.

picked_up_at

string

ISO 8601 datetime at which the rider picked up the order. Set automatically by pickup_confirmation. Nullable.

Example request

curl --request POST \
  --url https://api.agropulse.example.com/api/deliveries/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "order": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "transporter": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
    "delivery_address": "14 Adeyemi Street, Surulere, Lagos"
  }'

Example response

{
  "id": "3c4d5e6f-7a8b-9c0d-e1f2-a3b4c5d6e7f8",
  "order": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "transporter": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "transporter_name": "Emeka Okafor",
  "transporter_vehicle": "motorcycle",
  "delivery_status": "PENDING",
  "delivery_address": "14 Adeyemi Street, Surulere, Lagos",
  "buyer_name": "Amaka Nwosu",
  "farmer_name": "Chidi Eze",
  "order_total": "12500.00",
  "picked_up_at": null,
  "delivered_at": null,
  "created_at": "2026-05-13T09:15:00Z",
  "updated_at": "2026-05-13T09:15:00Z"
}

Delivery status lifecycle

A delivery moves through four statuses in strict order. Each transition is triggered by a dedicated POST action endpoint. Skipping a stage returns a 400 error.

PENDING

The delivery record has been created and a transporter is (optionally) assigned. The order is waiting to be collected. Use assign_rider at any point in this stage to set or update the transporter.

PICKED_UP

Call POST /api/deliveries/{id}/pickup_confirmation/ to advance from PENDING. The picked_up_at timestamp is recorded automatically. The delivery must currently be in PENDING status.

IN_TRANSIT

Call POST /api/deliveries/{id}/start_transit/ to advance from PICKED_UP. The transporter is now en route to the buyer. The delivery must currently be in PICKED_UP status.

DELIVERED

Call POST /api/deliveries/{id}/delivery_confirmation/ to advance from IN_TRANSIT. The delivered_at timestamp is recorded, the linked order’s order_status is set to COMPLETED, and a RiderEarnings record is created for 10% of the order total. The delivery must currently be in IN_TRANSIT status.

Assign a rider

POST /api/deliveries/{id}/assign_rider/ Assigns or replaces the transporter on a delivery. The target transporter must have fewer than 5 concurrent active deliveries (status PENDING, PICKED_UP, or IN_TRANSIT).

transporter_id

string

required

UUID of the TransporterProfile to assign.

Example request

curl --request POST \
  --url https://api.agropulse.example.com/api/deliveries/3c4d5e6f-7a8b-9c0d-e1f2-a3b4c5d6e7f8/assign_rider/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "transporter_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210"
  }'

Example response

{
  "id": "3c4d5e6f-7a8b-9c0d-e1f2-a3b4c5d6e7f8",
  "order": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "transporter": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "transporter_name": "Emeka Okafor",
  "transporter_vehicle": "motorcycle",
  "delivery_status": "PENDING",
  "delivery_address": "14 Adeyemi Street, Surulere, Lagos",
  "buyer_name": "Amaka Nwosu",
  "farmer_name": "Chidi Eze",
  "order_total": "12500.00",
  "picked_up_at": null,
  "delivered_at": null,
  "created_at": "2026-05-13T09:15:00Z",
  "updated_at": "2026-05-13T09:22:00Z"
}

If the transporter already has 5 or more active deliveries, the API returns 400 with "Transporter has reached maximum delivery capacity".

Filter deliveries

The list endpoint supports filtering, searching, and ordering via query parameters.

delivery_status

string

Filter by delivery status. One of PENDING, PICKED_UP, IN_TRANSIT, or DELIVERED.

transporter

string

Filter by transporter UUID. Returns only deliveries assigned to the specified TransporterProfile.

string

Full-text search across delivery_address and the buyer’s business_name.

ordering

string

Sort results. Accepted values: created_at, -created_at (default), delivered_at, -delivered_at.

status

string

Used exclusively with /api/deliveries/by_status/. One of PENDING, PICKED_UP, IN_TRANSIT, or DELIVERED. Returns 400 if omitted.

Example — filter by status

curl --request GET \
  --url 'https://api.agropulse.example.com/api/deliveries/?delivery_status=IN_TRANSIT&ordering=-created_at' \
  --header 'Authorization: Bearer <token>'

Example — by_status endpoint

curl --request GET \
  --url 'https://api.agropulse.example.com/api/deliveries/by_status/?status=DELIVERED'

Available riders

GET /api/deliveries/available_riders/ Returns all registered transporters with their current active delivery count and a computed is_available flag. A transporter is considered available when their active delivery count is below 5.

Example response

[
  {
    "id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
    "name": "Emeka Okafor",
    "email": "[email protected]",
    "phone": "+2348012345678",
    "vehicle_type": "motorcycle",
    "plate_number": "LG-123-AA",
    "service_area": "Lagos Island",
    "active_deliveries": 2,
    "is_available": true
  }
]

Response fields

string

required

UUID primary key of the delivery record.

order

string

required

UUID of the linked order.

transporter

string

UUID of the assigned TransporterProfile. Nullable if no rider has been assigned.

transporter_name

string

Full name of the assigned transporter’s user account. Read-only.

transporter_vehicle

string

Vehicle type of the assigned transporter (e.g. "motorcycle", "van"). Read-only.

delivery_status

string

required

Current stage in the lifecycle. One of PENDING, PICKED_UP, IN_TRANSIT, or DELIVERED.

delivery_address

string

required

Full text delivery address for this shipment.

buyer_name

string

Full name of the buyer on the linked order. Read-only.

farmer_name

string

Full name of the farmer on the linked order. Read-only.

order_total

string

Total value of the linked order as a decimal string (e.g. "12500.00"). Read-only.

picked_up_at

string

ISO 8601 datetime when the rider confirmed pickup. Set automatically by pickup_confirmation. Nullable.

delivered_at

string

ISO 8601 datetime when delivery was confirmed. Set automatically by delivery_confirmation. Nullable. Read-only.

created_at

string

required

ISO 8601 datetime when the delivery record was created. Read-only.

updated_at

string

required

ISO 8601 datetime of the most recent update to the record. Read-only.

Detail view (`GET /api/deliveries/{id}/`)

The retrieve action returns a richer DeliveryDetailSerializer with nested objects instead of flat read-only strings.

order_details

object

Show properties

string

UUID of the order.

buyer_name

string

Full name of the buyer.

farmer_name

string

Full name of the farmer.

total

string

Order total as a decimal string.

order_status

string

Current order status (e.g. "PENDING", "COMPLETED").

delivery_type

string

Order delivery type — always "DELIVERY" for records that have a linked delivery.

transporter_details

object

Show properties

string

UUID of the transporter profile.

name

string

Full name of the transporter.

string

Transporter’s email address.

phone

string

Transporter’s phone number.

vehicle_type

string

Type of vehicle used for deliveries.

plate_number

string

Vehicle plate number.

service_area

string

Geographic area the transporter operates in.

Users & Profiles

Produce & Orders

Delivery

Payments

Subscriptions

Deliveries API — assign riders and track shipments

Base path

Endpoints

Create a delivery

Example request

Example response

Delivery status lifecycle

Assign a rider

Example request

Example response

Filter deliveries

Example — filter by status

Example — by_status endpoint

Available riders

Example response

Response fields

Detail view (`GET /api/deliveries/{id}/`)

Build docs developers (and LLMs) love

Users & Profiles

Produce & Orders

Delivery

Payments

Subscriptions

Documentation Index

​Base path

​Endpoints

​Create a delivery

​Example request

​Example response

​Delivery status lifecycle

​Assign a rider

​Example request

​Example response

​Filter deliveries

​Example — filter by status

​Example — by_status endpoint

​Available riders

​Example response

​Response fields

​Detail view (GET /api/deliveries/{id}/)

Build docs developers (and LLMs) love

Base path

Endpoints

Create a delivery

Example request

Example response

Delivery status lifecycle

Assign a rider

Example request

Example response

Filter deliveries

Example — filter by status

Example — by_status endpoint

Available riders

Example response

Response fields

Detail view (`GET /api/deliveries/{id}/`)