revenuecat/ai-toolkit

rc-revenuecat-api-quick-reference

Use this skill as a quick reference for the RevenueCat Android SDK 11.x and REST API.

查看源码

使用方法

  1. 复制安装命令,在自己的智能体环境安装前先检查源码包。
  2. 从原始文档核对所需工具、凭据和支持的宿主。
  3. 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/revenuecat/ai-toolkit --skill rc-revenuecat-api-quick-reference

开始前需了解

  • 安装不包含模型订阅、API 额度或访问文件的权限。
  • 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
仓库原始内容

按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。

RevenueCat API Quick Reference

Phase 0: Intent

Use this skill when you need a fast lookup of a RevenueCat API surface while writing Android code or server logic. Typical questions you answer from here:

  • Which builder option controls a given Purchases.configure behavior?
  • What is the return type and signature of awaitPurchase, awaitOfferings, awaitCustomerInfo, awaitRestore, awaitLogIn, awaitLogOut?
  • How do I read offering, package, product, entitlement fields?
  • Which PurchasesErrorCode should I branch on?
  • Which listener callback do I register for customer info updates?

Do not use this skill as a deep tutorial. Reach for the feature-specific skills (purchase flow, configuring the SDK, error handling, subscription states) when you need step-by-step guidance or design rationale.

Phase 1: Locate

Decide SDK surface vs REST surface before you search the tables.

Route to the SDK (client side, Android app code):

  • Code runs inside the Android app, in an Activity, ViewModel, or background worker bundled with your app.
  • You need to launch a purchase, restore purchases, read cached CustomerInfo, fetch Offerings, identify or log out a user, or listen for updates.
  • You want entitlement gating in the UI.

Route to the REST API (server side):

  • Code runs on your backend, in a webhook handler, in an admin tool, or in a scheduled job.
  • You need to grant or revoke a promotional entitlement, override a subscription, look up a subscriber from another service, refund, or deliver events to another system.
  • You are integrating with a system that cannot embed the SDK.

The tables in this skill cover the Android SDK 11.x surface from appendix A (the same calls compile against 10.27.1), plus a short REST endpoint index. For full REST paths, authentication, and payloads, see the full appendix on revenuecat.com together with the backend and webhooks skills, and treat this file as the SDK index.

Phase 2: Reference Tables

SDK Initialization

kotlin
// Minimum setup
Purchases.configure(
    PurchasesConfiguration.Builder(context, "api_key").build()
)

// Full options
Purchases.configure(
    PurchasesConfiguration.Builder(context, "api_key")
        .appUserID("user_id")                    // null for anonymous
        .showInAppMessagesAutomatically(true)    // default: true
        .purchasesAreCompletedBy(PurchasesAreCompletedBy.REVENUECAT) // default
        .entitlementVerificationMode(EntitlementVerificationMode.INFORMATIONAL)
        .diagnosticsEnabled(false)               // default: false
        .pendingTransactionsForPrepaidPlansEnabled(false) // default: false
        .build()
)

Purchases.logLevel = LogLevel.DEBUG // before configure()

Core Operations (Coroutine)

kotlin
// Fetch offerings
val offerings: Offerings = Purchases.sharedInstance.awaitOfferings()

// Fetch specific products
val products: List<StoreProduct> = Purchases.sharedInstance.awaitGetProducts(
    listOf("product_id"),
    type = ProductType.INAPP // or SUBS, or null for all
)
kotlin
// Purchase
val result: PurchaseResult = Purchases.sharedInstance.awaitPurchase(
    PurchaseParams.Builder(activity, packageOrStoreProductOrSubscriptionOption).build()
)

// Purchase upgrade/downgrade
val result = Purchases.sharedInstance.awaitPurchase(
    PurchaseParams.Builder(activity, newPackage)
        .oldProductId("old_product_id")
        .replacementMode(StoreReplacementMode.WITH_TIME_PRORATION)
        .build()
)
kotlin
// Get customer info
val customerInfo: CustomerInfo = Purchases.sharedInstance.awaitCustomerInfo()
val fresh: CustomerInfo = Purchases.sharedInstance.awaitCustomerInfo(
    fetchPolicy = CacheFetchPolicy.FETCH_CURRENT
)

// Restore
val customerInfo: CustomerInfo = Purchases.sharedInstance.awaitRestore()

// Log in / log out
val loginResult: LogInResult = Purchases.sharedInstance.awaitLogIn("user_id")
// loginResult.customerInfo, loginResult.created (Boolean)
val customerInfo: CustomerInfo = Purchases.sharedInstance.awaitLogOut()

Offerings Structure

kotlin
val offerings: Offerings
offerings.current          // current Offering
offerings.all              // Map<String, Offering>
offerings["my_offering"]   // by identifier
offerings.getCurrentOfferingForPlacement("placement_id") // targeting
kotlin
val offering: Offering
offering.identifier
offering.monthly           // Package? (shortcut)
offering.annual            // Package?
offering.weekly            // Package?
offering.availablePackages // List<Package>
offering.metadata          // Map<String, Any>
kotlin
val pkg: Package
pkg.identifier             // "$rc_monthly", "$rc_annual", custom
pkg.packageType            // PackageType enum
pkg.product                // StoreProduct
pkg.webCheckoutURL         // URL? (RevenueCat web billing)
kotlin
val product: StoreProduct
product.id                 // "productId" (INAPP) or "productId:basePlanId" (SUBS); product.googleProduct?.productId for the bare Play ID
product.title
product.description
product.price.formatted    // "$4.99"
product.price.amountMicros
product.price.currencyCode
product.period             // Period? (null for INAPP); use period.iso8601 for "P1M", "P1Y", etc.
product.subscriptionOptions // List<SubscriptionOption>? (null for INAPP)
product.defaultOption       // SubscriptionOption? best available offer

Entitlements

kotlin
val customerInfo: CustomerInfo
customerInfo.entitlements.active         // Map<String, EntitlementInfo> (active only)
customerInfo.entitlements.all            // Map<String, EntitlementInfo> (all)
customerInfo.entitlements["pro_access"]  // EntitlementInfo?
customerInfo.activeSubscriptions         // Set<String> of "productId:basePlanId"
customerInfo.nonSubscriptionTransactions // List<Transaction>
customerInfo.managementURL               // Uri? to Play Store management
kotlin
val entitlement: EntitlementInfo
entitlement.isActive                     // Boolean, the main access gate
entitlement.willRenew                    // false if canceled
entitlement.expirationDate               // Date? (null for lifetime)
entitlement.periodType                   // NORMAL, TRIAL, INTRO, PREPAID
entitlement.billingIssueDetectedAt       // Date? (non null = grace/hold, or ended unrecovered)
entitlement.unsubscribeDetectedAt        // Date? (non null = canceled)
entitlement.store                        // PLAY_STORE, APP_STORE, etc.
entitlement.productIdentifier            // subscription product ID
entitlement.productPlanIdentifier        // base plan ID (Google only)
entitlement.verification                 // VerificationResult

Error Handling

kotlin
// Purchase errors
try {
    Purchases.sharedInstance.awaitPurchase(params)
} catch (e: PurchasesTransactionException) {
    e.userCancelled     // Boolean
    e.error.code        // PurchasesErrorCode
    e.error.message     // description string
}

// Other errors
try {
    Purchases.sharedInstance.awaitOfferings()
} catch (e: PurchasesException) {
    e.error.code        // PurchasesErrorCode
}
kotlin
// Key error codes
PurchasesErrorCode.PurchaseCancelledError
PurchasesErrorCode.ProductAlreadyPurchasedError
PurchasesErrorCode.PaymentPendingError
PurchasesErrorCode.NetworkError
PurchasesErrorCode.StoreProblemError
PurchasesErrorCode.PurchaseNotAllowedError // also a system blocked Play Store since 11.0.0
PurchasesErrorCode.ProductNotAvailableForPurchaseError
PurchasesErrorCode.ConfigurationError

Listeners

kotlin
// CustomerInfo updates
Purchases.sharedInstance.updatedCustomerInfoListener =
    UpdatedCustomerInfoListener { customerInfo -> }

// Show in-app messages manually
Purchases.sharedInstance.showInAppMessagesIfNeeded(activity)

Most Used REST Endpoints

All with Authorization: Bearer <secret key> from your backend only, never the client.

EndpointUse
GET /v1/subscribers/{app_user_id}Read a subscriber
POST /v1/subscribers/{app_user_id}/entitlements/{entitlement_id}/promotionalGrant promotional access (end_time_ms)
POST /v1/subscribers/{app_user_id}/entitlements/{entitlement_id}/revoke_promotionalsRevoke promotional access
POST /v1/subscribers/{app_user_id}/attributesSet subscriber attributes
POST /v1/subscribers/{app_user_id}/subscriptions/{product_identifier}/deferDefer a Google Play subscription
POST /v1/subscribers/{app_user_id}/subscriptions/{product_identifier}/revokeRefund and revoke a Google Play subscription
POST /v1/subscribers/{app_user_id}/transactions/{store_transaction_identifier}/refundRefund and revoke a Google Play purchase (subscription or one time, last 365 days)

See rc-backend and rc-webhooks for request and response payloads.

Phase 3: Typical Snippets

Gate a feature on an entitlement.

kotlin
val info = Purchases.sharedInstance.awaitCustomerInfo()
val hasPro = info.entitlements["pro_access"]?.isActive == true
if (hasPro) unlockFeature() else showPaywall()

Buy the monthly package from the current offering.

kotlin
val current = Purchases.sharedInstance.awaitOfferings().current ?: return
val monthly = current.monthly ?: return
val result = Purchases.sharedInstance.awaitPurchase(
    PurchaseParams.Builder(activity, monthly).build()
)

Handle cancel vs real failure.

kotlin
try {
    Purchases.sharedInstance.awaitPurchase(params)
} catch (e: PurchasesTransactionException) {
    if (e.userCancelled) return
    when (e.error.code) {
        PurchasesErrorCode.PaymentPendingError -> showPendingUi()
        PurchasesErrorCode.NetworkError -> showRetry()
        else -> showGenericError(userFacingMessage(e.error)) // log e.error.message
    }
}

Force a fresh CustomerInfo fetch after a server side grant.

kotlin
val fresh = Purchases.sharedInstance.awaitCustomerInfo(
    fetchPolicy = CacheFetchPolicy.FETCH_CURRENT
)

Log in an identified user and detect first login.

kotlin
val login = Purchases.sharedInstance.awaitLogIn("user_123")
val isNewAlias = login.created
val info = login.customerInfo

React to background entitlement changes.

kotlin
Purchases.sharedInstance.updatedCustomerInfoListener =
    UpdatedCustomerInfoListener { info ->
        val active = info.entitlements["pro_access"]?.isActive == true
        uiState.update { it.copy(hasPro = active) }
    }

References

来自同一仓库

更多 Skills

全部 Skills
revenuecat
社区

create-revenuecat-project

Set up a complete RevenueCat project from scratch — creates apps, products, entitlements, offerings, and packages in the correct order. Use when the user wants to create a new RevenueCat project, configure in-app purchases, set up subscriptions or monetization, or bootstrap IAP infrastructure for iOS, Android, or Web.

1小时安装量
2
GitHub Stars
79
最近更新
11月17日
revenuecat
社区

rc-cancellations-pauses-winback

Use this skill when surfacing cancellation, pause, and winback state on Android with RevenueCat. Covers reading unsubscribeDetectedAt, billingIssueDetectedAt, pause state and resume date via SubscriptionInfo.autoResumeDate, showManageSubscriptions for the deep link, and the SUBSCRIPTIONPAUSED webhook.

1小时安装量
2
GitHub Stars
79
最近更新
11月17日
revenuecat
社区

rc-configuring-the-sdk

Use this skill when adding and configuring the RevenueCat Android SDK (purchases-android, artifact com.revenuecat.purchases:purchases) in an app. Covers the Gradle dependency, Purchases.configure with PurchasesConfiguration, initial app user id strategy, and log level.

1小时安装量
2
GitHub Stars
79
最近更新
11月17日
revenuecat
社区

rc-plan-changes

Use this skill when implementing subscription upgrades, downgrades, and plan switches via RevenueCat on Android. Covers StoreReplacementMode, picking a replacement mode, and letting the SDK manage linkedPurchaseToken chaining.

1小时安装量
2
GitHub Stars
79
最近更新
11月17日