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.