App Store Connect Integration Guide

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 supported billing systems, allowing you to import sales and refund transactions 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 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 Data & Config > 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
  • subscriber_id_reset — added to a customer that has reactivated after more than half a year in App Store Connect.
  • ChartMogul adds the appname from subscriber reports as tags to customers.
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 Vendor ID and Subscriber ID (and can be found in the External IDs section of the customer record) as the customer’s name. Read more.

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

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.

  • Customers with subscriptions that started more than 12 months ago (and are still active at the time of the initial import) will have a subscription state date of approx. 12 months ago.

  • For example, if you added App Store Connect as a source on March 1, 2022, ChartMogul would import transactions from March 2021 onwards.

  • A customer with an active subscription that started in January 2021 would have an approx. subscription start date of March 1, 2021.

  • Customers whose subscriptions had expired before March 2021 would not be imported into ChartMogul.

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:

  • a refund has been processed within the subscription’s current service period,
  • the subscription’s current service period ends without a renewal transaction, or
  • no payment has been reported for more than three consecutive days after the expected renewal date.

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 Subscriber ID the first time a customer purchases a subscription, and the ID is used for subsequent purchases from the same customer.

However, after 180 days of inactivity, the Subscriber ID is deleted. If the same customer then re-subscribes, App Store Connect creates a new Subscriber ID and indicates that the ID has been reset for that customer.

ChartMogul creates a new customer record for each Subscriber ID it learns about. Therefore, when a former customer re-subscribers (after 180 days of inactivity), it creates a new customer with a new subscription instead of changing the existing customer’s status back to Active and classifying the MRR as Reactivation.

ChartMogul adds the subscriber_id_reset tag to these customers.

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 of Customer 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 of Customer 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.

  1. From within App Store Connect, navigate to Sales and Trends > Sales and Trends Reports.
  2. Click the tooltip icon next to About Reports in the upper-right corner and select Generate Reporter Token.
  3. Finally, copy the Access Token.

Step 2 — Add App Store Connect as a source

Next, add App Store Connect as a source in ChartMogul:

  1. Within ChartMogul, navigate to Data & Config > Sources.
  2. Click Add a Source and select App Store Connect.
  3. Enter a unique name for your source in the Name field and click Next.
  4. Next, enter the access token you retrieved in the previous step in the Access Token field.
  5. 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.
  6. 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:

  1. Within ChartMogul, navigate to Data & Config > Sources.
  2. Find your App Store Connect 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 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 Data & Config > 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!