Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/OluwagbeminiyiA/agro_pulse-API/llms.txt

Use this file to discover all available pages before exploring further.

AgroPulse ties every delivery to a single order and moves it through a four-stage status lifecycle. Farmers create deliveries when an order is ready to ship; riders confirm pickup and transit; delivery confirmation closes the order and calculates rider earnings automatically.

​
Delivery status lifecycle

StatusMeaning
PENDINGDelivery created, waiting for a rider to be assigned and pick up the order
PICKED_UPRider has collected the produce from the farmer
IN_TRANSITRider is en route to the buyer
DELIVEREDProduce has been delivered; order marked COMPLETED

​
Delivery model fields

FieldTypeDescription
idUUIDPrimary key, auto-generated
orderFKOne-to-one link to the Order being delivered
transporterFKThe assigned TransporterProfile (nullable)
delivery_statusstringCurrent status: PENDING, PICKED_UP, IN_TRANSIT, or DELIVERED
delivery_addresstextDestination address for the delivery
picked_up_atdatetimeTimestamp set when pickup is confirmed; null before pickup
delivered_atdatetimeTimestamp set when delivery is confirmed; null before delivery

​
Create a delivery

POST to /api/deliveries/ with the order ID, transporter ID, and delivery address. Only orders with delivery_type set to DELIVERY are eligible. 
curl -X POST https://localhost:8000/api/deliveries/ \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "order": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "transporter": "7cb92e11-1234-4abc-b3fc-8f1d3e5c6b22",
    "delivery_address": "12 Market Street, Lagos, Nigeria"
  }'

{
  "id": "a1b2c3d4-0000-0000-0000-000000000001",
  "order": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "transporter": "7cb92e11-1234-4abc-b3fc-8f1d3e5c6b22",
  "delivery_status": "PENDING",
  "delivery_address": "12 Market Street, Lagos, Nigeria",
  "picked_up_at": null,
  "delivered_at": null,
  "created_at": "2026-05-13T10:00:00Z"
}

​
Find available riders

Retrieve all transporter profiles along with their current workload. A transporter is considered available when they have fewer than 5 active deliveries (status PENDING, PICKED_UP, or IN_TRANSIT). 
curl https://localhost:8000/api/deliveries/available_riders/ \
  -H "Authorization: Bearer <access_token>"

[
  {
    "id": "7cb92e11-1234-4abc-b3fc-8f1d3e5c6b22",
    "name": "Emeka Okafor",
    "email": "[email protected]",
    "phone": "+2348012345678",
    "vehicle_type": "motorcycle",
    "plate_number": "LSD-123AB",
    "service_area": "Lagos Island",
    "active_deliveries": 2,
    "is_available": true
  }
]

​
Assign a rider

Assign or reassign a transporter to a delivery by providing the transporter_id in the request body. Assignment fails if the transporter already has 5 active deliveries. 
curl -X POST https://localhost:8000/api/deliveries/<id>/assign_rider/ \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "transporter_id": "7cb92e11-1234-4abc-b3fc-8f1d3e5c6b22"
  }'

​
Track delivery status

Move a delivery through each stage using the dedicated action endpoints.
1

Confirm pickup — PENDING → PICKED_UP

The rider calls this endpoint after collecting the produce from the farmer. The picked_up_at timestamp is recorded.
curl -X POST https://localhost:8000/api/deliveries/<id>/pickup_confirmation/ \
  -H "Authorization: Bearer <access_token>"
This endpoint returns 400 if the delivery is not in PENDING status.
2

Start transit — PICKED_UP → IN_TRANSIT

The rider calls this endpoint when they begin driving to the buyer.
curl -X POST https://localhost:8000/api/deliveries/<id>/start_transit/ \
  -H "Authorization: Bearer <access_token>"
This endpoint returns 400 if the delivery is not in PICKED_UP status.
3

Confirm delivery — IN_TRANSIT → DELIVERED

The rider calls this endpoint on successful drop-off. AgroPulse automatically sets delivered_at, updates the linked order’s order_status to COMPLETED, and creates a RiderEarnings record worth 10% of the order total.
curl -X POST https://localhost:8000/api/deliveries/<id>/delivery_confirmation/ \
  -H "Authorization: Bearer <access_token>"
This endpoint returns 400 if the delivery is not in IN_TRANSIT status.
delivery_confirmation triggers automatic escrow release: the linked order’s status is set to COMPLETED and a RiderEarnings record is created for the transporter. No separate escrow call is needed.

​
Filter deliveries

Filter the delivery list by status using the delivery_status query parameter: 
curl "https://localhost:8000/api/deliveries/?delivery_status=IN_TRANSIT" \
  -H "Authorization: Bearer <access_token>"
Retrieve only the deliveries assigned to the authenticated transporter: 
curl https://localhost:8000/api/deliveries/my_deliveries/ \
  -H "Authorization: Bearer <access_token>"
Retrieve all deliveries currently in PENDING status (publicly accessible): 
curl https://localhost:8000/api/deliveries/pending_deliveries/
You can also search by delivery_address or buyer business name, and order results by created_at or delivered_at: 
curl "https://localhost:8000/api/deliveries/?search=Lagos&ordering=-created_at" \
  -H "Authorization: Bearer <access_token>"

Build docs developers (and LLMs) love

Get started for freeTalk to us