Write off a vendor bill balance
Authorization: requires purchasing:write API-key scope AND the per-user
accounting.approve_bill permission (SoD parity sweep 2026-05-16; income
recognition is controller-tier authority). System-actor calls denied.
Writes off the outstanding balance of a vendor bill as income recognition.
GAAP basis (FASB ASC 405-20): writing off AP is a gain from extinguishment of liability — NOT an expense. The journal entry posted is:
DR Accounts Payable (ap_account) <balance_due>
CR Vendor Write-Off Income (4998) <balance_due>
Distinction from DELETE /vendor-bills/{id} (void):
- Void reverses the original AP entry entirely and requires
amount_paid = 0. - Write-off posts a new income-recognition JE and allows partial payments to remain.
Only the remaining
balance_dueis written off.
The bill’s status transitions to written_off (terminal state). The original bill
journal entry remains intact on the books.
Idempotency: re-POST with the same (source_type=WRITE_OFF, source_id=bill_id) pair
returns the cached result without re-posting the JE.
Period lock: write-off of a bill in a locked tax year returns HTTP 422 closed_period.
Requires purchasing:write scope.
Authorizations
API key issued per entity via Settings > Developers > API Keys.
Each key carries scopes (e.g. orders:read, products:write).
Bearer token format: Authorization: Bearer ark_live_ent_Test keys use ark_test_ent_. Both are issued per entity
via Settings > Developers > API Keys.
Headers
Optional idempotency key (UUID). Re-POST with same key returns cached 200 without re-processing.
Path Parameters
Body
Response
Bill written off

