This article covers the steps involved with connecting PayPal to ChartMogul:
- Creating an app in PayPal
- Adding a data source in ChartMogul
- Enabling Instant Payment Notifications in PayPal
- Downloading Profile IDs from PayPal
- Uploading Profile IDs to ChartMogul
- Configuring Transaction Fee Handling in ChartMogul
Please also review the Additional Notes section of this article before setting up this integration.
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:
- Billing Agreements and Billing Plans (deprecated by PayPal)
- Subscription API
- Smart Payment Buttons (only for subscription products)
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:
- 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.
- 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.
1. Create an app in PayPal
First, create a new app for ChartMogul in PayPal:
- Log into PayPal’s Developer Dashboard.
- Switch to Live mode and select Create App.
- Enter a name for the app (e.g., ChartMogul) and click Create App.
- Keep the Client ID and Secret (under Live API Credentials) handy. You’ll enter these into ChartMogul as part of creating the data source for PayPal.
2. Add a data source in ChartMogul
Using the Client ID and Secret from the previous section, add a data source for PayPal in ChartMogul:
- Go to Data Platform.
- Under Data Sources, select Add a Data Source.
- From the list of data sources, select PayPal.
- Enter a name for your data source (e.g., PayPal) and click Next.
- Copy the Client ID and Secret provided by PayPal into the corresponding fields in ChartMogul.
- Click Save.
- 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:
- Log into PayPal and navigate to Account Settings > Notifications (under Business Profile).
- For Instant payment notifications, choose Update.
- Click Edit Settings.
- Enter the Webhook URL from ChartMogul into the Notification URL field in PayPal.
- Choose the Receive IPN messages (Enabled) option.
- Click Save.
4. Download Profile IDs from PayPal
Billing Agreements and Billing Plans (deprecated by PayPal)
Download Profile IDs for your active and inactive customers:
- Go to PayPal Billing Agreement Report.
- Set Filter profile by to Active profiles, Date Range to Year to Date, and click Create Report.
- PayPal will then display a table with your data (i.e., Active profiles or Inactive profiles).
- Click Download report and choose CSV.
- Save the CSV file locally.
- 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:
"Profile ID","Description","Payer Name","Status","Amount Last Paid","Outstanding Balance","Next Bill date"
- Repeat steps 2–6 three more times with the following report parameters:
- Filter profiles by = Inactive profiles and Date Range = Year to Date
- Filter profiles by = Active profiles and Date Range = Last 1 year
- 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.
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.
5. Upload Profile IDs to ChartMogul
Upload the CSV files containing the Profile IDs you created in the previous section:
- Return to the PayPal Data Source configuration window in ChartMogul.
- In the Import Profile IDs from PayPal section, click Choose File, select a CSV file for active profiles, then click Upload List. ChartMogul will then add the IDs from the file to your Profile ID List.
- Repeat step 2 for each of the CSV files you created in the previous section.
- Check the Profile ID List to confirm it contains all of the Profile IDs that you want to save 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.
6. Configure Transaction Fee Handling
As the final step of configuring your new PayPal data 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.
There are a few additional details you should understand about how ChartMogul integrates with PayPal:
- Plans in ChartMogul may differ from plans in PayPal. PayPal doesn't include plan ids within transactions. Because of this, our integration will create the plans based on the description and service period. Therefore, it's possible that the plan names you have in ChartMogul do not match the ones on your PayPal account.
- ChartMogul imports one subscription per customer. If a customer has multiple subscriptions, or updates an existing subscription, it will be imported as multiple customers. You might want to merge these customers in ChartMogul into one customer.
- There is a lag of approximately three hours for importing data from PayPal into ChartMogul due to limitations with the PayPal API.
- PayPal’s API returns transactions for the previous three years, which means ChatMogul can only import your most recent three years of data. Keep this in mind if you choose to re-import data for your PayPal data source in the future.
- We don’t recommend clicking Import Data or performing a re-import between 00:00 and 05:00 UTC. During this time, we’ve found PayPal doesn’t always make all transactions available, resulting in missing data in ChartMogul.
- ChartMogul tracks refunds for PayPal. However, PayPal doesn't provide the date of the refund. As such, we use the date of the transaction as the refund date.
- ChartMogul does not support partial refunds.
- ChartMogul does not support trials.
- ChartMogul currently supports IPN transaction types with the recurring_* and subscr_* prefixes. Read more about IPN transaction types.
- Taxes billed through PayPal do not follow ChartMogul's default tax handling behavior. As such, ChartMogul doesn’t break out taxes into separate line items. Instead, they’re included in the following recurring revenue metrics: MRR, ARR, MRR movements, Average revenue per account, and Average sale price. Likewise, ChartMogul doesn’t exclude taxes from your Cash flow metrics, such as Net cash flow and Non-recurring revenue. Learn more about tax handling in ChartMogul.
- PayPal allows billing plans to have multiple payment definitions. ChartMogul imports each payment definition as a separate plan.
- ChartMogul imports failed transactions, but these transactions don’t generate MRR for the customer.
- Transactions funded by eCheck are added once the eCheck payment is cleared, with a retroactive transaction date (date when eCheck payment was initiated and sent for clearance).