Configuring App Store Connect as a data source

You’ll need to be an Admin 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:

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.
  • Locate any subscriber reports older than 12 months you may have downloaded and archived.

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.

An App Store Connect data source in ChartMogul consists of the following 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.
    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.
  • 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.
  • 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.

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 profile) 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 data 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 data source configuration 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 data 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.
  • If you’ve archived subscriber reports for periods prior to the most recent 12 months, we can import them for you.

After the initial import, however, if you manually re-sync your App Store Connect data 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 Newsstand Kit and offer auto-renewable In-App Purchase subscriptions.)

Adding App Store Connect as a data source

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 data source

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

  1. Within ChartMogul, navigate to Data Platform > Data Sources.
  2. Click ADD A DATA SOURCE and select App Store Connect.
  3. Enter a unique name for your data 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 data source. From there, it’ll start importing your data and let you know where it’s at with a progress bar.

Importing 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 data source.

If you’ve downloaded and stored subscriber reports for periods prior to the most recent 12 months and would like us to import them, please get in touch with support.

Manually re-syncing data

Re-syncing your App Store Connect data source will cause any changes you’ve subsequently made to customers and their subscriptions inside ChartMogul — such as manually editing MRR, merging customers, adding custom attributes, or connecting subscriptions — to be lost.

Manually re-syncing your App Store Connect data 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 Platform > Data Sources.
  2. Find your App Store Connect data 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.

Was this article helpful?