Create an incidental invoice via API

An incidental invoice is a manual, one-off charge that sits outside the regular billing run (advances, periodic invoices, end notes).
Creating an invoice is a two-step process:

  1. Create — stores the invoice in status created (draft).

  2. Approve — finalises the invoice, assigns an invoice number, and starts downstream payment processing.

Until you approve, the invoice is not billable and has no official invoice number.

Integration flow

Recommended order:

  1. Resolve customerId.

  2. Resolve contractId and contractNumber when the charge belongs to a contract.

  3. Resolve companyBankAccountId.

  4. Resolve taxCodeId (and optionally billingItemId / serviceLocationId) for each line.

  5. Create the invoice — save the returned id.

  6. Approve the invoice — poll until status is approved and invoiceNum is set.

  7. (Optional) Send the invoice to the customer.

Step 1 — Look up the customer

POST api/md/Customers/filter 
Content-Type: application/json  
{   
     "flexSearch": "Janssen",   
     "nameContains": "Janssen" 
}

API endpoint documentation

Step 2 — Look up the contract (optional)

Linking a contract is optional but recommended when the charge relates to an active supply agreement.
When you provide contractId, the platform copies property groups from the billing relation automatically.

POST /api/md/Contracts/filter?quickFilter=all 
Content-Type: application/json  {   
     "customerId": "{customerId}",   
     "excludeTerminatedContracts": true 
}

API endpoint documentation

Step 3 — Look up reference data

Company bank account (companyBankAccountId)

GET /api/cfg/BankAccounts

Use the id of the bank account configured for the organization.

API endpoint documentation


When you bill via a property group (no contract), you can also read companyBankAccountId from:

GET /api/bill/PropertyGroupBillingConfigurations/{propertyGroupId}

API endpoint documentation

Tax code (lines[].taxCodeId)

GET /api/cfg/TaxCodes

Each line must reference a valid taxCodeId.
VAT is calculated from the tax rate that applies to the line's startDateTime and endDateTime, unless you set disableVATCalculation to true.

API endpoint documentation

Billing item (lines[].billingItemId, optional)

GET /api/cfg/BillingItems

Optional. When provided, the platform can derive utility and consumption metadata from the billing item configuration.

API endpoint documentation

Service location (lines[].serviceLocationId, optional)

POST /api/md/ServiceLocations/filter?quickFilter=all 
Content-Type: application/json  
{   
     "customerId": "{customerId}" 
}

Alternatively, use serviceLocationId values from the contract's serviceLocations list.

API endpoint documentation

Step 4 — Create the invoice

POST /api/bill/Invoices 
Content-Type: application/json

Store data.id — you need it for approval and sending.

API endpoint documentation

Step 5 — Approve the invoice

Approval finalises the invoice.
When invoiceNum was empty at creation, the platform assigns an official invoice number as part of this step.

POST /api/bill/Invoices/{invoiceId}/approve 
Content-Type: application/json  
{   
    "invoiceDate": "2026-06-30T00:00:00+02:00" 
}

API endpoint documentation

Approval is asynchronous

The approve call returns immediately, but finalisation (especially invoice number assignment) may take a few seconds. After calling approve:

  1. Poll GET /api/bill/Invoices/{invoiceId}.

  2. Wait until status is approved and invoiceNum is no longer empty.

While processing you may briefly see status as approvalinprogress. Retry with a short interval (for example every 2–3 seconds) until the invoice reaches approved or an error appears in errors.

You can also subscribe to the invoice approved webhook. Check the "Webhooks" page for more information about the setup.