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 subscriptions let buyers arrange recurring produce orders from a specific farmer at a chosen frequency — daily, weekly, or monthly. Once a subscription is active, the platform automatically generates SubscriptionOrder records on each cycle and tracks payment status for every order through the SubscriptionPayment model.

​
Subscription model fields

FieldTypeDescription
idUUIDPrimary key, auto-generated
buyerFKThe BuyerProfile that owns this subscription
farmerFKThe FarmerProfile supplying the produce
produceFKThe Produce item being ordered
frequencystringDelivery cadence: DAILY, WEEKLY, or MONTHLY
expected_quantityintegerNumber of units expected per order cycle
next_expected_order_datedateDate the next SubscriptionOrder is scheduled for
statusstringLifecycle state: ACTIVE, PAUSED, or CANCELLED
activebooleanTrue when the subscription is actively generating orders
subscription_start_datedateDate the subscription was created (auto-set)
subscription_end_datedateDate the subscription was cancelled; null while active

​
Create a subscription

Send a POST request to /api/subscriptions/ with the buyer’s farmer, produce, and schedule details. 
curl -X POST https://localhost:8000/api/subscriptions/ \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "farmer": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "produce": "7cb92e11-1234-4abc-b3fc-8f1d3e5c6b22",
    "frequency": "WEEKLY",
    "expected_quantity": 10,
    "next_expected_order_date": "2026-05-20"
  }'

{
  "id": "a1b2c3d4-0000-0000-0000-000000000001",
  "buyer": "9d8e7f6a-0000-0000-0000-000000000002",
  "farmer": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "produce": "7cb92e11-1234-4abc-b3fc-8f1d3e5c6b22",
  "frequency": "WEEKLY",
  "expected_quantity": 10,
  "next_expected_order_date": "2026-05-20",
  "status": "ACTIVE",
  "active": true,
  "subscription_start_date": "2026-05-13",
  "subscription_end_date": null
}
The unique_together constraint on (buyer, farmer, produce) means each buyer can hold only one subscription per farmer-produce combination. Attempting to create a duplicate returns a 400 validation error.

​
View your subscriptions

List all subscriptions visible to the authenticated user: 
curl https://localhost:8000/api/subscriptions/ \
  -H "Authorization: Bearer <access_token>"
Retrieve the subscriptions belonging to the currently authenticated buyer: 
curl https://localhost:8000/api/subscriptions/my_subscriptions/ \
  -H "Authorization: Bearer <access_token>"
You can filter the list by status, frequency, or active: 
curl "https://localhost:8000/api/subscriptions/?status=ACTIVE&frequency=WEEKLY" \
  -H "Authorization: Bearer <access_token>"

​
Pause a subscription

Pausing a subscription sets status to PAUSED and active to false. No new SubscriptionOrder records are generated while paused. 
curl -X POST https://localhost:8000/api/subscriptions/<id>/pause/ \
  -H "Authorization: Bearer <access_token>"

​
Resume a subscription

Resuming a paused subscription sets status back to ACTIVE and active to true. Order generation resumes from the next scheduled date. 
curl -X POST https://localhost:8000/api/subscriptions/<id>/resume/ \
  -H "Authorization: Bearer <access_token>"

​
Cancel a subscription

Cancelling a subscription sets status to CANCELLED, active to false, and records subscription_end_date as today. A cancelled subscription cannot be resumed. 
curl -X POST https://localhost:8000/api/subscriptions/<id>/cancel/ \
  -H "Authorization: Bearer <access_token>"

​
Subscription orders

SubscriptionOrder records are created automatically each time an active subscription fires. Each order captures the quantity, unit price, total amount, and scheduled date for that cycle.
FieldTypeDescription
idUUIDPrimary key, auto-generated
subscriptionFKThe parent Subscription
order_idUUIDOptional link to a corresponding Order record
quantityintegerUnits ordered for this cycle
unit_pricedecimalPrice per unit at the time the order was generated
total_amountdecimalquantity × unit_price
order_statusstringPENDING, CONFIRMED, DELIVERED, FAILED, or SKIPPED
scheduled_datedateThe date this order was due
List subscription orders: 
curl https://localhost:8000/api/subscription-orders/ \
  -H "Authorization: Bearer <access_token>"
Filter by subscription or status: 
curl "https://localhost:8000/api/subscription-orders/?order_status=PENDING" \
  -H "Authorization: Bearer <access_token>"
Retrieve orders due today or earlier: 
curl https://localhost:8000/api/subscription-orders/due_orders/ \
  -H "Authorization: Bearer <access_token>"

​
Subscription payments

Each SubscriptionOrder has a corresponding SubscriptionPayment record that tracks whether the buyer has paid for that cycle.
FieldTypeDescription
idUUIDPrimary key, auto-generated
subscription_orderFKOne-to-one link to the SubscriptionOrder
amountdecimalAmount charged for this payment
payment_statusstringPENDING, COMPLETED, FAILED, or REFUNDED
payment_methodstringPayment method used (default: auto)
payment_datedatetimeTimestamp of successful payment; null while pending
List subscription payments: 
curl https://localhost:8000/api/subscription-payments/ \
  -H "Authorization: Bearer <access_token>"
Filter by status: 
curl "https://localhost:8000/api/subscription-payments/?payment_status=PENDING" \
  -H "Authorization: Bearer <access_token>"

Build docs developers (and LLMs) love

Get started for freeTalk to us