PayPal Integration Guide

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

You’ll need to be an Admin in both ChartMogul and PayPal to complete the following steps.

PayPal 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. Read our launch announcement.

Here’s what we cover in this article:

Overview

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

Customer import event ChartMogul imports customers when the customer profile is created in PayPal
Leads ChartMogul does not import lead dates from PayPal. Learn more about tracking leads and trials.
Free trials ChartMogul does not import free trial dates from Paypal. Learn more about tracking leads and trials.
Custom attributes ChartMogul does not import custom attributes from PayPal. It is, however, possible for you to create and populate custom attributes manually. Learn more.
Historical data ChartMogul does not import historical data from PayPal. However, follow the setup instructions below to import historical data.
Paused subscriptions When a subscription is paused in PayPal, is it canceled in ChartMogul. When it is unpaused, the subscription becomes active again.
Reviewing subscription data in-app using our Data Platform Once imported, ChartMogul gives you complete visibility into your data as it exists in our platform through a series of data tables. To view these tables, navigate to Data PlatformSources, then select the source you want to view. Learn more about the data stored in each table and table column or export it to CSV.
Tax handling PayPal does not separate taxes into separate invoice line items. As a result, ChartMogul is unable to determine the tax amount of the transaction, and tax is included in subscription revenue.
Automated tags ChartMogul does not add any automated tags to customers. Instead, learn how to add tags in-app or using our API.
Update frequency There is a lag of approximately three hours for importing data from PayPal into ChartMogul. 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.
Auto-churn of Delinquent Subscriptions Fully supported. Learn more.
Churn Recognition Fully supported. Learn more.
Free Customer Handling Supported for ChartMogul accounts opened after August 17, 2022. Learn more.
Refund Handling ChartMogul does not deduct refunded transactions from Monthly Recurring Revenue (MRR).
Transaction Fee Handling ChartMogul allows you to include or exclude transaction fees when calculating metrics. Learn more.
Open Invoice Support Not currently supported. Learn more.

How this integration works

There are also several additional details you should understand and consider when using PayPal with ChartMogul.

Detail Impact
PayPal doesn’t always make all transactions available between 00:00 and 05:00 UTC. We do not recommend clicking Import Data or performing a re-sync during these hours as it results in missing data in ChartMogul.
PayPal doesn't provide the date of a refund. ChartMogul uses the date of the original transaction as the refund date.
PayPal supports partial refunds. ChartMogul does not support partial refunds and, therefore, does not import them.
PayPal’s IPN service triggers a notification when an event occurs that pertains to a transaction. Read more about IPN transaction types. ChartMogul currently supports IPN transaction types with the recurring_* and subscr_* prefixes.
PayPal allows billing plans to have multiple payment definitions. ChartMogul imports each payment definition as a separate plan.
PayPal tracks failed transactions. ChartMogul imports failed transactions, but these transactions don’t generate MRR for the customer.

Before you begin

Compatibility with PayPal offerings

It’s important to understand PayPal offers several payment services for both subscription and non-subscription products.

ChartMogul supports the following PayPal payment solutions for products and services sold on a subscription basis:

Unfortunately, we don’t currently support the following:

If you’re using other PayPal payment solutions — or aren’t sure which solution you’re using — please contact us to find out if our integration will support your needs.

How your data gets from PayPal into ChartMogul

Getting your PayPal data into ChartMogul mainly involves downloading Profile IDs from PayPal and uploading them into ChartMogul:

  1. You’ll first need to locate and download Profile IDs for your subscriptions. PayPal sometimes refers to them as Subscription or Billing Agreement IDs, depending on the payment solution you’re using. Also, the steps involved with downloading Profile IDs differ for each payment solution.
  2. Then, you’ll upload the IDs into ChartMogul.

From there, ChartMogul does the heavy lifting of importing all of the customer, subscription, and transaction data for each ID — in effect, importing your historical data from PayPal. This process can take a few hours to complete, but once it does, you’ll be ready to use ChartMogul.

Connecting PayPal to ChartMogul

1. Create an app in PayPal

First, create a new app for ChartMogul in PayPal:

  1. Log into PayPal’s Developer Dashboard.
  2. Switch to Live mode and select Create App.
  3. Enter a name for the app (e.g., ChartMogul) and click Create App.
  4. Keep the Client ID and Secret (under Live API Credentials) handy. You’ll enter these into ChartMogul as part of creating the source for PayPal.

2. Add a source in ChartMogul

Using the Client ID and Secret from the previous section, add a source for PayPal in ChartMogul:

  1. Go to Data Platform.
  2. Under Sources, select ADD A SOURCE.
    add_a_source.png

  3. From the list of sources, select PayPal.
  4. Enter a name for your source (e.g., PayPal) and click Next.
  5. Copy the Client ID and Secret provided by PayPal into the corresponding fields in ChartMogul.
  6. Click Save.
  7. Note the WebHook URL — you’ll need it to enable Instant Payment Notifications.

3. Enable Instant Payment Notifications in PayPal

Enabling Instant Payment Notifications (IPN) in PayPal creates an automatic data sync between PayPal and ChartMogul so that you don’t have to export and upload Profile IDs manually going forward. Here’s how to set it up:

  1. Log into PayPal and navigate to Account Settings > Notifications (under Business Profile).
  2. For Instant payment notifications, choose Update.
  3. Click Edit Settings.
  4. Enter the Webhook URL from ChartMogul into the Notification URL field in PayPal.
  5. Choose the Receive IPN messages (Enabled) option.
  6. Click Save.

PayPal supports setting up a single IPN per account. If you're already using IPN for another service, you’ll need to forward notifications to ChartMogul.

4. Download Profile IDs from PayPal

Billing Agreements and Billing Plans (deprecated by PayPal)

Download Profile IDs for your active and inactive customers:

  1. Go to PayPal Billing Agreement Report.
  2. Set Filter profile by to Active profiles, Date Range to Year to Date, and click Create Report.
  3. PayPal will then display a table with your data (i.e., Active profiles or Inactive profiles).
  4. Click Download report and choose CSV.
  5. Save the CSV file locally.
  6. Edit the CSV file to remove the title row (e.g., Active profiles or Inactive profiles) and any blank rows that may be present. Do not, however, remove the header row (i.e., "Profile ID","Description","Payer Name"…).
  7. Repeat steps 2–6 three more times with the following report parameters:
    1. Filter profiles by = Inactive profiles and Date Range = Year to Date
    2. Filter profiles by = Active profiles and Date Range = Last 1 year
    3. Filter profiles by = Inactive profiles and Date Range = Last 1 year

After completing these steps, you should have four separate CSV files, which you’ll upload to ChartMogul.

If the report contains no customers (i.e., No data available), you may be storing Billing Agreement IDs in your database. In this case, we suggest working with your developer to access and download the IDs to a CSV file. Billing Agreement IDs have the format I-123450XX.

Subscription API and Smart Payment Buttons

You can find the list of Profile IDs (i.e., Subscription IDs) on the Pay & Get Paid -> Subscriptions page.

At the time of writing this article, PayPal did not provide a way to export all Subscription IDs. Given this, you may be storing Subscription IDs in your database. If this is the case, we suggest working with your developer to download the IDs to a CSV file.

5. Upload Profile IDs to ChartMogul

Upload the CSV files containing the Profile IDs you created in the previous section:

  1. Return to the PayPal Source configuration window in ChartMogul.
  2. In the Import Profile IDs from PayPal section, click Choose File, select a CSV file, then click Upload List. ChartMogul will then add the IDs from the file to your Profile ID List.
  3. Repeat step 2 for each CSV file you created in the previous section.
  4. Check the Profile ID List to confirm it contains all of the Profile IDs you want to store and work with in ChartMogul — including the IDs you just uploaded. If the Profile ID List looks correct, click Import Data.

After you click Import Data, ChartMogul retrieves from PayPal customer, subscription, and transaction data for all Profile IDs in your Profile ID List. This process can take a few hours to complete.

Set up the automatic data sync between PayPal and ChartMogul, so you don’t have to manually export, upload, or manage Profile IDs going forward. It’s easy to do — and we highly recommend it.

6. Configure Transaction Fee Handling

As the final step of configuring your new PayPal source, you’ll need to decide whether ChartMogul should deduct transaction fees from MRR and cash flow metrics.

Learn more about configuring transaction fee handling.

Manually re-syncing data

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

Detail Impact
PayPal’s API limits transaction data to the previous three years. ChatMogul can only import your most recent three years of data. Keep this in mind you ever choose to re-sync your PayPal source in the future.
PayPal doesn’t always make all transactions available between 00:00 and 05:00 UTC. We do not recommend clicking Import Data or performing a re-sync during these hours as it results in missing data in ChartMogul.

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

  1. Within ChartMogul, navigate to Data Platform > Sources.
  2. Find your PayPal 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.

Next Steps

Was this article helpful?

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


Thanks for your feedback!