Write-Offs
Overview
There are occasions where an individual or set of invoices may be deemed uncollectible, but still need to become settled so that they dont remain on the system, forever in an incomplete state. Additionally, use cases such as fee discounts at the invoice item level require an even more precise degree of credit handling. Write-Offs allow users to write off entire invoices, specific invoice items or partial amounts.
Key Capabilities
Target either full invoices or individual invoice items.
Specify a custom amount per target, or allow the system to compute the unsettled amount.
Supports partial write-offs of invoice items.
Multiple targets per write-off are supported, processed in the order provided.
Write-offs propagate to DataLake for downstream reporting.
A full reversal capability is supported via a simple
POST
call.
Accounting Behavior
Granular write-offs follow the same accounting rules as traditional full invoice write-offs. Each target is processed independently and credited accordingly.
API Usage
Create a write-off by specifying one or more invoice
or invoiceItem
targets. All targets must belong to the same account and use the same currency.
POST /billing/{tenantLocator}/writeOffs
Name | Position | Type | Required |
---|---|---|---|
tenantLocator | path | uuid | required |
requiredaccountLocator stringtargets WriteOffTarget[]
requiredcontainerLocator stringcontainerType Enum account | invoice | invoiceItem | subpaymentoptionalamount number?
Note
Invoices can also be directly targetted for write off via their locator, however this approach is limited in that it can target only the remaining balance of the invoice, and in its entirety.
PATCH /billing/{tenantLocator}/invoices/{locator}/writeOff
Name | Position | Type | Required |
---|---|---|---|
tenantLocator | path | uuid | required |
locator | path | string | required |
Reversal Support
Write-offs can be fully reversed using the existing reversal endpoint, unsetting all credits made across all invoice
and invoiceItem
targets. Partial reversals are not supported.
PATCH /billing/{tenantLocator}/writeOffs/{locator}/reverse
Name | Position | Type | Required |
---|---|---|---|
tenantLocator | path | uuid | required |
locator | path | string | required |
Limitations
Maximum targets: A request can include up to 100 a fixed maximum number of targets. Requests exceeding this limit will be rejected.
Same account constraint: All targets (
invoice
andinvoiceItems
) must belong to the account specified in the request. Cross-account targeting is not allowed.Same currency: All targets in a request must have the same currency.
No duplicate targets: Each target must be unique. Duplicate
invoice
orinvoiceItem
entries within the same request will result in an error.Disjoint targets:
invoiceItems
cannot be targeted individually if they are already indirectly included via their parent invoice in the same request. Each target must be independent.Valid types only:
Only
invoice
andinvoiceItem
container types are supported.Other types (e.g., account) are not valid targets.
Target must exist: All provided target locators must correspond to existing invoices or invoice items; otherwise, the request will fail.
Amount must be valid: The amount specified per target must be positive and non-zero. The amount must not exceed the target’s remaining unsettled amount.
Settled items cannot be written off: Targets that are already fully settled are not eligible for write-off.
Targets are required: A write-off request must include at least one valid target.