Get Collections Queue

GET

collections

queue

Collections worklist of currently-failing invoices

curl --request GET \
  --url https://billing.example.com/v1/collections/queue \
  --header 'Authorization: Bearer <token>'

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

fetch('https://billing.example.com/v1/collections/queue', 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/queue",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  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/queue"

	req, _ := http.NewRequest("GET", 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/queue")

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

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

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

{
  "data": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "customer_name": "<string>",
      "customer_email": "<string>",
      "invoice_number": "<string>",
      "status": "past_due",
      "currency": "<string>",
      "amount_remaining": 123,
      "due_date": "2023-11-07T05:31:56Z",
      "days_overdue": 123,
      "retry_count": 123,
      "last_payment_error": "<string>",
      "next_retry_at": "2023-11-07T05:31:56Z",
      "managed_by": "scheduler",
      "attempt_status": "<string>",
      "dunning_paused": true
    }
  ],
  "meta": {
    "page": 123,
    "per_page": 123,
    "total": 123
  }
}

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

Returns the tenant’s collections worklist: every invoice in a recovery state (past_due, or uncollectible with a balance still owing), paginated, with the customer, the amount remaining in minor units, days overdue, the retry count, the raw failure code from the last attempt, the next scheduled retry, which recovery engine owns the invoice, and the status of its latest payment attempt. Read-only — it changes nothing. Each row is the starting point for the operator actions on this resource: Retry Now, Pause Dunning and Mark Uncollectible. For the aggregate view of the same population see Get Collections Funnel and Get Collections Failures; for the per-attempt history behind last_payment_error see List Payment Attempts.

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Narrow to one recovery status: `past_due` or `uncollectible`. Any other value is ignored and the full worklist is returned.
`managed_by`	string	No	Narrow to invoices owned by one recovery engine: `scheduler`, `worker` or `campaign`. Any other value is ignored.
`page`	integer	No	Page number, from `1`. Default `1`.
`per_page`	integer	No	Rows per page. Default `50`, capped at `250`.
`limit`	integer	No	Alias for `per_page` (same default and cap).
`offset`	integer	No	Rows to skip. Overrides the offset derived from `page`.

Example Request

curl -G https://api.recurso.dev/v1/collections/queue \
  -H "Authorization: Bearer $API_KEY" \
  -d status=past_due \
  -d per_page=25

Response

{
  "data": [
    {
      "id": "06c151de-8d3a-4b21-9c77-2f0e5a9b4d12",
      "customer_id": "0b7a3f7e-4a2b-4c1d-9e8f-1a2b3c4d5e6f",
      "customer_name": "Northwind Traders",
      "customer_email": "ap@northwind.example",
      "invoice_number": "REC/2026/0042",
      "status": "past_due",
      "currency": "USD",
      "amount_remaining": 118000,
      "due_date": "2026-08-20T00:00:00Z",
      "days_overdue": 15,
      "retry_count": 3,
      "last_payment_error": "insufficient_funds",
      "next_retry_at": "2026-09-05T09:00:00Z",
      "managed_by": "worker",
      "attempt_status": "failed",
      "dunning_paused": false
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}

Fields

Field	Type	Description
`id`	string (uuid)	The invoice’s id — fetch it with Get Invoice
`customer_id`	string (uuid)	The customer the invoice bills
`customer_name` / `customer_email`	string	The customer’s name and email, so the row reads without a second lookup
`invoice_number`	string	The invoice’s human-readable number
`status`	string	`past_due` (still being chased) or `uncollectible` (written off, balance still owing)
`currency`	string	The invoice’s currency
`amount_remaining`	integer (int64)	Total minus amount paid, in minor units
`due_date`	string (date-time)	When the invoice fell due
`days_overdue`	integer	Whole days since `due_date`
`retry_count`	integer	Automated retries attempted so far
`last_payment_error`	string	Raw gateway or ACH failure code from the last attempt; empty when none
`next_retry_at`	string (date-time)	When the next automated retry is scheduled; omitted when nothing is scheduled
`managed_by`	string	The engine that owns recovery for this invoice: `scheduler`, `worker` or `campaign`
`attempt_status`	string	Status of the latest payment attempt (`initiated`, `processing`, `succeeded`, `failed` or `returned`); omitted when the invoice has no attempts
`dunning_paused`	boolean	`true` when an operator has paused automated dunning on the invoice

meta.total is the count of rows matching the filters across all pages.

Errors

Status	Code	When	Fix
`401`	`unauthorized`	Missing or invalid API key	Send a valid key in the `Authorization` header

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.

Query Parameters

limit

integer

default:50

Page size (default 50, capped at 250). Also accepts page/per_page.

Required range: x <= 250

offset

integer

Rows to skip (overrides page-derived offset).

Required range: x >= 0

status

enum<string>

Narrow to a single recovery status.

Available options:

past_due,

uncollectible

managed_by

enum<string>

Narrow to invoices owned by a specific recovery engine.

Available options:

scheduler,

worker,

campaign

page

integer

default:1

Required range: x >= 1

per_page

integer

default:50

Required range: 1 <= x <= 250

Response

The collections worklist.

data

object[]

Show child attributes

meta

object

Show child attributes

Collections worklist of currently-failing invoices

curl --request GET \
  --url https://billing.example.com/v1/collections/queue \
  --header 'Authorization: Bearer <token>'

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

fetch('https://billing.example.com/v1/collections/queue', 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/queue",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  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/queue"

	req, _ := http.NewRequest("GET", 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/queue")

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

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

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

{
  "data": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "customer_name": "<string>",
      "customer_email": "<string>",
      "invoice_number": "<string>",
      "status": "past_due",
      "currency": "<string>",
      "amount_remaining": 123,
      "due_date": "2023-11-07T05:31:56Z",
      "days_overdue": 123,
      "retry_count": 123,
      "last_payment_error": "<string>",
      "next_retry_at": "2023-11-07T05:31:56Z",
      "managed_by": "scheduler",
      "attempt_status": "<string>",
      "dunning_paused": true
    }
  ],
  "meta": {
    "page": 123,
    "per_page": 123,
    "total": 123
  }
}

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

Getting Started

Core

Billing & Invoicing

Revenue & Finance

Growth & Recovery

Compliance (India)

Platform

Customer Portal API

Query Parameters

Example Request

Response

Fields

Errors

Authorizations

Query Parameters

Response

​Query Parameters

​Example Request

​Response

​Fields

​Errors

Authorizations

Query Parameters

Response

Query Parameters

Example Request

Response

Fields

Errors