PO Matching
Match purchase orders to bills and manage match status. All endpoints require entityId.
Get Match Candidates
GET /api/ap/match?entityId=...Returns unmatched POs, unmatched bills, and auto-generated match suggestions.
Response:
{
"unmatchedPOs": [
{
"id": "uuid",
"amount": "10000.00",
"effectiveDate": "2025-06-01",
"reference": "PO-2025-042",
"externalCounterpartyName": "Acme Corp"
}
],
"unmatchedBills": [
{
"id": "uuid",
"totalAmount": "10000.00",
"dueDate": "2025-07-01",
"vendorName": "Acme Corp",
"poMatchStatus": null
}
],
"suggestedMatches": [
{
"po": { "id": "uuid", "amount": "10000.00" },
"bill": { "id": "uuid", "totalAmount": "10000.00" },
"reason": "Exact amount match"
}
]
}Suggestion Criteria
Matches are suggested when:
- Amount — bill and PO amounts are within 1% of each other
- Date — bill and PO dates are within 30 days
Match a Bill to a PO
POST /api/ap/match{
"action": "match",
"entityId": "uuid",
"billId": "uuid",
"purchaseOrderId": "uuid"
}The system compares the bill amount to the PO amount and assigns a status:
| Status | Condition |
|---|---|
MATCHED | Amounts differ by less than $0.005 |
PARTIAL | Bill amount < PO amount |
OVER | Bill amount > PO amount |
Response:
{
"bill": { "id": "uuid", "poMatchStatus": "MATCHED", "matchedAmount": "10000.00" },
"matchStatus": "MATCHED"
}Unmatch a Bill
POST /api/ap/match{
"action": "unmatch",
"entityId": "uuid",
"billId": "uuid"
}Clears the PO association. The bill's purchaseOrderId, poMatchStatus, and matchedAmount are set to null.
Response:
{
"bill": { "id": "uuid", "poMatchStatus": null, "matchedAmount": null },
"matchStatus": null
}