Payment plans

Base URL: $BUSINESS_API

The object

idstring · required
tenant_idstring · required
case_idstring · required
account_idstring · required
account_numberstring · optional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · optional

Display name of the customer who holds the referenced account. Omitted when unknown.

total_amount_centsinteger (int64) · required
installment_countinteger · required
installment_amount_centsinteger (int64) · required
remaining_amount_centsinteger (int64) · required
next_due_datestring (date-time) · required
statusstring · required

one of active, completed, defaulted, cancelled

interest_basis_pointsinteger · optional
interest_amount_centsinteger (int64) · optional
installmentsarray of PlanInstallment · optional
Show child attributes
idstring · required
tenant_idstring · required
plan_idstring · required
numberinteger · required
due_datestring (date-time) · required
amount_centsinteger (int64) · required
statusstring · required

one of pending, paid, overdue

paid_atstring · optional · nullable
created_atstring (date-time) · required
created_atstring (date-time) · required
updated_atstring (date-time) · required
The object
{
  "id": "pay_2Y8DroSLB6irBEM756sHb0qz5Mk",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "case_id": "cas_2gmnNK0lRMC9tOMtZsWDhKGHpGe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "total_amount_cents": 125000,
  "installment_count": 1,
  "installment_amount_cents": 125000,
  "remaining_amount_cents": 125000,
  "next_due_date": "2026-11-19T09:30:00Z",
  "status": "active",
  "interest_basis_points": 1,
  "interest_amount_cents": 125000,
  "installments": [
    {
      "id": "pla_2HjiILFe8bV48DfMmhxs4j54up1",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "plan_id": "pla_2lVU4nTwUfHw6nxUwjbOeRn8u5D",
      "number": 1,
      "due_date": "2026-11-19T09:30:00Z",
      "amount_cents": 125000,
      "status": "pending",
      "paid_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

List customer payment installment plans

Logs

GET /payment-plans

Returns one cursor-paginated page (limit, after) of the tenant's debt payment plans. The account_id, case_id and status (active, completed, defaulted or cancelled) query parameters narrow the list. Requires read access to collections.

Parameters

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Payment plans

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

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

Payment plans

Agree on a payment plan

Logs

POST /payment-plans

Turns a collection case's total debt into a payment plan and returns it with 201. Simple interest from interest_basis_points is added and the total is split into equal installments (default 3), with the rounding remainder on the last one. Installments fall due every interval_months (default 1) from first_due_date (default one month from now). Any interest is charged to the account's receivables, a payment plan created event is emitted, and the case moves to payment_plan_active. Requires the collections:write permission. Returns 404 for an unknown case and 400 for negative interest.

Body application/json

case_idstring · required
installment_countinteger · optional · default 3
first_due_datestring (date-time) · optional
interest_basis_pointsinteger · optional
interval_monthsinteger · optional · default 1

Returns

201 Payment plan created

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

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

Payment plan created

Get a payment installment plan with its installments

Logs

GET /payment-plans/{id}

Returns a payment plan with its installments, including each installment's due date, amount and status. Requires read access to collections in the tenant, and returns 404 when the plan does not exist.

Parameters

idstring · path · required

ID of the payment plan (prefixed pln_).

Returns

200 Payment plan details

Show attributes
idstring · required
tenant_idstring · required
case_idstring · required
account_idstring · required
account_numberstring · optional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · optional

Display name of the customer who holds the referenced account. Omitted when unknown.

total_amount_centsinteger (int64) · required
installment_countinteger · required
installment_amount_centsinteger (int64) · required
remaining_amount_centsinteger (int64) · required
next_due_datestring (date-time) · required
statusstring · required

one of active, completed, defaulted, cancelled

interest_basis_pointsinteger · optional
interest_amount_centsinteger (int64) · optional
installmentsarray of PlanInstallment · optional
Show child attributes
idstring · required
tenant_idstring · required
plan_idstring · required
numberinteger · required
due_datestring (date-time) · required
amount_centsinteger (int64) · required
statusstring · required

one of pending, paid, overdue

paid_atstring · optional · nullable
created_atstring (date-time) · required
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 403 · 404

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

curl -X GET "$BUSINESS_API/payment-plans/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "pay_2Y8DroSLB6irBEM756sHb0qz5Mk",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "case_id": "cas_2gmnNK0lRMC9tOMtZsWDhKGHpGe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "total_amount_cents": 125000,
  "installment_count": 1,
  "installment_amount_cents": 125000,
  "remaining_amount_cents": 125000,
  "next_due_date": "2026-11-19T09:30:00Z",
  "status": "active",
  "interest_basis_points": 1,
  "interest_amount_cents": 125000,
  "installments": [
    {
      "id": "pla_2HjiILFe8bV48DfMmhxs4j54up1",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "plan_id": "pla_2lVU4nTwUfHw6nxUwjbOeRn8u5D",
      "number": 1,
      "due_date": "2026-11-19T09:30:00Z",
      "amount_cents": 125000,
      "status": "pending",
      "paid_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Declare a payment plan in default

Logs

POST /payment-plans/{id}/default

Changes an active plan's status to defaulted and returns it, which makes the account eligible for cutoff again. Only an active plan can default; any other status returns 409. Requires the collections:write permission.

Parameters

idstring · path · required

ID of the active payment plan to mark as defaulted.

Returns

200 Payment plan declared in default

Show attributes
idstring · required
tenant_idstring · required
case_idstring · required
account_idstring · required
account_numberstring · optional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · optional

Display name of the customer who holds the referenced account. Omitted when unknown.

total_amount_centsinteger (int64) · required
installment_countinteger · required
installment_amount_centsinteger (int64) · required
remaining_amount_centsinteger (int64) · required
next_due_datestring (date-time) · required
statusstring · required

one of active, completed, defaulted, cancelled

interest_basis_pointsinteger · optional
interest_amount_centsinteger (int64) · optional
installmentsarray of PlanInstallment · optional
Show child attributes
idstring · required
tenant_idstring · required
plan_idstring · required
numberinteger · required
due_datestring (date-time) · required
amount_centsinteger (int64) · required
statusstring · required

one of pending, paid, overdue

paid_atstring · optional · nullable
created_atstring (date-time) · required
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 403 · 404 · 409

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

curl -X POST "$BUSINESS_API/payment-plans/{id}/default" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "pay_2Y8DroSLB6irBEM756sHb0qz5Mk",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "case_id": "cas_2gmnNK0lRMC9tOMtZsWDhKGHpGe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "total_amount_cents": 125000,
  "installment_count": 1,
  "installment_amount_cents": 125000,
  "remaining_amount_cents": 125000,
  "next_due_date": "2026-11-19T09:30:00Z",
  "status": "active",
  "interest_basis_points": 1,
  "interest_amount_cents": 125000,
  "installments": [
    {
      "id": "pla_2HjiILFe8bV48DfMmhxs4j54up1",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "plan_id": "pla_2lVU4nTwUfHw6nxUwjbOeRn8u5D",
      "number": 1,
      "due_date": "2026-11-19T09:30:00Z",
      "amount_cents": 125000,
      "status": "pending",
      "paid_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}