Braintree Integration Guide

If you're new to ChartMogul, learn how we import subscription data to generate metrics.

You’ll need to be an Admin or Owner in ChartMogul and have the Account Admin role in Braintree to complete the steps in this article.

Braintree is one of ChartMogul’s supported billing systems, allowing you to import customer, subscription, and transaction data to generate subscription analytics and cash flow metrics.

Learn more about other import methods in Getting started with importing data.

Here’s what we cover in his article:


The following table provides details on key aspects of how ChartMogul integrates with Braintree.

Customer import event

If you’re using the latest version of our Braintree integration, ChartMogul imports all customers, including those without subscriptions, during the initial import. After the initial import, only customers with a transaction are synced, due to a limitation with the Braintree webhooks API.

If you’re using a previous version, ChartMogul imports customers when they start a trial or have an invoice in Braintree.

Leads Braintree does not track the date a lead is created. So, ChartMogul calculates Lead created at by taking the customer’s first billing date, subtracting the trial duration, and adjusting the result to your time zone. Learn more about tracking leads and trials.
Free trials ChartMogul imports free trial start dates.
Contacts ChartMogul does not import contacts from Braintree. Learn more about adding contacts.
Custom attributes ChartMogul does not import custom attributes. It is, however, possible for you to create and populate custom attributes manually. Learn more.
Historical data After adding Braintree as a source, ChartMogul imports all existing customer, subscription, and transaction data.
Credits Credits in Braintree are not imported by ChartMogul.
Reviewing subscription data in-app For select billing systems, ChartMogul gives complete visibility into your data as it exists in our platform through a series of data tables. These data tables are, unfortunately, not currently available for Braintree.
Tax handling Braintree does not separate taxes into separate invoice line items. As a result, Monthly Recurring Revenue (MRR) includes taxes.
Automated tags ChartMogul does not add any automated tags to customers. Instead, learn how to add tags in-app or using our API.
Voided transactions Voided transactions in Braintree are imported by ChartMogul.
Update frequency Real-time. Learn more.
Maintained by This integration is built and maintained by ChartMogul. Contact our support team for assistance.

Data Settings

The following table provides details on how ChartMogul’s data settings work with your billing system.

Smart Activity Classification Fully supported. Learn more.
Handling Past-due Subscriptions Fully supported. Learn more.
Churn Recognition Fully supported. Learn more.
Free Customer Handling Fully supported. Learn more.
Refund Handling ChartMogul does not deduct refunded transactions from Monthly Recurring Revenue (MRR).
Transaction Fee Handling ChartMogul does not import transaction fees from Braintree, and as a result, transaction fees are automatically excluded from MRR calculations. 

Source configuration

Each Braintree source in ChartMogul consists of the following configuration elements:

  • Environment — the Braintree environment ChartMogul imports data from.
  • Public Key — the public key assigned to the read-only user you create in Step 1.
  • Private Key — the private key assigned to the read-only user you create in Step 1.
  • Merchant ID — the unique identifier for your entire Braintree payment gateway account.
  • Fixed term add-on — an option to exclude fixed-term add-ons from recurring revenue in ChartMogul. Fixed-term add-ons have a set number of billing cycles in Braintree (i.e., they are not billed in perpetuity).
  • Webhook URL — the webhook URL assigned by ChartMogul to your Braintree source. Used as part of Step 3 to keep data in ChartMogul synced with Braintree.
  • Name — a unique name for your Braintree source that enables you to identify where data in ChartMogul is coming from.

Integration versioning

On March 22, 2024, we released a new version of our Braintree integration. Read our launch announcement.

To check if you’re using the latest version, navigate to Data & Config > Sources and select your Braintree source. If you see a series of tables with customer and invoice data, you’re using the latest version of our Braintree integration. If you’re only able to view the setup modal, you’re using a previous version, and some features may be unavailable.

To migrate your account to the latest version of our Braintree integration, contact support.

Before you begin

Please review these details before completing the following steps.

  • Add-ons in Braintree are reported in ChartMogul as part of a base subscription. At the moment, ChartMogul doesn't include the quantity of add-ons when we include them in the base plan, we only consider the amount paid. When viewing a customer’s record, you’ll be able to view the breakdown when viewing transactions, however, not when viewing subscriptions.
  • Select which Braintree environment ChartMogul will import data from, either Sandbox or Production. Learn more.
  • Locate your Braintree Merchant ID.

Connecting Braintree to ChartMogul

Step 1 — Create a read-only API key

ChartMogul uses API keys to connect to Braintree. For added security, we recommend creating a read-only user in Braintree and using the API keys from this user to grant ChartMogul access to your Braintree account.

  1. Log in as admin to your Braintree account, navigate to Settings > Team > Roles, then click + New Role.
  2. Name the role, e.g., ChartMogul Read-only.
  3. Grant the role the following permissions:
    • Transactions > Download Transactions with Masked Payment Data
    • Customer Management > Download Vault Records with Masked Payment Data
    • Recurring Billing
      • Download Subscription Records
      • View Modifications
      • View Subscription Plans
      • View Subscriptions
      • Search Subscriptions
    • Read-Only Access (check all permissions)
    • Search (check all permissions)
  4. Next, go to Settings > Team > Users and click + New user.
  5. Enter an email address for the new account in the Email field. (Braintree will send an activation email link address.)
    • Under API Access, select API Access.
    • Under Roles, select the read-only role (e.g., ChartMogul Read-only) you created in Step 1
    • Assign access to your merchant account(s) (typically All).
  6. Click Create User.
  7. Log out of Braintree, activate the new read-only user you just created (using the activation link you should have received from Braintree), and log back in as the new user.
  8. Next, navigate to Account > My User.
  9. Under API Keys, Tokenization Keys, Encryption Keys, click View Authorizations.
  10. Under API Keys, note the Public Key and Private Key. You'll need these in Step 2 when adding Braintree as a source in ChartMogul.
  11. Log out of Braintree.

Step 2 — Add Braintree as a source

Next, add Braintree as a source in ChartMogul:

  1. Within ChartMogul, navigate to Data & Config > Sources.
  2. Click Add Source and select Braintree.
  3. Enter a unique name for your source in the Name field and click Next.
  4. From the Environment drop-down, select either Sandbox or Production.
  5. In the fields provided, enter the Public Key and Private Keys assigned to the read-only user you created in Step 1.
  6. Enter your Merchant ID in the field provided.
  7. Click SAVE.
  8. ChartMogul will then generate a Webhook URL that you'll need in Step 3.

Step 3 — Add a webhook in Braintree to keep your data synced

  1. Log in to Braintree using your Account Admin credentials.
  2. Navigate to Settings > API > Webhooks.
  3. Click + CreateNew Webhook, then paste in the Webhook URL from Step 2 in the Destination URL field.
  4. Under Notifications, check the following options:
    • Canceled
    • Charged Successfully
    • Charged Unsuccessfully
    • Expired
    • Went Active
    • Went Past Due
  5. Finally, click Create Webhook.

Step 4 — Import your Braintree data

In ChartMogul, click IMPORT DATA. This will connect the Braintree webhook to ChartMogul and start your data import.

The import can take some time, depending on the number of customers. After the import has concluded, ChartMogul will update automatically with any new activity from Braintree.

ChartMogul automatically imports all data once you’ve successfully connected it to Braintree. No further action is needed to import historical data.

Manually re-syncing data

Re-syncing your Braintree source will not cause any changes you’ve subsequently made to customers and their subscriptions inside ChartMogul — such as lead and trial data, manually edited MRR, merged customers, custom attributes, or connected subscriptions — to be lost.

Here’s how to manually re-sync data when needed:

  1. Within ChartMogul, navigate to Data & Config > Sources.
  2. Find your Braintree source and click the Settings  icon.
  3. Click RE-SYNC DATA.

ChartMogul will start re-importing your data and let you know where it’s at with a progress bar.

Deleting Braintree as a source

Deleting a source is permanent and cannot be undone

Before deleting a source, please note the following:

  • All data from this source will be immediately and irrevocably removed from ChartMogul.
  • All MRR adjustments and connected subscriptions will be lost.
  • If this source contains a merged customer, the customer record and data from the non-deleted source will remain in ChartMogul.

To delete a Braintree source, navigate to Data & Config > Sources. Find the source in the list and click the Settings  icon. From there, click DELETE THIS SOURCE.

Next Steps

Was this article helpful?

We’re sorry to hear that. Would you like to share more feedback?

Thanks for your feedback!