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
- Download PayPal Profile IDs
- Uploading your historical data to ChartMogul
Please also review the Additional Notes section of this article before setting up this integration.
Before you begin
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.
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 (we display 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 to enable Instant Payment Notifications.
3. Enable Instant Payment Notifications in PayPal
Next, enable Instant Payment Notifications (IPN) in PayPal:
- 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 PayPal Profile IDs
Importing your historical data from PayPal into ChartMogul involves a few steps:
- First, you’ll locate and download Profile IDs for your subscriptions. PayPal sometimes refers to 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.
- Next, you’ll upload the IDs as a CSV into ChartMogul.
- ChartMogul will then download subscription data for each ID from PayPal.
Once this process is complete, you’ll be ready to fully use ChartMogul.
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 Historical Data
Upload the CSV files you created in the previous step:
- Return to the PayPal Data Source configuration window in ChartMogul
- In the Import historic data from PayPal section, click Choose File, select a CSV file for active profiles, then click Upload List
- ChartMogul will then display the Profile IDs from your CSV file in a table. Check the table to confirm it contains the list of IDs you’re expecting to import. If it looks correct, click Import Data
- Repeat steps 2–4 for each of the CSV files you created in previous step
After you click Import Data, ChartMogul retrieves subscription data from PayPal for each Profile ID you uploaded. Once complete, you’ll see your PayPal data in ChartMogul. If you enabled instant payment notifications, PayPal will send new Profile IDs to ChartMogul so it stays up-to-date.
There are a few additional details you should understand about how ChartMogul integrates with PayPal:
- 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 uploading historical data (as we outline above) to ChartMogul or performing a re-import between 00:00 and 05:00 UTC. During this time, we’ve found PayPal doesn’t 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. 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.