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_due is 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.

POST /vendor-bills/{id}/write-off

Write off a vendor bill balance

cURL

curl --request POST \
  --url https://api.arcuserp.com/v1/vendor-bills/{id}/write-off \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "Vendor bankruptcy -- confirmed 2026-05-13",
  "notes": "Docket 24-11842, Western District of Louisiana"
}
'

200

{
  "data": {
    "success": true,
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "bill_number": "<string>",
    "amount_written_off": 123,
    "new_status": "written_off",
    "journal_entry_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

Authorizations

Authorization · string · header · required

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

Idempotency-Key · string

Optional idempotency key (UUID). Re-POST with same key returns cached 200 without re-processing.

Path Parameters

id · string<uuid> · required

Body

application/json

reason · string · required

Human-readable reason for the write-off (e.g., "Vendor bankruptcy", "Negotiated settlement").

notes · string

Optional additional context.

idempotency_key · string<uuid>

Optional idempotency key. Identical to Idempotency-Key header; body value takes precedence.

Response

200

application/json

Bill written off

data · object

Show child attributes