Batches API

A batch is one lot of produce with its source, quantity and history. These are the endpoints the IndiTrace web app uses. Signed-in requests need an access token (see Authentication); the public trace lookup needs none.

All paths start with your edition's API base, for example https://<your-edition-api>/api/v1.

Endpoints

{id} is the numeric id from the list. {batch_uid} is the batch ID printed on labels and QR codes: B followed by 14 digits in the India edition (for example B68286692756350) and GL followed by 14 digits in the global edition.

There is no endpoint to edit a batch's source, quantity or dates after it is created. Batch records are fingerprinted on a public blockchain, so a wrong batch is discarded and recorded again, and evidence is added as documents.

List batches

GET /api/v1/batches/?search=makhana&page=1&page_size=20
Authorization: Bearer <access token>

Query parameters (all optional):

The response is paginated. summary counts every batch that matches the filters, not just this page:

{
  "count": 42,
  "next": "…?page=2",
  "previous": null,
  "total_pages": 3,
  "current_page": 1,
  "results": [
    {
      "id": 118,
      "batch_uid": "B68286692756350",
      "farmer_name": "…",
      "product_name": "Makhana",
      "harvest_date": "2026-09-06",
      "quantity": "500.00",
      "quantity_unit": "kg",
      "status": "PROCESSED",
      "blockchain_status": "anchored",
      "blockchain_tx_hash": "0x…",
      "available_quantity": "142.50",
      "created_at": "2026-09-06T10:12:31Z"
    }
  ],
  "summary": { "total": 42, "active": 30, "anchored": 38, "pending": 4, "failed": 0, "discarded": 0 }
}

List items also carry product_variety, photos, source_kind, supplier_name, items (one row per farmer and product in the batch) and the receiving-review summary the dashboard shows.

Create a batch

POST /api/v1/batches/
Authorization: Bearer <access token>
Content-Type: application/json
Idempotency-Key: <optional unique string>

{
  "farmer": 31,
  "product": 7,
  "harvest_date": "2026-09-06",
  "quantity": "500",
  "quantity_unit": "kg",
  "photos": ["https://…/harvest.jpg"],
  "origin_story": "Hand-harvested from the family ponds.",
  "receiving_video_id": "<id of an uploaded capture video>"
}

• harvest_date is required. Send either farmer and product with a positive quantity and a quantity_unit, or a sources list for a batch from several farmers: [{"farmer": 31, "product": 7, "quantity": "200", "quantity_unit": "kg"}, …]. The batch quantity is the sum of its sources.
• quantity_unit is one of kg, ton, qtl, litre or boxes.
• Farmers and products must belong to your organization, and farmers must be active.
• A capture video is required. receiving_video_id names a short video of the harvest or stock, recorded and uploaded in the IndiTrace app. The video upload is not part of this reference, so in practice batches are created in the app. If you need to create batches from another system, talk to us.
• A new batch uses one proof credit when its record is written to the blockchain. Sending the same Idempotency-Key again returns the first response instead of creating a second batch.

A successful call returns 201 with the full batch, in the same shape as Read a batch.

Read a batch

GET /api/v1/batches/{id}/ returns the batch with its events timeline, sources, processing_history and blockchain fields (blockchain_status, blockchain_tx_hash, anchored_at). Partners a batch was transferred to can read it too.

Discard a batch

DELETE /api/v1/batches/{id}/ marks the batch DISCARDED and stops its proof from being written. Only admins of the owning organization can do it, and it is refused, with a message saying why, for a batch that has processing history or is still in use. The record is kept, not deleted.

Batch statuses

status follows the batch through the supply chain:

blockchain_status is the proof state: pending (waiting to be written), anchored (fingerprint confirmed on Polygon), failed (being retried) or discarded.

Documents

Lab reports, certificates and invoices are attached as documents. The file is uploaded first (the app does this for you), then its URL is sent:

POST /api/v1/batches/{id}/documents/
{"doc_type": "LAB_REPORT", "title": "Certificate of analysis", "file_url": "https://…/coa.pdf"}

doc_type is LAB_REPORT, CERTIFICATE, INVOICE or OTHER. Lab reports and certificates appear on the public trace page; invoices and other documents stay private to your organization. Documents cannot be deleted: a PATCH saves a new version and keeps earlier versions in history.

Public trace lookup

GET /api/v1/batches/public/trace/{batch_uid}/ needs no sign-in. It returns what the public trace page shows, including product_name, harvest_date, farmer_name, farm_locations, timeline, photos, public documents, blockchain_proof (transaction hash and explorer link once anchored) and blockchain_network. An unknown batch ID returns 404.

Errors