Set up MRR Sync in three steps
With MRR Sync it takes two connections: sign in with HubSpot, then install our Stripe App. Your Stripe subscription data then appears on your HubSpot companies and contacts. You need a HubSpot user who can install apps and a Stripe user who can install apps.
Comparing ways to connect Stripe and HubSpot? Read How to connect Stripe to HubSpot, and what each option syncs.
Install in three steps
- Sign in with HubSpot. Choose Start 14-day free trial. HubSpot asks which account to use and lists the permissions below. Accept them. Your 14-day free trial starts, and no card is needed. In HubSpot you need Super Admin access or App Marketplace access permissions to install an app.
- Connect Stripe. In the app choose Connect Stripe. Stripe shows our app and its permissions, which are all read permissions. Accept them. Ask a Stripe administrator if Stripe says you can’t install apps.
- Watch the first import. First we ask HubSpot how many custom properties your plan allows. We create the property group MRR Sync in HubSpot and as many of the fields below as fit, most useful first. Then we read your Stripe customers and match them to HubSpot records. The app shows how many customers are read so far. When it ends, it shows how many companies and contacts were updated, the customers we couldn’t match, the fields left out if there are any, and a preview of five records.
After that, a change in Stripe reaches HubSpot within about a minute. Each night we check the last day’s changes, and each week we check every customer again. Choose Sync now in the app if you don’t want to wait.
What appears in HubSpot, and where
We add a property group called MRR Sync with up to 22 properties, on companies and on contacts. Open a company or a contact and look for the group. We write only these properties, and only on records we matched. We never change your other properties.
HubSpot limits how many custom properties an account can have, and the limit depends on your plan. Some plans, such as HubSpot Free, have one. We read HubSpot’s limit for your plan and create the fields in the order of the table: for each field the company property first, then the contact property. We stop when the limit is reached. Subscription status, MRR, Payment failed, Next renewal and Plan come first on every plan. The app lists the fields that were left out and says why. To create them later, delete properties you no longer use or change plan, then choose Retry fields. We write only the fields that exist.
| Field | Order | Internal name | Type | What it shows |
|---|---|---|---|---|
| Subscription status Always first | 1 | mrr_sync_status | Dropdown | Active, Trial, Past due, Unpaid, Paused, Incomplete, Canceled or No subscription. |
| MRR Always first | 2 | mrr_sync_mrr | Number | Monthly recurring revenue after discounts. |
| Payment failed Always first | 3 | mrr_sync_payment_failed | Yes/No checkbox | Yes when a payment failed and is not paid yet. |
| Next renewal Always first | 4 | mrr_sync_next_renewal | Date | The next date the subscription renews. Empty when it ends instead. |
| Plan Always first | 5 | mrr_sync_plan | Text | The Stripe product names, the biggest first. |
| Trial ends | 6 | mrr_sync_trial_end | Date | The day a trial ends. Empty when there is no trial. |
| ARR | 7 | mrr_sync_arr | Number | MRR times 12. |
| MRR currency | 8 | mrr_sync_currency | Text | The currency of MRR and ARR. |
| Last payment | 9 | mrr_sync_last_payment | Date | The date of the latest paid invoice. |
| Failed payment attempts | 10 | mrr_sync_failed_payments | Number | How many times Stripe tried an open invoice and failed. |
| Stripe customer ID | 11 | mrr_sync_stripe_customer_id | Text | The Stripe customer ID, so you can find the customer in Stripe. |
| Billing interval | 12 | mrr_sync_billing_interval | Dropdown | Monthly, Quarterly, Yearly, Weekly, Daily, Other or Mixed. |
| MRR excludes metered usage | 13 | mrr_sync_metered_excluded | Yes/No checkbox | Yes when usage-based (metered) prices are left out of MRR. |
| Cancels on | 14 | mrr_sync_cancels_on | Date | The day a subscription is set to end. Empty when any subscription goes on renewing. |
| Amount overdue | 15 | mrr_sync_amount_overdue | Number | The unpaid part of open invoices that Stripe tried and failed to collect, in the MRR currency. 0 when nothing is overdue. |
| Cancellation reason | 16 | mrr_sync_cancel_reason | Dropdown | Why the customer canceled, as Stripe records it. Empty when Stripe has no reason. |
| Canceled on | 17 | mrr_sync_canceled_on | Date | The day the last subscription ended. Filled only when the status is Canceled. |
| Customer since | 18 | mrr_sync_customer_since | Date | The day the first subscription started, a trial included. |
| Payment failing since | 19 | mrr_sync_failing_since | Date | The date of the oldest open invoice that Stripe failed to collect. Empty when there is none. |
| Last payment amount | 20 | mrr_sync_last_payment_amount | Number | The amount of the latest paid invoice, in the MRR currency. Empty when it was paid in another currency. |
| Cancellation comment | 21 | mrr_sync_cancel_comment | Text | The comment that came with the cancellation, cut to 500 characters. Empty when there is none. |
| Updated by MRR Sync | 22 | mrr_sync_updated_at | Date and time | When MRR Sync last wrote the record. |
The lifecycle fields work from the subscriptions Stripe already gives us. Cancels on is the day a subscription is set to end, and stays empty while any subscription goes on renewing. Canceled on, Cancellation reason and Cancellation comment fill in when the customer’s status is Canceled, and the reason and comment are the ones Stripe records, so they stay empty when Stripe has none. Amount overdue adds up what is unpaid on open invoices where Stripe tried and failed to collect the payment, and stays empty when those are in more than one currency. If you connected before these fields existed, we create them at the next weekly check, as far as your HubSpot plan has room.
MRR is each live subscription’s price per month after discounts, summed. A yearly price is divided by 12. Usage-based (metered) prices are left out, and the field MRR excludes metered usage says so. When a customer pays in more than one currency, MRR and ARR stay empty, because we don’t convert between currencies. A company with several Stripe customers shows their values added up.
How the numbers are counted: how to calculate MRR from Stripe subscriptions and MRR vs ARR.
How customers are matched
We never create a contact or a company. We look for the record that already exists, in this order, and stop at the first single match.
| Record | We look for |
|---|---|
| Contact | 1. A contact whose Stripe customer ID field holds the customer’s ID. 2. A contact with the same email address (capital letters and spaces don’t matter). |
| Company | 1. A company whose Stripe customer ID field holds the customer’s ID. 2. The company of the contact we matched. 3. The one company whose Company domain name is the domain of the customer’s email, unless it is a free email provider such as Gmail or Outlook. |
When more than one record fits, we link none of them and list the customer instead. Once a customer is linked we keep the link. If HubSpot says the record was deleted or merged, we match that customer again.
The Stripe customer ID field is the eleventh in the order, so a plan with a tight limit may not get it. Then step 1 is skipped: we match on email and domain, and we keep the link for each customer ourselves.
If your HubSpot has the Stripe customer ID field, you can link a customer yourself: type its Stripe customer ID in that field of the right company or contact. It is the first thing we check.
What to do with customers we couldn’t match
The app lists them with the reason. After you fix one, choose Sync now. Without that, the weekly full check picks it up.
| Reason | What to do |
|---|---|
| The Stripe customer has no email. | Add an email to the customer in Stripe, or, if you have the Stripe customer ID field, type the ID in the right HubSpot record. |
| No contact has this email. | Add the email to a contact in HubSpot. |
| Several records fit. | Merge the duplicates in HubSpot, or, if you have the Stripe customer ID field, type the ID in the one that should get the values. |
| The email is from a free email provider. | The address doesn’t tell us the employer. Associate the contact with its company in HubSpot, or, if you have the Stripe customer ID field, type the ID in the company. |
| No company has this domain. | Fill in the company’s domain name in HubSpot, or associate the contact with its company. |
| We couldn’t read this customer from Stripe. | Click Sync now to try again, or wait for tonight’s retry. |
Build a segment of failed payments
HubSpot calls its lists segments. To list every company whose payment failed:
- In HubSpot choose CRM, then Segments (it may sit under More).
- Choose Create segment, then Manually. Choose the Company object and choose Next.
- Give the segment a name. Choose Add filter, then Properties, and search for Payment failed.
- Set it to is equal to and tick Yes. Choose Next.
- Choose the type Active, so companies join and leave the segment by themselves. Choose Save and process segment.
Payment failed is one of the fields every plan gets first. For a trial that is about to end, filter on Trial ends instead; it is the sixth field we create, so check that your HubSpot has it. For a renewal, use Next renewal. HubSpot lets you use the same properties in workflows and reports on the plans that include them.
To win those payments back in Stripe, see Stripe failed payments: why they fail and how to recover them.
What we ask access to, and why
Stripe: read only. The app can’t charge, refund, create or change anything in your Stripe account.
| Stripe permission | Why we need it |
|---|---|
customer_read | Reads your customers (name and email) so each one can be matched to a HubSpot contact or company. |
subscription_read | Reads each customer's subscriptions to work out plan, status, MRR, ARR and renewal date. |
invoice_read | Reads open and paid invoices to show failed payments and the date of the last payment. |
product_read | Reads product names to show the plan name in HubSpot. |
plan_read | Reads prices, including tiered prices, to compute the monthly amount of each subscription. |
coupon_read | Reads coupons on subscriptions so MRR is shown after discounts. |
event_read | Lists and receives events about customers, subscriptions and invoices, so HubSpot is updated within minutes of a change. |
connected_account_read | Reads the default currency of your Stripe account. |
HubSpot: your companies and contacts. We read them to find the match, and we write only our own fields.
| HubSpot permission | Why we need it |
|---|---|
oauth | Required by HubSpot for every app that signs in with OAuth. |
crm.objects.contacts.read | Find the contact that matches a Stripe customer. |
crm.objects.contacts.write | Write our fields on the contacts we matched. |
crm.objects.companies.read | Find the company that matches a Stripe customer. |
crm.objects.companies.write | Write our fields on the companies we matched. |
crm.schemas.contacts.write | Create the property group and the fields on contacts. |
crm.schemas.companies.write | Create the property group and the fields on companies. |
We keep a small summary of each Stripe customer, not your invoices or payments. Details: Privacy.
If something goes wrong
The app shows the problem in plain words, with a button that fixes it. The most common ones:
| You see | What to do |
|---|---|
| Stripe disconnected. | Choose Reconnect Stripe. This happens when the app was uninstalled in Stripe or Stripe stopped our access. |
| HubSpot disconnected. | Sign in with HubSpot again. |
| Reinstall to grant the new permissions. | Sign in with HubSpot again and accept all the permissions. |
| A property with our name has another type. | A HubSpot property already uses one of our internal names. Rename or delete that property in HubSpot, then choose Sync now. |
| Some fields are listed as left out. | HubSpot limits custom properties by plan, and your plan has no room for them. The fields left out come last in the order above. Delete properties you no longer use or change plan, then choose Retry fields. |
| Stripe or HubSpot asked us to slow down, or isn’t answering. | Nothing. We try again by ourselves in a few minutes. |
Disconnect and delete your data
- Disconnect Stripe: choose Disconnect Stripe in the app. We delete the Stripe tokens, the summary of each customer, the links to your HubSpot records, the list of unmatched customers and the waiting list.
- Uninstall in Stripe: in your Stripe Dashboard open Settings, then Installed apps. Choose the … menu of MRR Sync, View app details, then Uninstall app. We stop reading at once.
- Uninstall in HubSpot: choose the settings icon, then Integrations, then Connected Apps. Choose Actions next to MRR Sync, then Uninstall, and type “uninstall”. We stop writing at once.
- The values stay in HubSpot. The properties and the values we wrote belong to your HubSpot account. To remove them, delete the property group MRR Sync in HubSpot’s property settings.
- Cancel your plan: choose Manage billing in the app. Syncing pauses at the end of the paid period.
- Delete everything: choose Delete account in the app, or email us. We delete your account, tokens and summaries. 90 days after a trial ends unpaid or a plan is cancelled, we delete them by ourselves.
Help
Email support@webitsolutions.net. We answer within 2 working days.
Ready? Start 14-day free trial 14 days free. No card to start.