Create and manage invoices

Resources at a glance

Field	Purpose
id	Immutable Adfin identifier
invoiceNo	Unique invoice number
description	Short information is shown to the payer
totalAmount / taxAmount / dueAmount	Calculated aggregates for amount and tax
dueDate / issueDate	Key dates for distribution
status	DRAFT, UNPAID, SCHEDULED, SUBMITTED, OVERDUE, PAID, SETTLED, VOID
itemsTaxType	EXCLUSIVE, INCLUSIVE, or NONE defines how the line-item tax is applied
items[]	Line items with description, unitAmount, quantity, taxrate, etc.
paymentRequests[]	On-demand or partial collections linked to this invoice. Only applicable when using On-Demand invoices
externalData[]	Contains data related to accounting systems such as Xero or QuickBooks.

Full API endpoint: https://docs.adfin.com/v2.0/reference/postinvoice#/

Create a draft invoice

Endpoint: POST /invoices

Typical request:

{
  "customer": { "id": "123" },
  "items": [
    { "description": "Pro plan", "unitAmount": 4900, "quantity": 1 }
  ],
  "dueDate": "2025-09-30"
}

Rules of thumb

Customer first – pass either Adfin customer ID
Invoice totals are calculated server-side; you only supply raw line-items.
Duplicate invoice No is treated as idempotent and returns the existing record.

Activate & distribute

Endpoint: PUT /invoices/[id]:activate with an ActivateInvoiceRequest body

Move a DRAFT invoice to UNPAID (and optionally trigger Direct Debit) in one call:

{
  "collectionMethod": "DIRECT_DEBIT_PAYMENT",
  "customMessage": "Thanks for your business!"
}

• ONE_TIME_PAYMENT opens a hosted payment page (card / open banking).
• DIRECT_DEBIT_PAYMENT queues automatic collection on the charge date. • The payer is emailed automatically using your chosen template.

Update, void, or mark as paid

Action	Method & Path
Retrieve	GET /invoices/[id]
Update	PUT /invoices/[id]
Void	PUT /invoices/[id]/:void
Mark as paid (offline or from your system)	PUT /invoices/[id]/:mark-as-paid
Delete	DELETE /invoices/[id] (irreversable)

Best practice

Best-practice workflow

Draft early – create invoices as soon as you know the amount; update until ready.
Activate when final – sends notifications and triggers collection rules.
Leverage Direct Debit – if the customer’s mandate is ACTIVE, Adfin auto-collects.
Subscribe to webhooks to track OVERDUE, PAID, and SETTLED without polling.