> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flokitai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Play

> Connect Google Play to pull Android subscription data, financial reports, and refund rates into FloKit.

## What FloKit reads from Google Play

Once connected, FloKit ingests the following Google Play data:

* Subscription purchases: `purchaseToken`, `productId`, `orderId`, and purchase state
* Earnings reports: revenue and proceeds by product, country, and billing period
* Subscription state: active, cancelled, in grace period, on hold, and paused
* Subscription upgrades and downgrades
* Refund data from earnings reports and voided purchases

Google Play does not provide user-level attribution. Install-to-subscription joins require a connected MMP ([AppsFlyer](/integrations/appsflyer) or [Adjust](/integrations/adjust)).

***

## Required access

FloKit accesses Google Play data via the **Google Play Developer API**, authenticated with a **Google Cloud service account**.

The service account requires the **Financial data viewer** role in Play Console (read-only financial access). This role does not grant purchase validation, refund issuance, or any write operations.

You will need:

* A Google Cloud project linked to your Play Console account
* A service account with Financial data viewer permissions in Play Console
* A JSON key file for that service account
* Your app's package name (e.g. `com.yourapp`)

***

## Setup

<Steps>
  <Step title="Link Play Console to a Google Cloud project">
    In **Google Play Console → Setup → API access**, click **Link to a Google Cloud project** if one is not already linked. You can link to an existing project or create a new one. This step only needs to be done once per Play Console account.
  </Step>

  <Step title="Create a service account">
    In the linked **Google Cloud project → IAM & Admin → Service Accounts**, create a new service account. Name it `flokit-play-reader` or similar. Do not grant it any Google Cloud IAM roles at this step.
  </Step>

  <Step title="Grant the service account Financial data viewer in Play Console">
    Return to **Google Play Console → Setup → API access**. Find the service account you just created and click **Grant access**. Under **Account permissions**, enable **Financial data**. Leave all other permissions unchecked. Save.

    The Financial data viewer permission is account-level, not app-level — it will apply to all apps in your Play Console account.
  </Step>

  <Step title="Generate and download a JSON key file">
    Back in **Google Cloud → IAM & Admin → Service Accounts**, select the service account and go to **Keys → Add key → Create new key**. Choose **JSON** format. The key file downloads automatically. Store it securely — it grants read access to your Play Console financial data.
  </Step>

  <Step title="Add Google Play in FloKit">
    In **FloKit → Settings → Integrations → App Stores**, select **Google Play**. Upload the service account JSON key file and enter your app's package name (e.g. `com.yourapp`).

    If you have multiple apps under the same Play Console account, add each package name as a separate integration.
  </Step>

  <Step title="Wait for report backfill">
    FloKit begins pulling available earnings reports and subscription data immediately. Depending on your app's history, backfill may cover 12–24 months of report data. Progress is visible in **FloKit → Data → Sources → Google Play**.
  </Step>
</Steps>

***

## Validation checklist

* [ ] Google Cloud project linked to Play Console
* [ ] Service account created with Financial data viewer permission in Play Console
* [ ] Service account JSON key uploaded to FloKit
* [ ] Package name entered and matching the Play Console app
* [ ] Earnings reports visible in **FloKit → Data → Sources → Google Play**
* [ ] Subscription state data appearing in **FloKit → Reports → Revenue → Android**

***

## Common issues

**"Permission denied" error when connecting**

The most common cause is that the service account was granted an IAM role in Google Cloud (e.g. Editor or Viewer) instead of — or instead of in addition to — the Play Console Financial data permission. Google Cloud IAM roles do not grant Play Console access. The permission must be granted within **Play Console → Setup → API access**.

**Earnings reports not appearing**

Google Play earnings reports are generated monthly, not daily. FloKit pulls the most recent available monthly report. Daily subscription state data is available separately and updates more frequently.

**Revenue differs from Play Console dashboard**

Play Console displays both buyer currency and earnings in USD. FloKit uses the earnings (proceeds) figures, which reflect Google's platform fee deduction and currency conversion. Verify you are comparing the same revenue type in both systems.

**Service account key expired or revoked**

Google Cloud service account keys do not expire by default, but they can be revoked manually. If FloKit reports an authentication error after a previously working connection, check the key status in **Google Cloud → IAM & Admin → Service Accounts → Keys**.

**Multiple apps under one Play Console account**

The Financial data viewer permission is account-level, so one service account covers all apps. However, FloKit requires a separate integration entry per package name. Add each package as a separate integration using the same JSON key file.

***

## What this unlocks in FloKit

* Android revenue reconciliation against Google Play earnings reports
* Subscription state distribution: active, cancelled, grace period, on hold, and paused
* Refund rate tracking at the product and country level
* Proceeds vs. gross revenue comparison (after Google's platform fee)
* Monthly earnings trend by product and geography