Stock Management

Inventory and supplier management for Malawi EIS.

📌 Typical order

Fetch reference data: HS codes, units of measure, suppliers and adjustment reasons.
Add products. Each one starts with zero quantity in the warehouse.
Bring stock in with an informal purchase (non-VAT-registered suppliers) or a stock adjustment.
Transfer stock from the warehouse to a site, or between sites, so the site can sell it.
For manufacturing, convert raw materials into finished products.

Endpoints in this section

Get stock adjustment reasons

POST/api/v1/{tin}/stock-adjustment-reasons🔒 token required

Retrieve available stock adjustment reasons from Malawi Revenue Authority (MRA) EIS system. These reasons are used when adjusting inventory quantities.

Parameters

Name	In	Required	Description
`tin`	path	Yes	Taxpayer Identification Number (e.g., 20154457)
`deploymentEnvironment`	query	Yes	MRA deployment environment - 'Sandbox' for testing or 'Production' for live One of: Sandbox, Production
`token`	query	Yes	API access token for authentication

Request Body

Field	Type	Required	Description
`terminalId`	string	Yes	Terminal ID from activation (used to fetch JWT token) Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`

Responses

200Stock adjustment reasons retrieved successfully
400Bad request - invalid parameters or missing terminal
403Forbidden - Company inactive, license expired, or environment mismatch
404Terminal not found - Please activate the terminal first

Get suppliers

🚀 Try it

POST/api/v1/{tin}/get-suppliers🔒 token required

Retrieve available suppliers from Malawi Revenue Authority (MRA) EIS system. Requires an activated terminal and valid JWT token.

Parameters

Name	In	Required	Description
`tin`	path	Yes	Taxpayer Identification Number (e.g., 20154457)
`deploymentEnvironment`	query	Yes	MRA deployment environment - 'Sandbox' for testing or 'Production' for live One of: Sandbox, Production
`token`	query	Yes	API access token for authentication

Request Body

Field	Type	Required	Description
`terminalId`	string	Yes	Terminal ID from activation (used to fetch JWT token) Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`

Responses

200Suppliers retrieved successfully
400Bad request - invalid parameters or missing terminal
403Forbidden - Company inactive, license expired, or environment mismatch
404Terminal not found - Please activate the terminal first

Get units of measure

🚀 Try it

POST/api/v1/{tin}/get-units-of-measure🔒 token required

Retrieve available units of measure from Malawi Revenue Authority (MRA) EIS system. Requires an activated terminal and valid JWT token.

Parameters

Name	In	Required	Description
`tin`	path	Yes	Taxpayer Identification Number (e.g., 20154457)
`deploymentEnvironment`	query	Yes	MRA deployment environment - 'Sandbox' for testing or 'Production' for live One of: Sandbox, Production
`token`	query	Yes	API access token for authentication

Request Body

Field	Type	Required	Description
`terminalId`	string	Yes	Terminal ID from activation (used to fetch JWT token) Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`

Responses

200Units of measure retrieved successfully
400Bad request - invalid parameters or missing terminal
403Forbidden - Company inactive, license expired, or environment mismatch
404Terminal not found - Please activate the terminal first

Get HS codes

🚀 Try it

POST/api/v1/{tin}/get-hs-codes🔒 token required

Retrieve available Harmonized System (HS) codes from Malawi Revenue Authority (MRA) EIS system. Requires an activated terminal and valid JWT token.

Parameters

Name	In	Required	Description
`tin`	path	Yes	Taxpayer Identification Number (e.g., 20154457)
`deploymentEnvironment`	query	Yes	MRA deployment environment - 'Sandbox' for testing or 'Production' for live One of: Sandbox, Production
`token`	query	Yes	API access token for authentication

Request Body

Field	Type	Required	Description
`terminalId`	string	Yes	Terminal ID from activation (used to fetch JWT token) Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`

Responses

200HS codes retrieved successfully
400Bad request - invalid parameters or missing terminal
403Forbidden - Company inactive, license expired, or environment mismatch
404Terminal not found - Please activate the terminal first

Add a new product

🚀 Try it

POST/api/v1/{tin}/add-product🔒 token required

Add a new product to master products and create zero-quantity warehouse inventory for the taxpayer on the Malawi Revenue Authority (MRA) EIS system. Requires an activated terminal and valid JWT token.

Sample HS Codes:

HS Code	Description	Tax Rate
`94061010`	GREEN HOUSES OF WOOD	E
`94061090`	OTHER PREFABRICATED BUILDINGS	E
`94062000`	MODULAR BUILDING UNITS, OF STEEL	A
`94069000`	OTHER PREFABRICATED BUILDINGS	A

Sample UOM Codes:

UOM	Description
`DR`	Drum
`%`	Percentage
`%O`	Per mille
`D`	Day

Parameters

Name	In	Required	Description
`tin`	path	Yes	Taxpayer Identification Number (e.g., 20154457)
`deploymentEnvironment`	query	Yes	MRA deployment environment - 'Sandbox' for testing or 'Production' for live One of: Sandbox, Production
`token`	query	Yes	API access token for authentication

Request Body

Field	Type	Required	Description
`barcode`	string	Yes	Product barcode / item code Example: `260306145930`
`hsCode`	string	Yes	Harmonized System (HS) code. Sample HS codes: 94061010 (GREEN HOUSES OF WOOD, Tax Rate E), 94061090 (OTHER PREFABRICATED BUILDINGS, Tax Rate E), 94062000 (MODULAR BUILDING UNITS, OF STEEL, Tax Rate A), 94069000 (OTHER PREFABRICATED BUILDINGS, Tax Rate A) Example: `94062000`
`name`	string	Yes	Product name Example: `Breeding Horse Premium`
`description`	string	No	Optional product description Example: `Premium breeding horses from local farm`
`uom`	string	Yes	Unit of Measure (UOM) code. Sample UOMs: DR (Drum), % (Percentage), %O (Per mille), D (Day) Example: `DR`
`terminalId`	string	Yes	Terminal ID from activation (used to fetch JWT token) Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`

Responses

200Product added successfully
400Bad request - invalid parameters or validation errors
403Forbidden - Company inactive, license expired, or environment mismatch
404Terminal not found - Please activate the terminal first

Submit Stock Adjustment

🚀 Try it

POST/api/v1/{tin}/stock-adjustment🔒 token required

Submit a stock adjustment request to the Malawi Revenue Authority (MRA) EIS system. Use this for adjustments like Theft, Damage, Loss, etc. Requires an activated terminal and valid JWT token.

Parameters

Name	In	Required	Description
`tin`	path	Yes	Taxpayer Identification Number (e.g., 20154457)
`deploymentEnvironment`	query	Yes	MRA deployment environment - 'Sandbox' for testing or 'Production' for live One of: Sandbox, Production
`token`	query	Yes	API access token for authentication

Request Body

Field	Type	Required	Description
`purchaseOrderNumber`	string	Yes	Your unique reference for this adjustment Example: `PO-ADJ-001`
`barcode`	string	Yes	Product barcode / item code Example: `260306145930`
`quantity`	number	Yes	Quantity to adjust Example: `1`
`adjustmentReason`	string	Yes	Reason for adjustment (see /stock-adjustment-reasons) Example: `Theft`
`adjustmentType`	string	Yes	One of: `Increase`, `Decrease` Example: `Decrease`
`terminalId`	string	Yes	Terminal ID from activation Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`
`siteId`	string	No	Optional Site ID (overrides terminal site if provided) Example: `CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce`
`taxpayerRemarks`	string	No	Optional remarks Example: `Inventory audit adjustment`

Responses

200Stock adjustment submitted successfully
400Bad request - invalid parameters

Stock Adjustment DEBUG TESTING AID

🚀 Try it

POST/api/v1/{tin}/stock-adjustment-debug🔒 token required

Debug endpoint for stock adjustment. Returns the formatted payload that would be sent to the MRA EIS system without actually sending it.

Parameters

Name	In	Required	Description
`tin`	path	Yes	Taxpayer Identification Number (e.g., 20154457)
`deploymentEnvironment`	query	Yes	MRA deployment environment - 'Sandbox' or 'Production' One of: Sandbox, Production
`token`	query	Yes	API access token for authentication

Request Body

Field	Type	Required	Description
`purchaseOrderNumber`	string	Yes	Example: `PO-DEBUG-001`
`barcode`	string	Yes	Example: `260306145930`
`quantity`	number	Yes	Example: `10`
`adjustmentReason`	string	Yes	Example: `Damaged goods`
`adjustmentType`	string	Yes	One of: `Increase`, `Decrease` Example: `Decrease`
`terminalId`	string (uuid)	Yes	Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`
`siteId`	string	No	nullable Example: `CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce`
`taxpayerRemarks`	string	No	nullable Example: `Debug simulation`

Responses

200Debug payload generated successfully

Submit Informal Purchase

🚀 Try it

POST/api/v1/{tin}/increase-descrease-stock-request🔒 token required

Submit an informal purchase request to the Malawi Revenue Authority (MRA) EIS system. This is typically used to increase stock from non-VAT registered suppliers. Requires an activated terminal and valid JWT token.

Parameters

Name	In	Required	Description
`tin`	path	Yes	Taxpayer Identification Number (e.g., 20154457)
`deploymentEnvironment`	query	Yes	MRA deployment environment - 'Sandbox' for testing or 'Production' for live One of: Sandbox, Production
`token`	query	Yes	API access token for authentication

Request Body

Field	Type	Required	Description
`supplierId`	integer	Yes	Example: `346`
`deliveryNoteNumber`	string	Yes	Example: `DN-2026-001`
`receivingDate`	string (date-time)	Yes	Example: `2026-03-26T10:00:00.000Z`
`purchaseOrderNumber`	string	No	Example: `PO-2026-001`
`receivedBy`	string	Yes	Example: `John Doe`
`totalItems`	integer	Yes	Example: `1`
`totalQuantity`	integer	Yes	Example: `50`
`totalValue`	number (float)	Yes	Example: `500000`
`notes`	string	Yes	Example: `Informal timber purchase`
`terminalId`	string	Yes	Terminal ID from activation (used to fetch JWT token) Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`
`items`	array<object>	Yes
`items[].itemCode`	string	No	Example: `260306145930`
`items[].description`	string	No	Example: `MDF LAMINATED`
`items[].quantityOrdered`	integer	No	Example: `50`
`items[].quantityReceived`	integer	No	Example: `50`
`items[].unitOfMeasure`	string	No	Example: `Piece`
`items[].unitPrice`	number (float)	No	Example: `10000`
`items[].totalPrice`	number (float)	No	Example: `500000`
`items[].isFinishedProduct`	boolean	No	Example: `true`

Responses

200Informal purchase submitted successfully

Query Stock Adjustments

🚀 Try it

POST/api/v1/{tin}/query-stock-adjustments🔒 token required

Retrieve a list of stock adjustments stored in the local database.

Parameters

Name	In	Required	Description
`tin`	path	Yes	Taxpayer Identification Number

Request Body

Field	Type	Required	Description
`purchaseOrderNumber`	string	No
`status`	string	No	One of: `success`, `failed`, ``
`pageSize`	integer	No	Example: `20`
`pageNo`	integer	No	Example: `1`

Responses

200List of stock adjustments

Check Product Status

🚀 Try it

POST/api/v1/{tin}/check-product-status🔒 token required

Retrieve detailed stock information, tax rates, and descriptions for a specific product directly from the MRA system.

Parameters

Name	In	Required	Description
`tin`	path	Yes	Taxpayer Identification Number
`token`	query	Yes	API access token for authentication
`deploymentEnvironment`	query	Yes	MRA deployment environment One of: Sandbox, Production

Request Body

Field	Type	Required	Description
`terminalId`	string	Yes	Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`
`productId`	string	Yes	Barcode or product code Example: `260306145930`

Responses

200Product status retrieved successfully

Stock Transfer

🚀 Try it

POST/api/v1/{tin}/stock-transfer🔒 token required

Transfer inventory from warehouse to site or between sites. Requires an activated terminal and valid JWT token.

Parameters

Name	In	Required	Description
`tin`	path	Yes	Taxpayer Identification Number (e.g., 20154457)
`deploymentEnvironment`	query	Yes	MRA deployment environment - 'Sandbox' for testing or 'Production' for live One of: Sandbox, Production
`token`	query	Yes	API access token for authentication

Request Body

Field	Type	Required	Description
`terminalId`	string	Yes	Terminal ID from activation (used to fetch JWT token) Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`
`fromWarehouseToSite`	boolean	No	Flag indicating if transfer is from warehouse to site Example: `true`
`fromSiteId`	string	No	Source site or warehouse ID Example: `warehouse-001`
`toSiteId`	string	No	Destination site ID Example: `CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce`
`items`	array<object>	No
`items[].barcode`	string	No	Product barcode Example: `260306145930`
`items[].quantity`	number	No	Quantity to transfer Example: `10`
`items[].price`	number	No	Unit price of the item Example: `1000`

Responses

200Stock transfer processed successfully
400Bad request - invalid parameters
403Forbidden - Company error or environment mismatch
404Not Found - Terminal or company not found

Get Raw Materials

🚀 Try it

POST/api/v1/{tin}/get-raw-materials🔒 token required

Retrieve a paginated list of raw materials from the Malawi Revenue Authority (MRA) EIS system. This refers to goods that are used as inputs for production processes.

Parameters

Name	In	Required	Description
`tin`	path	Yes	Taxpayer Identification Number (e.g., 20154457)
`deploymentEnvironment`	query	Yes	MRA deployment environment - 'Sandbox' or 'Production' One of: Sandbox, Production
`token`	query	Yes	API access token for authentication

Request Body

Field	Type	Required	Description
`terminalId`	string (uuid)	Yes	Terminal ID from activation Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`
`page`	integer	No	Page number to retrieve Example: `1`
`pageSize`	integer	No	Number of items per page (max 200) Example: `50`

Responses

200Raw materials retrieved successfully
401Unauthorized - Session expired
404Company or Terminal not found

Submit Raw Material Conversion

🚀 Try it

POST/api/v1/{tin}/submit-raw-material-conversion🔒 token required

Submit a production conversion request to the Malawi Revenue Authority (MRA) EIS system. This endpoint records the processing of raw materials into finished goods, ensuring inventory levels are adjusted accordingly for both input and output products.

Parameters

Name	In	Required	Description
`tin`	path	Yes	Taxpayer Identification Number (e.g., 20154457)
`deploymentEnvironment`	query	Yes	MRA deployment environment - 'Sandbox' or 'Production' One of: Sandbox, Production
`token`	query	Yes	API access token for authentication

Request Body

Field	Type	Required	Description
`terminalId`	string (uuid)	Yes	Terminal ID from activation Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`
`productionBatchId`	string	Yes	Unique batch identifier for this production run Example: `BATCH-2026-001`
`productionDate`	string (date-time)	Yes	The date and time production occurred Example: `2026-04-16T09:52:52.772Z`
`rawMaterials`	array<object>	Yes	List of raw materials consumed
`rawMaterials[].productId`	string	No	Example: `RM-001`
`rawMaterials[].productName`	string	No	Example: `Timber Log`
`rawMaterials[].availableQuantity`	number (float)	No	Example: `10.5`
`rawMaterials[].usedQuantity`	number (float)	No	Example: `2`
`finishedProducts`	array<object>	Yes	List of finished products generated
`finishedProducts[].quantity`	number (float)	No	Example: `5`
`finishedProducts[].unitOfMeasure`	string	No	Example: `Piece`
`finishedProducts[].expiryDate`	string (date-time)	No	Example: `2027-04-16T09:52:52.772Z`
`finishedProducts[].productDescription`	string	No	Example: `MDF Board`
`finishedProducts[].barcode`	string	No	Example: `260306145930`

Responses

200Conversion submitted successfully
400MRA Validation Error or Processing Error
401Unauthorized - Terminal session expired
404Company or Terminal not found

Ping MRA Server

🚀 Try it

POST/api/v1/{tin}/ping-server🔒 token required

Check the connectivity between the WEAF system and the Malawi Revenue Authority (MRA) EIS system. This endpoint verifies that the terminal is correctly activated and the JWT token is valid for the selected environment.

Parameters

Name	In	Required	Description
`tin`	path	Yes	Taxpayer Identification Number (e.g., 20154457)
`deploymentEnvironment`	query	Yes	MRA deployment environment - 'Sandbox' or 'Production' One of: Sandbox, Production
`token`	query	Yes	API access token for authentication

Request Body

Field	Type	Required	Description
`terminalId`	string (uuid)	Yes	Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`

Responses

200Ping successful