Skip to main content
Most of this page is reading a clinic’s inventory. The last sections cover the ways your key can retire things: archiving an item, restoring it, deleting one that was never used, and writing off a lot of stock. Creating items and receiving, adjusting or transferring stock are in the API reference and in Retries and duplicates. Each endpoint needs a specific permission on the key making the request — see Permissions for what each one means before you build against it.

Locations

Requires inventory.items:read. Returns the clinic’s stock locations — the storerooms, shelves or fridges stock is held in.

List catalogue items

Requires inventory.items:read. Cursor-paginated (see Pagination).
Each item in the response:
identifiers lists every code recorded for the item — a barcode (gtin) or a national drug registration number (nafdac) — and appears only where the clinic’s own record has it. Nothing is inferred or guessed on your behalf: an item with no barcode on file simply has no gtin entry. When you create an item, its upc (the barcode) must be a valid GTIN. When you update one, only a changed upc is checked: sending back the value the item already holds is accepted even if it is not a valid GTIN, so an item you read can be written back as it is. A new or different upc that is not a valid GTIN is refused with 400 invalid_gtin. To compare, the API reads the item’s current value with your key, so a key without inventory.items:read cannot send an unchanged invalid value, and that read counts toward your rate limit (if it is refused, for example when you are rate limited, you get that answer instead of invalid_gtin). The barcode filter when you list items is not checked: it matches exactly what is stored, so you can still find an item whose stored barcode is not a valid GTIN. null clears the barcode. is_active is false and archived_at holds the time while an item is archived; both go back to normal when it is restored. is_controlled is true when the clinic has marked the item as a controlled medicine. It is read-only: it can only be changed in the ClinikEHR app, by staff the clinic has allowed to mark medicines as controlled. A clinic that has not marked anything reports false for every item, so treat false as “not marked”, not as a statement about the medicine’s legal status. retail_price is null when the clinic hasn’t set a price for the item — never a fabricated 0.

Get one item

Requires inventory.items:read. Same fields as one entry of the list above. An item_id that doesn’t exist, or that belongs to a different clinic, returns 404 with code: "not_found" — see Errors.

Check availability

Requires inventory.availability:read. Checks up to 100 items in one request — by their ID, or by any identifier you already hold (a barcode, for example) — and returns a band for each, never an exact number. A gtin value must be a valid barcode number: 8, 12, 13 or 14 digits, digits only, with a correct GS1 check digit. Anything else is refused with 400 invalid_gtin, and the answer names the field and the value.
A positive band is not a reservation. Nothing about calling this endpoint holds, claims, or sets anything aside. Between reading in_stock and a customer actually being sold the item, stock can change — always show as_of to whoever is relying on the answer, and never present availability as a guarantee.

Exact stock levels

Requires inventory.stock:read — a separate, more sensitive permission than availability (see Permissions). Returns exact quantities, by location and lot.
quantity is a decimal string, the same convention used for money — see Pagination for the list envelope this sits inside.

Archive an item

Requires inventory.items:write. Archiving hides an item from sale and dispensing without erasing anything — it is always reversible, and the item keeps its history. You can send an optional reason, which is kept with the item. No Idempotency-Key is needed, and archiving an item that is already archived simply succeeds.
The response is the item under data, now with is_active: false and an archived_at time. An item that still has stock on hand is refused with 409 and code: "item_has_stock"; the detail says how many units are left. Write the stock off (below) or move it first, then archive.

Restore an item

Requires inventory.items:write. Brings an archived item back so it can be sold and dispensed again. Restoring an item that is already active simply succeeds. No body and no Idempotency-Key.
The response is the item under data, with is_active: true and archived_at: null.

Delete an item that was never used

Requires inventory.items:write. Deleting is permanent, so it is only allowed for an item that has never been used: it has never held stock and is not part of any order, count, recipe or dispense. If you added an item by mistake, this removes it.
Anything with history is refused with 409 and code: "item_has_history" — archive it instead, which keeps the history. Sending the same delete a second time returns 404, because the item is gone.

Write off a lot of stock

Requires inventory.stock:write. Use this when a lot has expired, been damaged or been recalled. It records the lot’s remaining quantity as wasted, at every location where it is held, and then archives the lot. The clinic’s stock history keeps the movement; nothing is deleted. The request needs two things:
  • a reason in the body — say why the stock is being written off;
  • an Idempotency-Key header, so a retry after a timeout cannot write the same lot off twice. See Retries and duplicates.
quantity_written_off is a decimal string, like every quantity. Leaving reason out is a 400 that names the field; a blank reason is refused with code: "reason_required". A controlled drug is refused with 403 and code: "controlled_drug_not_api_movable" — an API key has no witness to countersign, so the clinic records that loss itself. A lot with part of its stock reserved is refused with 409 and code: "insufficient_stock" until the reservation is released.

Send a stock report

For a pharmacy that sells through another system. The pharmacy’s owner first switches Settings → API access → Stock source to “Another system’s stock report”; your system then sends that system’s stock as a report, and the pharmacy’s listings show it. Nothing is added to the pharmacy’s own ledger: a report only sets what listings say. Permission. The key needs inventory.external_stock:write, the narrow permission for exactly this. It is available on every paid pharmacy plan, including the Listing plan, and it cannot read, adjust or receive stock. A key that already holds inventory.stock:write (Team and above) works too, and GET also accepts inventory.stock:read. Clinic keys only: an organization never sends a pharmacy’s stock.
  • A row that matches none of the pharmacy’s products is counted as unmatched and ignored. Nothing is guessed.
  • A report is applied whole or not at all. One with an unreadable row (invalid_rows), far fewer products than the last accepted report (suspicious_shrink) or no rows (empty) is refused with 409 batch_rejected and nothing is saved.
  • A pharmacy that is not in “Another system’s stock report” mode is refused with 409 external_stock_mode_required.
  • A report older than the pharmacy’s freshness window makes its products read as unknown in listings. Send them regularly.

What’s never in an inventory response

No inventory endpoint returns cost price, vendor information, margins, or anything about a specific customer or sale. This release exposes only what a clinic explicitly permits under Availability, Catalogue, or Stock levels — nothing else rides along.