Reconcile payments to invoices

Learn how to combine the getRemittanceHeaders and getRemittance operations to reconcile each payment to the invoices it covers. This workflow replaces manual Vendor Central exports, so you can feed reconciled remittance data directly into your ERP.

Prerequisites

To complete this tutorial, you must have:

• Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.
• Approval for the Finance and Accounting role in your developer profile.
• The Finance and Accounting role selected in the App registration page for your application.

Step 1. Retrieve the payments in your reconciliation window

Call the getRemittanceHeaders operation with the marketplaceId, startDate, and endDate to retrieve payments for your reconciliation window. Each request supports a date window of up to 90 days. To cover a longer period, split it into non-overlapping 90-day ranges and page through each range with nextToken. For more information, refer to Retrieve remittance headers.

Match each payment against your bank statement using paymentAmount, paymentDate, and paymentNumber. Retain the uniquePaymentId for each payment—you use it in the next step.

📘

Note

The unique payment ID (uniquePaymentId) is different from the payment number (paymentNumber). Use uniquePaymentId when you call getRemittance in the next step.

Step 2. Retrieve the invoices covered by each payment

For each uniquePaymentId from Step 1, call the getRemittance operation with the marketplaceId parameter to retrieve the invoice-level line items covered by that payment. Page through the line items with nextTokenForLineItems until you retrieve all pages. For more information, refer to Retrieve payment line-item detail.

Step 3. Reconcile each payment to its invoices

For each payment, reconcile the line items to the payment total:

• Use invoiceNumber to match each line item to the corresponding invoice in your ERP.
• Compare totalAmount (the invoiced amount) against netAmountPaid (the net cash paid) to identify variances. The totalAmount breaks down into InvoiceAmount and TaxAmount. The netAmountPaid breaks down into AmountPaid and TermsDiscountTaken.
• Use the TermsDiscountTaken breakdown to identify early-payment discounts applied to specific invoices.

The sum of netAmountPaid across the line items reconciles to the payment recorded in Step 1, giving you a complete audit trail from bank statement to invoice.

A single invoice can be paid or deducted across multiple payments. In such cases, the netAmountPaid represents the portion of the invoice amount that was paid through the paymentNumber or uniquePaymentId included in the API request.

Step 4. Automate the workflow

Schedule the workflow to run on a recurring basis. For example, run a daily job that queries the previous day's payments, or a monthly job for month-end close. Persist the uniquePaymentId values you have already processed so that each run only retrieves and reconciles new payments.

📘

Note

The date range between startDate and endDate can't exceed 90 days per request, and remittance data is available from 1 January 2024 onward. Plan your reconciliation windows accordingly.