Integrating with Stripe
If you are a Stripe customer, our Stripe integration can be used to automatically track your MRR, trials, and churn in Vitally. Let's take a look!
To get started with our Stripe integration, navigate to our Integrations Catalog (click on your name in the top left and choose the Integrations option) and click on the Stripe integration.
Step 1 - Connect to your Stripe account
Simply click the Connect to Stripe button to authorize access to your Stripe account. Once you grant us access, you should end up back in Vitally on the next step.
Step 2 - Configuring how accounts between Stripe and Vitally should be 'linked'
Once you connect us to your Stripe account, the first option in Vitally displays the question "Do your Stripe customers have the primary ID of the account attached in
metadata?" with 2 options - "Yes" or "No":
Step 2a: The "Yes" option (recommended)
As Vitally unifies your customer data from various sources, we need a way to 'link' the data stored by those sources together under the same account in Vitally. The most accurate way of doing that is by using the same "global ID" across all systems (which is usually the ID defined by your database), but different systems have different ways of specifying this ID. For example, in Segment, it is the first option passed when using
analytics.group . In Intercom, it's the
company_id field supported on their company object.
In Stripe, they have no way of natively specifying this ID. However, Stripe does have support for attaching arbitrary data to your accounts via a
metadata field, and we recommend using that field to add each account's global ID to your Stripe customers.
If you can attach each account's global ID to your Stripe metadata, selecting "Yes" to the "Do your Stripe customers have the primary ID of the account attached in
metadata?" question lets you select which field in your
metadata contains that ID.
Step 2b: The "No" option
If you aren't already tracking each account's ID in your Stripe
metadata, it may be a bit difficult to make the technical changes necessary to do so. If that's the case, you can select "No" to the "Do your Stripe customers have the primary ID of the account attached in
Selecting "No" means we'll attempt to import an account's Stripe data using the email of the customer in Stripe. The process is pretty straightforward - once we get the customer from Stripe, we'll use the email attached to the customer to locate a user in Vitally with that email. If we find a user, we'll associate the subscription for that Stripe customer to the user's account in Vitally.
There are a few downsides to this option:
- If you have multiple users in Vitally with the given Stripe email, we'll simply use the account associated to the first user with the email, which may or may not be the 'correct' choice.
- If your Stripe emails aren't the same ones users sign up with (e.g. they are "billing@" emails), then we won't be able to attach the Stripe subscription to the right Vitally account.
- We won't be able to import your Stripe customers and payment history until a user with the Stripe email exists in Vitally.
Step 3 - Handling customers with multiple Stripe subscriptions
While uncommon, if your Stripe customers have multiple subscriptions, Vitally needs to be able to select one of those subscriptions as the 'primary' one to track in Vitally. In other words, we do not support tracking multiple subscriptions for a single account at this time - you have to choose just one subscription.
If you do have multiple subscriptions in Stripe for an account, you can identify the one to track in Vitally via Stripe's
Once you have the
metadata updated for all your 'primary' subscriptions in Stripe, you just need to map that metadata in Vitally by defining 1) the metadata key (e.g. "isPrimarySubscription") and 2) the value given to your 'primary' subscriptions (e.g. "true").
Once defined, we'll only import subscriptions in Stripe with the defined metadata key & value set.
Details about the Stripe integration
- The Stripe integration works by initially importing all your existing customers as well as their past paid invoices.
- Moving forward, we then listen for customer, subscription, and invoice changes using Stripe webhooks. If a customer or subscription is created, updated, or deleted in Stripe, we will handle that appropriately by creating, updating, or deleting (churning) the customer in Vitally. Additionally, if a Stripe invoice is paid, we will update the customer's MRR and renewal dates in Vitally.
- Once you enable the Stripe integration, we will automatically adjust your revenue and churn tracking configuration to sync with Stripe. This means we will override any past configuration you had. If you'd rather that not happen, please reconfigure each after the integration is enabled. Note that if you have an existing trial tracking configuration, we will not override it. We do this because many teams choose to track trials internally, outside of Stripe.
- All Stripe data is also attached to your Vitally customers as traits, giving you the ability to leverage that data in reports and Indicators.