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 or Owner in ChartMogul and an Admin in PayPal to complete the steps in this article.

PayPal is one of ChartMogul’s billing system integrations, allowing you to import customer, subscription, and transaction data to generate subscription analytics and cash flow metrics. Read our launch announcement.

Learn more about getting started with importing data for Subscription Analytics.

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 start dates from Paypal. Learn more about tracking leads and trials.
Contacts ChartMogul does not import contacts from PayPal. Learn more about adding contacts.
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 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 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 Settings & Data > Sources, 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, 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.
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.
Handling Past-due 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 contribute to the customer's calculated Monthly Recurring Revenue (MRR).

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 customer, subscription, and transaction data for the past three years 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.
    Screenshot of PayPay’s switch to toggle between the Sandbox and Live modes
  3. Under Apps & Credentials, select Create App.
    Screenshot of PayPay’s interface for creating a REST API app
  4. Enter a name for the app (e.g., ChartMogul) and click Create App.
    Screenshot of PayPay’s interface for entering a name for the app
  5. Keep the Client ID and Secret key 1 (under API Credentials) handy. You’ll enter these into ChartMogul as part of creating the source for PayPal.
    Screenshot of PayPal’s interface for creating an app with the Client ID and Secret values highlighted

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 Settings & Data > Sources.
  2. Under Sources, select Add Source .
    Screenshot of the Sources page as described
  3. Make sure that the Subscription data tab is selected and click PayPal.
    Screenshot of the Select a source type dialog showing the locations of the Subscription data tab and the PayPal source.
  4. Enter a name for your source (e.g., PayPal) and click Next.
    Screenshot of source name field
  5. Copy the Client ID and Secret provided by PayPal into the corresponding fields in ChartMogul.
    Screenshot of the PayPal Source setup window with the Client ID and Secret fields
  6. Click Save.
  7. Note the WebHook URL — you’ll need it to enable Instant Payment Notifications.
    Screenshot highlighting the Webhook URL as we describe

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.
    Screenshot of PayPal’s interface showing how to access the Instant payment notification settings we describe
  3. Click Choose IPN Settings.
  4. Enter the Webhook URL from ChartMogul into the Notification URL field in PayPal.
  5. Choose the Receive IPN messages (Enabled) option.
    Screenshot of PayPal’s Edit Instant Payment Notification (IPN) settings screen
  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

To download Profile IDs for your active and inactive customers:

  1. In PayPal, go to Reports.
  2. Under Activities, click Recurring payment profiles report. If you don’t see that report, you may need to contact PayPal to have it enabled.
    Screenshot of the Reports page showing the location of the Recurring payment profiles report
  3. Set Filter profile by to Active profiles, Date Range to Year to Date, and click Create Report.
    Screenshot of the Reports page showing the location of the Recurring payment profiles report
  4. PayPal will display a table with your data (i.e., active profiles or inactive profiles).
  5. Click Download report and select CSV.
    Screenshot of PayPal’s download report menu with CSV highlighted
  6. Save the CSV file locally.
  7. 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"…).
  8. Repeat steps 3–7 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

If you re-sync your PayPal source, you won’t lose any changes you’ve subsequently made to customers and their subscriptions inside ChartMogul — such as manually editing MRR, connecting subscriptions, merging customers, adding custom attributes, or adding trial and lead data.

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 Settings & Data > 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.

Deleting PayPal 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 profile and data from the non-deleted source will remain in ChartMogul.

To delete a PayPal source, navigate to Settings & Data > 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!