Acknowledge Purchase Orders

POST /api/external/v1/po/acknowledge

Tells Openleaf which version of each PO your system has ingested. Use it to:

• pull only POs you haven't seen yet (filters.is_acknowledged: false), and
• find POs that changed after you ingested them (filters.is_updated_since_acknowledged: true), e.g. a quantity, address or status change.

Acknowledging does not change the PO's status or anything else about the PO — it's only bookkeeping for your integration. Fetching a PO without acknowledging it has no side effects.

Request body

Field	Type	Required	Description
purchase_orders	array (1–1000 items)	Yes	POs to acknowledge
purchase_orders[].po_id	string (UUID)	Yes	PO ID
purchase_orders[].sync_hash	string	Recommended	The sync_hash you received for this PO. If omitted, the PO's current version is acknowledged — so a change made between your fetch and this call would be missed.

Request Example

{
  "purchase_orders": [
    { "po_id": "b6b2a3e1-0c61-4fd2-9a07-3bf2035888f1", "sync_hash": "e85ac4651d63d68c345e51d94b37421c" }
  ]
}

Response 200 OK

{
  "success": true,
  "status_code": 200,
  "message": "Successfully acknowledged purchase orders",
  "data": {
    "acknowledged": ["b6b2a3e1-0c61-4fd2-9a07-3bf2035888f1"],
    "not_found": []
  }
}

not_found lists PO IDs that don't exist on your account; they are ignored. Re-acknowledging a PO is safe and simply overwrites the previous acknowledgement. Requires the account's admin token (403 otherwise).

Recommended sync flow

1. Pull new POs

loop:
  POST /po/getOrdersBatchwise  { "batch": 0, "filters": { "is_acknowledged": false } }
  if purchase_orders is empty: stop
  save the POs in your system (upsert by po_id)
  POST /po/acknowledge  with each po_id + sync_hash you just saved

Always request batch: 0: each acknowledged batch drops out of the is_acknowledged: false result, so the next unseen 200 move up to the first page. (Stepping batch 0, 1, 2… while acknowledging in between would skip POs.) Call Count Purchase Orders with the same filters first if you need the total for progress reporting.

2. Pull changed POs — the same loop with "filters": { "is_updated_since_acknowledged": true }. Update the PO in your system (check status for CANCELLED / HOLD / EXPIRED), then acknowledge it with the new sync_hash.

Both filters combine with all other filters (e.g. channel, received_start_date).

What counts as a change

sync_hash covers the PO's business fields: po_number, reference_number, status, readable_status, customer / billing / vendor details, fc_code, sku_details (codes, quantities, prices, taxes), amounts, channel, received / release / expiry dates, warehouse assignment, is_assigned, is_fulfilled, batch_number, SO date (so_date), invoice number and date, e-way bill number, and note.

It does not cover remarks, custom_data, sap_whs_code, transaction_type, appointment / GRN flags, or shipment documents (waybills, labels) — changes to those alone don't flag the PO as updated.

In rare cases (e.g. certain warehouse-system integrations rewriting a PO's data) an acknowledgement can be cleared, and the PO will show up again as is_acknowledged: false. Treat ingestion as an upsert keyed on po_id so this is harmless.