subscriptions.mrr-arr

def mrr_arr(subscriptions: Sequence[RecurringCharge], currency: str) -> MrrArr

SubscriptionStatus = Literal["active", "past-due", "trialing", "paused", "canceled"]

@dataclass(frozen=True)
class RecurringCharge:
    """One subscription's recurring charge."""

    #: charged every intervalCount intervals, after recurring discounts, before tax
    amount: Money
    interval: BillingInterval
    #: 1 or more: month with 6 is every six months
    interval_count: int
    #: only active and past-due count towards MRR
    status: SubscriptionStatus

@dataclass(frozen=True)
class MrrArr:
    """Recurring revenue, each figure rounded once from the exact total."""

    mrr: Money
    arr: Money
    #: subscriptions included: active and past-due
    counted: int
    #: subscriptions left out: trialing, paused and canceled
    excluded: int

from fune.subscriptions.mrr_arr import mrr_arr  # subscriptions.mrr-arr@^1

from typing import Dict, Sequence

from .math_rational import add_rational, multiply_rational, rational, rational_to_integer  ← from math.rational ^1.0.0 · built alongside by fune
from .money_amount import assert_same_currency, money  ← from money.amount ^1.0.0 · built alongside by fune
from .subscriptions_mrr_arr_types import MrrArr, RecurringCharge

# 1.0.0 declared its own BillingInterval, which callers imported from this
# module; it is now subscriptions.next-billing-date's, imported here so they
# still can.
from .subscriptions_next_billing_date import BillingInterval  ← from subscriptions.next-billing-date ^1.0.0 · built alongside by fune

PER_YEAR: Dict[BillingInterval, int] = {"day": 365, "week": 52, "month": 12, "quarter": 4, "year": 1}


def mrr_arr(subscriptions: Sequence[RecurringCharge], currency: str) -> MrrArr:
    """MRR and ARR from active and past-due subscriptions. Every charge becomes
    an exact annual amount first, and each total is rounded once at the end,
    so a list of annual plans does not lose a penny per plan.
    """
    zero = money(0, currency)
    annual = rational(0, 1)
    counted = 0
    excluded = 0
    for s in subscriptions:
        assert_same_currency(zero, s.amount)
        if s.amount.minor < 0:
            raise ValueError("recurring amount must not be negative, received %d" % (s.amount.minor,))
        if isinstance(s.interval_count, bool) or not isinstance(s.interval_count, int) or s.interval_count < 1:
            raise ValueError("interval count must be 1 or more, received %r" % (s.interval_count,))
        if s.interval not in PER_YEAR:
            raise ValueError(
                'unknown billing interval "%s": expected day, week, month, quarter or year' % (s.interval,)
            )
        if s.status in ("active", "past-due"):
            counted += 1
            annual = add_rational(annual, rational(s.amount.minor * PER_YEAR[s.interval], s.interval_count))
        elif s.status in ("trialing", "paused", "canceled"):
            excluded += 1
        else:
            raise ValueError(
                'unknown subscription status "%s": expected active, past-due, trialing, paused or canceled'
                % (s.status,)
            )
    return MrrArr(
        mrr=money(rational_to_integer(multiply_rational(annual, rational(1, 12)), "half-up"), currency),
        arr=money(rational_to_integer(annual, "half-up"), currency),
        counted=counted,
        excluded=excluded,
    )

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 3 dependencies, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add subscriptions.mrr-arr

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./subscriptions.mrr-arr-1.1.0-python.fune, or fetch it from a terminal with fune pull subscriptions.mrr-arr@1.1.0:python.

The whole function, every language, is one file too: subscriptions.mrr-arr-1.1.0.fune, 20,656 bytes, sha256 00720786d3b507dce9b22f2e8966b5ec051a2a993e0df8eef8ed7f42d5596938. It installs into a project of any language.

# fune: before subscriptions.mrr-arr

# fune: after subscriptions.mrr-arr

# fune: replace math.rational in subscriptions.mrr-arr
# fune: replace money.amount in subscriptions.mrr-arr
# fune: replace subscriptions.next-billing-date in subscriptions.mrr-arr

# fune: step subscriptions.mrr-arr after <n|label>

More from the author

divided by `intervalCount` (a 6-monthly plan earns its price twice a year). ARR is the sum of those, and MRR is the same sum divided by 12. Both are rounded once, half-up to the minor unit, from the exact fraction (math.rational). Rounding each subscription's monthly share first and adding up is the naive way and it drifts: three annual plans of 100.00 are 25.00 of MRR, but 8.33 + 8.33 + 8.33 is 24.99. Because each figure is rounded separately, MRR x 12 can differ from ARR by a few minor units; both are right.

Weeks and days are conventions, not calendar facts: 52 weeks and 365 days to the year. Businesses that use 52.14 weeks or 365.25 days get slightly different figures for weekly and daily plans; monthly, quarterly and annual plans are exact under any convention.

What counts. `active` and `past-due` subscriptions count: a failed payment still in dunning has not churned yet, so it stays in MRR until it is cancelled. (Metrics tools differ on this; filter past-due out before calling if yours does.) `trialing` subscriptions are left out (no revenue yet), as are `paused` and `canceled` ones. The amount should be the recurring price after recurring discounts and before tax; one-off charges, usage and setup fees are not recurring revenue and do not belong here.

Errors: an amount in a currency other than `currency`, a negative amount, and an interval count below 1.

Since 1.1.0 the `interval` of a `RecurringCharge` is the `BillingInterval` declared by `subscriptions.next-billing-date` (the same five values, `day`, `week`, `month`, `quarter` and `year`), rather than a copy declared here, so a subscription record typed for one capability is accepted by the other. `BillingInterval` can still be imported from this capability's module in TypeScript and Python, which re-export it. The answers are the same as 1.0.0's.

Files