Skip to main content
Glama

curatedapi

Subscription proration calculator

calc_billing_proration
Read-only

Credit for unused time and charge for the remaining time when a subscription changes plan mid-period, prorated to the second like Stripe, or by hour, day or week.

When a customer changes plan part-way through a billing period, they are credited the unused part of what they paid for the old plan and charged the remaining part of the new one. Both are the full-period amount times the fraction of the period left: (period end − change time) ÷ (period end − period start). By default this is exact to the second, as Stripe and Chargebee prorate; with an hour, day or week granularity the change time first moves to a boundary counted from the period start, like Stripe's custom-interval proration. The credit and the charge are each rounded, and the net is charge minus credit, as on the invoice.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "period_start": "<period_start>",
      "period_end": "<period_end>",
      "change_at": "<change_at>",
      "old_amount": "<old_amount>",
      "new_amount": "<new_amount>"
    },
    "name": "calc_billing_proration"
  }
}

Input Schema

NameRequiredDescriptionDefault
snapNoWith an hour, day or week granularity, which boundary the change time moves to. Options: nearest: the closer boundary; exactly halfway goes to the later one; up: the next boundary: the old plan runs for the whole unit; down: the previous boundary: the new plan applies for the whole unitnearest
optionsNoPrecision and rounding of the results (default: rounding=half_up, decimals=2).
change_atYesWhen the plan changes (Stripe's proration_date). Must be within the period.
new_amountYesWhat the new plan costs for a full period. 0 when cancelling or removing an item. Allowed: >= 0 and <= 1000000000000000. Unit: currency.
old_amountYesWhat the old plan costs for a full period (price × quantity, after discounts). In Stripe's flexible billing mode, use what was actually billed for the period. 0 when adding a new item. Allowed: >= 0 and <= 1000000000000000. Unit: currency.
period_endYesEnd of the current billing period (the next renewal).
granularityNoUnit of time the proration is counted in. Options: exact: to the second (to the microsecond if the times have one), as Stripe and Chargebee do by default; hour: whole hours from the period start; day: whole days from the period start; week: whole weeks from the period startexact
period_startYesStart of the current billing period, ISO 8601 (2026-04-01T00:00:00Z). A time without an offset is read as UTC.

Output Schema

NameRequiredDescriptionDefault
inputsYesThe inputs as understood.
resultYes
formulaNo
receiptNoOnly with ?receipt=true: a signed receipt for this answer, a JSON Web Token signed with Ed25519 (alg EdDSA). Its claims are iss, iat, jti (the request id), endpoint, date and response (this response without the receipt). Check it with the keys at /.well-known/jwks.json or POST /v1/receipts/verify.
warningsYes
exactnessYesFor each decimal output: exact; rounded (correctly, to the precision); rounded_uncertified (the last digit could not be proven); or underflow (below 1e-100, reported as 0).
precisionNoThe precision and rounding that were applied.
calculatorYesThe calculator and version that ran.
referencesNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare this is a read-only, non-destructive, closed-world calculation, so the bar is lower; the description still adds real behavioral detail: the exact proration formula, that each side is rounded separately, and that the net is charge minus credit as on an invoice. It does not contradict any annotation, and the mention of Stripe/Chargebee parity gives an agent a mental model for expected output.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in the first sentence, and the following sentences carry the formula and rounding semantics, all of which earn their place. There is mild redundancy between the first and second sentences, which both restate the credit/charge concept.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an eight-parameter calculation tool with an output schema, the description covers the mechanics, the default behavior, the granularity alternatives, and edge framing (zero amounts for cancelling or adding an item). Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage the baseline is 3, but the description goes further by explaining how granularity and snap interact (change time moves to a boundary counted from the period start) and by framing period_start, period_end and change_at inside the proration fraction. It adds meaning beyond the field-level descriptions rather than merely restating them.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names a specific computation (credit for unused time, charge for remaining time on a mid-period plan change) with a precise verb-like framing, which clearly separates it from siblings like calc_billing_discounts or calc_billing_tiered_price. An agent can identify the resource and the operation without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a clear triggering scenario ('when a customer changes plan part-way through a billing period') and explains the default mode versus the hour/day/week alternative, which is genuine when-to-use context. It stops short of naming an alternative tool or stating exclusions, so it lands at 4 rather than 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources