Batches

List deliveries

Receipts of deliveries you can see, newest first: of your shipments, and by you or your linked facilities.

Each row is a receipt on the ledger (a RECEIVE event): who received it (receiver), the shipment it names (shipment_event_id, null if it names none), the quantity and when.

A manufacturer sees the receipts of its supplier account's shipments, whoever received them. A distributor or pharmacy sees the deliveries its linked facilities received, not their opening stock, branch transfers or customer returns.

Filter with gtin and batch_number. A batch number matches in any spelling (case, spaces).

To report a delivery, write events: a SHIP from the sender and a RECEIVE from the receiver (POST /events/). There is no other way to record one.

Query parameters

• batch_number string Optional

  Any spelling; compared in its one format.

• gtin string Optional

  GTIN-14.

• ordering string Optional

  Which field to use when ordering the results.

• page integer Optional

  A page number within the paginated result set.

• page_size integer Optional

  Number of results to return per page.

• search string Optional

  A search term.

Example request

curl -X GET https://api.dawatrack.com/partner-api/v1/batches/ \
  -H "Authorization: Bearer $DAWATRACK_TOKEN"

import requests

token = "..."  # from POST /oauth/token/
response = requests.get(
    "https://api.dawatrack.com/partner-api/v1/batches/",
    headers={"Authorization": f"Bearer {token}"},
)
response.raise_for_status()
print(response.json())

const token = "..."; // from POST /oauth/token/
const response = await fetch("https://api.dawatrack.com/partner-api/v1/batches/", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
console.log(await response.json());

Response fields

A page of results. These are the fields of each item in results. See Pagination.

• event_id integer

  The RECEIVE event.

• shipment_event_id integer or null

  The SHIP event this receipt names as its parent, if any.

• gtin string

  The product's GS1 GTIN, as 14 digits.

• batch_number string

  The batch or lot number.

• medicine_name string

  From the product catalogue, by GTIN.

• quantity integer or null

  The number of units.

• received_at datetime

  When the facility received it.

• receiver object
  Show child fields
  • type enum

    facility: a DawaTrack pharmacy; supplier: a supplier on DawaTrack; partner: an API account.

    Possible values: facilitysupplierpartner
  • schema_name string

    The facility's identifier; blank otherwise.

  • name string

Example response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "event_id": "5c0e7d2a-91b4-4f63-8a27-0d4e6b9c1f35",
      "shipment_event_id": 1,
      "gtin": "06164004321562",
      "batch_number": "BTH-2026-041",
      "medicine_name": "Amoxicillin 500 mg capsules",
      "quantity": 2600,
      "received_at": "2026-10-10T09:00:00Z",
      "receiver": {
        "type": "facility",
        "schema_name": "pharmacy_a",
        "name": "name"
      }
    }
  ]
}

Status codes

Trace a batch

The deliveries of this batch you can see, as in the list above.

404 when there is none. Use the distribution tree for every hop, wholesale resale included.

Path parameters

• batch_number string Required
• gtin string Required

Example request

curl -X GET https://api.dawatrack.com/partner-api/v1/batches/06164004321562/BTH-2026-041/ \
  -H "Authorization: Bearer $DAWATRACK_TOKEN"

import requests

token = "..."  # from POST /oauth/token/
response = requests.get(
    "https://api.dawatrack.com/partner-api/v1/batches/06164004321562/BTH-2026-041/",
    headers={"Authorization": f"Bearer {token}"},
)
response.raise_for_status()
print(response.json())

const token = "..."; // from POST /oauth/token/
const response = await fetch("https://api.dawatrack.com/partner-api/v1/batches/06164004321562/BTH-2026-041/", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
console.log(await response.json());

Response fields

• event_id integer

  The RECEIVE event.

• shipment_event_id integer or null

  The SHIP event this receipt names as its parent, if any.

• gtin string

  The product's GS1 GTIN, as 14 digits.

• batch_number string

  The batch or lot number.

• medicine_name string

  From the product catalogue, by GTIN.

• quantity integer or null

  The number of units.

• received_at datetime

  When the facility received it.

• receiver object
  Show child fields
  • type enum

    facility: a DawaTrack pharmacy; supplier: a supplier on DawaTrack; partner: an API account.

    Possible values: facilitysupplierpartner
  • schema_name string

    The facility's identifier; blank otherwise.

  • name string

Example response

[
  {
    "event_id": "5c0e7d2a-91b4-4f63-8a27-0d4e6b9c1f35",
    "shipment_event_id": 1,
    "gtin": "06164004321562",
    "batch_number": "BTH-2026-041",
    "medicine_name": "Amoxicillin 500 mg capsules",
    "quantity": 2600,
    "received_at": "2026-10-10T09:00:00Z",
    "receiver": {
      "type": "facility",
      "schema_name": "pharmacy_a",
      "name": "name"
    }
  }
]

Status codes

Get a batch's distribution tree

Every party this batch reached, on DawaTrack or not, hop by hop, each under the party it came from.

The same tree as the supplier portal's Trace page, from the same walk as a recall's reach.

Each node is a party (kind): you, supplier (a distributor on DawaTrack), partner (a connected system), pharmacy, outside (a party outside DawaTrack), sender (a party outside DawaTrack that sold the batch on), or an end (end: true, with quantity): patients, transit (not received yet), returned, gap (receiver not recorded). also points to a party shown elsewhere that this one also supplied.

A party's figures (received, dispensed, sent_on, on_hand, quarantined) come from its own events, read on every call. acknowledged is when a receiver answered a recall notice; disputed marks a party reached through a delivery its supplier disputes.

A manufacturer sees the whole tree, rooted at itself. A distributor or pharmacy sees only its own lots of the batch as roots, with their own downstream: never who supplied it.

Path parameters

• batch_number string Required
• gtin string Required

Example request

curl -X GET https://api.dawatrack.com/partner-api/v1/batches/06164004321562/BTH-2026-041/tree/ \
  -H "Authorization: Bearer $DAWATRACK_TOKEN"

import requests

token = "..."  # from POST /oauth/token/
response = requests.get(
    "https://api.dawatrack.com/partner-api/v1/batches/06164004321562/BTH-2026-041/tree/",
    headers={"Authorization": f"Bearer {token}"},
)
response.raise_for_status()
print(response.json())

const token = "..."; // from POST /oauth/token/
const response = await fetch("https://api.dawatrack.com/partner-api/v1/batches/06164004321562/BTH-2026-041/tree/", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
console.log(await response.json());

Response fields

• key string

  Stable id of the party in this tree.

• kind enum

  you: your organisation; supplier: a distributor on DawaTrack; partner: a connected system; pharmacy: a pharmacy branch; outside: a party outside DawaTrack; sender: a party outside DawaTrack that sold the batch on; patients: units dispensed; transit: a shipment not yet received; returned: a return to a supplier; gap: a shipment whose receiver nobody recorded; also: a party shown elsewhere in the tree that this one also supplied.

  Possible values: yousupplierpartnerpharmacyoutsidesenderpatientstransitreturnedgapalso
• name string
• detail string
• hop integer

  Parties from the root.

• end boolean

  True for patients, transit, returned and gap: quantity applies.

  Default: False

• quantity integer or null

  The number of units.

• occurred_at datetime or null

  When the event happened.

• received integer or null
• dispensed integer or null
• sent_on integer or null
• on_hand integer or null
• quarantined integer or null
• shipped integer or null

  For you: units shipped.

• shipments integer or null
• acknowledged datetime or null

  When the receiver acknowledged a recall notice.

• disputed boolean

  Reached through a delivery its supplier disputes.

  Default: False

• branch_of boolean

  A branch of the pharmacy above it (a stock transfer).

  Default: False

• also_under string
• confirmation enum or null

  recorded: on DawaTrack by the receiver itself; scanned/typed: confirmed through its link, a scan matching the batch or the quantities typed; declared: on another party's word (declared_by); waiting: a shipment not confirmed yet; not-confirmed: not confirmed 7 days after it left. The weakest of a party's receipts.

  Possible values: recordedscannedtypeddeclaredwaitingnot-confirmed
• declared_by string

  The party outside DawaTrack that declared it.

• consignments array of objects
  Show child fields
  • number string
  • carrier string
  • waybill string
• short integer

  Units its receiver reported short.

  Default: 0

• damaged integer

  Units it reported arrived damaged.

  Default: 0

• refused integer

  Units it refused.

  Default: 0

• reachable boolean or null

  A party outside DawaTrack: whether a recall can reach it (a verified email and a phone on file). Null for a party on DawaTrack.

• sender string

  A shipment waiting: who sent it.

• children array of objects Read-only

  The facilities it passed the batch on to, in the same shape.

Example response

[
  {
    "key": "you",
    "kind": "you",
    "name": "Big Pharma",
    "hop": 0,
    "end": false,
    "shipped": 1850,
    "shipments": 5,
    "children": [
      {
        "key": "pharmacy:bondo/1",
        "kind": "pharmacy",
        "name": "Blooming World International",
        "detail": "",
        "hop": 1,
        "end": false,
        "received": 1800,
        "dispensed": 10,
        "sent_on": 1575,
        "on_hand": 215,
        "quarantined": 0,
        "disputed": false,
        "children": [
          {
            "key": "patients:pharmacy:bondo/1",
            "kind": "patients",
            "name": "Patients",
            "hop": 2,
            "end": true,
            "quantity": 10,
            "children": []
          },
          {
            "key": "outside:4367",
            "kind": "outside",
            "name": "dobling pharmacy",
            "hop": 2,
            "end": true,
            "quantity": 870,
            "occurred_at": "2026-10-23T09:12:00Z",
            "acknowledged": "2026-10-25T08:30:00Z",
            "children": []
          },
          {
            "key": "transit:4452",
            "kind": "transit",
            "name": "Blooming World International",
            "hop": 2,
            "end": true,
            "quantity": 50,
            "occurred_at": "2026-10-30T10:02:00Z",
            "children": []
          }
        ]
      }
    ]
  }
]

Status codes

List a batch's events the graph can't connect

Events of this batch that are on the ledger but not connected to the rest of it: the graph can't walk to or from them.

An orphan names no predecessor (parent_event, a receipt in its sources, or a receipt link) though its type follows from one: a RECEIVE, DISPENSE, QUARANTINE, RELEASE, TRANSFER, DISAGGREGATE or RECEIVE_LINK. A COMMISSION and an AGGREGATE never are.

A SHIP is an orphan when its sender received the batch on DawaTrack before it. When the sender didn't, the SHIP is the first movement DawaTrack saw, and isn't one.

Your own orphans show their event_id and facility. Another party's are withheld: their type and when they happened only. A batch you can't see is 404. Requires batches:read.

Path parameters

• batch_number string Required
• gtin string Required

Example request

curl -X GET https://api.dawatrack.com/partner-api/v1/batches/06164004321562/BTH-2026-041/orphans/ \
  -H "Authorization: Bearer $DAWATRACK_TOKEN"

import requests

token = "..."  # from POST /oauth/token/
response = requests.get(
    "https://api.dawatrack.com/partner-api/v1/batches/06164004321562/BTH-2026-041/orphans/",
    headers={"Authorization": f"Bearer {token}"},
)
response.raise_for_status()
print(response.json())

const token = "..."; // from POST /oauth/token/
const response = await fetch("https://api.dawatrack.com/partner-api/v1/batches/06164004321562/BTH-2026-041/orphans/", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
console.log(await response.json());

Response fields

• gtin string

  The product's GS1 GTIN, as 14 digits.

• batch_number string

  The batch or lot number.

• count integer
• orphans array of objects
  Show child fields
  • event_type string

    The kind of event.

  • occurred_at datetime

    When the event happened.

  • withheld boolean

    Another party's event: only its type and time are shown.

  • event_id integer
  • facility string

    Where it happened, as the graph keys a facility.

Example response

{
  "gtin": "06164004321562",
  "batch_number": "AMX-2026-041",
  "count": 2,
  "orphans": [
    {
      "event_type": "SHIP",
      "occurred_at": "2026-10-20T09:15:00Z",
      "withheld": false,
      "event_id": 9123,
      "facility": "partner:12/0614141000005"
    },
    {
      "event_type": "RECEIVE",
      "occurred_at": "2026-10-21T11:02:00Z",
      "withheld": true
    }
  ]
}

Status codes

Export a batch as EPCIS 2.0

The batch's event history as a GS1 EPCIS 2.0 JSON-LD document, for EPCIS-based systems.

Unit identifiers use urn:epc:id:sgtin: and urn:epc:class:lgtin: when the manufacturer recorded its GS1 Company Prefix length, and GS1 Digital Link URIs otherwise.

A batch-level event is reported as a quantityList entry. Packing and unpacking appear as AggregationEvent ADD and DELETE.

A batch of a product you make or pack with no events yet returns 200 with an empty eventList, not 404.

The lot's details: a commissioning (ADD) event carries them as ilmd, the expiry as cbvmda:itemExpirationDate and the manufacture date as dawatrack:manufactureDate (CBV 2.0 has no production-date attribute). Other events carry the dates they declared as dawatrack:itemExpirationDate and dawatrack:manufactureDate. The lot's current details, after any correction by its owner, are in epcisHeader.epcisMasterData under the lot's class identifier.

Path parameters

• batch_number string Required
• gtin string Required

Example request

curl -X GET https://api.dawatrack.com/partner-api/v1/batches/06164004321562/BTH-2026-041/epcis/ \
  -H "Authorization: Bearer $DAWATRACK_TOKEN"

import requests

token = "..."  # from POST /oauth/token/
response = requests.get(
    "https://api.dawatrack.com/partner-api/v1/batches/06164004321562/BTH-2026-041/epcis/",
    headers={"Authorization": f"Bearer {token}"},
)
response.raise_for_status()
print(response.json())

const token = "..."; // from POST /oauth/token/
const response = await fetch("https://api.dawatrack.com/partner-api/v1/batches/06164004321562/BTH-2026-041/epcis/", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
console.log(await response.json());

Example response

{
  "@context": [
    "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld",
    {
      "dawatrack": "https://dawatrack.com/ns/epcis#"
    }
  ],
  "type": "EPCISDocument",
  "schemaVersion": "2.0",
  "creationDate": "2026-10-10T12:00:00+00:00",
  "epcisBody": {
    "eventList": [
      {
        "type": "ObjectEvent",
        "eventTime": "2026-10-01T09:00:00+00:00",
        "eventTimeZoneOffset": "+00:00",
        "eventID": "urn:uuid:0b0f6c7e-5a3c-5b2e-9a51-3f2d7c1e8a44",
        "action": "OBSERVE",
        "bizStep": "shipping",
        "disposition": "in_transit",
        "readPoint": {
          "id": "urn:dawatrack:facility:distributor_nairobi"
        },
        "bizLocation": {
          "id": "urn:dawatrack:facility:distributor_nairobi"
        },
        "destinationList": [
          {
            "type": "location",
            "destination": "urn:dawatrack:facility:pharmacy_c"
          }
        ],
        "quantityList": [
          {
            "epcClass": "https://id.gs1.org/01/06164004321562/10/BTH-2026-041",
            "quantity": 2600
          }
        ]
      }
    ]
  }
}

Status codes

List your lots

The lots you own, with their current expiry and manufacture date, most recently changed first.

You own a lot as the product's registered manufacturer, or as the first to declare a lot of a product with no manufacturer on DawaTrack. Filter with gtin. Needs batches:read.

Query parameters

• ordering string Optional

  Which field to use when ordering the results.

• page integer Optional

  A page number within the paginated result set.

• page_size integer Optional

  Number of results to return per page.

• search string Optional

  A search term.

Example request

curl -X GET https://api.dawatrack.com/partner-api/v1/lots/ \
  -H "Authorization: Bearer $DAWATRACK_TOKEN"

import requests

token = "..."  # from POST /oauth/token/
response = requests.get(
    "https://api.dawatrack.com/partner-api/v1/lots/",
    headers={"Authorization": f"Bearer {token}"},
)
response.raise_for_status()
print(response.json())

const token = "..."; // from POST /oauth/token/
const response = await fetch("https://api.dawatrack.com/partner-api/v1/lots/", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
console.log(await response.json());

Response fields

A page of results. These are the fields of each item in results. See Pagination.

• gtin string

  The product's GS1 GTIN, as 14 digits.

• batch_number string

  The batch or lot number.

• expiry_date date or null

  The batch's expiry date.

• manufacture_date date or null
• owner string
• declared boolean

  True when a party on DawaTrack declared these dates; false when they are only what a pharmacy receiving it from a sender not on DawaTrack reported (provisional until declared).

• is_owner boolean Read-only
• history array of valuess Read-only
• discrepancies array of valuess Read-only

  Receipts of a provisional lot whose pack disagreed with the record.

Example response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "gtin": "06164004321562",
      "batch_number": "BTH-2026-041",
      "expiry_date": "2026-10-10",
      "manufacture_date": "2026-10-10",
      "owner": "owner",
      "declared": false,
      "is_owner": true,
      "history": [
        "string"
      ],
      "discrepancies": [
        "string"
      ]
    }
  ]
}

Status codes

Read a lot's details

A batch's expiry and manufacture date as its owner recorded them, who the owner is, and their history.

Every event for the batch carries these dates (see POST /events/). The owner is the product's registered manufacturer, or whoever first declared the batch when the product has no manufacturer on DawaTrack.

Visible when you can see an event of the batch, or you own it; otherwise 404. Needs batches:read.

Path parameters

• batch_number string Required
• gtin string Required

Example request

curl -X GET https://api.dawatrack.com/partner-api/v1/lots/06164004321562/BTH-2026-041/ \
  -H "Authorization: Bearer $DAWATRACK_TOKEN"

import requests

token = "..."  # from POST /oauth/token/
response = requests.get(
    "https://api.dawatrack.com/partner-api/v1/lots/06164004321562/BTH-2026-041/",
    headers={"Authorization": f"Bearer {token}"},
)
response.raise_for_status()
print(response.json())

const token = "..."; // from POST /oauth/token/
const response = await fetch("https://api.dawatrack.com/partner-api/v1/lots/06164004321562/BTH-2026-041/", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
console.log(await response.json());

Response fields

• gtin string

  The product's GS1 GTIN, as 14 digits.

• batch_number string

  The batch or lot number.

• expiry_date date or null

  The batch's expiry date.

• manufacture_date date or null
• owner string
• declared boolean

  True when a party on DawaTrack declared these dates; false when they are only what a pharmacy receiving it from a sender not on DawaTrack reported (provisional until declared).

• is_owner boolean Read-only
• history array of valuess Read-only
• discrepancies array of valuess Read-only

  Receipts of a provisional lot whose pack disagreed with the record.

Example response

{
  "gtin": "06164004321562",
  "batch_number": "BTH-2026-041",
  "expiry_date": "2026-10-10",
  "manufacture_date": "2026-10-10",
  "owner": "owner",
  "declared": false,
  "is_owner": true,
  "history": [
    "string"
  ],
  "discrepancies": [
    "string"
  ]
}

Status codes

Correct a lot's details

The owner corrects a batch's expiry or manufacture date, with a reason.

Send expiry_date, optionally manufacture_date, and reason. The new dates replace the old everywhere: each pharmacy holding the batch has its stock corrected and is alerted, and each supplier that handled it is emailed with your reason. The history keeps both.

Only the owner (or a contract packer it authorized for the GTIN); anyone else is 403. No reason, no change, a manufacture date in the future or on or after the expiry is 400. Needs products:write and production credentials.

Path parameters

• batch_number string Required
• gtin string Required

Request body

JSON. Send Content-Type: application/json.

• expiry_date date Optional

  The batch's expiry date.

• manufacture_date date or null Optional
• reason string Optional

Example request

curl -X PATCH https://api.dawatrack.com/partner-api/v1/lots/06164004321562/BTH-2026-041/ \
  -H "Authorization: Bearer $DAWATRACK_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "expiry_date": "2028-06-30",
    "manufacture_date": "2026-06-01",
    "reason": "The expiry was keyed wrongly on the first shipment."
  }'

import uuid
import requests

token = "..."  # from POST /oauth/token/
response = requests.patch(
    "https://api.dawatrack.com/partner-api/v1/lots/06164004321562/BTH-2026-041/",
    headers={"Authorization": f"Bearer {token}", "Idempotency-Key": str(uuid.uuid4())},
    json={
      "expiry_date": "2028-06-30",
      "manufacture_date": "2026-06-01",
      "reason": "The expiry was keyed wrongly on the first shipment."
    },
)
response.raise_for_status()
print(response.json())

const token = "..."; // from POST /oauth/token/
const response = await fetch("https://api.dawatrack.com/partner-api/v1/lots/06164004321562/BTH-2026-041/", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${token}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "expiry_date": "2028-06-30",
    "manufacture_date": "2026-06-01",
    "reason": "The expiry was keyed wrongly on the first shipment."
  }),
});
console.log(await response.json());

Response fields

• gtin string

  The product's GS1 GTIN, as 14 digits.

• batch_number string

  The batch or lot number.

• expiry_date date or null

  The batch's expiry date.

• manufacture_date date or null
• owner string
• declared boolean

  True when a party on DawaTrack declared these dates; false when they are only what a pharmacy receiving it from a sender not on DawaTrack reported (provisional until declared).

• is_owner boolean Read-only
• history array of valuess Read-only
• discrepancies array of valuess Read-only

  Receipts of a provisional lot whose pack disagreed with the record.

Example response

{
  "gtin": "06164004321562",
  "batch_number": "BTH-2026-041",
  "expiry_date": "2026-10-10",
  "manufacture_date": "2026-10-10",
  "owner": "owner",
  "declared": false,
  "is_owner": true,
  "history": [
    "string"
  ],
  "discrepancies": [
    "string"
  ]
}

Status codes