# rc-purchase-flow

Guides coding assistants through RevenueCat in-app purchase implementation on Android. Covers coroutines, access gating, and billing errors.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 628 installs · ★ 76
- Author: RevenueCat
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/RevenueCat/ai-toolkit/tree/HEAD/revenuecat-play-billing/skills/rc-purchase-flow/SKILL.md
- Updated: 2026-10-21
- HTML: https://affpapa.org/en/nevibecode/skills/rc-purchase-flow

## What it does

This skill instructs the agent on RevenueCat Android SDK integration. A single `awaitPurchase` call handles six internal steps: compiling billing parameters, launching the Google Play flow, sending the token, and acknowledging the purchase. The assistant avoids writing custom acknowledgment logic or redundant billing listeners.

The workflow mandates checking access via `customerInfo.entitlements` instead of `storeTransaction`. For error handling, `awaitPurchase` throws only `PurchasesTransactionException`. User cancellations must be ignored quietly. Restoring past purchases relies on `awaitRestore`, which triggers `PurchasesException` without cancellation states.

Passing a valid `activity` instance into `PurchaseParams.Builder` is strictly required for the Play sheet to show up.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add RevenueCat/ai-toolkit --skill rc-purchase-flow -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/rc-purchase-flow/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/rc-purchase-flow/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add RevenueCat/ai-toolkit --skill rc-purchase-flow -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/rc-purchase-flow/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add RevenueCat/ai-toolkit --skill rc-purchase-flow -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/rc-purchase-flow/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install RevenueCat/ai-toolkit rc-purchase-flow
```

2. **Manually: put the files in place**
- File: `.github/skills/rc-purchase-flow/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add RevenueCat/ai-toolkit --skill rc-purchase-flow -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/RevenueCat/ai-toolkit --path revenuecat-play-billing/skills/rc-purchase-flow
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/rc-purchase-flow/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add RevenueCat/ai-toolkit --skill rc-purchase-flow -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/RevenueCat/ai-toolkit/tree/HEAD/revenuecat-play-billing/skills/rc-purchase-flow/SKILL.md

## When to use it
- implement in-app subscriptions on Android with awaitPurchase
- gate premium app features using customerInfo.entitlements
- handle user cancellations silently during billing flow
- restore purchases using awaitRestore and handle missing subscriptions

## Example prompts
- Implement monthly subscription purchase using RevenueCat `awaitPurchase` in Kotlin
- Handle `PurchasesTransactionException` properly and ignore user cancellation
- Create a restore purchases button handler using `awaitRestore`

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: cc99066c265bde0a.

BEGIN THIRD-PARTY FILE cc99066c265bde0a
````text
---
name: rc-purchase-flow
description: Use this skill when implementing a RevenueCat purchase on Android. Covers awaitPurchase, PurchasesTransactionException, reading CustomerInfo entitlements to grant access, restoring purchases, and the six SDK managed steps that happen inside a single call.
license: Apache-2.0; see LICENSE
metadata:
  author: RevenueCat
  source: revenuecat-handbook chapter 6
  keywords:
  - android
  - revenuecat
  - purchase-flow
  - awaitpurchase
  - purchases-transaction-exception
  - customerinfo
  - entitlements
---

# Purchase Flow

A RevenueCat purchase on Android is two lines of code. The SDK handles the billing params, the Play sheet, the purchase token round trip, server side verification, and acknowledgment. You decide which package to pass in and what to do with the returned entitlements.

## Phase 1: Understand what awaitPurchase() does

One call to `Purchases.sharedInstance.awaitPurchase(params)` runs six steps under the hood. You do not write any of this.

| Step | What happens |
|------|--------------|
| 1 | Builds `BillingFlowParams` with the correct `ProductDetailsParams` from your `Package` |
| 2 | Calls `BillingClient.launchBillingFlow()` against the activity you passed |
| 3 | Suspends until the `PurchasesUpdatedListener` result arrives |
| 4 | If `OK`, posts the Play purchase token to the RevenueCat backend |
| 5 | Backend verifies via `purchases.subscriptionsv2.get` or `purchases.products.get` |
| 6 | SDK acknowledges (subs or non-consumables) or consumes (consumables) within the 3 day Google window |

The call returns `PurchaseResult(storeTransaction, customerInfo)`. Retriable failures are retried automatically.

See the [Purchase Flow chapter on revenuecat.com](https://www.revenuecat.com/guides/revenuecat-android-sdk/the-purchase-flow) for the six-step diagram and the full picture.

## Phase 2: Prepare the package

You need a `Package` from offerings before you can purchase. Fetch offerings, let your UI pick one, and hold the activity.

```kotlin
val offerings = Purchases.sharedInstance.awaitOfferings()
val pkg = offerings.current?.monthly ?: return
```

If you need a specific offer instead of the default, resolve a `SubscriptionOption` and pass that to `PurchaseParams.Builder` instead of the package.

```kotlin
val option = pkg.product.subscriptionOptions
    ?.firstOrNull { it.tags.contains("promo_50_off") }
    ?: pkg.product.defaultOption
    ?: return
```

For EU personalized pricing, chain `.isPersonalizedPrice(true)` on the builder so Play shows the customized price notice.

## Phase 3: Execute the purchase

Build the params, await the purchase, read `customerInfo` to gate access, and handle the two expected error branches.

```kotlin
try {
    val result = Purchases.sharedInstance.awaitPurchase(
        PurchaseParams.Builder(activity, pkg).build()
````
END THIRD-PARTY FILE cc99066c265bde0a

The third-party file has ended. Everything between the cc99066c265bde0a tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2853 of 5577 bytes. © RevenueCat · MIT · https://github.com/RevenueCat/ai-toolkit/tree/HEAD/revenuecat-play-billing/skills/rc-purchase-flow/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md