Purchasing

A purchase order records what a merchant ordered from a supplier and at what price. Receiving it moves the goods into stock at the ordered cost.

Endpoints

Method	Path	Scope
GET	/v1/purchase-orders	purchase_orders.read
GET	/v1/purchase-orders/:id	purchase_orders.read
POST	/v1/purchase-orders	purchase_orders.write
PATCH	/v1/purchase-orders/:id	purchase_orders.write
PATCH	/v1/purchase-orders/:id/receive	purchase_orders.write

Raise an order

curl -s "$API_BASE_URL/purchase-orders" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "orderNo": 4471,
    "date": "2026-07-29",
    "reciveDate": "2026-08-02",
    "supplierId": 17,
    "storeId": 1,
    "narration": "Weekly coffee order",
    "incTax": false,
    "items": [
      {
        "itemId": 9001,
        "qty": 24,
        "rate": 12.40,
        "taxableAmount": 297.60,
        "taxId": 3
      },
      {
        "itemId": 9002,
        "qty": 60,
        "rate": 0.92,
        "taxableAmount": 55.20,
        "taxId": 3,
        "note": "Oat, 1L"
      }
    ]
  }'

Header fields

Field	Type	Required	Notes
orderNo	number	yes	Document number in the merchant’s own sequence
date	string	yes	YYYY-MM-DD order date
reciveDate	string	yes	Expected delivery date
supplierId	number	yes	Existing supplier row
storeId	number	yes	Where the goods will land
invoNo	string	no	Supplier invoice number. Required when receiving on create
narration	string	no	Free-text note
currencyId	number	no	For orders priced in a foreign currency
exchangeRate	number	no	Rate used to convert to the merchant’s currency
incTax	boolean	no	true when line rates already include tax
roudOfAmount	number	no	Rounding adjustment applied to the document total
provider	string	no	Free-text source marker for the document

Line fields

Field	Type	Required	Notes
itemId	number	yes
variantId	number	no	0 when the item has no variants
qty	number	yes	Ordered quantity
rate	number	yes	Unit purchase price
taxableAmount	number	yes	rate × qty before tax. Recomputed server-side
supplyPrice	number	no	Supplier list price, when it differs from the negotiated rate
taxId	number	no	Purchase tax for the line. Defaults to the item’s purchase tax
cessId / cess	number	no	Additional levies where applicable
note	string	no	Per-line note
serialNo	{ value: string }[]	no	Pre-picked serial numbers for serial-tracked items
id	number	no	Existing line id — send it on PATCH to update a line instead of adding one

Patching lines

On PATCH, the items array is the new state of the document. Include the id of every line you want to keep; lines you omit are removed.

Receive the goods

Receiving raises stock at the destination store and closes the order.

curl -s -X PATCH "$API_BASE_URL/purchase-orders/9912/receive" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "invoNo": "SUP-2026-8841",
    "reciveDate": "2026-08-02"
  }'

invoNo is required at receipt — it is the link between the merchant’s stock ledger and the supplier’s invoice. Partial receipts are handled by patching quantities on the order before receiving it.

Listing orders

curl -s "$API_BASE_URL/purchase-orders?storeId=1&fromDate=2026-07-01&toDate=2026-07-31&limit=100" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Parameter	Notes
storeId	Restrict to one store
supplierId	Restrict to one supplier
fromDate / toDate	Document date window, YYYY-MM-DD
search	Matches order number and supplier invoice number
page, limit, sort, order	Standard paging