Getting started
You need a HubSpot Starter, Professional or Enterprise portal and permission to install apps. HubSpot Free cannot hold the custom properties the app creates.
- Click Install free and choose your HubSpot account.
- Approve the requested access. The app reads deals, line items and companies, and writes the properties described below.
- You land in the dashboard while your Closed Won deals are imported. Most portals finish within a few minutes.
The install creates a property group called Contract MRR Engine on companies and on line items. If a label already exists in your portal, ours gets the suffix “(Termline)”. Nothing else in your portal is changed.
How MRR is calculated
For every company, the engine collects the line items on its Closed Won deals and works out each recurring line's contract window. MRR on any date is the sum of the windows that cover that date. All dates are UTC calendar dates.
Which line items count
- Recurring: the line item has a billing frequency (
recurringbillingfrequency). One-time fees never count. - Priced: its
hs_mrris above zero. Amendment and cancellation lines priced at $0 still count, so they can end the line they replace. - Closed Won: the deal has
hs_is_closed_won = true. Open and lost deals are ignored.
Start date
hs_recurring_billing_start_date, if set.- Otherwise the deal close date plus the billing start delay in days or months.
- Otherwise the deal close date.
End date
cm_effective_end_date_override, if you set one.- Otherwise the start date plus the billing term (
hs_recurring_billing_period, for exampleP12M), minus one day. - Otherwise, for fixed terms, the start date plus the number of payments at the billing frequency, minus one day.
- Otherwise the line is evergreen and has no end.
What gets written
- Active MRR: the lines whose window covers today. Active ARR is Active MRR × 12.
- Committed future MRR: the lines that start after today.
- Next renewal date: the day after the earliest natural end of a fixed term among active and future lines. Ends cut short by an amendment or an override count as terminations, not renewals.
- Contract status: Active if any line is live, Signed – Pending Start if only future lines exist, Churned if lines ran and ended, otherwise No Recurring Contracts.
Amounts are taken in each line item's own currency without FX conversion.
Upgrades, downgrades & cancellations
HubSpot Starter has no custom association labels, so amendments are recorded on the line item itself with three properties. The Contract MRR card in the deal sidebar sets them for you.
| Action | Effect |
|---|---|
| Additive (default) | A new product or an expansion. It adds to MRR from its start date. |
| Replaces a prior line | The target line ends the day before this line starts. Use it for upgrades, downgrades and price changes of one product while the rest of the contract stays. |
| Terminates a prior line | The target line ends the day before this line starts, and this line adds nothing. Use it to record a cancellation. |
Using the deal card
- Open the new deal (the upgrade or cancellation) in HubSpot.
- In the right sidebar, find Contract MRR. It lists the deal's recurring line items with their windows.
- For a line, choose Replaces or Terminates, then pick the line it supersedes from the company's active lines.
The company recalculates immediately. If you leave the target blank, the engine looks for exactly one earlier line with the same product or SKU that is still running when the new line starts. If several match, it records a warning in the audit log and guesses nothing.
Ending a line on a specific date
Set Effective End Date Override on the line item. The line stops counting after that date.
Properties reference
Companies
| Label | Internal name | Type |
|---|---|---|
| Active MRR | cm_active_mrr | Number (currency) |
| Active ARR | cm_active_arr | Number (currency) |
| Committed Future MRR | cm_committed_future_mrr | Number (currency) |
| Contract Next Renewal Date | cm_next_renewal_date | Date |
| Contract Status | cm_contract_status | Dropdown: Active, Signed – Pending Start, Churned, No Recurring Contracts |
| MRR Audit Log | cm_mrr_audit_log | Multi-line text |
Line items
| Label | Internal name | Type |
|---|---|---|
| Contract Line Action | cm_line_action | Dropdown: Additive, Replaces, Terminates |
| Replaces Line Item ID | cm_replaces_line_item_id | Text: the record ID of the superseded line |
| Effective End Date Override | cm_effective_end_date_override | Date |
Reading the audit log
Active MRR $1,800.00 | Active ARR $21,600.00 | Committed future MRR $600.00
Status ACTIVE | Next renewal 2027-03-01 | Next change 2026-11-01
Active MRR = #4302 $300.00 + #4588 $1,500.00
Recurring line items (effective start -> end):
- #4211 Growth plan $1,000.00/mo 2025-11-01 -> 2026-08-31 ENDED, term cut by #4588
- #4588 Scale plan $1,500.00/mo 2026-09-01 -> open ACTIVE, replaces #4211The first lines summarise the company. Each recurring line then appears with its effective window, its state and the amendment that shaped it. Next change is the next date the figures move without anyone editing a deal.
The dashboard
Sign in with HubSpot to see your portfolio. The figures come from the same contract windows as the properties, so they always agree.
| Metric | Definition |
|---|---|
| Active MRR / ARR | Sum over all tracked companies, today. |
| Committed future MRR | Signed MRR on lines that start after today. |
| Active customers | Companies with Active MRR above zero. |
| ARPA | Active MRR ÷ active customers. |
| Net new MRR | Change in MRR since the end of the previous month: new + expansion + reactivation − contraction − churn. |
| MRR by month | MRR on the last day of each past month, today for the current month, and the contracted MRR on the last day of each future month. |
| New | A company goes from $0 to positive MRR for the first time. Reactivations (a returning customer) are counted with new in the chart. |
| Expansion / contraction | A company's MRR rises or falls but stays above zero. |
| Churn | A company's MRR falls to zero. |
| Renewals | Fixed terms reaching their natural end, dated the first day they would stop billing. |
Future months show contracts already signed. They are not a forecast: new business and renewals not yet closed are not included.
When numbers update
- After an edit: HubSpot notifies the app about deals and line items. A company recalculates about 10 seconds after the last related change; a stream of edits is batched for at most 2 minutes.
- At 00:05 UTC every day: companies with a contract starting or ending that day are recalculated, even though nothing was edited.
- On demand: Recalculate on a customer in the dashboard updates it straight away.
The app writes to HubSpot only when a value actually changes and stays well under HubSpot's API limits.
Plans & limits
Free covers up to 15 tracked companies. A company is tracked once it has a recurring line item on a Closed Won deal. Beyond the limit, new companies wait and the dashboard shows how many; companies already tracked keep updating. Pro removes the limit. See pricing.
Troubleshooting
A company shows $0 but has a deal
Check that the deal is Closed Won, the line item has a billing frequency and an MRR, and its start date has arrived. Committed future MRR shows lines that have not started yet.
MRR is double counted after an upgrade
The upgrade line was added as Additive. Open the upgrade deal and set the line to Replaces the old one in the deal card.
The audit log has a warning about an ambiguous match
A Replaces or Terminates line has no target, and several earlier lines share its product. Pick the target in the deal card.
Numbers did not change after an edit
Wait a minute, then use Recalculate on the customer. If it still looks wrong, contact support with the company's record ID.
Security & data
- OAuth tokens are encrypted at rest with AES-256-GCM.
- Webhooks and deal-card requests are verified with HubSpot's v3 request signature.
- We store the computed figures and the contract windows of recurring line items, not your contacts or emails.
- Hosting is in the EU (Hetzner, Germany), behind Cloudflare.
Read the full privacy policy.