A shop platform sends the merchant's orders to FinBaze as sales invoices, and payouts from the payment provider as bank transactions. FinBaze does the VAT, including OSS for sales to consumers elsewhere in the EU.

1. Orders to invoices#

One order is one invoice, keyed by your order id. Sending it again changes nothing, and unchanged in the answer tells you so.

mutation Order($company: CompanyRef!) {
  upsertSalesInvoice(input: {
    company: $company
    externalId: "order-10442"
    metadata: { channel: "web", orderNumber: "10442" }
    salesInvoice: {
      relation: { externalId: "cust-8812" }
      currency: EUR
      date: "2026-03-05"
      reference: "Order 10442"
      finalise: true
      expectedTotalMinor: 4840
      lines: [
        { name: "Linen shirt", quantity: 2, priceMinor: 1900, taxCode: "DE_2025_HIGH" }
        { name: "Shipping", priceMinor: 420, taxCode: "DE_2025_HIGH" }
      ]
    }
  }) { status id externalId }
}

Before the first order, send the customer with upsertRelation (a consumer needs no VAT number). Prices are net minor units; tax is derived from the tax code, never taken from the line. finalise: true numbers and books the invoice; after that only metadata can change.

2. Which tax code#

Choose the tax code from the destination, as your checkout already does:

The company needs the matching tax obligation: nl_vat for the Dutch and EU transfer codes, nl_oss for the EU country codes. Use only codes the company's obligations allow. Mount oss-return to show the quarter's OSS return and let the merchant file it. Filing needs the merchant's consent for nl_oss (Filing consent).

3. Refunds are credit notes#

A finalised invoice cannot be edited. Refund by sending an invoice that credits it, with no lines:

mutation Refund($company: CompanyRef!) {
  upsertSalesInvoice(input: {
    company: $company
    externalId: "refund-10442-1"
    salesInvoice: { relation: { externalId: "cust-8812" }, currency: EUR, date: "2026-03-09", creditOf: { externalId: "order-10442" }, finalise: true }
  }) { status id }
}

4. Payouts#

The payment provider pays out a lump sum per day. Register a payout_feed data source, create the PSP account (upsertFeedBankAccount with type: psp) and push each payout with ingestPayoutTransactions, with the reference the bank statement will show:

mutation Payout($company: CompanyRef!) {
  ingestPayoutTransactions(source: "shop-payouts", company: $company, account: "psp-main", payouts: [
    { externalId: "po_1NbxYZ", payoutDate: "2026-03-05", arrivalDate: "2026-03-07", amountMinor: 48700, currency: EUR,
      feesMinor: 300, reference: "SHOPPAY po_1NbxYZ", destination: { iban: "NL91ABNA0417164300" } }
  ]) { line status error { code } }
}

FinBaze pairs the payout with the credit on the merchant's bank account when it arrives (by amount, arrival day, reference and IBAN) and books both on the suspense ledger, so the books reconcile with the bank. payoutTransferMatches shows the pairs. The mechanics are in Data sources.

5. Events to listen for#

sales_invoice.created, bank_transaction.booked, bank_transaction.needs_review and company.requirements.updated cover most integrations. See the webhook catalogue for the payloads and Events and webhooks for retries and signatures.

Many orders at once#

For a backfill use a bulk job: POST /v2/platform/bulk-jobs?object=sales_invoices with an Idempotency-Key header and an NDJSON body. Every line is applied on its own; read results with platformBulkJob(id). See Sending data.

Try it in the sandbox#

Seed nl_eenmanszaak_services or nl_bv_logistics_oss (the latter has the OSS obligation), push a day of orders, then advance a test clock past the quarter end and open oss-return.

Pitfalls#

• Using a code for a country the company is not registered to sell to under OSS.
• Expecting to edit a finalised invoice. Credit it.
• Sending one invoice per cart line. One order is one invoice.