Products & templates

A product is the behavior contract behind every obligation. It supplies defaults and hard constraints for new loans; creating a loan resolves those terms into the contract, and the resolved facts stay with the loan.

Everything a lender governs about an obligation’s behavior is configured on the product: the schedule cadence and term, how interest accrues and payments allocate, which charges may attach and how each is classified under Regulation Z, how APR is disclosed, when statements generate, and how far an overpayment may run before the servicing guard rejects it.

Three product families

Merchant advances are a separate product family. Selecting merchant_advance changes the allowed terms, lifecycle, accounting, reconciliation, and API resource; it does not toggle an installment loan into a commercial contract.

One aggregate, two policy blocks

A consumer product is created atomically at POST /v1/loanproducts and carries two blocks: the native calculation settings—the math that must not drift between schedule preview and servicing—and the LendEasy lmsConfig policy that governs disclosure and statements. The sections below walk each policy surface conceptually; the exact request payload appears in The wire format.

Schedules, interest, and allocation

The native block pins the calculation choices that must not drift between schedule preview and servicing:

• repayment frequency (repaymentEvery plus its frequency type) and term;
• interest rate per period, declining-balance interest type, and the interest-calculation period;
• equal-installment amortization;
• transactionProcessingStrategyCode—the server owns the payment-allocation order for due, overdue, and in-advance money; and
• loanScheduleType: "PROGRESSIVE" with interest recalculation disabled.

Progressive schedules are required for consumer products in the public catalog. They recalculate after dated transactions and schedule modifications while preserving posted history.

Charges carry immutable Reg Z classification

The native block attaches charges by id from the charge-definition catalog at /v1/charges. Charge definitions are themselves two-block aggregates: the native charge settings plus an lmsConfig with a financeChargeFlag (FINANCE_CHARGE, NOT_FINANCE_CHARGE, or EXCLUDED) and a legalBasis citation.

A charge definition without its classification reports configurationStatus: "MISSING" and cannot be attached to products or loans, so an APR-enabled product can never reference an unclassified fee.

APR configuration

lmsConfig carries the Regulation Z posture: productClass: "COVERED_CONSUMER" marks the product as covered consumer credit, aprEnabled requires a finalized disclosure at approval, aprRounding pins the disclosed scale, and aprTolerancePolicy (REGULAR or IRREGULAR) records the accuracy class the product asserts.

See APR & disclosures for Harbor’s worked calculation.

Statement and overpayment policy

statementEnabled schedules due-date statements for every loan on the product, and statementLeadDays sets how many days before each due date the statement job generates them. An optional overpaymentTolerance bounds how far a payment may exceed the outstanding balance before the overpayment guard rejects it.

Autopay and notice timing

For variable preauthorized consumer debits, the statement is the notice artifact, so the lead time must satisfy Regulation E § 1005.10(d): a FULL_DUE autopay enrollment is rejected unless the product’s statement lead leaves at least the ten-day advance-notice window. Per-rail payment failure handling is tenant-level policy, not product configuration—see autopay failure policies.

Merchant-advance settings

Merchant products configure purchase-price and purchased-amount bounds, remittance-rate limits, permitted sales sources, reporting cadence, projection method, reconciliation tolerances, grace windows, near-breach indicators, breach rules, and payment allocation. They do not expose consumer-only APR or installment-interest settings.

Reading and updating products

GET /v1/loanproducts returns the product list with each product’s lmsConfig and a derived configurationStatus—CONFIGURED or MISSING. A product whose LendEasy configuration is MISSING cannot originate loans. GET /v1/loanproducts/template returns the option catalogs, including the product-class, APR-rounding, and APR-tolerance options, and GET /v1/loanproducts/{productId} returns one product.

PUT /v1/loanproducts/{productId} is a full replacement of both blocks—native settings and lmsConfig together. Product changes take effect for the next origination, never for existing loans: the terms a loan resolved at origination are frozen on the loan, not looked up from the product at servicing time. There is no separate draft, validate, or activate lifecycle and no product versioning—a single write defines the behavior of every loan created after it, so treat edits to a live product as a governed operational change.

The wire format

The atomic create submits both blocks in one request. The native block is keyed fineract and uses the engine’s wire encoding, including integer-coded enumerations for the frequency, amortization, interest, and accounting options shown conceptually above; GET /v1/loanproducts/template returns the option catalogs to build these payloads against.

curl -X POST "$BASE/v1/loanproducts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "LendEasy-Tenant: demo-lender" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-harbor-product-01" \
  -d '{
    "fineract": {
      "name": "Harbor 18-month personal loan",
      "shortName": "HBR18",
      "currencyCode": "USD",
      "principal": 8400.0,
      "numberOfRepayments": 18,
      "repaymentEvery": 1,
      "repaymentFrequencyType": 2,
      "interestRatePerPeriod": 13.25,
      "interestRateFrequencyType": 3,
      "amortizationType": 1,
      "interestType": 0,
      "interestCalculationPeriodType": 1,
      "transactionProcessingStrategyCode": "advanced-payment-allocation-strategy",
      "loanScheduleType": "PROGRESSIVE",
      "isInterestRecalculationEnabled": false,
      "accountingRule": 1,
      "charges": [{ "id": 12 }]
    },
    "lmsConfig": {
      "productClass": "COVERED_CONSUMER",
      "aprEnabled": true,
      "aprRounding": "NEAREST_0_01_PERCENT_HALF_UP",
      "aprTolerancePolicy": "REGULAR",
      "statementEnabled": true,
      "statementLeadDays": 10
    }
  }'

{ "resourceId": 3 }