Stripe Overview
Vitally's Stripe integration can be used to sync the following Stripe data into Vitally in real time:
Customers - Vitally can import your Stripe customers into Vitally as accounts. When done, we'll add a wealth of new Stripe-defined traits to your Vitally profiles, such as the expiration of the customer's credit card, the plans they are subscribed to, and much more!
Revenue data - Vitally also imports your historical paid invoices from Stripe so that you have immediate, accurate insight into the purchase history of every account in Vitally.
Enabling the Stripe integration
To enable the Stripe integration, navigate to your Settings (⚙️) by selecting your Account Logo on the top left and under Operations select Integrations to find Stripe (or via Quick Jump). When there, first click the Connect to Stripe button. That will redirect you to Stripe, where you'll need to grant Vitally access to your Stripe data. Once you do, you'll be redirected back to Vitally, where you'll be able to configure the integration.
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":
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 unique ID for each account across all systems. Here is more information on the significance of the external ID.
Stripe has no way of natively specifying this ID. However, Stripe has support for attaching arbitrary data to accounts via a metadata field. We recommend using that field to add each account's external ID to your Stripe customers.
By attaching each account's external ID to your Stripe metadata, you can select "Yes" to the "Do your Stripe customers have the primary ID of the account attached in metadata?" question. Then select the field that contains the external ID in your metadata.
When selecting this option, only Stripe customers that have an external ID in this metadata field will be created as accounts in Vitally.
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 metadata?" question.
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:
We won't be able to import your Stripe customers and payment history until a user with the Stripe email exists in Vitally. Accounts will only be created in Vitally when a matching customer email is found.
If you have multiple users in Vitally with the same Stripe email, we'll use the account associated to the first user returned with the email, which may or may not be the 'correct' choice.
If your Stripe emails aren't the same as the ones users sign up with (e.g. they are "billing@" emails), we won't be able to attach the Stripe subscription to the right Vitally account. A user with the Stripe email will need to be created in Vitally in order to link to Stripe.
Handling customers with multiple Stripe subscriptions
If your Stripe customers have multiple subscriptions, just choose the "Yes" option to the question below:
Selecting "Yes" here defaults your trial, revenue, and churn tracking to use traits we'll attach to your accounts that identify the number of paying (the Subscription Paying Count trait) and trialing (the Subscription Trialing Count trait) subscriptions the account has in Stripe. We'll also default your MRR trait to one that totals revenue across all active subscriptions for each account.
More 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.
Stripe account traits available in Vitally
When we import a customer from Stripe, we'll automatically add the below traits to your accounts in Vitally. Keep in mind that you can segment accounts by any traits, so you'll be able to run reports across all these fields below in Vitally 🎉
Trait | Type | Description |
Account Balance | number | The current balance of the account in Stripe |
Cancel At Period End | boolean | Whether the customer is canceling their subscription prior to the next renewal |
Canceled At | date | The date the customer canceled their subscription |
Card Expiration | date | The date the customer's primary card in Stripe is set to expire |
Created | date | The date the customer was created in Stripe |
Currency | string | The currency used for the customer in Stripe |
Current Period End | date | The date the customer's subscription is set to renew. Note that we'll automatically use this trait as your renewal trait in your Subscribed Customers configuration. |
Current Period Start | date | The date the customer's subscription started |
Current Subscription Status | string | Set to either |
Customer Id | string | The ID of the customer in Stripe |
Delinquent | boolean | Whether the customer has an overdue balance in Stripe |
Discount Amount Off | number | The flat discount the customer applies to their balance, if applicable |
Discount Duration In Months | number | The number of months the customer's discount is valid for, if applicable |
Discount Id | string | The ID of the customer's discount, if applicable |
Discount Name | string | The name of the customer's discount, if applicable |
Discount Percent Off | number | The percentage discount the customer applies to their balance, if applicable |
string | The email of the customer in Stripe | |
Last Invoice Id | string | The ID of the customer's last invoice in Stripe |
Last Invoice Amount | number | The amount of the customer's last invoice in Stripe |
Last Invoice Timestamp | date | The date of the customer's last invoice in Stripe |
Metadata | objet | We'll import each key/value pair you add to the metadata of your Stripe customers |
Mrr | number | This is an auto-calculated trait we set for you. It is set to the maximum of either 1) the customer's last invoice amount or 2) the customer's subscription amount. We'll also automatically use this trait as your revenue trait in your Subscribed Customers configuration. |
Name | string | The name of the customer in Stripe |
Plan Amounts | array | An array of numbers representing the amount of each plan the customer is subscribed to |
Plan Ids | array | An array of strings representing the ID of each plan the customer is subscribed to |
Plan Names | array | An array of strings representing the names of each plan the customer is subscribed to |
Status | string | The Stripe-defined status for the customer's Stripe subscription |
Subscription Amount | number | The amount of the customer's Stripe subscription |
Subscription Id | string | The ID of the customer's Stripe subscription |
Subscription Interval | string | The interval (e.g. month, year) of the customer's Stripe subscription |
Trial Start | date | The start date of the customer's trial in Stripe |
Trial End | date | The end date of the customer's trial in Stripe. Note that we'll automatically use this trait as your trial end trait in your Trials configuration. |
If you select that customers have multiple subscriptions in Stripe, we’ll automatically transition to exclusively using the following set of traits:
Trait | Type | Description |
Subscription Ids | array | An array of IDs for every Stripe subscription the customer has |
Subscription Statuses | array | The Stripe-defined statuses for the customer's Stripe subscriptions (*note that once an account is canceled in Stripe, there is no API call to update this trait) |
Subscription Paying Count | number | The number of Stripe subscriptions with active revenue |
Subscription Trialing Count | number | The number of Stripe subscriptions with an active trial |
Subscription Amounts Total | number | The total sum of all the customer's Stripe subscription amounts |
Last Invoice Ids | array | An array of IDs for the last invoice of each subscription |
Last Invoice Amounts | array | An array of amounts for the last invoice of each subscription |
All Mrr | number | The total MRR across all paying subscriptions for the customer |
Stripe FAQ
Q: Will all customers be imported from Stripe into Vitally?
A: Only customers with an ID in the Stripe Metadata field will be imported.
Q: What happens to customers without active subscriptions?
A: We will sync in all customers that have an ID set in the metadata field you select regardless of status, but their Stripe subscription details won’t be included.
Q: What does "Churn customers without subscriptions" do?
A: If this is enabled, then customers without subscriptions will automatically be marked as Churned.