Articles on: API & Integrations

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 

https://api.clinicea.com 


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
https://api.clinicea.com/swagger/ui/index#/StockReduction
https://api.clinicea.com/swagger/ui/index#/StockTake


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": "" 
    } 
  ] 
} 


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

Was this article helpful?

Share your feedback

Cancel

Thank you!