> ## Documentation Index > Fetch the complete documentation index at: https://docs.recurso.dev/llms.txt > Use this file to discover all available pages before exploring further. # Get Collections Queue > The operator's worklist of currently-failing invoices — past due or written off with a balance owing — each with its amount remaining, days overdue, retry state, last failure code and owning recovery engine. 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](/api-reference/collections/retry-now), [Pause Dunning](/api-reference/collections/pause) and [Mark Uncollectible](/api-reference/collections/mark-uncollectible). For the aggregate view of the same population see [Get Collections Funnel](/api-reference/analytics/collections-funnel) and [Get Collections Failures](/api-reference/analytics/collections-failures); for the per-attempt history behind `last_payment_error` see [List Payment Attempts](/api-reference/payment-attempts/list). ## 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 ```bash theme={null} curl -G https://api.recurso.dev/v1/collections/queue \ -H "Authorization: Bearer $API_KEY" \ -d status=past_due \ -d per_page=25 ``` ## Response ```json theme={null} { "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](/api-reference/invoices/get) | | `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](/api-reference/errors). ## OpenAPI ````yaml GET /v1/collections/queue openapi: 3.1.0 info: title: Recurso API version: 1.0.0 description: | The Recurso billing engine REST API. Authenticate by passing your API key as a bearer token: Authorization: Bearer Obtain an API key by registering a tenant via `POST /auth/register`. All authenticated endpoints live under the `/v1` prefix. Mutating endpoints support idempotency via the `Idempotency-Key` header. license: name: MIT identifier: MIT servers: - url: https://billing.example.com description: >- Example deployment — substitute the base URL of your own Recurso deployment. security: - bearerAuth: [] tags: - name: System description: Health, version, and API metadata - name: Auth description: Tenant registration - name: Plans description: Product catalog plans - name: Customers description: Customer management - name: Subscriptions description: Subscription lifecycle - name: Invoices description: Invoices, PDFs, and Indian GST e-invoicing - name: Coupons description: Discounts - name: Usage description: Metered usage events - name: Credit Notes description: Customer credits - name: Quotes description: Quote-to-invoice lifecycle - name: Webhooks description: Webhook endpoint management and event feed - name: Analytics description: Revenue analytics - name: Checkout description: Public hosted checkout for invoices - name: Payments description: Payment order creation - name: Inbound Webhooks description: Receivers for payment-gateway callbacks (Razorpay, Stripe) - name: Customer Portal description: Customer-facing portal — magic-link auth and session-scoped data - name: Developer description: API key management - name: Account description: Tenant account settings - name: Finance description: Ledger accounts, entries, reconciliation, and revenue recognition - name: Settings description: Tax (GST) and e-invoicing (IRP) configuration - name: Consents description: Consent records for RBI-compliant recurring billing - name: Referrals description: Customer referral program - name: Gifts description: Gift subscriptions - name: Mandates description: UPI Autopay mandates - name: Offline Payments description: Virtual accounts and manually recorded payments - name: Organizations description: Multi-entity organizations grouping several tenants - name: Accounting description: QuickBooks / Xero accounting integrations - name: Churn description: Churn risk scoring and alerts - name: Cancel Flows description: Configurable retention flows shown at cancellation time - name: Dunning description: Dunning analytics and multi-channel dunning campaigns paths: /v1/collections/queue: get: tags: - Collections summary: Collections worklist of currently-failing invoices description: > Operator-facing list of invoices in a recovery state (past_due or uncollectible with a balance owing), each with its customer, amount remaining, days overdue, retry count, last failure code, next scheduled retry, which engine owns it, and the latest ACH attempt status. Read-only. operationId: getCollectionsQueue parameters: - name: limit in: query schema: type: integer default: 50 maximum: 250 description: Page size (default 50, capped at 250). Also accepts page/per_page. - name: offset in: query schema: type: integer minimum: 0 description: Rows to skip (overrides page-derived offset). - name: status in: query description: Narrow to a single recovery status. schema: type: string enum: - past_due - uncollectible - name: managed_by in: query description: Narrow to invoices owned by a specific recovery engine. schema: type: string enum: - scheduler - worker - campaign - name: page in: query schema: type: integer minimum: 1 default: 1 - name: per_page in: query schema: type: integer minimum: 1 maximum: 250 default: 50 responses: '200': description: The collections worklist. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/CollectionsQueueItem' meta: type: object properties: page: type: integer per_page: type: integer total: type: integer '401': $ref: '#/components/responses/Unauthorized' components: schemas: CollectionsQueueItem: type: object description: One currently-failing invoice on the collections worklist. properties: id: type: string format: uuid customer_id: type: string format: uuid customer_name: type: string customer_email: type: string invoice_number: type: string status: type: string enum: - past_due - uncollectible currency: type: string amount_remaining: type: integer format: int64 description: Total minus amount paid, in minor units. due_date: type: string format: date-time days_overdue: type: integer retry_count: type: integer last_payment_error: type: string description: Raw gateway/ACH failure code from the last attempt, if any. next_retry_at: type: string format: date-time nullable: true managed_by: type: string enum: - scheduler - worker - campaign attempt_status: type: string description: Status of the latest payment attempt (ACH), if one exists. dunning_paused: type: boolean description: True when an operator has paused automated dunning on the invoice. Error: type: object required: - error properties: error: type: object description: Structured error detail. required: - code - message properties: code: type: string description: Stable machine-readable error code. examples: - validation_failed - unauthorized - forbidden - not_found - conflict - rate_limited - internal_error - invalid_api_key - key_mode_mismatch - over_refund - invoice_not_paid - invoice_already_paid message: type: string description: Human-readable explanation. responses: Unauthorized: description: Missing or invalid credentials (API key or session cookie). content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Tenant API key obtained from `POST /auth/register` or `POST /v1/developer/keys`. ````