Amortizing Reserved Instance Upfront Fees Monthly

The specific bottleneck this page solves is the lump-sum distortion: an All-Upfront or Partial-Upfront Reserved Instance charges its entire upfront fee on a single invoice line the day it is purchased, but that fee actually pays for compute delivered across the full 1-year (8,760-hour) or 3-year (26,280-hour) commitment term. Book the raw upfront line as-is and your unit-economics dashboard shows a massive cost spike in the purchase month and an artificially cheap reservation for every month after — the exact opposite of the flat, comparable-to-on-demand cost a monthly report needs. AWS’s Cost and Usage Report (CUR) already ships a field built to fix this, reservation_amortized_upfront_fee_for_billing_period, which pre-spreads the fee across billing periods at the line-item hour grain. The engineering problem is not computing an amortization schedule from scratch — it is consuming that field correctly, because naive pipelines either ignore it and sum the lump sum, sum it alongside the raw fee and double-count, or aggregate it at the payer-account level and mis-allocate cost away from the linked accounts that actually shared the reservation. This page covers the amortization step inside Reserved Instance Mapping Logic — the piece that turns a lumpy purchase-date charge into a flat, per-account monthly cost.

# Root Cause & Failure Modes

Three naive approaches to “amortizing” an upfront RI fee each fail in a distinct, quantifiable way:

• Summing line_item_unblended_cost for the RI purchase row. This is the actual invoice line AWS bills you on, and it is correct for the invoice — but wrong for unit cost. An All-Upfront 3-year RI with an 18,000 USD fee posts the full 18,000 USD in month one and 0 USD for the remaining 35 months. Any per-transaction or per-workload unit-cost report built on this number is unusable for 3 years.
• Dividing the upfront fee by term months. 18000 / 36 = $500.00/month looks reasonable, but it ignores that AWS amortizes on an hourly basis (8,760 hours/year, 26,280 hours over 3 years, no leap-year adjustment) and prorates the first and last billing periods by the actual hours the commitment was active within that period. A reservation purchased on the 17th of the month has a partial first period; the flat-division approach silently drifts from what AWS itself reports, and the drift compounds if you also need to reconcile against the vendor’s own amortized-cost API.
• Summing reservation_amortized_upfront_fee_for_billing_period incorrectly. This is the field that already does the hourly spread correctly — but two mistakes turn it into a bug. First, adding reservation_recurring_fee_for_usage (the separate hourly commitment component of a Partial-Upfront RI) into the same total double-counts a component that was never part of the upfront fee. Second, summing at bill_payer_account_id instead of line_item_usage_account_id collapses every linked account’s share of a shared, regional reservation into the payer account, so cost allocation reports understate every consuming team’s spend and overstate the payer’s.

The numbers that bound a correct design: a 1-year term is exactly 8,760 hours (365 × 24) and a 3-year term is 26,280 hours, both computed without leap-year adjustment because that is the convention AWS itself uses. The effective hourly rate — the number you actually compare against on-demand pricing for a savings calculation — is upfront_fee / term_hours plus any recurring hourly fee for Partial-Upfront. For the 18,000 USD All-Upfront example above, that is 18000 / 26280 ≈ $0.6850/hr. For a Partial-Upfront RI with a 9,000 USD upfront fee and a 0.30 USD/hr recurring charge over the same 3-year term, the effective rate is (9000 / 26280) + 0.30 ≈ $0.6425/hr — a number a workload owner can actually put next to an on-demand rate to justify the commitment.

# Production Pipeline Architecture

This amortization step runs as a four-phase batch job, typically triggered once per billing-period close:

1. CUR ingestion & filter. Read the raw Parquet/CSV export and keep only RIFee and SavingsPlanRecurringFee line-item types — the only rows where reservation_amortized_upfront_fee_for_billing_period is populated. The ingestion mechanics here are the same ones covered in Parsing AWS CUR Parquet Files with Python & pandas.
2. Decimal-safe field extraction. Parse the amortized field as Decimal, never float, and explicitly avoid touching line_item_unblended_cost or reservation_recurring_fee_for_usage in this sum — those are separate cost components handled elsewhere in the pipeline.
3. Grouping on the natural key. Aggregate by (reservation_id, linked_account_id, billing_period). This is the key that determines correctness: group on the payer account instead of the linked account and you reproduce the mis-allocation failure mode above.
4. Idempotent upsert. Write monthly totals keyed on that same composite key so a re-run after a CUR backfill overwrites in place instead of appending. The resulting monthly-per-account series is what feeds the coverage math in Reserved Instance Coverage vs Utilization Metrics and the equivalent Savings Plan spread documented in Calculating Savings Plan Coverage and Utilization.

# Step-by-Step Python Implementation

The module below reads CUR-style records, isolates the RIFee/SavingsPlanRecurringFee rows, sums reservation_amortized_upfront_fee_for_billing_period as Decimal on the correct composite key, and upserts idempotently. It also exposes an effective_hourly_rate helper for the savings-comparison numbers quoted above.

import logging
from dataclasses import dataclass, field
from decimal import Decimal, ROUND_HALF_UP
from typing import Dict, List

import pandas as pd

logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s")
logger = logging.getLogger("ri_upfront_amortizer")

HOURS_PER_YEAR = Decimal("8760")  # AWS's flat convention; no leap-year adjustment

REQUIRED_COLUMNS = {
    "line_item_usage_account_id",
    "reservation_reservation_a_r_n",
    "reservation_amortized_upfront_fee_for_billing_period",
    "bill_billing_period_start_date",
    "line_item_line_item_type",
}


@dataclass(frozen=True)
class ReservationTerm:
    reservation_id: str
    purchase_option: str  # "All Upfront" | "Partial Upfront"
    term_years: int  # 1 or 3
    upfront_fee: Decimal
    recurring_hourly_fee: Decimal = Decimal("0")

    def term_hours(self) -> Decimal:
        return HOURS_PER_YEAR * self.term_years

    def effective_hourly_rate(self) -> Decimal:
        """Blended $/hr comparable to on-demand pricing."""
        amortized_hourly = self.upfront_fee / self.term_hours()
        return (amortized_hourly + self.recurring_hourly_fee).quantize(
            Decimal("0.000001"), rounding=ROUND_HALF_UP)


@dataclass
class MonthlyAmortizedCost:
    reservation_id: str
    linked_account_id: str
    billing_period: str  # "YYYY-MM"
    amortized_upfront_cost: Decimal
    dedup_key: str = field(init=False)

    def __post_init__(self) -> None:
        # Grouping on linked account (not payer account) is what prevents
        # the mis-allocation failure mode for shared, regional reservations.
        self.dedup_key = f"{self.reservation_id}:{self.linked_account_id}:{self.billing_period}"


def load_cur_records(path: str) -> pd.DataFrame:
    df = pd.read_parquet(path)
    missing = REQUIRED_COLUMNS - set(df.columns)
    if missing:
        raise ValueError(f"CUR export missing required columns: {missing}")
    # DiscountedUsage and Usage rows carry $0 in the amortized-upfront field;
    # including them would not double-count, but excluding them keeps the
    # aggregation cheap and the intent explicit.
    return df[df["line_item_line_item_type"].isin(["RIFee", "SavingsPlanRecurringFee"])].copy()


def amortize_monthly(df: pd.DataFrame) -> List[MonthlyAmortizedCost]:
    """Sum ONLY the pre-spread amortized field per (reservation, linked
    account, billing period). Never sum line_item_unblended_cost (the lump
    sum) or reservation_recurring_fee_for_usage (a separate cost component)
    into this total.
    """
    df = df.copy()
    df["amortized_upfront_cost"] = df["reservation_amortized_upfront_fee_for_billing_period"].apply(
        lambda v: Decimal(str(v))
    )
    df["billing_period"] = pd.to_datetime(df["bill_billing_period_start_date"]).dt.strftime("%Y-%m")

    grouped = (
        df.groupby(["reservation_reservation_a_r_n", "line_item_usage_account_id", "billing_period"])
        ["amortized_upfront_cost"].apply(lambda s: sum(s, Decimal("0")))
        .reset_index()
    )

    results = []
    for _, row in grouped.iterrows():
        results.append(MonthlyAmortizedCost(
            reservation_id=row["reservation_reservation_a_r_n"],
            linked_account_id=row["line_item_usage_account_id"],
            billing_period=row["billing_period"],
            amortized_upfront_cost=row["amortized_upfront_cost"].quantize(
                Decimal("0.000001"), rounding=ROUND_HALF_UP),
        ))
    return results


def upsert_monthly_costs(records: List[MonthlyAmortizedCost], store: Dict[str, MonthlyAmortizedCost]) -> int:
    """Idempotent upsert keyed on dedup_key so re-running a billing period
    after a CUR backfill overwrites in place instead of appending a
    duplicate row — the double-counting failure mode."""
    written = 0
    for rec in records:
        existing = store.get(rec.dedup_key)
        if existing is None or existing.amortized_upfront_cost != rec.amortized_upfront_cost:
            store[rec.dedup_key] = rec
            written += 1
    logger.info("Upserted %d/%d monthly amortized records", written, len(records))
    return written


def main() -> None:
    store: Dict[str, MonthlyAmortizedCost] = {}
    df = load_cur_records("cur_export_2026_06.parquet")
    monthly = amortize_monthly(df)
    upsert_monthly_costs(monthly, store)

    term = ReservationTerm(
        reservation_id="ri-0123456789abcdef0",
        purchase_option="All Upfront",
        term_years=3,
        upfront_fee=Decimal("18000.00"),
    )
    logger.info("Effective hourly rate for %s: $%s/hr over %s hours",
                term.reservation_id, term.effective_hourly_rate(), term.term_hours())

    for rec in sorted(monthly, key=lambda r: (r.billing_period, r.linked_account_id))[:5]:
        logger.info("account=%s period=%s amortized=$%s",
                     rec.linked_account_id, rec.billing_period, rec.amortized_upfront_cost)


if __name__ == "__main__":
    main()

# Verification & Testing

• Term-total reconciliation. Sum every monthly amortized_upfront_cost produced across the full term for one reservation_id and assert it equals the reservation’s total upfront fee to the cent. A shortfall almost always means a partial first or last billing period was dropped by an off-by-one date filter.
• Idempotency assertion. Call amortize_monthly and upsert_monthly_costs twice against the same input DataFrame. The second call’s written count should be 0 and the store’s total value must not move — if it does, the dedup key is missing a dimension.
• Vendor cross-check. Compare the monthly total for a reservation against AWS Cost Explorer’s GetCostAndUsage call with AmortizedCost as the cost metric, filtered to the same account and period. They must match; a persistent gap usually means reservation_recurring_fee_for_usage leaked into the sum.
• Dry-run on a synthetic fixture. Build a two-row fixture — a purchase-month row and a mid-term row for the same reservation and linked account — and assert amortize_monthly returns exactly one row per billing period, not two.

# Common Pitfalls Checklist

• Summing line_item_unblended_cost for RI purchase rows. Posts the entire fee in month one — read reservation_amortized_upfront_fee_for_billing_period instead.
• Adding reservation_recurring_fee_for_usage into the amortized total. Double-counts the hourly component of a Partial-Upfront RI — keep the two cost components separate in the schema.
• Recomputing the spread with upfront_fee / term_months. Drifts from AWS’s own hour-weighted, partial-period-aware figure — always source the number from the CUR field, never re-derive it.
• Grouping by bill_payer_account_id instead of line_item_usage_account_id. Collapses every linked account’s share of a shared reservation into the payer — group on the linked account to preserve attribution.
• Appending instead of upserting on re-run. A CUR backfill or pipeline retry silently doubles the reported cost for the affected months — enforce the (reservation_id, linked_account_id, billing_period) dedup key on every write.

# Frequently Asked Questions

# Related

• Reserved Instance Mapping Logic — the parent engine that assigns usage hours to commitments before this amortization step spreads their cost.
• Reserved Instance Coverage vs Utilization Metrics — the usage-side metrics that pair with the amortized cost produced here.
• Calculating Savings Plan Coverage and Utilization — the equivalent amortization and coverage math for Savings Plans rather than RIs.
• Parsing AWS CUR Parquet Files with Python & pandas — the CUR ingestion mechanics this module’s load_cur_records step builds on.
• FinOps Architecture & Billing Fundamentals — the broader acquisition → normalization → allocation → persistence pipeline this amortization step feeds into.

Up: Reserved Instance Mapping Logic · Home: Cloud Cost Optimization & FinOps Automation