You’ll need to be an Admin or Owner in ChartMogul and have either the Admin or Finance role in App Store Connect to complete the steps outlined in this article.
App Store Connect is one of ChartMogul’s billing system integrations, allowing you to import sales and refund transactions 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
- Data Settings
- How this integration works
- Before you begin
- Source configuration
- Connecting App Store Connect to ChartMogul
- Manually re-syncing data
- Deleting App Store Connect as a source
Overview
The following table provides details on key aspects of how ChartMogul integrates with App Store Connect.
Customer import event | ChartMogul imports customers once per day by downloading the most recently published subscriber reports. |
---|---|
Leads | ChartMogul imports lead dates when customers have their first transaction in App Store Connect. |
Free trials | ChartMogul imports the Event Date as the free trial start date when the Subscription Offer Type is Free Trial in subscriber reports. |
Contacts | ChartMogul does not import contacts from App Store Connect. Learn more about adding contacts. |
Custom attributes | When an access token is connected to more than one account or vendor, ChartMogul imports the customer’s Account ID and Vendor ID as custom attributes to help you with filtering and segmentation. |
Historical data | App Store Connect only provides subscriber reports for the most recent 12 months, limiting how much data ChartMogul can initially import when you create a new source. |
Paused subscriptions | ChartMogul does not offer native support for paused subscriptions. When an active subscription in App Store Connect is downgraded to a free plan or (has a 100% discount) ChartMogul treats this as a non-renewal and cancels the subscription. |
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 | Taxes are not listed separately in subscriber reports. ChartMogul, therefore, includes taxes in Monthly Recurring Revenue (MRR). To exclude taxes, enable the Use Developer Proceeds instead of Customer Price for calculating MRR option when adding App Store Connect as a source. |
Automated tags |
|
Subscriptions with multiple components | Not currently supported. Learn more. |
Update frequency | About once per day, ChartMogul downloads the most recently published subscriber reports for iOS auto-renewable subscriptions from App Store Connect using an access token for Reporter. |
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 | Subscriptions in App Store Connect cannot be 14 days (or more) past-due. Therefore, this setting does not apply to App Store Connect sources. Learn more. |
Churn Recognition | ChartMogul recognizes churn at the end of the service period, except when customers are refunded. When customers are refunded, ChartMogul recognizes churn according to your churn recognition setting. 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 can’t report on or deduct transaction fees from Monthly Recurring Revenue (MRR). However transaction fees are excluded when the Use Developer Proceeds instead of Customer Price for calculating MRR option is enabled. |
How this integration works
About once per day, ChartMogul downloads the most recently published subscriber reports for iOS auto-renewable subscriptions from App Store Connect using an access token for Reporter.
Limitations
App Store Connect’s subscriber reports don’t include several data elements. Here’s how they impact your use of ChartMogul.
Data Element | Impact |
---|---|
Subscriber personal information such as name or email address |
ChartMogul doesn’t store or report these data elements and uses a combination of the |
Transaction and sales tax/VAT fees |
ChartMogul can’t report on or deduct these from revenue metrics. You can, however, enable the Use Developer Proceeds instead of Customer Price for calculating MRR option. |
Failed payments |
ChartMogul can’t report these in the Failed Payments chart. |
There are also several additional details you should understand and consider when using App Store Connect with ChartMogul.
Detail | Impact |
---|---|
ChartMogul imports subscription-related data once every 24 hours. |
ChartMogul does not import data at the same time each day. Therefore, data for a given App Store Connect source may be out-of-date by as much as 24 hours. When ChartMogul generates an MRR movement 12 hours or more after the activity occurs in App Store Connect, it is not considered real-time and does not trigger a real-time email, Slack notification or webhook. Such delays may cause ChartMogul to generate an MRR movement after a daily recap email or Slack notification is sent, therefore excluding the update. |
App Store Connect access tokens are only valid for 180 days. |
Each time the access token expires, ChartMogul stops syncing with App Store Connect and displays an alert in the source configuration pop-up. You will receive an in-app and email notification when the token expires. To restart syncing, generate a new access token and enter it in the Access Token field in the source configuration pop-up. After entering the token, make sure to click on RE-SYNC in the pop-up. |
App Store Connect only provides subscriber reports for the most recent 12 months. |
During the initial import, ChartMogul can only import sales and refund transactions for customers who had an active subscription at some point in the previous 12 months.
After the initial import, however, if you manually re-sync your App Store Connect source, ChartMogul will retrieve and re-sync data for all of the transactions that have ever been imported. |
Subscriber reports are sometimes delayed for several days. |
When a report is not available, ChartMogul continues to check for the report as part of its daily sync. Once it’s available, ChartMogul imports the transactions and retroactively adjusts metrics as needed. |
Not all transactions occurring on a specific day are included in that day’s subscriber report. Instead, they may be included in a future report. |
ChartMogul imports the transactions and retroactively adjusts metrics as needed. |
Subscriber reports don’t include cancellations, and there is no mechanism (e.g., webhook) through which subscription cancellation notifications are provided. |
ChartMogul presumes all subscriptions are Active until:
ChartMogul then presumes the subscription has been canceled, changing its status and cancellation date accordingly and retroactively adjusting metrics as needed. |
Subscriber reports don’t include plan switches. |
ChartMogul reports plan switches as a cancellation followed by a reactivation. These activities may be grouped with Smart Activity Classification. |
App Store Connect creates a However, after 180 days of inactivity, the |
ChartMogul creates a new customer record for each ChartMogul adds the |
ChartMogul treats marketing opt-ins as extended trials and does not track them independently. (Applies to Magazines & Newspapers apps that use the newsstand app category and offer auto-renewable In-App Purchase subscriptions.)
Before you begin
Before completing the steps we outline in this article, please read each section to familiarize yourself with how ChartMogul integrates with App Store Connect.
- Decide whether you’d like ChartMogul to exclude transaction fees and sales tax/VAT from subscription and revenue metrics by using
Developer Proceeds
instead ofCustomer Price
to calculate MRR. - Decide whether you’d like ChartMogul to create separate customer records for customers who have subscribed to more than one app. Read more about splitting subscribers per app.
Source configuration
Each App Store Connect source in ChartMogul consists of the following configuration elements:
- Name — a unique name that enables you to identify where the data is coming from.
- Access Token — a unique code you generate in App Store Connect that allows ChartMogul to download subscriber reports.
-
Use Developer Proceeds instead of Customer Price for calculating MRR — an option to exclude transaction fees and sales tax/VAT from subscription and revenue metrics by using
Developer Proceeds
instead ofCustomer Price
to calculate MRR. Developer Proceeds are calculated as Customer Price minus taxes and fees. - Split subscribers per app — an option to create separate customer records for customers who have subscribed to more than one app. Learn more.
- Vendor selection — an option to limit which customers ChartMogul imports when the access token is connected to more than one vendor.
Connecting App Store Connect to ChartMogul
Step 1 — Generate an access token
First, generate an access token that ChartMogul will use to download the subscriber reports each day.
- From within App Store Connect, navigate to Sales and Trends > Sales and Trends Reports.
- Click the tooltip icon next to About Reports in the upper-right corner and select Generate Reporter Token.
- Finally, copy the Access Token.
Step 2 — Add App Store Connect as a source
Next, add App Store Connect as a source in ChartMogul:
- Within ChartMogul, navigate to Settings & Data > Sources.
- Click Add Source.
- Make sure that the Subscription data tab is selected and click App Store Connect.
- Enter a unique name for your source in the Name field and click Next.
- Next, enter the access token you retrieved in the previous step in the Access Token field.
- Select whether you’d like to enable Use Developer Proceeds instead of Customer Price for calculating MRR or Split subscribers per app under Data import options.
- Lastly, click Import Data.
ChartMogul will perform a test connection and, if successful, add App Store Connect as a new source. From there, it will start importing your data and let you know where it’s at with a progress bar.
Manually re-syncing data
Re-syncing your App Store Connect source will cause lead and trial data you’ve added inside ChartMogul to be lost. Re-syncing your App Store Connect source will not impact manually edited MRR, merged customers, custom attributes, or connected subscriptions.
Manually re-syncing your App Store Connect source is necessary when you change any of the Data import options or any of your Data Settings and would like to apply the change to the data ChartMogul has already imported.
Here’s how to manually re-sync data when needed:
- Within ChartMogul, navigate to Settings & Data > Sources.
- Find your App Store Connect source and click the Settings icon.
- Click Re-sync Data.
ChartMogul will start re-importing your data and let you know where it’s at with a progress bar.
Deleting App Store Connect 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 an App Store Connect 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
- Learn more about segmentation.
- Customize your Dashboard.
- Download the ChartMogul mobile app.
- Get started with charts.