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 order in AgroPulse follows a defined state machine. When a buyer places an order, it starts as PENDING and progresses through payment, fulfillment, and delivery before reaching COMPLETED. Each transition is driven by a specific API action — no state can be skipped, and any order can be moved to CANCELLED if the transaction cannot continue. Understanding this lifecycle is essential for integrating correctly with the orders, payments, and deliveries APIs.

​
Order statuses

The order_status field on the Order model can hold one of the following values:
StatusMeaning
PENDINGOrder has been placed but payment has not been received
PAIDPayment confirmed by Squad; escrow is active
PROCESSINGFarmer has accepted the order and is preparing it
IN_TRANSITA transporter has picked up the order and is en route
COMPLETEDDelivery confirmed; escrow funds released
CANCELLEDOrder was cancelled at any point before completion

​
Delivery types

The delivery_type field determines whether a transporter is involved:
ValueMeaning
PICKUPBuyer collects the order directly from the farm — no transporter is assigned
DELIVERYA transporter is assigned to collect from the farm and deliver to the buyer
PICKUP orders skip rider assignment, the IN_TRANSIT transition, and all transporter payout steps. After the farmer marks the order as PROCESSING, the buyer collecting in person triggers COMPLETED directly.

​
Full order flow

1

Buyer places an order (PENDING)

The buyer sends a POST /api/orders/ request specifying the farmer, produce items, quantities, and delivery_type. The order is created with order_status: "PENDING" and a total calculated from the OrderItem subtotals.
{
  "farmer": "<farmer_profile_id>",
  "delivery_type": "DELIVERY",
  "items": [
    { "produce": "<produce_id>", "quantity": 10 }
  ]
}
2

Buyer initializes and completes payment (PENDING → PAID)

The buyer calls POST /api/payments/initialize_payment/ with the order ID. The API creates a Payment record and contacts Squad to generate a checkout_url. The buyer is redirected to Squad’s hosted checkout to complete payment.Once payment is captured, Squad sends a webhook to POST /api/payments/webhook_callback/. The API verifies the payload, sets payment_status to SUCCESS, and advances order_status to PAID. An EscrowAccount is created simultaneously, holding the funds at release_status: "HELD".Payment status can also be checked manually:
POST /api/payments/{id}/verify_payment/
3

Farmer processes the order (PAID → PROCESSING)

The farmer reviews their incoming orders and accepts the one that has reached PAID. They update the order status via:
PATCH /api/orders/{id}/update_status/

{ "order_status": "PROCESSING" }
order_status advances to PROCESSING, signalling to the platform that fulfillment has begun.
4

Transporter picks up and starts delivery (PROCESSING → IN_TRANSIT)

(DELIVERY orders only)A transporter is assigned to the order. Once they pick up the goods from the farm, they call:
POST /api/deliveries/{id}/start_transit/
This sets the Delivery record’s delivery_status to IN_TRANSIT and advances order_status to IN_TRANSIT. The picked_up_at timestamp is recorded on the Delivery.
5

Delivery confirmed and order completed (IN_TRANSIT → COMPLETED)

When the goods are delivered, the transporter (or system) confirms delivery:
POST /api/deliveries/{id}/delivery_confirmation/
This sets delivery_status to DELIVERED, records delivered_at, and advances order_status to COMPLETED. The escrow is released (release_status → RELEASED), a PaymentSplit record is created, and Payout records are queued for the farmer and rider.

​
Cancellation

An order can be cancelled from any status before COMPLETED using: 
PATCH /api/orders/{id}/update_status/

{ "order_status": "CANCELLED" }
If the order was already PAID and escrow is active, the escrow release_status moves to DISPUTED pending resolution. Refund handling should be managed separately.

​
Key endpoints by stage

StageEndpointActor
Place orderPOST /api/orders/Buyer
Initialize paymentPOST /api/payments/initialize_payment/Buyer
Webhook callbackPOST /api/payments/webhook_callback/Squad (system)
Verify paymentPOST /api/payments/{id}/verify_payment/Buyer
Process orderPATCH /api/orders/{id}/update_status/Farmer
Start transitPOST /api/deliveries/{id}/start_transit/Transporter
Confirm deliveryPOST /api/deliveries/{id}/delivery_confirmation/Transporter
Cancel orderPATCH /api/orders/{id}/update_status/Buyer or Farmer

Build docs developers (and LLMs) love

Get started for freeTalk to us