Collections

Base URL: $BUSINESS_API

List eligible cutoffs

Logs

GET /collections/eligible-cutoffs

Accounts past the tenant threshold, excluding active plans and disputes

Lists, most overdue first, the accounts that the tenant's collection policy allows to be disconnected now: overdue past cutoff_past_due_days, owing at least cutoff_min_debt_cents, not on an active payment plan, with no disputed invoice, with an active connection, and not already pending cutoff or disconnected. The list is computed live from billing; page with limit (default 20, max 100) and the after cursor, which stays stable when an account pays between pages. Requires collections:read.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions collections:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/collections/eligible-cutoffs" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Success

Create disconnect field orders for eligible accounts

Logs

POST /collections/orders/generate

Raises a disconnection field order for each currently eligible account, or only for the ids in account_ids. For each one it opens a case if none exists, moves the case to enforcement_requested with dunning set to cutoff pending, creates the order with the optional priority and scheduled_for, and emits a cutoff-order-generated event. It first defaults payment plans that are overdue past the grace period. An existing order on a case is reused, so repeating the call does not create duplicates; requested accounts that are not eligible come back in skipped. Returns 400 when field orders are not connected. Requires collections:write.

Body application/json

account_idsarray of object · optional
scheduled_forstring · optional
prioritystring · optional

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions collections:write · Roles: admin, finance, owner

curl -X POST "$BUSINESS_API/collections/orders/generate" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "account_ids": [],
  "scheduled_for": "scheduled for",
  "priority": "priority"
}'
Response 200

Success

Debt ageing buckets

Logs

GET /collections/ageing

Debt ageing buckets (current, 30, 60, 90, 120+)

Totals the outstanding balance of the tenant's open invoices into ageing buckets (current, 1-30, 31-60, 61-90 and over 90 days past due) with the number of distinct accounts in each, as of now. The figures are computed live from billing, not from collection cases. Returns 400 when billing is not connected to collections. Requires collections:read.

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions collections:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/collections/ageing" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Success

Get the tenant cutoff policy

Logs

GET /collections/policy

Returns the tenant's disconnection policy: how many days past due an account must be (cutoff_past_due_days), the minimum overdue debt (cutoff_min_debt_cents), and how many days an unpaid instalment may be late before its plan defaults (plan_default_grace_days). When the tenant has not saved a policy, the defaults are returned: 30 days, 1 minor unit and 30 days. Requires collections:read.

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions collections:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/collections/policy" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Success

Update the tenant cutoff policy

Logs

PUT /collections/policy

Changes only the policy fields sent and returns the full policy; omitted fields keep their current or default values. Values must not be negative, otherwise 400. The new values apply on the next eligibility check, cutoff generation and plan-default sweep. Requires collections:write.

Body application/json

cutoff_past_due_daysinteger · optional
cutoff_min_debt_centsinteger · optional
plan_default_grace_daysinteger · optional

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions collections:write · Roles: admin, finance, owner

curl -X PUT "$BUSINESS_API/collections/policy" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "cutoff_past_due_days": 125000,
  "cutoff_min_debt_cents": 1,
  "plan_default_grace_days": 1
}'
Response 200

Success

List payment plans

Logs

GET /collections/payment-plans

Returns a cursor-paginated list of the tenant's payment plans with their instalments, filterable by account_id, case_id and status. Page with limit (default 20, max 100) and the after cursor. Requires collections:read.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions collections:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/collections/payment-plans" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Success

Create a payment plan with installments and interest

Logs

POST /collections/payment-plans

Puts a collection case on an instalment plan and moves the case to payment_plan_active, which takes the account out of cutoff eligibility. installment_count defaults to 3, interval_months to 1 and first_due_date to one month from now; simple interest from interest_basis_points is added to the debt, with the rounding remainder on the last instalment. Interest is charged to the account in billing, and a payment-plan-created event is emitted. Returns 404 for an unknown case and 400 for negative interest. Requires collections:write.

Body application/json

case_idstring · optional
installment_countinteger · optional
first_due_datestring · optional
interest_basis_pointsinteger · optional
interval_monthsinteger · optional

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions collections:write · Roles: admin, finance, owner

curl -X POST "$BUSINESS_API/collections/payment-plans" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "case_id": "cas_2gmnNK0lRMC9tOMtZsWDhKGHpGe",
  "installment_count": 1,
  "first_due_date": "2026-11-19",
  "interest_basis_points": 1,
  "interval_months": 1
}'
Response 200

Success

Get a plan with installments

Logs

GET /collections/payment-plans/{id}

Returns one payment plan with its totals, interest, remaining amount, next due date, status and the full instalment schedule. Returns 404 when the plan is not in this tenant. Requires collections:read.

Parameters

idstring · path · required

Id of the payment plan (prefix pln).

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions collections:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/collections/payment-plans/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Success

Declare a plan defaulted

Logs

POST /collections/payment-plans/{id}/default

Marks an active payment plan as defaulted, which makes the account eligible for cutoff again under the collection policy. Only an active plan can default; any other status returns 409. Plans are also defaulted automatically when an instalment is unpaid past the policy's grace period. Requires collections:write.

Parameters

idstring · path · required

Id of the payment plan to default (prefix pln).

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions collections:write · Roles: admin, finance, owner

curl -X POST "$BUSINESS_API/collections/payment-plans/{id}/default" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Success

Write off a case's open debt and close it

Logs

POST /collections/cases/{id}/write-off

Declares the account's debt uncollectible: writes off every open invoice of the case's account in billing, moves the case to written_off (a final status), and settles any active dunning status. A non-empty reason is required and is passed to each invoice write-off. A case that cannot move to written off returns 409. Requires collections:write.

Parameters

idstring · path · required

Id of the collection case to write off (prefix col).

Body application/json

reasonstring · optional

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions collections:write · Roles: admin, finance, owner

curl -X POST "$BUSINESS_API/collections/cases/{id}/write-off" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Leitura confirmada no local."
}'
Response 200

Success