---
title: "Three-way matching API guide: POs, receipts and bills"
description: "A three-way matching API guide: where ERPs store goods receipts, how receipt lines link to PO lines and bills, and why QuickBooks and Xero stop at two-way."
author: "GJ"
published: "2026-11-16"
updated: "2026-11-16T04:18:00.052Z"
url: "https://www.apideck.com/blog/three-way-matching-api"
category: "Accounting"
tags: ["Accounting", "Guides & Tutorials"]
---

# Three-way matching API guide: POs, receipts and bills

A purchase order in Xero has five possible statuses, and none of them means the goods arrived. Xero's [accounting OpenAPI spec](https://github.com/XeroAPI/Xero-OpenAPI/blob/master/xero_accounting.yaml) lists `DRAFT`, `SUBMITTED`, `AUTHORISED`, `BILLED` and `DELETED`, and there is no receiving endpoint anywhere in it. An AP automation product that promises three-way matching to a Xero customer has nothing to match the bill against except the order. Building a three-way matching API integration starts there, with whether the customer's ERP records a receipt at all and whether you can read it and tie it back to a purchase order line.

## Three-way matching in accounts payable

Three documents describe every purchase of goods. The buyer raises a purchase order. When the delivery arrives, the warehouse records a goods receipt against that order. The supplier's invoice comes in separately, and most accounting systems store it as a bill. Three-way matching compares them line by line before the bill is paid, so the company pays the agreed price and only for goods that actually arrived.

Oracle's [Payables documentation](https://docs.oracle.com/cd/A60725_05/html/comnls/us/ap/point04.htm) spells out the checks. Two-way matching compares the invoice with the purchase order: the quantity billed must not exceed the quantity ordered, and the invoice price must not exceed the order price. Three-way matching adds the receipt, so the quantity billed must not exceed the quantity received. Four-way matching adds a check against the quantity accepted after inspection. Each check runs within tolerances, and an invoice that falls outside them gets a matching hold that has to be released before anyone can pay it.

![Diagram of the three documents in three-way matching: the purchase order sets price and quantity ordered, the goods receipt records quantity received, and each invoice line is checked against both before payment](https://images.ctfassets.net/d6o5ai4eeewt/26dPF3fCDTp8pT6XwHYm58/422ebd15d34994f69dbaaa92cb0a4ef5/concept.png)

Microsoft's [invoice matching docs](https://learn.microsoft.com/en-us/dynamics365/finance/accounts-payable/accounts-payable-invoice-matching) give a worked example. An order and a receipt cover 1,000 batteries at 1.00, and the invoice arrives at 1.10. With a 5% price tolerance, anything up to 1.05 would pass and 1.10 is flagged. The receipt is the document that catches the other common case, a bill for goods that were short-shipped or never delivered.

## Matching controls inside each ERP

Every ERP that records receipts also ships some form of matching, and they differ more than the shared name suggests. NetSuite's [3 Way Match Vendor Bill Approval workflow](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_4096219721.html) comes in a separately installed SuiteApp and reads quantity and amount tolerances set on records such as the vendor and the item. It does not support partially received item receipts. SAP S/4HANA posts an invoice that breaks an upper tolerance but [blocks the whole invoice for payment](https://learning.sap.com/courses/invoice-verification-in-sap-s-4hana/entering-invoices-with-variances-1). Odoo's version is a "Should Be Paid" field on the bill that marks exceptions, and it only works when the product's [bill control policy](https://www.odoo.com/documentation/18.0/applications/inventory_and_mrp/purchase/manage_deals/control_bills.html) is set to received quantities. Business Central has the person entering the invoice [pull in receipt lines](https://learn.microsoft.com/en-us/dynamics365/business-central/purchasing-how-to-combine-receipts) with Get Receipt Lines, from one vendor in one currency, or match order lines with Get Order Lines, which shows price and quantity warnings on incoming invoice drafts.

If your product does the matching, you are replacing or sitting in front of those controls. That means reading the three documents out of the ledger and joining them at line level, with the received quantity summed across every receipt for a line.

## Receipt records in four ERPs

The receipt goes by a different name in every system, and the link back to the order sits in a different place.

| ERP | Receipt record | Link from receipt line to PO line | Link from bill line |
|---|---|---|---|
| NetSuite | Item receipt (`itemreceipt`), created by transforming the PO | `orderLine` during the transform | Bill Purchase Orders, optionally per receipt |
| Business Central | `purchaseReceipt`, read-only in API v2.0 | None in the API, header `orderNumber` only | None in the API |
| SAP S/4HANA Cloud | Material document, movement type 101 | Purchase order and item number on each line | `PurchaseOrder`, `PurchaseOrderItem` and, with GR-based verification, the material document |
| Odoo | Incoming `stock.picking` with `stock.move` lines | `purchase_line_id` on each move | `purchase_line_id` on the bill line |

NetSuite creates an item receipt by [transforming the purchase order](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_0817102411.html) (`POST /record/v1/purchaseorder/{id}/!transform/itemreceipt`), and the [SOAP docs](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N3681685.html) use `orderLine` to tie each receipt line to its order line during the transform. Our [NetSuite integration guide](https://www.apideck.com/blog/netsuite-integration-guide) covers authentication and SuiteQL for the rest of the sync. Without Advanced Receiving, NetSuite combines receiving and billing, so there is no separate receipt to match against.

Business Central's [purchaseReceipt](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_purchasereceipt) resource supports GET only. The header carries `orderNumber`, and the [receipt lines](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_purchasereceiptline) carry quantities and unit cost but no reference to an order line. Purchase invoice lines in API v2.0 have no order or receipt reference either. What the API does give you is `receivedQuantity` and `invoicedQuantity` on each [purchase order line](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_purchaseorderline), which is often enough to check a bill against. The [Business Central API guide](https://www.apideck.com/blog/microsoft-dynamics-business-central-api-integration-guide-2025) covers the auth and environment setup.

In SAP, a goods receipt for a purchase order is a material document with [movement type 101](https://userapps.support.sap.com/sap/support/knowledge/en/3697643), and posting it credits the [GR/IR clearing account](https://learning.sap.com/courses/exploring-end-to-end-business-processes-in-sap/managing-goods-movements_d7cf8543-eb45-490b-810a-237bbd17485f) that the invoice later clears. The supplier invoice API takes `PurchaseOrder` and `PurchaseOrderItem` per line, and SAP [KBA 3537312](https://userapps.support.sap.com/sap/support/knowledge/en/3537312) explains that the material document reference fields are only needed when the GR-based invoice verification indicator is set on the order.

Odoo has the most direct links of the four. Each incoming stock move and each vendor bill line carries `purchase_line_id`, and the purchase order line computes `qty_received` itself, converting receipts into the order line's unit of measure ([Odoo 18 source](https://github.com/odoo/odoo/blob/18.0/addons/purchase_stock/models/purchase_order_line.py)). Connection details are in our [Odoo API guide](https://www.apideck.com/blog/how-to-integrate-with-the-odoo-api).

## QuickBooks Online and Xero stop at two-way

QuickBooks Online has purchase orders and bills but no receipt entity. Intuit's own [v3 SDK schema](https://github.com/intuit/QuickBooks-V3-Java-SDK/blob/develop/ipp-v3-java-data/src/main/xsd/Finance.xsd) defines `Bill` and `PurchaseOrder` entities and no `ItemReceipt` entity. A bill can link to a purchase order line through `LinkedTxn` with a `TxnLineId`, so line-level two-way matching works.

Xero gives you less. Neither its invoice nor its line item has a purchase order field, and the `/Receipts` endpoint is for expense claim receipts. Apideck's spec notes that on Xero, a bill's `bill_number` and `po_number` both come from `InvoiceNumber` and are always identical. Matching a Xero bill to an order means comparing reference text.

For customers on either ledger, three-way matching has to happen in your product, with the receipt captured there or in a warehouse system. Say so in the sales conversation. A customer who runs QuickBooks Online and expects the third leg from the ledger will find out during onboarding otherwise.

## Three-way matching API calls with Apideck

Apideck's [Accounting API](https://www.apideck.com/accounting-api) reads the three documents through one model. Purchase orders and bills are live resources, and [Goods Receipts](https://developers.apideck.com/apis/accounting/reference#tag/Goods-Receipts) is in beta, read-only, for four connectors:

- NetSuite (item receipts)
- Microsoft Dynamics 365 Business Central
- SAP S/4HANA Cloud
- Odoo

The [coverage page](https://developers.apideck.com/apis/accounting/coverage) lists which operations and filters each connector supports. Purchase orders cover 23 connectors and bills cover 49.

![Diagram of the join: one purchase order line linked from several goods receipt lines and from bill lines through the same purchase_order object with id, line_id and line_number](https://images.ctfassets.net/d6o5ai4eeewt/QlIGtJC8CSczoMGVIoJAb/8caa23e9176b56f765d6f2dca1a0ad54/join.png)

The join key is the same object on every line that points at an order. A goods receipt line and a bill line both carry `purchase_order` with `id`, `line_id` and `line_number`, so receipts and bills meet on the purchase order line. A request for one order's receipts on an Odoo tenant, and one receipt from the `data` array of the response (illustrative values, shortened):

```bash
curl "https://unify.apideck.com/accounting/goods-receipts?filter[purchase_order_id]=PO-123" \
  -H "Authorization: Bearer $APIDECK_API_KEY" \
  -H "x-apideck-app-id: $APIDECK_APP_ID" \
  -H "x-apideck-consumer-id: customer-42" \
  -H "x-apideck-service-id: odoo"
```

```json
{
  "id": "1834",
  "receipt_number": "WH/IN/00412",
  "purchase_order_id": "PO-123",
  "status": "received",
  "received_date": "2026-11-12",
  "line_items": [
    {
      "line_number": 1,
      "purchase_order": {
        "id": "PO-123",
        "line_id": "981",
        "line_number": "1"
      },
      "item": { "id": "55", "name": "AA battery, pack of 4" },
      "quantity_received": 600
    }
  ]
}
```

A split delivery in Odoo produces one receipt per delivery, so the same `line_id` can appear on several receipts. Sum `quantity_received` per `purchase_order.line_id` before comparing it with the bill. The [`filter[purchase_order_id]`](https://developers.apideck.com/apis/accounting/reference#tag/Goods-Receipts) parameter only matches the order a receipt was generated from, so a receipt that merges lines from a second order will not come back for that second order. Match on `line_id`.

The other three connectors each need a small adjustment, all documented in the spec's per-connector notes:

- Business Central receipt lines have no order line reference, so `purchase_order_id` and `line_items[].purchase_order` are always null. Match on the header `po_number` plus item and quantity, or compare the bill against the order line's received quantity. Receipts posted straight from a purchase invoice have no `po_number` at all.
- SAP S/4HANA Cloud gives `purchase_order.line_number` but no `line_id`, and receipt ids are a composite of document number and fiscal year, such as `5000000123:2026`. A cancellation comes back as a separate receipt with `status: cancelled`, and the original is reported as cancelled too.
- NetSuite returns only receipts created from a purchase order, and this release supports no filters or sorts. A voided receipt still reports `status: received`, so check the order when that matters. The spec doesn't document whether receipt lines carry `purchase_order.line_id` on NetSuite, so check a few real receipts before you rely on it.

Bill lines use the same `purchase_order` shape, and whether a connector fills it on bills differs per connector. Check a few real bills from the customer's ledger before you rely on it, and fall back to the bill's `po_number` and the line's item when it is empty.

## Bills that arrive before the goods

Business Central's documentation names the case directly: "A vendor invoice arrives before you receive the goods they're billing you for." SAP posts such an invoice to the GR/IR account, and with the DW tolerance key set to Check Limit it blocks the invoice for payment instead of putting it in error. SAP [KBA 3769147](https://userapps.support.sap.com/sap/support/knowledge/en/3769147) adds that it will not release itself after the goods receipt unless the background verification and release jobs are scheduled.

Your product has the same problem one step removed. Apideck has webhooks for purchase orders and bills but none for goods receipts, so a bill waiting on a receipt needs a poll. Business Central and Odoo support `filter[updated_since]` on receipts. SAP records no last-changed timestamp on a goods receipt and NetSuite takes no filters, so for those two you re-read the list, sorted by `created_at` on SAP. Keep the bill in a waiting state and re-run the match when a receipt for its order line shows up. A person only needs to see it once a tolerance is broken.

If you sell AP automation into mid-market companies, check which ledger each customer runs before you promise the match. Odoo and SAP S/4HANA Cloud support line-level matching today. Test NetSuite on a few real receipts first. On Business Central, plan for matching on the PO number and item, and on the two small-business ledgers, capture the receipt in your own product. Start with the [Apideck Accounting API](https://www.apideck.com/accounting-api) to read all three documents from your customers' ledgers through one integration.
