Clinicea Inventory Stock Movement API – Integration Guide
This guide is for partners integrating with Clinicea Inventory: sync documents, create stock movements, and consume outbound webhooks using the same JSON shapes.
1. Overview
Clinicea Inventory exposes REST endpoints so partners can sync stock documents and create purchase orders, stock requests, send/receive stock, and returns. Outbound webhooks use the same payload shapes when stock changes in the Clinicea App.
Environment | Base URL |
|---|---|
Production |
Area | Path prefix |
|---|---|
Stock movement | /api/v3/stockMovement/... |
Stock reduction | /api/v3/stockReduction/... |
Swagger doc ref link | https://api.clinicea.com/swagger/ui/index#/StockMovement |
2. Authentication and permissions
Authenticate with a Clinicea API key for a login that has Inventory feature permission. Patient logins are rejected (HTTP 401).
• use the same API-key header pattern as your other Clinicea integrations.
Always use HTTPS.
3. Common conventions
3.1 Sync reads (GET)
• lastSyncDTime — ISO datetime. Blank uses Clinicea default minimum sync time.
• organisationID — optional clinic GUID. Blank = every clinic in the head organisation.
• pageNo — 1-based. pageSize — 10 to 100.
Persist the latest ModifiedDatetime from responses and pass it on the next sync call.
3.2 Creates (POST)
• Content-Type: application/json. Error bodies are plain text.
• ID must be blank on create.
• VoucherDate is required and must not be in the future (UTC).
• Mode and party types are forced by the route — do not rely on VoucherMode from the body.
Never send empty string ("") for DateTime fields. Use ISO-8601, or 1900-01-01T00:00:00 when a date means "not set". Empty DateTime often yields HTTP 400 with an empty body.
3.3 Parties
Route family | SuppliedBy | SuppliedTo |
|---|---|---|
Purchase order | Vendor | Clinic |
Stock request / Send / Receive-from-clinic | Clinic | Clinic |
Return stock | Clinic | Vendor or Clinic |
3.4 Batch tracking
Document | Batch required? |
|---|---|
Purchase order / Stock request | No |
Receive / Send / Return (if item maintains batch) | Yes — BatchNo + future BatchExpiryDate |
Clinic→clinic receive / send / return | Batch must exist on the clinic that loses stock (SuppliedBy) |
3.5 Linking documents
• Allowed on createReceivedOrder* and createSendStock: LinkType + LinkTypeID.
• Against vendor PO: LinkType = "PurchaseOrder".
• Against send-stock: LinkType = "SentOrder" (set explicitly — do not omit).
• Forbidden on createPurchaseOrder, createStockRequest, createReturnStock → HTTP 400.
3.6 HTTP status
Code | Meaning |
|---|---|
200 | Success (JSON for lists/creates) |
400 | Validation or business error (plain text) |
401 | Not authorized / patient login / missing Inventory permission |
HTTP 200 on create means the voucher was saved. Stock quantity changes follow App rules (e.g. return reduces clinic stock; vendor inventory is not increased).
4. Stock Movement API — GET (sync)
GET /api/v3/stockMovement/{route}?lastSyncDTime=&organisationID=&pageNo=1&pageSize=10&api_key=
4.1 Posted documents
Route | Returns |
|---|---|
getPurchaseOrders | Vendor → clinic purchase orders |
getStockRequests | Clinic → clinic stock requests |
getReceivedOrders | Received stock (not debit/credit/return) |
getReturnStock | Returns |
getDebitNotes | Debit notes |
getCreditNotes | Credit notes |
getSendStock | Posted send-stock orders |
4.2 Drafts
getPurchaseOrderDrafts, getStockRequestDrafts, getReceivedOrderDrafts, getReturnStockDrafts, getSendStockDrafts — IsDraft = true.
4.3 Transactions and template
• getTransactions — one row per inventory adjustment. Quantity is signed. TransactionType: Consumable | Adjustment | Bill | Voucher.
• getReceiveStockCustomFieldTemplate — empty ReceiveStockDetails layout for createReceivedOrderFromVendor.
5. Stock Movement API — POST (create)
POST /api/v3/stockMovement/{route}?api_key= Body & response: DTOInventoryStockVoucher
5.1 createPurchaseOrder
Vendor → clinic. No stock movement. Batch not required. Link forbidden.
{
"ID": "",
"VoucherDate": "2026-11-15T10:00:00",
"PurchaseOrderDueDate": "2026-11-30T00:00:00",
"ReferenceNo": "PO-TEST-001",
"Comments": "Optional",
"SuppliedByID": "{vendor-guid}",
"SuppliedToID": "{clinic-guid}",
"VoucherItems": [
{
"InventoryID": "{inventory-guid}",
"PackQuantity": 2,
"FreePackQuantity": 0,
"DiscountPercentage": 0,
"BuyingPrice": 10.5,
"SellingPrice": 20,
"BatchNo": "",
"BatchExpiryDate": "1900-01-01T00:00:00",
"ItemNotes": ""
}
]
}
5.2 createStockRequest
Clinic → clinic. Batch not required. Link forbidden.
{
"ID": "",
"VoucherDate": "2026-11-15T10:00:00",
"PurchaseOrderDueDate": "2026-11-30T00:00:00",
"ReferenceNo": "SR-TEST-001",
"Comments": "Optional",
"SuppliedByID": "{requesting-clinic-guid}",
"SuppliedToID": "{fulfilling-clinic-guid}",
"VoucherItems": [
{
"InventoryID": "{inventory-guid}",
"PackQuantity": 2,
"FreePackQuantity": 0,
"DiscountPercentage": 0,
"BuyingPrice": 10.5,
"SellingPrice": 20,
"BatchNo": "",
"BatchExpiryDate": "1900-01-01T00:00:00",
"ItemNotes": ""
}
]
}
5.3 createSendStock
Clinic → clinic send. Reduces stock at SuppliedByID. Batch required when item is batched.
{
"ID": "",
"VoucherDate": "2026-11-15T10:00:00",
"ReferenceNo": "SEND-TEST-001",
"Comments": "Optional",
"SuppliedByID": "{sending-clinic-guid}",
"SuppliedToID": "{receiving-clinic-guid}",
"VoucherItems": [
{
"InventoryID": "{inventory-guid}",
"PackQuantity": 2,
"FreePackQuantity": 0,
"DiscountPercentage": 0,
"BuyingPrice": 10.5,
"SellingPrice": 20,
"BatchNo": "{batch-on-sender}",
"BatchExpiryDate": "2027-07-31T00:00:00",
"ItemNotes": ""
}
]
}
5.4 createReturnStock
Clinic returns to vendor/clinic. StockTransfer + Rejection. Reduces clinic stock. Link forbidden.
{
"ID": "",
"VoucherDate": "2026-11-15T10:00:00",
"ReferenceNo": "RET-TEST-001",
"Comments": "Optional",
"SuppliedByID": "{clinic-guid}",
"SuppliedToID": "{vendor-or-clinic-guid}",
"SuppliedTo": "Vendor",
"VoucherItems": [
{
"InventoryID": "{inventory-guid}",
"PackQuantity": 1,
"FreePackQuantity": 0,
"DiscountPercentage": 0,
"BuyingPrice": 10.5,
"SellingPrice": 20,
"BatchNo": "{batch-on-clinic}",
"BatchExpiryDate": "2027-07-31T00:00:00",
"ItemNotes": ""
}
]
}
5.5 createReceivedOrderFromVendor
Receive into clinic from vendor. Optional LinkType=PurchaseOrder + LinkTypeID to link/close a PO. Omit link for direct receive.
{
"ID": "",
"VoucherDate": "2026-11-15T10:00:00",
"ReferenceNo": "RCV-VENDOR-001",
"Comments": "Optional",
"SuppliedByID": "{vendor-guid}",
"SuppliedToID": "{receiving-clinic-guid}",
"LinkType": "PurchaseOrder",
"LinkTypeID": "{optional-po-guid}",
"VoucherItems": [
{
"InventoryID": "{inventory-guid}",
"PackQuantity": 2,
"FreePackQuantity": 0,
"DiscountPercentage": 0,
"BuyingPrice": 10.5,
"SellingPrice": 20,
"BatchNo": "BATCH-001",
"BatchExpiryDate": "2027-06-30T00:00:00",
"ItemNotes": ""
}
]
}
5.6 createReceivedOrderFromClinic
Receive from another clinic. Batches from sending clinic (SuppliedByID). Against send-stock: LinkType=SentOrder.
{
"ID": "",
"VoucherDate": "2026-11-15T10:00:00",
"ReferenceNo": "RCV-CLINIC-001",
"Comments": "Optional",
"SuppliedByID": "{sending-clinic-guid}",
"SuppliedToID": "{receiving-clinic-guid}",
"LinkType": "SentOrder",
"LinkTypeID": "{optional-send-stock-guid}",
"VoucherItems": [
{
"InventoryID": "{inventory-guid}",
"PackQuantity": 2,
"FreePackQuantity": 0,
"DiscountPercentage": 0,
"BuyingPrice": 10.5,
"SellingPrice": 20,
"BatchNo": "{batch-on-sender}",
"BatchExpiryDate": "2027-07-31T00:00:00",
"ItemNotes": ""
}
]
}
6. Recommended workflows
Workflow | Steps |
|---|---|
Vendor PO → receive | 1) createPurchaseOrder 2) createReceivedOrderFromVendor with LinkType=PurchaseOrder + LinkTypeID |
Direct vendor receive | createReceivedOrderFromVendor without LinkTypeID |
Clinic send → receive | 1) createSendStock 2) optional createReceivedOrderFromClinic with LinkType=SentOrder |
Stock request | createStockRequest between clinics |
Return to vendor | createReturnStock (clinic SuppliedByID, vendor SuppliedToID) |
7. Stock Reduction API
GET /api/v3/stockReduction/getChanges
Query: lastSyncDTime, organisationID, pageNo, pageSize, api_key
Returns stock reduction documents changed after lastSyncDTime. Each document includes Items. Line Quantity is negative. Deleted documents are appended after the live page. Ordered by ModifiedDatetime.
Response: List of DTOInventoryStockReduction.
8. Payload reference
8.1 DTOInventoryStockVoucher
• Header: ID, InvoiceNo, ReferenceNo, VoucherMode, VoucherType, VoucherDate
• Org: OrganisationID, HeadOrganisationID, OrganisationName
• Status: PurchaseOrderStatus, IsAuthorizationDue, IsDraft, Comments, PurchaseOrderDueDate
• Link: LinkType, LinkTypeID, LinkTypeNo (+ collated/split PO flags)
• Parties: SuppliedBy/ID/Name, SuppliedTo/ID/Name
• Lines: VoucherItems[], ReceiveStockCustomDetails[]
• Lists also include DTOAPIBase sync fields (ModifiedDatetime, IsDeleted, …)
8.2 DTOInventoryStockVoucherItem
InventoryID, InventoryName, BatchNo, BatchExpiryDate, PackSize, PackQuantity, FreePackQuantity, Quantity, StockDirection, QOH, BatchQOH, BuyingPrice, SellingPrice (nullable; null = master; 0 = explicit zero), DiscountPercentage, TaxID, ItemNotes.
8.3 DTOInventoryStockTransaction / Reduction / Adjust
• Transaction — getTransactions row; signed Quantity; TransactionType Consumable|Adjustment|Bill|Voucher.
• Reduction — ReductionNumber, ClinicID/Name, Reason, ReductionDate, Comments, Items (Quantity negative).
• Adjust (webhook) — hand add/new batch/reduce only; not used for voucher lines.
9. Webhooks
Register URLs in Clinicea Organisation webhook settings. Clinicea POSTs JSON asynchronously after a successful save. Webhook failure does not roll back the save.
9.1 Feature map
Feature | When | Payload |
|---|---|---|
StockAdjust | Hand inventory increase / decrease / new batch | DTOInventoryStockAdjust |
StockVoucher | Posted send / receive / return | DTOInventoryStockVoucher |
PurchaseOrderRequest | Vendor PO + clinic stock request | DTOInventoryStockVoucher |
PurchaseOrderRequestDraft | Drafts of PO / stock request | DTOInventoryStockVoucher |
StockVoucherDraft | Drafts of send / receive / return | DTOInventoryStockVoucher |
StockReduction | Stock reduction document (+ Delete) | DTOInventoryStockReduction |
StockTake | Completed stock take | DTOInventoryStockTake |
9.2 API / App → webhook
Action | Webhook feature |
|---|---|
createPurchaseOrder / App PO | PurchaseOrderRequest |
createStockRequest | PurchaseOrderRequest |
createSendStock / createReceivedOrder* / createReturnStock | StockVoucher |
Matching drafts | PurchaseOrderRequestDraft or StockVoucherDraft |
Manual App stock adjust | StockAdjust |
App stock reduction | StockReduction |
10. Validation catalogue (creates)
• Body not null; ID blank; VoucherDate valid and not future
• SuppliedByID / SuppliedToID required GUIDs; parties exist
• Return: SuppliedTo Vendor or Clinic when provided
• Link forbidden on PO / stock request / return
• Items required; InventoryID GUID; PackQuantity > 0; FreePackQuantity >= 0; Discount 0–100
• Inventory exists in owning clinic; tax exists if overridden
• Batch rules per section 3.4; BatchExpiryDate future when present
• Receive-from-vendor: required custom fields must have PrimaryValue when posted
• Insufficient stock: -Ve###{InventoryID}###{BatchNo}
11. Error examples
HTTP | Example body / meaning |
|---|---|
400 | Operation Failed: Object cannot be null (JSON bind / empty DateTime) |
400 | LinkType and LinkTypeID are not allowed for purchase order, stock request, or return stock. |
400 | Batch number is required for inventory … because batch tracking is on. |
400 | BatchExpiryDate … must be a future date. |
400 | -Ve###{inventoryId}###{batchNo} |
401 | You are not Authorized to view this content |
Updated on: 16/11/2026
Thank you!