Month-end close from documents rather than bank statements

At month end a marketplace payout lands in the account. Netted inside it: sales, shipping, refunds and fees. The tax adviser needs each of these amounts separately and with a document — and nobody wants to back them out of a lump payment.

The Commerce contract’s documents separate exactly these amounts: invoices with net, tax and gross per line, credit notes referencing their invoice, fee statements with recomputable lines and refunds per order. The close is built from them, not from the payout.

What this case requires

• A connected selling account. Documents arise from orders; no order, no document.
• A mapping to your accounting accounts. The documents deliver amounts and references, not your chart of accounts.
• Paged collection. Lists come with nextCursor; a month-end close reads them completely.
• A rule for open items. outstandingAmount shows what is not yet paid.

The sequence

The table names the responsible call per stage and what exists afterwards. The reasoning for why a stage cannot be skipped follows below it.

Why each stage is needed

1. List the invoices. GET /commerce/v1/invoices returns pages of invoiceId, salesOrderId, documentReference, state, issuedAt and dueAt. The cursor is evidence of completeness here: a close that skips a page is wrong.
2. Read the invoice. GET /commerce/v1/invoices/{invoiceId} names netAmount, taxAmount and grossAmount per line and, in totals, additionally paidAmount and outstandingAmount. Net, tax and gross arrive separately — accounting has nothing to back out.
3. Read the credit note. GET /commerce/v1/credit-notes/{creditNoteId} references invoiceId and salesOrderId and carries a reasonCode. A correction is thus always tied to an invoice and not just a negative amount in the month.
4. Read the fee statement. GET /commerce/v1/fee-statements/{feeStatementId} returns lines with basis, feeBasisPoints and feeAmount, corrections with adjustmentOfLineId. The applicable rate in feeBasisPoints is defined outside the contract; the lines can be recomputed from basis and feeBasisPoints.
5. Match the refunds. GET /commerce/v1/refunds lists refunds with amount, state, salesOrderId, returnId and reasonCode. Every refund should face a credit note; where it does not, that is a finding for the close.

curl -H 'X-Api-Key: <API_KEY>' \
  'https://commerce-preview.invalid/commerce/v1/invoices?limit=100'

What you end up with

In the end the month consists of documents: revenue from invoices, corrections from credit notes, fees from fee statements and refunds, with their state, from the refund list — each amount separately and linked to its order.

Where to find this in the documentation

The binding field lists, error codes and sample responses live in this surface’s OpenAPI contract at docs.tapinomahub.com (tapinoma-commerce). All use cases arranged by surface and role: overview of the use cases.