The new Apideck developer docs are live. See what’s new →

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

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.

GJGJ

GJ · Co-founder, Apideck

10 min readView as .md
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 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 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

Microsoft's invoice matching docs 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 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. 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 is set to received quantities. Business Central has the person entering the invoice pull in receipt lines 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.

ERPReceipt recordLink from receipt line to PO lineLink from bill line
NetSuiteItem receipt (itemreceipt), created by transforming the POorderLine during the transformBill Purchase Orders, optionally per receipt
Business CentralpurchaseReceipt, read-only in API v2.0None in the API, header orderNumber onlyNone in the API
SAP S/4HANA CloudMaterial document, movement type 101Purchase order and item number on each linePurchaseOrder, PurchaseOrderItem and, with GR-based verification, the material document
OdooIncoming stock.picking with stock.move linespurchase_line_id on each movepurchase_line_id on the bill line

NetSuite creates an item receipt by transforming the purchase order (POST /record/v1/purchaseorder/{id}/!transform/itemreceipt), and the SOAP docs use orderLine to tie each receipt line to its order line during the transform. Our 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 resource supports GET only. The header carries orderNumber, and the receipt lines 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, which is often enough to check a bill against. The Business Central API guide covers the auth and environment setup.

In SAP, a goods receipt for a purchase order is a material document with movement type 101, and posting it credits the GR/IR clearing account that the invoice later clears. The supplier invoice API takes PurchaseOrder and PurchaseOrderItem per line, and SAP KBA 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). Connection details are in our Odoo API guide.

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 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 reads the three documents through one model. Purchase orders and bills are live resources, and 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 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

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):

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"
{
  "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] 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 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 to read all three documents from your customers' ledgers through one integration.

Frequently asked questions

Trusted by fast-moving product & engineering teams

Bonsai by Zoom
JobNimbus
Blue Zinc
Exact
Drata