Recurring revenue and renewal deals

Monthly and annual recurring revenue (MRR, ARR) and churn, read from the subscriptions, and the renewal deals the pipeline gets ahead of every term a person has to renew (ADR-0087, ADR-0036 sections 5 to 7). On screen: Sales > Recurring revenue.

MRR, ARR and churn

GET /v1/subscriptions/metrics   ?entity&from_month&to_month

An AI assistant reads it through the MCP tool recurring_revenue, and the renewal deals through list_opportunities with kind renewal (GET /v1/opportunities?kind=renewal).

MRR on a day is the monthly rate of every subscription line in force that day (quantity x the price per month, a yearly price over 12, less the discount) of every subscription serving its customer that day: from its first day to the day it ends early, or to the end of a term nothing renews; a subscription that renews itself, or whose renewal is approved, goes on. It is read at each month's last day, and today for the current month; a month to come is refused (month_in_future), and one report reads at most 36 months (range_too_long). By default the twelve months through the current one. ARR is 12 x MRR. MRR is a commercial figure, never read from the ledger: the revenue the income statement shows is the recognition run's.

Each month explains its change customer by customer:

Each movement names the subscriptions whose MRR changed. The month also gives the customers at its start and end, how many were new, churned and back, the customer churn rate (churned over the customers at the start), the gross MRR churn rate (churn and contraction over the opening MRR) and the net MRR retention (the opening MRR with expansion, less contraction and churn, over the opening MRR; new and returning customers are not counted).

Currencies. Each customer's MRR stays in the currency it is billed in (by_currency). The totals are in the entity's functional currency, each customer converted at the ECB fixing of the month's day (fixing_date). Opening is the month before's closing at its own fixing; the difference the rates make is the month's currency_effect, so opening + movements + currency effect = closing. The rates compare amounts at the same fixing. A currency without a rate is listed in unconverted and left out of the totals of that month.

Example (CH01, CHF; a customer at EUR 520.00 a month; EUR at 0.96 CHF at the end of April and 0.97 at the end of May): the customer leaves on 14 May. May's churn is EUR -520.00 = CHF -504.40 (at 0.97), its opening CHF 1,099.20 (CHF 600.00 + 520.00 x 0.96), its closing CHF 600.00, and the currency effect CHF 5.20 (520.00 x 0.01).

Renewal deals

A subscription that does not renew itself (no auto_renew) is renewed when a person asks and a second person approves (Renewals). From the day its renewal is due (renewal_notice_days before the term's last day), the daily job opens a renewal deal in the pipeline of its company:

• kind renewal, stage proposal, with the subscription's customer, in its currency;
• worth the next term's price (the prices in force raised by the uplift the terms set);
• expected to close on the term's last day;
• owned by the owner of the deal the subscription came from, else of its previous renewal deal;
• linked to the subscription and the term (subscription_id, subscription_number, renewal_term_start on the deal; renewal_deal_id, renewal_deal_number on the subscription).

One deal per subscription and term (the database refuses a second). A subscription that renews itself gets none.

The deal follows the renewal: it is won when a second person approves the renewal of its term and lost when the subscription is ended early in that term. A term the billing run ended without a renewal can still be renewed, so its deal stays open (and late) until a person loses it or the renewal is approved. A person who marks a renewal deal won asks for the renewal at the same time when nobody has; a second person still approves it before the next term starts. An assistant cannot win a renewal deal (403), since it cannot ask for a renewal.