Merge branch 'ADP-5308' into develop

Author: titerman

.claude/skills/product-manager/references/mobile-product-context.md

@@ -449,7 +449,7 @@ Initialize the SDK in your app delegate:
 
 ```swift
 // AppDelegate.swift
-func application(_ application: UIApplication, 
+func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
     Adapty.activate("YOUR_API_KEY")
     return true

src/assets/shared/img/autopilot-paywall-diagnostic.webp

@@ -0,0 +1,10 @@
+---
+no_index: true
+---
+
+Two time settings control what the table shows:
+
+- **Time frame** — the date range. Set it in the calendar above the table.
+- **Cohort length** — how big each row is: day, week, month, quarter, or year. With a monthly length, each row covers one month of installs.
+
+The two work separately. For example: a 6-month time frame plus a monthly cohort length gives you a table with 6 rows. A 1-year time frame plus a weekly cohort length gives you 52 rows.

src/components/reusable/CohortLengthAndTimeFrame.mdx

@@ -0,0 +1,15 @@
+---
+no_index: true
+---
+
+Adapty displays all monetary charts in **US dollars**, regardless of the original transaction currency. This includes Revenue, MRR, ARR, ARPU, ARPPU, LTV, predicted revenue, refund money, and the revenue figures inside cohorts and A/B test reports. There's no setting to display them in another currency.
+
+Adapty converts each transaction to USD using a rate from [currencylayer.com](https://currencylayer.com/) refreshed every 8 hours, **fixed at the time of the transaction**. Historical USD values don't re-rate when FX moves.
+
+Local-currency values are available per-transaction in:
+
+- The `price` and `currency_code` fields in webhooks
+- The `price` and `currency_code` columns in S3, GCS, and BigQuery exports
+- The profile page (per-transaction view)
+
+For finance reporting in a local currency, pull the per-transaction local-currency values from an export and aggregate them yourself.

src/components/reusable/CurrencyUsdOnly.mdx

@@ -0,0 +1,7 @@
+---
+no_index: true
+---
+
+Adapty calculates renewal revenue at the product's current price, even for users who were on a previous price when they first subscribed. After you change a price in App Store Connect or Google Play, the dashboard's Revenue, MRR, and ARR figures for existing subscribers may diverge from the actual revenue collected — Adapty applies the new price, even if the store kept those users on the old one.
+
+To verify, compare the per-transaction `price` field in the S3, GCS, or BigQuery export against the dashboard for the same transactions. The export field reflects what the store reported (the price the customer actually paid); the dashboard reflects the current product price.

src/components/reusable/RenewalPricing.mdx

@@ -0,0 +1,15 @@
+---
+no_index: true
+---
+
+### Retroactive setting changes
+
+When you change your reduced commission status in Adapty with a retroactive effective date, the new commission rate appears across Adapty's data on different schedules:
+
+| Where the rate appears | What happens after you change the rate |
+| --- | --- |
+| Analytics dashboard (Revenue, Proceeds, MRR, ARR) | Adapty applies the new rate within 24 hours, when the daily recalculation runs. |
+| S3, GCS, and BigQuery exports | Adapty applies the new rate at the next scheduled export. |
+| Webhook events already delivered | Adapty cannot modify webhook events after delivery. They keep the old rate. |
+
+If your data warehouse stores revenue from webhook events, those records keep the old commission rate. To reconcile, retrieve the affected period from the analytics dashboard, or generate a fresh export to S3, GCS, or BigQuery.

src/components/reusable/RetroactiveSettingChanges.mdx

@@ -0,0 +1,9 @@
+---
+no_index: true
+---
+
+import Callout from '../Callout.astro';
+
+<Callout type="note">
+**Sandbox transactions are excluded from all analytics charts.** They still appear on individual profile pages and in the event feed.
+</Callout>

src/components/reusable/SandboxExclusion.mdx

@@ -15,7 +15,7 @@ Adapty users may encounter **discrepancies** when comparing similar sets of data
 
 ## Troubleshooting algorithm
 
-Most discrepancies between Adapty and other platforms are expected and normal. They occur because **different sources process the same data differently**. 
+Most discrepancies between Adapty and other platforms are expected and normal. They occur because **different sources process the same data differently**.
 
 Other times, they indicate an **issue with your Adapty configuration**.
 
@@ -31,7 +31,7 @@ After you identify where the data diverges, you can look into the following comm
 
 ## Issues with server notifications and RTDN
 
-Adapty does not receive the necessary event data if you didn't correctly configure the store connections. This particularly affects events that occur without direct user involvement — subscription renewals, billing issues, etc. 
+Adapty does not receive the necessary event data if you didn't correctly configure the store connections. This particularly affects events that occur without direct user involvement — subscription renewals, billing issues, etc.
 
 Complete the server-to-server configuration as soon as you can ([App Store](enable-app-store-server-notifications) | [Play Store](enable-real-time-developer-notifications-rtdn)) and [wait](#data-delays) for the stores to establish the connection.
 
@@ -43,13 +43,13 @@ You can [manually upload](importing-historical-data-to-adapty) the missing App S
 
 If some of your users run an older version of your app without the Adapty SDK, Adapty does not receive their data. For this reason the numbers of Adapty and other sources will diverge.
 
-### Integration issues 
+### Integration issues
 
 Some Adapty integrations (for example, Adjust or AppsFlyer) require additional application code to work. If you configure the Adapty dashboard, but do not update your application, the necessary data won't show up in Adapty.
 
 ### Missing historical data
 
-Adapty doesn't have access to your application's historical data, unless you [manually import](importing-historical-data-to-adapty) it. If a chart's [time range](controls-filters-grouping-compare-proceeds#time-ranges) starts before you integrated Adapty, and you didn't import historical data, its values will differ from other sources.
+Adapty doesn't have access to your application's historical data, unless you [manually import](importing-historical-data-to-adapty) it. If a chart's [time range](controls-filters-grouping-compare-proceeds#set-the-date-range) starts before you integrated Adapty, and you didn't import historical data, its values will differ from other sources.
 
 ## Data delays
 
@@ -81,7 +81,7 @@ Each "month" in the calendar consists of **4 or 5 weeks**, and **may include day
 
 For example, the "January 2026" sales period begins on December 28th, 2025 — 4 days before the start of the calendar month. The estimated payment date for this period is March 5th.
 
-Do not compare data from Apple payout reports to calendar months. Instead, select a [custom date range](controls-filters-grouping-compare-proceeds#time-ranges) that corresponds to the necessary sales period.
+Do not compare data from Apple payout reports to calendar months. Instead, select a [custom date range](controls-filters-grouping-compare-proceeds#set-the-date-range) that corresponds to the necessary sales period.
 
 #### Transaction dates
 
@@ -91,7 +91,7 @@ Some services (for example, AppsFlyer) may apply [cohort](analytics-cohorts) rul
 
 ### Fees and taxes
 
-Depending on the [setting](controls-filters-grouping-compare-proceeds#store-commission-and-taxes), Adapty charts can display your **gross revenue**, **revenue after store commission**, or **revenue after store commission and tax**. 
+Depending on the [setting](controls-filters-grouping-compare-proceeds#display-gross-or-net-revenue), Adapty charts can display your **gross revenue**, **revenue after store commission**, or **revenue after store commission and tax**.
 
 <ZoomImage id="revenue-types.webp" width="500px" />
 
@@ -115,9 +115,9 @@ Adapty can only register an installation when a user launches the application, r
 
 ## Country and store
 
-To ensure accurate reporting, Adapty [may infer](controls-filters-grouping-compare-proceeds#filtering-and-grouping) the user's country from their IP. Stores always attribute downloads and purchases to a specific app store.
+To ensure accurate reporting, Adapty [may infer](controls-filters-grouping-compare-proceeds#filter-and-group-data) the user's country from their IP. Stores always attribute downloads and purchases to a specific app store.
 
-If you need to clearly distinguish between the two, you can [create a new user segment](segments) with the `Country by store account` attribute, and [filter analytics by segment](controls-filters-grouping-compare-proceeds#filtering-and-grouping).
+If you need to clearly distinguish between the two, you can [create a new user segment](segments) with the `Country by store account` attribute, and [filter analytics by segment](controls-filters-grouping-compare-proceeds#filter-and-group-data).
 
 ## Product pricing
 
@@ -144,10 +144,10 @@ Different platforms may have different names for the same concept. Metrics relat
 
 Other metrics may differ in definition, as well:
 
-- **Subscriptions**: 
+- **Subscriptions**:
         - Adapty does not count new trials as subscriptions. A [new subscription](reactivated-subscriptions) always starts with a financial transaction.
         - Other platforms, such as Google Play Console, may count **each trial as a new subscription**, even before the first payment was made.
-- **Retention**: 
-        - Adapty measures retention based on the number of subscription renewals. 
+- **Retention**:
+        - Adapty measures retention based on the number of subscription renewals.
         - App Store Connect considers a user retained if they open the application on the specified day. A user without a subscription will count, but the subscribed user who didn't open the app on that day won't.
         - Google Play Console's "Retained Installers" metric measures retention based on the number of days the application remains installed on the user's device. Users that don't open the application count towards this metric.

src/content/docs/guides/analytics/discrepancies-and-troubleshooting.mdx

@@ -18,22 +18,22 @@ This article describes how Adapty Analytics works: what data it displays, where
 
         Adapty offers [close to real-time](#data-processing) analytics.
 
-- **Advanced metrics**: App stores display basic metrics such as downloads, revenue, and retention rates. 
-        
+- **Advanced metrics**: App stores display basic metrics such as downloads, revenue, and retention rates.
+
         Adapty also calculates advanced metrics, such as recurring revenue or average revenue per user. Dedicated sections analyze subscription issues: user churn, billing failures, etc. See the [Metric comparison table](metric-comparison-table) article for a full list.
 
 - **Predictions**: Adapty uses advanced machine learning algorithms to [predict future LTV and revenue](predicted-ltv-and-revenue).
-    
+
 
 ## Data and its sources
 
 Adapty Analytics processes the following data into [charts and graphs](analytics):
 
-- [Subscription events](events) such as <InlineTooltip tooltip="purchases and cancellations"> Open the [event feed](event-feed) to see your users' subscription events in real time.</InlineTooltip>. 
+- [Subscription events](events) generated throughout the user lifecycle — trial starts, purchases, renewals, cancellations, billing failures, refunds. Adapty aggregates these into the [analytics charts](analytics) and forwards them in real time to [webhooks](webhook), the [event feed](event-feed), and [event-based integrations](analytics-integration).
 - [Transaction data](revenue) — revenue, refunds, the buyer's country, etc.
 - **Application data** such as the number of installations or [paywall interactions](paywalls).
 - [Attribution data for transactions](attribution-integration): traffic sources and ad campaigns.
- 
+
 This data comes from the following sources:
 
 - The <InlineTooltip tooltip="Adapty SDK">[iOS](ios-sdk-overview), [Android](android-sdk-overview), [React Native](react-native-sdk-overview), [Flutter](flutter-sdk-overview), [Unity](unity-sdk-overview), [Kotlin Multiplatform](kmp-sdk-overview), [Capacitor](capacitor-sdk-overview) </InlineTooltip> reports user behavior data from inside the app. If Adapty handles your purchase flow management, the SDK shares first-hand information about the purchase events. If you use the [observer mode](observer-vs-full-mode), the SDK receives [event reports](report-transactions-observer-mode) that you set up manually.
@@ -51,16 +51,19 @@ Likewise, you can [export](analytics-integration) analytics data to third-party
 
 ## Data processing
 
-Adapty offers close to real-time analytics, which allows users to quickly react to changes in key metrics. 
+Adapty offers close to real-time analytics, which allows users to quickly react to changes in key metrics.
 
-- For store events, the processing delay is 15 to 30 minutes long. 
-- Data from third-party sources updates in near real time. The exact delay depends on the platform and infrastructure conditions.
+- **Analytics charts**: data appears with a **15–30 minute delay** after a transaction occurs. Adapty needs this time to validate the transaction, apply commissions and taxes, and aggregate the data.
+- **[Event feed](event-feed)**: updates in real time, as soon as the stores deliver an event.
+- **[Webhooks](webhook) and event-based integrations** (AppsFlyer, Branch, etc.): Adapty forwards events as they occur — the 15–30 minute analytics delay does not apply. The receiving service may introduce its own processing time.
 
-## Tax and commission logic
+## Commissions and taxes
 
-When you view revenue-related charts, Adapty gives you the option to choose between **Gross revenue**, **Revenue after commissions**, and **Revenue after commissions and taxes**. 
+When you view revenue-related charts, you can choose between **Gross revenue**, **Revenue after commissions**, and **Revenue after commissions and taxes**.
 
-If your organization is enrolled in a reduced commission program, change your Adapty settings to modify commission rate calculations:
+### Commissions
+
+Stores deduct a commission from each transaction. If your organization is enrolled in a reduced commission program, change your Adapty settings to modify commission rate calculations:
 
 * [App Store Small Business Program](app-store-small-business-program)
 * Google's [reduced service fee program](google-reduced-service-fee)
@@ -70,14 +73,29 @@ The stores automatically report whether other factors reduce your transaction co
 * [Renewals for 1+ year long App Store subscriptions](https://developer.apple.com/app-store/subscriptions/) — 15% commission
 * Country-specific rates (for example, [21% for App Store apps distributed in Japan](https://developer.apple.com/support/app-distribution-in-japan/#business-terms))
 
-Adapty retrieves the applicable **tax rate** directly from the stores.
+### Taxes
+
+**Adapty does not calculate taxes.** Apple and Google determine the tax rate that applies to each transaction and report it back to Adapty, which displays the value as-is.
+
+The tax rate shown for a given transaction depends on:
+
+- The **buyer's billing country** and the local tax rate in effect there.
+- The **store's tax-handling rules**. In some jurisdictions, the store collects and remits tax on the developer's behalf; in others, the developer is responsible.
+- For App Store transactions, the **tax category** assigned to the app or in-app purchase (books, news, videos, etc.) — categories can be taxed at different rates depending on local rules.
+
+Tax rates can vary significantly between apps — and even between transactions within the same app — because of the mix of buyer countries, the stores' handling rules, and (for the App Store) the assigned tax category.
+
+For the authoritative rules, refer to the stores' official documentation:
+
+- [App Store: Understanding taxes](https://developer.apple.com/help/app-store-connect/making-payments-to-apple/understanding-taxes/)
+- [Google Play: Tax rates and VAT](https://support.google.com/googleplay/android-developer/answer/138000)
 
 ## Troubleshooting
 
 :::link
 Main article: [Discrepancies and Troubleshooting](discrepancies-and-troubleshooting)
 :::
 
-* A misconfigured or missing data source can negatively affect the entire analytics system. If you encounter data issues, make sure your integrations with stores and third-party platforms are configured and active. 
+* A misconfigured or missing data source can negatively affect the entire analytics system. If you encounter data issues, make sure your integrations with stores and third-party platforms are configured and active.
 
 * If you compare Adapty charts to other analytics platforms, you may notice discrepancies. This is expected behavior that may result from differences in data processing. Read the [discrepancies guide](discrepancies-and-troubleshooting) article to learn about common causes of data discrepancies.