Payment Plans API — Manage Installment Credit Plans

Payment plans in Credith represent the credit agreement attached to an INSTALLMENT bill. When an installment bill is created, a BillPaymentPlan record is automatically generated along with one MonthlyPayment record per installment period. The plan tracks totalToPay, payedAmount, and status (PENDING, OVERDUE, or PAYED). These endpoints let store operators view upcoming obligations, record payments distributed across monthly installments, and recalculate the remaining payment schedule when a client wishes to accelerate repayment. All four endpoints require authentication via a valid JWT (Authorization: Bearer <token>). The pending-payments endpoint additionally requires the ADMIN or OWNER role.

`GET /api/payment-plan/pending-payments`

Returns all monthly installments that are PENDING or OVERDUE and have a paymentDeadline before the start of the month that is 3 months ahead of today. Results include the associated client’s name, DNI, and phone number, ordered by client name then deadline ascending.

This endpoint powers the collections dashboard. ADMIN-role users only see payments for bills issued by their own store; OWNER-role users see all payments company-wide.

No query parameters required. Example

curl -X GET https://your-domain.com/api/payment-plan/pending-payments \
  -H "Authorization: Bearer <token>"

Response fields

period

object

Describes the time window covered by this response.

Show period fields

period.type

string

Always "upToMonthsAhead" for this endpoint.

period.year

integer

Current calendar year.

period.month

integer

Current calendar month (1–12).

period.endDate

string (date)

Exclusive upper bound used in the SQL filter (payment_deadline < endDate).

period.monthsAhead

integer

Number of months ahead included in the window (currently 3).

pendingPayments

array

List of pending monthly installment records.

Show pendingPayments item fields

monthlyPaymentId

string (UUID)

Primary key of the monthly payment record.

billPaymentPlanId

string (UUID)

Parent payment plan UUID.

paymentDeadline

string (date-time)

Date by which this installment should be paid.

paymentAmount

number

Base installment amount for this month (excluding interest).

interestToPay

number

Any accrued interest added to this installment.

payedAmount

number

Amount already paid toward this specific monthly installment.

amountToPay

number

Remaining balance for this installment: paymentAmount + interestToPay - payedAmount.

totalToPay

number

Total outstanding balance of the parent plan.

planPayedAmount

number

Total amount paid against the parent plan so far.

planStatus

string

Status of the parent plan: "PENDING" or "OVERDUE".

client

object

Basic client information.

Show client fields

client.clientId

string (UUID)

UUID of the client.

client.name

string

Full name of the client.

client.dni

string

National identity document number.

client.phone

string

Client phone number.

`GET /api/payment-plan/:dni`

Returns the most recent active payment plan for a client identified by their national ID (dni). Includes all monthly payment records. ADMIN-role users are automatically scoped to bills from their own store. Path parameter

dni

string

required

The client’s national identity number (DNI). Must be non-empty. Example: "0801-1990-12345".

Response

{
  "paymentPlan": {
    "billPaymentPlanId": "dd556677-5717-4562-b3fc-2c963f66afa6",
    "totalToPay": 1380.00,
    "initialPayment": 380.00,
    "payedAmount": 546.67,
    "startingDate": "2025-02-01T00:00:00.000Z",
    "monthsToPay": 6,
    "paymentDay": 15,
    "interestRate": 0,
    "status": "PENDING",
    "lastPaymentTime": "2025-03-15T14:23:00.000Z",
    "client": {
      "clientId": "f22222e5-9ae8-4597-b95e-9889028f5555",
      "name": "Juan Pérez",
      "dni": "0801-1990-12345"
    },
    "monthlyPayments": [
      {
        "monthlyPaymentId": "aab11122-5717-4562-b3fc-2c963f66afa6",
        "paymentAmount": 166.67,
        "interestToPay": 0,
        "paymentDeadline": "2025-02-15T00:00:00.000Z",
        "payedAmount": 166.67,
        "isPayed": true
      }
    ]
  }
}

Error responses

Status	Cause
`400`	`dni` path parameter is empty
`404`	No active payment plan found for the given DNI

`POST /api/payment-plan/:planId/pay`

Credits a payment amount against a plan, distributing funds across monthly installments starting from a specific month index and working forward in deadline order. A month is marked isPayed = true when payedAmount ≥ paymentAmount + interestToPay. The plan’s payedAmount is re-computed as the sum of all monthly payedAmount values plus the initial payment. The plan is set to PAYED if all installments are covered or if totalToPay ≤ healedPayedAmount. Path parameter

planId

string (UUID)

required

UUID of the BillPaymentPlan to apply the payment to.

Request body

amount

number

required

The monetary amount to credit. Distributed sequentially across open installments from month onward until exhausted.

month

integer

required

Zero-based index of the monthly payment array from which to start applying the payment. A value of 0 starts from the first installment; a value of 1 skips the first and starts from the second.

Example

curl -X POST https://your-domain.com/api/payment-plan/dd556677-5717-4562-b3fc-2c963f66afa6/pay \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500.00,
    "month": 1
  }'

Error responses

Status	Cause
`400`	Plan is already `PAYED`, or `month` exceeds the plan’s `monthsToPay`
`404`	Plan not found

`POST /api/payment-plan/:planId/recalculate`

Destroys all existing monthly payment records for a plan and recreates them with a new installment count. The remaining balance (totalToPay - payedAmount) is evenly distributed across the new months, with any rounding adjustment applied to the final installment. The new schedule starts from the current calendar month.

Recalculation is blocked if the plan has already been fully paid (status = "PAYED") or if any open monthly installment has a non-zero interestToPay still outstanding. Additionally, newMonths cannot be greater than the current monthsToPay — this operation can only shorten, not extend, a payment schedule.

Path parameter

planId

string (UUID)

required

UUID of the BillPaymentPlan to recalculate.

Request body

newMonths

integer

required

The new total number of monthly installments. Must be greater than zero and must not exceed the plan’s current monthsToPay.

Example

curl -X POST https://your-domain.com/api/payment-plan/dd556677-5717-4562-b3fc-2c963f66afa6/recalculate \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "newMonths": 3
  }'

Error responses

Status	Cause
`400`	Plan is `PAYED`, `newMonths ≤ 0`, `newMonths > monthsToPay`, or open installments with pending interest exist
`404`	Plan not found

Payment Plan data model

billPaymentPlanId

string (UUID)

Primary key of the payment plan.

totalToPay

number

The full invoice total that must eventually be paid under this plan.

initialPayment

number

Down-payment made at the time the installment bill was created.

payedAmount

number

Running total of all payments received (initial payment + sum of monthly payedAmount).

startingDate

string (date-time)

The date from which installment deadlines are calculated.

monthsToPay

integer

Current number of installment periods remaining on the plan.

paymentDay

integer

Day of the month (1–31) each installment falls due. Dates are normalized to the last day of the month if the month is shorter.

interestRate

integer

Annual interest rate as a percentage (stored as SMALLINT). Default is 0.

status

string

Current plan status. One of "PENDING", "OVERDUE", or "PAYED".

lastPaymentTime

string (date-time) | null

Timestamp of the last payment event, if any.

monthlyPayments

array

Ordered list of individual monthly installment records for this plan.

Show monthlyPayment fields

monthlyPaymentId

string (UUID)

Primary key.

paymentAmount

number

Scheduled installment amount for this month.

interestToPay

number

Accrued interest added to this installment (default 0).

paymentDeadline

string (date-time)

Due date for this installment.

payedAmount

number

Amount already credited toward this installment.

isPayed

boolean

true once payedAmount ≥ paymentAmount + interestToPay.

Overview

Users & Access

Organization

Catalog

Billing & Payments

Analytics

Payment Plans API — Manage Installment Credit Plans

`GET /api/payment-plan/pending-payments`

`GET /api/payment-plan/:dni`

`POST /api/payment-plan/:planId/pay`

`POST /api/payment-plan/:planId/recalculate`

Payment Plan data model

Build docs developers (and LLMs) love

Overview

Users & Access

Organization

Catalog

Billing & Payments

Analytics

Documentation Index

​GET /api/payment-plan/pending-payments

​GET /api/payment-plan/:dni

​POST /api/payment-plan/:planId/pay

​POST /api/payment-plan/:planId/recalculate

​Payment Plan data model

Build docs developers (and LLMs) love

`GET /api/payment-plan/pending-payments`

`GET /api/payment-plan/:dni`

`POST /api/payment-plan/:planId/pay`

`POST /api/payment-plan/:planId/recalculate`

Payment Plan data model