사용 방법
- 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
- 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
- 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
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.configurebehavior? - What is the return type and signature of
awaitPurchase,awaitOfferings,awaitCustomerInfo,awaitRestore,awaitLogIn,awaitLogOut? - How do I read offering, package, product, entitlement fields?
- Which
PurchasesErrorCodeshould 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, fetchOfferings, 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
// 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)
// 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
)// 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()
)// 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
val offerings: Offerings
offerings.current // current Offering
offerings.all // Map<String, Offering>
offerings["my_offering"] // by identifier
offerings.getCurrentOfferingForPlacement("placement_id") // targetingval offering: Offering
offering.identifier
offering.monthly // Package? (shortcut)
offering.annual // Package?
offering.weekly // Package?
offering.availablePackages // List<Package>
offering.metadata // Map<String, Any>val pkg: Package
pkg.identifier // "$rc_monthly", "$rc_annual", custom
pkg.packageType // PackageType enum
pkg.product // StoreProduct
pkg.webCheckoutURL // URL? (RevenueCat web billing)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 offerEntitlements
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 managementval 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 // VerificationResultError Handling
// 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
}// 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.ConfigurationErrorListeners
// 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.
| Endpoint | Use |
|---|---|
GET /v1/subscribers/{app_user_id} | Read a subscriber |
POST /v1/subscribers/{app_user_id}/entitlements/{entitlement_id}/promotional | Grant promotional access (end_time_ms) |
POST /v1/subscribers/{app_user_id}/entitlements/{entitlement_id}/revoke_promotionals | Revoke promotional access |
POST /v1/subscribers/{app_user_id}/attributes | Set subscriber attributes |
POST /v1/subscribers/{app_user_id}/subscriptions/{product_identifier}/defer | Defer a Google Play subscription |
POST /v1/subscribers/{app_user_id}/subscriptions/{product_identifier}/revoke | Refund and revoke a Google Play subscription |
POST /v1/subscribers/{app_user_id}/transactions/{store_transaction_identifier}/refund | Refund 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.
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.
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.
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.
val fresh = Purchases.sharedInstance.awaitCustomerInfo(
fetchPolicy = CacheFetchPolicy.FETCH_CURRENT
)Log in an identified user and detect first login.
val login = Purchases.sharedInstance.awaitLogIn("user_123")
val isNewAlias = login.created
val info = login.customerInfoReact to background entitlement changes.
Purchases.sharedInstance.updatedCustomerInfoListener =
UpdatedCustomerInfoListener { info ->
val active = info.entitlements["pro_access"]?.isActive == true
uiState.update { it.copy(hasPro = active) }
}References
- Related skills in this repo: rc-configuring-the-sdk, rc-purchase-flow, rc-error-handling, rc-subscription-states, rc-backend, rc-webhooks.