Add a charge

A charge is a named economic component, not a free-form debit. Adding one applies a configured charge definition—with its calculation method, penalty flag, finance-charge classification, and ledger accounts—to the loan.

Execute

Adding a charge is a governed command on its own route. A human call carries LendEasy-Case naming an open case when case management is enabled; without it the call is rejected before execution.

curl -X POST "$BASE/v1/loans/7204/charges" \
  -H "Authorization: Bearer $TOKEN" \
  -H "LendEasy-Tenant: demo-lender" \
  -H "LendEasy-Case: case_HBR_COL_51" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hbr-late-fee-2027-04-10" \
  -d '{
    "chargeId": 21,
    "amount": 18.0,
    "dueDate": "2027-04-10",
    "dateFormat": "yyyy-MM-dd",
    "locale": "en"
  }'

{
  "officeId": 1,
  "clientId": 412,
  "loanId": 7204,
  "resourceId": 44
}

resourceId is the applied loan charge—loanChargeId in later routes. chargeId names the charge definition; GET /v1/loans/7204/charges/template returns the definitions applicable to this loan, and the definition catalog lives at /v1/charges. Automated fees—such as returned-payment fees assessed by policy—are applied by the system, not through this route.

The definition, not the caller, sets policy

The charge definition controls the calculation type, whether the charge is a penalty, amount bounds, and its ledger accounts. Its lmsConfig carries the immutable finance-charge classification (FINANCE_CHARGE, NOT_FINANCE_CHARGE, or EXCLUDED) and legal basis. A definition whose configuration is MISSING is unusable until an administrator completes it—the add is rejected, not guessed at.

Eligibility evaluation

The command validates the definition against the loan’s product, the amount against the definition’s bounds, the due date against the schedule, and the loan’s state—active, not charged off or terminated—along with any blocking restriction. Each failure returns a named, field-level error before anything posts. LendEasy never silently lowers an $18 request to a $12 cap; the caller must resubmit the permitted amount.

APR and disclosure impact

Every consumer charge definition has an effective finance-charge classification. Adding a finance charge after consummation may affect account disclosures, statements, payoff, and legal reporting even when it does not change the original finalized APR. That consequence follows from the definition’s classification—never from the charge name.

Accounting and schedule

Read GET /v1/loans/7204/charges/44 for the applied charge: assessed, paid, waived, and outstanding amounts, due date, and penalty flag. A charge posts no cash. Later payment allocation, waiver, adjustment, or refund refers to that stable loan-charge id.

Duplicate and governance controls

The Idempotency-Key protects request retries. Business duplicates—two late fees for the same installment—are prevented by charge frequency policy on the definition and surface as validation errors. Every add writes a governance record readable at GET /v1/loans/7204/governance-records, and maker-checker can park the command for a second approver.

Reverse or correct

Use adjust a charge to correct its assessed amount, waive a charge to forgive an unpaid amount, and refund a charge when paid money must be returned. An unapplied charge with no financial dependencies can be removed outright with DELETE /v1/loans/7204/charges/44. Those economic meanings remain distinct in reporting.