Mark Invoice Uncollectible

POST

collections

invoices

{id}

mark-uncollectible

Manually write off an invoice as uncollectible

curl --request POST \
  --url https://billing.example.com/v1/collections/invoices/{id}/mark-uncollectible \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://billing.example.com/v1/collections/invoices/{id}/mark-uncollectible"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://billing.example.com/v1/collections/invoices/{id}/mark-uncollectible', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.example.com/v1/collections/invoices/{id}/mark-uncollectible",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/collections/invoices/{id}/mark-uncollectible"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://billing.example.com/v1/collections/invoices/{id}/mark-uncollectible")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": {
    "status": "uncollectible"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

Writes off an invoice by hand. The invoice’s status becomes uncollectible, any scheduled retry is cleared, and the write-off reversal is posted to the ledger so AR no longer overstates what is owed. It is the manual counterpart of the write-off the dunning engine performs automatically. The reversal credits Accounts Receivable for the full invoice total, split by what has already happened to the revenue:

Still-deferred portion (a subscription invoice’s pre-tax amount not yet recognized): debit Deferred Revenue, credit AR. Under the cash model this is the whole pre-tax amount.
Already-recognized portion (accrual-model revenue recognized before payment, or all of a one-off invoice’s pre-tax amount): recognized revenue cannot be un-deferred, so it is expensed — debit Bad Debt Expense, credit AR.
Tax: debit Tax Payable, credit AR, since tax on money that will never be collected is not owed.

A partially-recognized invoice therefore shows all three legs in Invoice Journal Entries. Only an open or past_due invoice can be written off — the call cannot resurrect a paid, voided or already-uncollectible invoice, so it is safe to repeat: a second call returns 404. The invoice stays on the collections queue with status: uncollectible while a balance is still owing, and counts toward the uncollectible bucket of the collections funnel. To see the posted legs, use Invoice Journal Entries.

Path Parameters

Parameter	Type	Required	Description
`id`	string (uuid)	Yes	The invoice’s id.

No request body.

Example Request

curl -X POST "https://api.recurso.dev/v1/collections/invoices/06c151de-8d3a-4b21-9c77-2f0e5a9b4d12/mark-uncollectible" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": {
    "status": "uncollectible"
  }
}

Fields

Field	Type	Description
`status`	string	Always `uncollectible` — the invoice’s new status

Errors

Status	Code	When	Fix
`400`	`validation_failed`	`id` in the path is not a UUID	Use the invoice’s UUID
`404`	`not_found`	Invoice doesn’t exist, belongs to another tenant (existence is never confirmed across tenants), or is not `open` or `past_due` (already paid, voided or written off)	Check the ID and status from the collections queue

The status change is committed before the ledger reversal is posted. If the posting fails the invoice stays uncollectible, the failure is logged, and the un-reversed write-off remains visible in the tie-out’s unscheduled bucket until it is reconciled — the write-off is never silently lost.

Errors use the standard envelope — see Errors.

Authorizations

Authorization

string

header

required

Tenant API key obtained from POST /auth/register or POST /v1/developer/keys.

Path Parameters

string<uuid>

required

Response

Invoice marked uncollectible.

data

object

Show child attributes

Manually write off an invoice as uncollectible

curl --request POST \
  --url https://billing.example.com/v1/collections/invoices/{id}/mark-uncollectible \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://billing.example.com/v1/collections/invoices/{id}/mark-uncollectible"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://billing.example.com/v1/collections/invoices/{id}/mark-uncollectible', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.example.com/v1/collections/invoices/{id}/mark-uncollectible",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/collections/invoices/{id}/mark-uncollectible"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://billing.example.com/v1/collections/invoices/{id}/mark-uncollectible")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": {
    "status": "uncollectible"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

Getting Started

Core

Billing & Invoicing

Revenue & Finance

Growth & Recovery

Compliance (India)

Platform

Customer Portal API

Mark Invoice Uncollectible

Path Parameters

Example Request

Response

Fields

Errors

Authorizations

Path Parameters

Response

​Path Parameters

​Example Request

​Response

​Fields

​Errors

Authorizations

Path Parameters

Response

Path Parameters

Example Request

Response

Fields

Errors