Amortization Schedule

finance.amortization_schedule

ProductionBounded custom (Class B)Deterministicstrictfastv1.0.0

No network

Overview

You send a principal, a nominal annual rate, a term in periods and a payment frequency; we return one row per period with the payment split into interest and principal, and a closing balance that reaches exactly zero. Rounding the level payment to your currency's minor units always leaves a residue, so the final period absorbs it and we publish the difference rather than hiding it. No fees, no prepayments, no day-count conventions — a schedule you can book, not a mortgage product.

Every rounded schedule leaves a residue, and where it goes decides whether your table matches the lender's. We put it in the final payment, say how big it was, and close the balance at exactly zero, so the schedule can be booked instead of argued over.

Reliability

The rate per period is your annual rate divided by the payments per year, kept to 20 decimals and published, because a nominal rate divided and an effective rate compounded differ by real money over a long term. Interest is rounded each period, the payment once, and the final period absorbs the residue so the balance lands on zero. AMORT_PRINCIPAL_INVALID — trigger: a principal we cannot read, one at or below zero, or one with more decimals than the schedule rounds to; retryable: no, the same payload always fails; next: send a plain decimal above zero at your currency's minor units. AMORT_RATE_INVALID — trigger: an annual rate we cannot read, one outside 0 to 1 as a decimal, or a rate so high that the payment would not even cover the first period's interest; retryable: no; next: send the rate as a decimal such as 0.045 and check it against the term. AMORT_TERM_INVALID — trigger: a term over which each payment would round to nothing, or one long enough that the rounded payment clears the balance before the last period; retryable: no; next: use fewer periods, or ask for a rounding scale with more decimals. AMORT_FREQUENCY_UNSUPPORTED — trigger: a frequency other than MONTHLY, QUARTERLY, SEMI_ANNUAL, ANNUAL or WEEKLY; retryable: no; next: pick one of those five, or convert your term into periods yourself and use ANNUAL. AMORT_SCHEDULE_LIMIT_EXCEEDED — trigger: more than 1,200 periods in one call; retryable: no; next: use a coarser frequency, or split the term and chain two schedules. CURRENCY_UNKNOWN — trigger: a currency code we do not support; retryable: no; next: send one of the supported ISO 4217 codes.

Context footprint

One row per period, so a 360-payment mortgage is a long answer — ask for fewer periods when you only need the summary. A successful call costs 1 execution credit.

When to use it

When you know the principal, the nominal annual rate, the number of payments and the currency, and you need a table that closes.

When the rate moves, fees ride along, or the product allows prepayments — those change the schedule in ways no single table can express.

Scope

Note

Level-payment amortization in exact decimals, closing at zero with the residue published.

Non-goals

Does not handle adjustable rates, fees, insurance or balloon payments
Does not model prepayments, grace periods or interest-only periods
Does not apply a day-count convention such as 30/360 or actual/365
Does not spread the rounding residue across periods or leave a balance standing

Properties

IdempotentRetry safeStreaming supportedFile input supportedRequires external service

Capabilities

math

Cost & billing

Flat rate per invocation

MetercallsBillable onsuccessCost per call1 credit

File handling

Accepts file_refProduces file_refMax input64 KB

How we handle your data

Sensitive input, safe output

What this means

This skill may receive sensitive content, but it does not target sensitive data and returns only a structured non-sensitive result.

Squillify guarantees

Runs inside Squillify
This skill runs inside Squillify.
Payloads are not sent to an external service by this skill.
Squillify does not permanently store submitted payloads.
Telemetry records metadata only, not submitted content.
Submitted payloads are not used for training.
Submitted payloads are not reviewed by humans.
This skill does not target sensitive data.
The response does not contain submitted content.

Your responsibility

Squillify does not determine whether submitted content is sensitive. Your application is responsible for deciding what data it is allowed to submit. Your application is responsible for securing the response.

Read the Microskill Data Handling Policy

Input schema

Field	Type	Required	Description
principal	object	Yes	Amount borrowed as a plain decimal string or JSON number greater than zero and under 1E18.
annualRate	object	Yes	Nominal annual rate as a decimal from 0 through 1, so 0.045 means four and a half percent a year.
termPeriods	integer	Yes	How many payments the loan runs for, from 1 through 1,200 periods.
frequency	string	Yes	How often payments fall, which sets the periods per year the annual rate is divided by.
currency	string	Yes	ISO 4217 code whose minor units fix the default rounding for every schedule figure.
rounding	object	No	Optional mode and scale for schedule figures; omit it and the currency's minor units decide.
firstPaymentPeriod	integer	No	Number to start counting periods from; omit it for 1. Shifts numbering only.

Output schema

Field	Type	Required	Description
schedule	array	Yes	One row per period in order, each with payment, interest, principal, and closingBalance at the rounding scale.
totals	object	Yes	Closed loan-cost totals with totalPaid, totalInterest, and totalPrincipal as decimal strings at the rounding scale.
periodicRate	string	Yes	Annual rate divided by periods per year, published without trailing zeros as the exact value the schedule used.
periodsPerYear	integer	Yes	Payments per year implied by frequency, from 1 for ANNUAL through 52 for WEEKLY.
levelPayment	string	Yes	Constant payment every period except the last, rounded once to the rounding scale.
finalPaymentAdjustment	string	Yes	Last payment minus the level payment: the rounding residue the final period absorbed.
currency	string	Yes	ISO 4217 unit every figure in the schedule is expressed in.
rounding	object	Yes	Mode and scale the schedule was actually built at after currency defaults filled any omitted fields.

API contract

POST /v1/execute

curl

curl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"finance.amortization_schedule","input":{"principal":"1000.00","annualRate":"0.12","termPeriods":3,"frequency":"MONTHLY","currency":"EUR"}}'

Integrations

TypeScript SDK

import { Squillify } from "@squillify/sdk";

const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });

const { output } = await sq.execute("finance.amortization_schedule", {"frequency":"MONTHLY","principal":"1000.00","annualRate":"0.12","termPeriods":3,"currency":"EUR"});

Errors

Code	HTTP	Retryable	Description
VALIDATION_ERROR	400	No	The request payload failed schema validation.
UNAUTHORIZED	401	No	Missing or invalid API key.
SKILL_NOT_ACCESSIBLE	403	No	The API key is not granted access to this skill.
SKILL_NOT_AVAILABLE_FOR_PLAN	403	No	This skill is not included in your current plan.
PLAN_ELIGIBILITY_UNAVAILABLE	503	Yes	Plan eligibility could not be decided. Retry after backoff.
SKILL_NOT_FOUND	404	No	The requested skill or version does not exist.
TENANT_RATE_LIMITED	429	Yes	Request rate limit exceeded. Retry after backoff.
QUOTA_EXCEEDED	429	Yes	Plan quota exhausted. Retryable once the quota period resets.
EXECUTION_TIMEOUT	504	Yes	Execution exceeded the allowed time budget.
AMORT_PRINCIPAL_INVALID	400	No	The request payload failed this skill's input validation.
AMORT_RATE_INVALID	400	No	The request payload failed this skill's input validation.
AMORT_TERM_INVALID	400	No	The request payload failed this skill's input validation.
AMORT_FREQUENCY_UNSUPPORTED	400	No	The skill does not support the requested variant.
AMORT_SCHEDULE_LIMIT_EXCEEDED	429	No	A size, quota, rate, or time limit was exceeded.
CURRENCY_UNKNOWN	400	No	The request payload failed this skill's input validation.

Other limits

Limit	Value
Recommended inline bytes	32 KiB

Limitations

Does not handle adjustable rates, fees, insurance or balloon payments
Does not model prepayments, grace periods or interest-only periods
Does not apply a day-count convention such as 30/360 or actual/365
Does not spread the rounding residue across periods or leave a balance standing
Variable-rate or fee-bearing products
Schedules that must follow a market day-count convention
Modelling early repayment or restructuring

How to call

POST /v1/execute (requires authentication)

Request bodyjson

{
  "skillKey": "finance.amortization_schedule",
  "input": {
    "frequency": "MONTHLY",
    "principal": "1000.00",
    "annualRate": "0.12",
    "termPeriods": 3,
    "currency": "EUR"
  }
}

Examples

Three monthly payments at twelve percent a year

Inputjson

{
  "frequency": "MONTHLY",
  "principal": "1000.00",
  "annualRate": "0.12",
  "termPeriods": 3,
  "currency": "EUR"
}

Expected outputjson

{
  "periodsPerYear": 12,
  "periodicRate": "0.01",
  "finalPaymentAdjustment": "0.01",
  "totals": {
    "totalPaid": "1020.07",
    "totalInterest": "20.07",
    "totalPrincipal": "1000.00"
  },
  "currency": "EUR",
  "levelPayment": "340.02",
  "rounding": {
    "scale": 2,
    "mode": "HALF_UP"
  },
  "schedule": [
    {
      "period": 1,
      "payment": "340.02",
      "interest": "10.00",
      "principal": "330.02",
      "closingBalance": "669.98"
    },
    {
      "period": 2,
      "payment": "340.02",
      "interest": "6.70",
      "principal": "333.32",
      "closingBalance": "336.66"
    },
    {
      "period": 3,
      "payment": "340.03",
      "interest": "3.37",
      "principal": "336.66",
      "closingBalance": "0.00"
    }
  ]
}

Interest-free yen loan in three annual payments