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 Subscriptions API lets buyers set up recurring produce orders from a specific farmer at a chosen frequency — daily, weekly, or monthly. Once created, a subscription automatically tracks the next expected order date and advances it after each fulfilment cycle. Both buyers and farmers have scoped read access to their own subscriptions; staff accounts see all records. Lifecycle transitions (pause, resume, cancel) are handled through dedicated action endpoints rather than generic PATCH requests, keeping state changes explicit and auditable. All endpoints require a valid JWT Bearer token.

​
Base path

/api/subscriptions/

​
Authentication

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

​
Endpoints

MethodPathDescriptionAuth required
GET/api/subscriptions/List subscriptions scoped to the authenticated userYes
POST/api/subscriptions/Create a new subscriptionYes
GET/api/subscriptions/{id}/Retrieve a subscription with full buyer/farmer/produce detail and last 10 ordersYes
PUT/api/subscriptions/{id}/Full update of a subscriptionYes
PATCH/api/subscriptions/{id}/Partial update of a subscriptionYes
DELETE/api/subscriptions/{id}/Delete a subscriptionYes
POST/api/subscriptions/{id}/pause/Pause an active subscriptionYes
POST/api/subscriptions/{id}/resume/Resume a paused subscriptionYes
POST/api/subscriptions/{id}/cancel/Cancel a subscriptionYes
GET/api/subscriptions/my_subscriptions/Subscriptions belonging to the authenticated buyerYes
GET/api/subscriptions/active_subscriptions/All subscriptions where active is trueYes
GET/api/subscription-orders/List subscription orders scoped to the authenticated userYes
GET/api/subscription-orders/{id}/Retrieve a single subscription order with payment detailYes
GET/api/subscription-orders/pending_orders/All subscription orders with status PENDINGYes
GET/api/subscription-orders/due_orders/Orders scheduled for today or earlier that are PENDING or CONFIRMEDYes
GET/api/subscription-payments/List subscription payments scoped to the authenticated userYes
GET/api/subscription-payments/{id}/Retrieve a single subscription paymentYes
GET/api/subscription-payments/pending_payments/All subscription payments with status PENDINGYes

​
Create a subscription

POST /api/subscriptions/ Creates a new Subscription record linking a buyer to a specific farmer’s produce at a recurring frequency. The system enforces a unique_together constraint on (buyer, farmer, produce) — a buyer can hold only one active subscription per farmer-produce combination. The id, subscription_start_date, created_at, and updated_at fields are set automatically. Status defaults to ACTIVE.
​
buyer
string
required
UUID of the BuyerProfile setting up the subscription.
​
farmer
string
required
UUID of the FarmerProfile supplying the produce.
​
produce
string
required
UUID of the Produce item to receive on a recurring basis.
​
frequency
string
required
Delivery cadence. Must be one of: DAILY, WEEKLY, MONTHLY. Defaults to WEEKLY if omitted.
​
expected_quantity
integer
required
Number of units expected per delivery cycle. Defaults to 1 if omitted.
​
next_expected_order_date
string
required
ISO 8601 date (YYYY-MM-DD) of the first — or next — expected order. The date advances automatically after each cycle based on the chosen frequency.

​
Example request

curl --request POST \
  --url https://api.agropulse.example.com/api/subscriptions/ \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "buyer": "c2d5f3b8-44e0-4c9f-b6a1-83d2e4f0a716",
    "farmer": "b7d2e4f6-91c3-4a2b-8d0e-56f7a8b9c012",
    "produce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "frequency": "WEEKLY",
    "expected_quantity": 5,
    "next_expected_order_date": "2026-05-20"
  }'

​
Example response

{
  "id": "d4e5f6a7-b8c9-0123-def0-456789abcdef",
  "buyer": "c2d5f3b8-44e0-4c9f-b6a1-83d2e4f0a716",
  "buyer_name": "Kofi Mensah",
  "farmer": "b7d2e4f6-91c3-4a2b-8d0e-56f7a8b9c012",
  "farmer_name": "Amara Osei",
  "produce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "produce_name": "Tomatoes",
  "produce_price": "12.50",
  "frequency": "WEEKLY",
  "expected_quantity": 5,
  "next_expected_order_date": "2026-05-20",
  "active": true,
  "status": "ACTIVE",
  "subscription_start_date": "2026-05-13",
  "subscription_end_date": null,
  "created_at": "2026-05-13T12:00:00.000000Z",
  "updated_at": "2026-05-13T12:00:00.000000Z"
}

​
Subscription lifecycle actions

Use the action endpoints below to transition a subscription’s status. Each action accepts a POST with no request body and returns the updated subscription object.

​
Pause a subscription

POST /api/subscriptions/{id}/pause/ Sets status to PAUSED and active to false. Paused subscriptions are excluded from automated order generation. 
curl --request POST \
  --url https://api.agropulse.example.com/api/subscriptions/d4e5f6a7-b8c9-0123-def0-456789abcdef/pause/ \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "id": "d4e5f6a7-b8c9-0123-def0-456789abcdef",
  "buyer": "c2d5f3b8-44e0-4c9f-b6a1-83d2e4f0a716",
  "buyer_name": "Kofi Mensah",
  "farmer": "b7d2e4f6-91c3-4a2b-8d0e-56f7a8b9c012",
  "farmer_name": "Amara Osei",
  "produce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "produce_name": "Tomatoes",
  "produce_price": "12.50",
  "frequency": "WEEKLY",
  "expected_quantity": 5,
  "next_expected_order_date": "2026-05-20",
  "active": false,
  "status": "PAUSED",
  "subscription_start_date": "2026-05-13",
  "subscription_end_date": null,
  "created_at": "2026-05-13T12:00:00.000000Z",
  "updated_at": "2026-05-13T12:10:00.000000Z"
}

​
Resume a subscription

POST /api/subscriptions/{id}/resume/ Sets status back to ACTIVE and active to true. Only meaningful on a PAUSED subscription. 
curl --request POST \
  --url https://api.agropulse.example.com/api/subscriptions/d4e5f6a7-b8c9-0123-def0-456789abcdef/resume/ \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "id": "d4e5f6a7-b8c9-0123-def0-456789abcdef",
  "buyer": "c2d5f3b8-44e0-4c9f-b6a1-83d2e4f0a716",
  "buyer_name": "Kofi Mensah",
  "farmer": "b7d2e4f6-91c3-4a2b-8d0e-56f7a8b9c012",
  "farmer_name": "Amara Osei",
  "produce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "produce_name": "Tomatoes",
  "produce_price": "12.50",
  "frequency": "WEEKLY",
  "expected_quantity": 5,
  "next_expected_order_date": "2026-05-20",
  "active": true,
  "status": "ACTIVE",
  "subscription_start_date": "2026-05-13",
  "subscription_end_date": null,
  "created_at": "2026-05-13T12:00:00.000000Z",
  "updated_at": "2026-05-13T12:15:00.000000Z"
}

​
Cancel a subscription

POST /api/subscriptions/{id}/cancel/ Sets status to CANCELLED, active to false, and stamps subscription_end_date with today’s date. Cancellation is permanent — use pause if you intend to resume later. 
curl --request POST \
  --url https://api.agropulse.example.com/api/subscriptions/d4e5f6a7-b8c9-0123-def0-456789abcdef/cancel/ \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "id": "d4e5f6a7-b8c9-0123-def0-456789abcdef",
  "buyer": "c2d5f3b8-44e0-4c9f-b6a1-83d2e4f0a716",
  "buyer_name": "Kofi Mensah",
  "farmer": "b7d2e4f6-91c3-4a2b-8d0e-56f7a8b9c012",
  "farmer_name": "Amara Osei",
  "produce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "produce_name": "Tomatoes",
  "produce_price": "12.50",
  "frequency": "WEEKLY",
  "expected_quantity": 5,
  "next_expected_order_date": "2026-05-20",
  "active": false,
  "status": "CANCELLED",
  "subscription_start_date": "2026-05-13",
  "subscription_end_date": "2026-05-13",
  "created_at": "2026-05-13T12:00:00.000000Z",
  "updated_at": "2026-05-13T12:20:00.000000Z"
}

​
Frequency values

ValueNext order date advanceDescription
DAILY+1 dayA new order is expected every calendar day.
WEEKLY+7 daysA new order is expected every seven days.
MONTHLY+30 daysA new order is expected every thirty days.

​
Status values

Valueactive flagDescription
ACTIVEtrueSubscription is running and eligible for automated order generation.
PAUSEDfalseSubscription is temporarily suspended. Can be resumed.
CANCELLEDfalseSubscription has been permanently ended. subscription_end_date is set.

​
Subscription orders

Each time a subscription cycle falls due, the system auto-generates a SubscriptionOrder record linked to the parent subscription. Subscription orders are read-only through the API — you cannot create or modify them directly. SubscriptionOrder records capture the quantity, unit price, total amount, and scheduled date for each cycle. Each order progresses through its own order_status: PENDING → CONFIRMED → DELIVERED (or FAILED / SKIPPED). A SubscriptionPayment record is associated one-to-one with each order and tracks payment processing separately. Use GET /api/subscription-orders/due_orders/ to retrieve orders scheduled for today or earlier that are still in PENDING or CONFIRMED state — useful for automated fulfilment workflows.
The orders field on a subscription detail response (GET /api/subscriptions/{id}/) includes the 10 most recent subscription orders, ordered by scheduled date descending. Retrieve the full order history through /api/subscription-orders/?subscription={id}.

​
Query parameters

The list endpoint (GET /api/subscriptions/) supports the following query parameters for filtering and ordering.
​
status
string
Filter by subscription status. One of: ACTIVE, PAUSED, CANCELLED.
​
frequency
string
Filter by delivery frequency. One of: DAILY, WEEKLY, MONTHLY.
​
active
boolean
Filter by the active boolean flag. Use true for running subscriptions, false for paused or cancelled ones.
​
ordering
string
Sort results by a field name. Supported fields: created_at, next_expected_order_date. Prefix with - for descending order (e.g., -created_at).

​
Subscription object

​
id
string
required
UUID primary key. Auto-generated on creation, never editable.
​
buyer
string
required
UUID of the BuyerProfile that owns the subscription.
​
buyer_name
string
required
Full name of the buyer. Read-only, derived from the linked BuyerProfile.
​
farmer
string
required
UUID of the FarmerProfile supplying the produce.
​
farmer_name
string
required
Full name of the farmer. Read-only, derived from the linked FarmerProfile.
​
produce
string
required
UUID of the Produce item covered by the subscription.
​
produce_name
string
required
Name of the produce item. Read-only, derived from the linked Produce record.
​
produce_price
string
required
Current unit price of the produce as a decimal string (e.g., "12.50"). Read-only.
​
frequency
string
required
Delivery cadence. One of: DAILY, WEEKLY, MONTHLY. Defaults to WEEKLY.
​
expected_quantity
integer
required
Number of units expected per delivery cycle. Defaults to 1.
​
next_expected_order_date
string
required
ISO 8601 date (YYYY-MM-DD) of the next scheduled order. Advances automatically after each cycle.
​
active
boolean
required
true when the subscription is ACTIVE; false when PAUSED or CANCELLED.
​
status
string
required
Current lifecycle status. One of: ACTIVE, PAUSED, CANCELLED. Defaults to ACTIVE.
​
subscription_start_date
string
required
ISO 8601 date the subscription was created. Set automatically, read-only.
​
subscription_end_date
string
ISO 8601 date the subscription was cancelled. null until the subscription is cancelled.
​
created_at
string
required
ISO 8601 timestamp of record creation. Read-only.
​
updated_at
string
required
ISO 8601 timestamp of the last update. Read-only.
The unique_together constraint on (buyer, farmer, produce) means a buyer can hold exactly one subscription per farmer-produce combination. Attempting to create a duplicate returns a 400 Bad Request.

Build docs developers (and LLMs) love

Get started for freeTalk to us