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.

The Order Items API represents the individual line items that make up an order — each linking a specific Produce listing to an Order at a recorded unit price and quantity. The subtotal for each item is computed automatically on save (quantity × unit_price) and is always read-only. Visibility is role-scoped in the same way as the Orders API: buyers see items from their own orders, farmers see items from orders placed against their produce, and staff have full access. All endpoints require a valid JWT Bearer token.

​
Base path

/api/order-items/

​
Authentication

All endpoints require a JWT Bearer token in the Authorization header.

​
Endpoints

MethodPathDescriptionAuth required
GET/api/order-items/List order items (scoped to the authenticated user)Yes
POST/api/order-items/Create a new order itemYes
GET/api/order-items/{id}/Retrieve a single order item by UUIDYes
PUT/api/order-items/{id}/Full update of an order itemYes
PATCH/api/order-items/{id}/Partial update of an order itemYes
DELETE/api/order-items/{id}/Delete an order itemYes
GET/api/order-items/by_order/List all items belonging to a specific orderYes

​
Create an order item

POST /api/order-items/ Adds a line item to an existing order. The subtotal is calculated automatically as quantity × unit_price and must not be included in the request body. The id, subtotal, created_at, and updated_at fields are all read-only.
​
order
string
required
UUID of the Order this item belongs to.
​
produce
string
required
UUID of the Produce listing being ordered.
​
quantity
integer
required
Number of units of the produce item being ordered.
​
unit_price
number
required
Price per unit at the time of ordering. Decimal, up to 2 decimal places (e.g., 4.50). This is recorded independently of the produce listing’s current unit_price to preserve order history.

​
Example request

curl --request POST \
  --url https://api.agropulse.example.com/api/order-items/ \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "order": "f3a1c7e9-55b2-4d0e-c8f4-94e5g6h7i820",
    "produce": "e1c4f2a7-33d9-4b8e-a5f0-72c1d3e9b405",
    "quantity": 30,
    "unit_price": "4.50"
  }'

​
Example response

{
  "id": "a9b3d6f1-77c4-4e2a-d1g5-05h6i7j8k931",
  "order": "f3a1c7e9-55b2-4d0e-c8f4-94e5g6h7i820",
  "produce": "e1c4f2a7-33d9-4b8e-a5f0-72c1d3e9b405",
  "produce_name": "Roma Tomatoes",
  "produce_category": "VEGETABLES",
  "quantity": 30,
  "unit_price": "4.50",
  "subtotal": "135.00",
  "created_at": "2026-05-13T12:01:00.000000Z",
  "updated_at": "2026-05-13T12:01:00.000000Z"
}
subtotal is always computed server-side as quantity × unit_price. Any value you include in the request body for subtotal is ignored.

​
Fetch items by order

GET /api/order-items/by_order/ Returns all line items belonging to a specific order. Requires the order_id query parameter.
​
order_id
string
required
UUID of the order whose items you want to retrieve.

​
Example request

curl --request GET \
  --url 'https://api.agropulse.example.com/api/order-items/by_order/?order_id=f3a1c7e9-55b2-4d0e-c8f4-94e5g6h7i820' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

​
Filter order items

GET /api/order-items/ Returns order items scoped to the authenticated user’s role. Use the query parameters below to narrow results.

​
Query parameters

​
order
string
Filter by order UUID. Returns only items belonging to the specified Order.
​
produce
string
Filter by produce UUID. Returns only items that reference the specified Produce listing.
​
ordering
string
Sort results by a field name. Supported fields: unit_price, quantity, created_at. Prefix with - for descending order (e.g., -created_at).

​
Example request

curl --request GET \
  --url 'https://api.agropulse.example.com/api/order-items/?produce=e1c4f2a7-33d9-4b8e-a5f0-72c1d3e9b405&ordering=-created_at' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

​
OrderItem object

​
id
string
required
UUID primary key. Auto-generated on creation, never editable.
​
order
string
required
UUID of the parent Order.
​
produce
string
required
UUID of the Produce listing this item references.
​
produce_name
string
required
Name of the produce item. Read-only, derived from the linked Produce record.
​
produce_category
string
required
Category of the produce item. Read-only, derived from the linked Produce record. One of: VEGETABLES, FRUITS, GRAINS, DAIRY, MEAT, OTHER.
​
quantity
integer
required
Number of units ordered.
​
unit_price
string
required
Price per unit at the time the item was created, as a decimal string (e.g., "4.50").
​
subtotal
string
required
Computed total for this line item (quantity × unit_price), as a decimal string (e.g., "135.00"). Read-only.
​
created_at
string
required
ISO 8601 timestamp of item creation. Read-only.
​
updated_at
string
required
ISO 8601 timestamp of the last update. Read-only.

Build docs developers (and LLMs) love

Get started for freeTalk to us