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.

Every AgroPulse account is assigned exactly one role at registration: BUYER, SELLER, or TRANSPORTER. The role is stored on the User model and determines which profile is created for the account, which endpoints the user can call, and what actions they are permitted to take. All authenticated endpoints require a valid JWT Bearer token in the Authorization header.

​
The three roles

Buyer

Places orders and pays for produce through the Squad checkout. Can be an individual, restaurant, or wholesaler.

Seller (Farmer)

Lists produce for sale, receives and processes orders, and collects earnings via escrow release and payouts.

Transporter

Picks up fulfilled orders from farms and delivers them to buyers. Receives a rider payout after delivery confirmation.

​
Farmer (SELLER)

A farmer is any user registered with role: "SELLER". On registration, a FarmerProfile is automatically linked to the user account. Profile fields
FieldTypeDescription
farm_namestringThe name of the farm or agricultural business
farm_locationstringPhysical location of the farm
trust_scoredecimal (0.00–9.99)Platform-computed reputation score based on order history
What farmers do
  • List produce items with pricing and quantity
  • Receive new order notifications when a buyer places an order
  • Move orders from PAID to PROCESSING once they begin fulfilling them
  • Have funds held in escrow after payment and released to their payout account after delivery confirmation
Typical endpoints
  • GET /api/produces/ — manage produce listings
  • GET /api/orders/ — view incoming orders
  • PATCH /api/orders/{id}/update_status/ — accept and process orders
  • GET /api/payouts/ — view payout history

​
Buyer (BUYER)

A buyer is any user registered with role: "BUYER". A BuyerProfile is linked to the account and captures purchasing context. Profile fields
FieldTypeDescription
business_namestring (optional)Name of the buyer’s business, if applicable
buyer_typeenumOne of INDIVIDUAL, RESTAURANT, or WHOLESALER
locationstringDelivery or pickup location for orders
What buyers do
  • Browse and search produce listings from farmers
  • Place orders specifying delivery_type (PICKUP or DELIVERY) and the desired produce items
  • Complete payment through a Squad-hosted checkout URL
  • Track order progress from PENDING through to COMPLETED
Typical endpoints
  • GET /api/produces/ — browse available produce
  • POST /api/orders/ — place a new order
  • POST /api/payments/initialize_payment/ — start the Squad payment flow
  • GET /api/orders/{id}/ — track order status

​
Transporter (TRANSPORTER)

A transporter is any user registered with role: "TRANSPORTER". A TransporterProfile records vehicle and coverage details. Profile fields
FieldTypeDescription
vehicle_typestringType of vehicle used for deliveries (e.g., van, motorcycle)
plate_numberstringVehicle registration plate number
service_areastringGeographic area the transporter covers
What transporters do
  • Are assigned to DELIVERY-type orders once the farmer has processed them
  • Transition deliveries through PENDING → PICKED_UP → IN_TRANSIT → DELIVERED
  • Receive a RiderEarnings record and a Payout (type RIDER) after delivery is confirmed
Typical endpoints
  • GET /api/deliveries/ — view assigned deliveries
  • POST /api/deliveries/{id}/start_transit/ — mark a delivery as in transit
  • POST /api/deliveries/{id}/delivery_confirmation/ — confirm delivery completion
  • GET /api/payouts/ — view payout history

​
Registration

Roles are set at account creation and cannot be changed after the fact. Send a POST request to /api/users/ with the role field included in the request body. 
{
  "full_name": "Amara Okafor",
  "email": "[email protected]",
  "phone_number": "+2348012345678",
  "password": "securepassword",
  "password_confirm": "securepassword",
  "role": "SELLER"
}
The API will create the corresponding profile record (FarmerProfile, BuyerProfile, or TransporterProfile) automatically. After registration, obtain a JWT token via POST /api/token/ and use it to authenticate all subsequent requests.

​
Role permissions

Role membership gates specific actions across the API:
ActionBUYERSELLERTRANSPORTER
Browse produce listingsYesYes—
Place an orderYes——
Initialize paymentYes——
Process (accept) an order—Yes—
List produce for sale—Yes—
Be assigned to a delivery——Yes
Start transit on a delivery——Yes
Confirm delivery completion——Yes
Receive farmer payouts—Yes—
Receive rider payouts——Yes
Requests that violate role boundaries return a 403 Forbidden response.

Build docs developers (and LLMs) love

Get started for freeTalk to us