The Orders API is the transactional core of the AgroPulse platform. Buyers use it to place orders for produce from a specific farmer, and both buyers and farmers can track order progress through a lifecycle of statuses — fromDocumentation 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.
PENDING through to COMPLETED or CANCELLED. Role-based visibility is enforced automatically: buyers see only their own orders, farmers see only orders placed against their produce, and staff accounts have full access. All endpoints require a valid JWT Bearer token.
Base path
Authentication
All endpoints require a JWT Bearer token in theAuthorization header.
Endpoints
| Method | Path | Description | Auth required |
|---|---|---|---|
GET | /api/orders/ | List orders (scoped to the authenticated user) | Yes |
POST | /api/orders/ | Create a new order | Yes |
GET | /api/orders/{id}/ | Retrieve a single order with its line items | Yes |
PUT | /api/orders/{id}/ | Full update of an order | Yes |
PATCH | /api/orders/{id}/ | Partial update of an order | Yes |
DELETE | /api/orders/{id}/ | Delete an order | Yes |
GET | /api/orders/my_orders/ | Orders belonging to the authenticated user | Yes |
GET | /api/orders/pending_orders/ | All orders with status PENDING | Yes |
GET | /api/orders/by_status/ | Filter orders by a specific status value | Yes |
PATCH | /api/orders/{id}/update_status/ | Transition an order to a new status | Yes |
Create an order
POST /api/orders/
Creates a new Order record linking a buyer to a farmer. The id, order_status, created_at, and updated_at fields are set automatically. order_status always starts as PENDING.
UUID of the
BuyerProfile placing the order.UUID of the
FarmerProfile whose produce is being ordered.Total monetary value of the order. Decimal, up to 2 decimal places (e.g.,
135.00).How the order will be fulfilled. Must be one of:
PICKUP, DELIVERY.Example request
Example response
Update order status
PATCH /api/orders/{id}/update_status/
Transitions an order to a new status value. Only order_status is accepted in the request body. Supplying an invalid status value returns a 400 Bad Request with the list of valid options.
The target status for the order. Must be one of:
PENDING, PAID, PROCESSING, IN_TRANSIT, COMPLETED, CANCELLED.Order status values
| Status | Description |
|---|---|
PENDING | Order created but not yet paid for. |
PAID | Payment received; awaiting processing. |
PROCESSING | Farmer is preparing the order. |
IN_TRANSIT | Order has been dispatched and is on the way. |
COMPLETED | Order successfully delivered and fulfilled. |
CANCELLED | Order was cancelled before fulfilment. |
Example request
Example response
Filter orders
GET /api/orders/
Returns orders scoped to the authenticated user’s role. Use the query parameters below to narrow results. For a status-specific shortcut, use GET /api/orders/by_status/?status=PROCESSING.
Query parameters
Filter by buyer UUID. Returns orders placed by the specified
BuyerProfile. Admin only in practice — buyers are automatically scoped to their own profile.Filter by farmer UUID. Returns orders directed at the specified
FarmerProfile.Filter by status. One of:
PENDING, PAID, PROCESSING, IN_TRANSIT, COMPLETED, CANCELLED.Filter by delivery type. One of:
PICKUP, DELIVERY.Search term matched against
buyer__business_name and farmer__farm_name.Sort results by a field name. Supported fields:
total, created_at. Prefix with - for descending order (e.g., -created_at).Example request
Order object
UUID primary key. Auto-generated on creation, never editable.
UUID of the
BuyerProfile that placed the order.Business name of the buyer. Read-only, derived from the linked
BuyerProfile.Email of the buyer’s user account. Read-only.
UUID of the
FarmerProfile fulfilling the order.Name of the farmer’s farm. Read-only, derived from the linked
FarmerProfile.Email of the farmer’s user account. Read-only.
Total order value as a decimal string (e.g.,
"135.00").Current lifecycle status. One of:
PENDING, PAID, PROCESSING, IN_TRANSIT, COMPLETED, CANCELLED. Defaults to PENDING on creation.Fulfilment method. One of:
PICKUP, DELIVERY.ISO 8601 timestamp of order creation. Read-only.
ISO 8601 timestamp of the last update. Read-only.