Skip to content
Last updated

Create and manage invoices

Resources at a glance

FieldPurpose
idImmutable Adfin identifier
invoiceNoUnique invoice number
descriptionShort information is shown to the payer
totalAmount / taxAmount / dueAmountCalculated aggregates for amount and tax
dueDate / issueDateKey dates for distribution
statusDRAFT, UNPAID, SCHEDULED, SUBMITTED, OVERDUE, PAID, SETTLED, VOID
itemsTaxTypeEXCLUSIVE, 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.

Lifecycle of an invoice

Invoices can be paid either using Adfin workflows, which instructs a corresponding payment status. This is represented by the invoice.status

These workflows are:

  1. On Demand (Card, Apple Pay, Google Pay, Pay by bank, bank transfer)
  2. Auto Collect (Direct debit)

Depending on the payment method, it will travel through different invoice.status path.

Start and end state:

  • Invoices will always start in DRAFT
  • Invoices will always end in SETTLED or VOID or PAID

On demand

Image description

Auto collect

Lifecycle

Creating your first invoice

Rules of thumb

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

Create a draft invoice

Endpoint: POST /invoices

Typical request:

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

Activate and send

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

ActionMethod & Path
RetrieveGET /invoices/[id]
UpdatePUT /invoices/[id]
VoidPUT /invoices/[id]/:void
Mark as paid (offline or from your system)PUT /invoices/[id]/:mark-as-paid
DeleteDELETE /invoices/[id] (irreversable)

Best practices

Best-practice workflow

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