Mark Invoice Uncollectible

POST

/api/:account_id/invoices/:external_id/mark-uncollectible

POST

/api/:account_id/invoices/:external_id/mark-uncollectible

$ curl -X POST https://app.paymentkit.com/api/account_id/invoices/external_id/mark-uncollectible \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{}'

1 {
2   "id": "inv_8f3b2c9d7a1e4b2f",
3   "customer_id": "cus_4a7d9e2f1b6c4d3e",
4   "status": "uncollectible",
5   "currency": "usd",
6   "subtotal_amount_atom": 150000,
7   "tax_amount_atom": 12000,
8   "total_amount_atom": 162000,
9   "due_amount_atom": 162000,
10   "paid_amount_atom": 0,
11   "remaining_amount_atom": 162000,
12   "issued_at": "2024-04-01T10:00:00Z",
13   "due_date": "2024-04-15T10:00:00Z",
14   "description": "Write-off for unpaid invoice due to customer bankruptcy",
15   "metadata": {
16     "write_off_reason": "bankruptcy",
17     "processed_by": "ar_team_lead"
18   },
19   "created_at": "2024-04-01T09:55:00Z",
20   "updated_at": "2024-04-20T15:30:00Z",
21   "applied_balance_amount_atom": 0,
22   "total_discount_amount_atom": 0,
23   "period_start": "2024-03-01T00:00:00Z",
24   "period_end": "2024-03-31T23:59:59Z",
25   "collection_method": "charge_automatically",
26   "custom_fields": {
27     "irs_compliant": true,
28     "write_off_code": "WO2024-04"
29   },
30   "items": [
31     {
32       "id": "item_9d7a1e4b2f8f3b2c",
33       "invoice_id": "inv_8f3b2c9d7a1e4b2f",
34       "description": "Monthly subscription fee for April 2024",
35       "quantity": 1,
36       "amount": 150000,
37       "currency": "usd",
38       "metadata": {},
39       "created_at": "2024-04-01T10:00:00Z",
40       "updated_at": "2024-04-01T10:00:00Z",
41       "price": {
42         "id": "price_123abc456def789gh",
43         "account_id": "acct_0011223344556677",
44         "product_id": "prod_9988776655443322",
45         "name": "Premium Support Monthly",
46         "unit_amount_atom": 150000,
47         "currency": "usd",
48         "is_active": true,
49         "unit_label": "month",
50         "pricing_type": "recurring",
51         "recurring_interval": "month",
52         "recurring_interval_count": 1,
53         "auto_renew": true,
54         "contract_term_multiple": 1,
55         "trial_days": 0,
56         "usage_type": "licensed",
57         "metered_id": null,
58         "billing_scheme": "per_unit",
59         "tier_amount_info": {
60           "mode": "volume",
61           "amount_atoms": [
62             {
63               "unit_amount_atom": 150000,
64               "units_upto": null,
65               "flat_amount_atom": 0
66             }
67           ]
68         },
69         "prerequisite_price_ids": [],
70         "exclusive_customer_ids": [],
71         "metadata": {
72           "plan_level": "premium"
73         },
74         "created_at": "2023-12-01T08:00:00Z",
75         "updated_at": "2024-03-01T08:00:00Z",
76         "product_name": "Premium Support Plan",
77         "product_description": "Monthly subscription for premium customer support",
78         "custom_fields": {},
79         "quantity_divisor": 1,
80         "quantity_rounding": "ceil"
81       },
82       "product_name": "Premium Support Plan",
83       "proration": false,
84       "period_start": "2024-04-01T00:00:00Z",
85       "period_end": "2024-04-30T23:59:59Z",
86       "subscription_id": "sub_556677889900aabb",
87       "subscription_item_id": "si_1122334455667788",
88       "tier_breakdown": [
89         {
90           "label": "1 - ∞ units",
91           "quantity": 1,
92           "amount_atom": 150000,
93           "units_from": 1,
94           "unit_amount_atom": 150000,
95           "flat_fee": false,
96           "units_to": null
97         }
98       ]
99     }
100   ],
101   "invoice_number": 1024,
102   "billing_reason": "manual",
103   "subscription_id": "sub_556677889900aabb",
104   "payment_method_id": "pm_33445566778899aa",
105   "invoice_pdf_url": "https://app.paymentkit.com/invoices/inv_8f3b2c9d7a1e4b2f.pdf",
106   "receipt_pdf_url": null,
107   "hosted_invoice_url": "https://app.paymentkit.com/invoices/inv_8f3b2c9d7a1e4b2f",
108   "show_payment_link": false
109 }

Mark an invoice as uncollectible (write-off).

Previously the backend supported this transition (used internally by the dunning end-behavior flow) but the route was not exposed for manual write-offs. This endpoint surfaces it for AR cleanup, IRS-compliant bad-debt write-offs, and customer-specific concessions.

Allowed source states: OPEN, PAST_DUE. Other states return 422.

Requirements:

Invoice must be in OPEN or PAST_DUE state.
DRAFT / PARTIALLY_PAID / PAID / VOID / UNCOLLECTIBLE invoices are rejected.

Returns:

The invoice with UNCOLLECTIBLE status.

Mark an invoice as uncollectible (write-off). Previously the backend supported this transition (used internally by the dunning end-behavior flow) but the route was not exposed for manual write-offs. This endpoint surfaces it for AR cleanup, IRS-compliant bad-debt write-offs, and customer-specific concessions. Allowed source states: OPEN, PAST_DUE. Other states return 422. Requirements: - Invoice must be in OPEN or PAST_DUE state. - DRAFT / PARTIALLY_PAID / PAID / VOID / UNCOLLECTIBLE invoices are rejected. Returns: - The invoice with UNCOLLECTIBLE status.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

external_idstringRequired

account_idstringRequired

Response

Successful Response

idstring

customer_idstring

statusenum

currencyenum

ISO 4217 currency codes.

subtotal_amount_atominteger or null

tax_amount_atominteger or null

total_amount_atominteger or null

due_amount_atominteger or null

paid_amount_atominteger or null

remaining_amount_atominteger or null

issued_atdatetime

due_datedatetime or null

descriptionstring or null

metadatamap from strings to any or null

created_atdatetime

updated_atdatetime

applied_balance_amount_atominteger or nullOptional

total_discount_amount_atominteger or nullOptional

period_startdatetime or nullOptional

period_enddatetime or nullOptional

collection_methodenumOptional

custom_fieldsmap from strings to any or nullOptional

Custom field values. Only included when expand=custom_fields is specified.

itemslist of objectsOptional

invoice_numberinteger or nullOptional

billing_reasonenum or nullOptional

subscription_idstring or nullOptional

payment_method_idstring or nullOptional

invoice_pdf_urlstring or nullOptional

receipt_pdf_urlstring or nullOptional

hosted_invoice_urlstring or nullOptional

show_payment_linkbooleanOptionalDefaults to false

Errors

422

Unprocessable Entity Error