llms-full.txt

# OpenIAP Complete Reference

> OpenIAP: Unified cross-platform in-app purchase SDK
> Documentation: https://openiap.dev
> Quick Reference: https://openiap.dev/llms.txt
> GitHub: https://github.com/hyodotdev/openiap

## Table of Contents

1. Overview
2. Installation
3. Core API Reference
4. iOS-Specific APIs
5. Android-Specific APIs
6. Types & Data Structures
7. Events
8. Error Handling
9. Platform Usage Examples
10. Naming Conventions

---

# 1. Overview

OpenIAP is a standardized protocol for in-app purchases across all platforms.
One specification, consistent APIs, platform-specific optimizations.

**Supported Platforms:**
- React Native (react-native-iap) — npm
- Expo (expo-iap) — npm
- Flutter (flutter_inapp_purchase) — pub.dev
- Godot (godot-iap) — Godot Asset Library
- Kotlin Multiplatform (kmp-iap) — Maven Central
- iOS Native (openiap-apple) — SPM / CocoaPods
- Android Native (openiap-google) — Maven Central

**Current Versions:**
- react-native-iap: 14.7.20
- expo-iap: 3.4.13
- flutter_inapp_purchase: 8.2.10
- godot-iap: 1.2.9
- kmp-iap: 1.3.8
- openiap-apple: 1.3.15
- openiap-google: 1.3.28

---

# 2. Installation

## React Native
```bash
npm install react-native-iap
# or
yarn add react-native-iap
```
- iOS: StoreKit 2, requires iOS 15.0+
- Android: Google Play Billing 8.0+, compileSdkVersion 34+
- Uses Nitro Modules bridge

## Expo
```bash
npx expo install expo-iap
```
- Works with managed and bare workflows
- iOS: Set `"ios": { "deploymentTarget": "15.0" }` in app.json
- Android: Google Play Billing 8.0+

## Flutter
```bash
flutter pub add flutter_inapp_purchase
```
- iOS: Requires iOS 15.0+
- Android: minSdkVersion 21+

## Godot
- Download from Godot Asset Library or GitHub Release
- Extract to `addons/godot-iap/`
- Enable in Project Settings → Plugins
- Requires Godot 4.x

## Kotlin Multiplatform
```kotlin
// build.gradle.kts
dependencies {
    implementation("io.github.hyochan.kmpiap:library:1.3.8")
}
```

## iOS Native
```swift
// Swift Package Manager
.package(url: "https://github.com/hyodotdev/openiap.git", from: "1.3.15")
```
```ruby
# CocoaPods
pod 'openiap', '~> 1.3'
```

## Android Native
```kotlin
implementation("io.github.hyochan.openiap:openiap-google:1.3.28")
```

---

# 3. Core API Reference

## Connection Management

### initConnection(config?: InitConnectionConfig): Promise<boolean>
Initialize connection to store service. Must be called before any IAP operations.

Parameters:
- config.alternativeBillingAndroid?: 'none' | 'user-choice' | 'alternative-only'
  - 'none': Standard Google Play (default)
  - 'user-choice': User can select billing method
  - 'alternative-only': Alternative billing only

Returns: boolean indicating success

### endConnection(): Promise<boolean>
Close store service connection. Call on app close or component unmount.

---

## Product Management

### fetchProducts(params: ProductRequest): Promise<Product[]>
Retrieve product details from the store.

Parameters:
- skus: string[] — Product IDs to fetch
- type?: 'inapp' | 'subs' | 'all' (defaults to 'inapp')

Returns: Product[] with platform-specific fields

### getAvailablePurchases(options?: PurchaseOptions): Promise<Purchase[]>
Get user's unfinished purchases and active subscriptions.

Parameters (optional):
- alsoPublishToEventListenerIOS?: boolean
- onlyIncludeActiveItemsIOS?: boolean

---

## Purchase Management

### requestPurchase(props: RequestPurchaseProps): Promise<Purchase | void>
Initiate purchase flow. Event-based — results delivered via purchaseUpdatedListener.

Parameters:
- request: { apple: { sku: string }, google: { skus: string[] } }
- type: 'inapp' | 'subs'

### finishTransaction(purchase: Purchase, isConsumable?: boolean): Promise<void>
Complete purchase transaction. Must be called after receipt verification.

Parameters:
- purchase: Purchase object from event listener
- isConsumable?: boolean (default false)
  - true: Coins, gems (can be repurchased)
  - false: Premium unlocks, subscriptions

CRITICAL: Android purchases must be acknowledged within 3 days or are auto-refunded.

### restorePurchases(): Promise<void>
Restore completed transactions. Fires purchaseUpdatedListener for each restored purchase.

### getStorefront(): Promise<string>
Get user's storefront country code (ISO 3166-1 alpha-2, e.g., "US", "JP").

---

## Subscription Management

### getActiveSubscriptions(subscriptionIds?: string[]): Promise<ActiveSubscription[]>
Get all active subscriptions with renewal info. Optional filter by IDs.

### hasActiveSubscriptions(subscriptionIds?: string[]): Promise<boolean>
Quick check if user has any active subscriptions.

### deepLinkToSubscriptions(options: DeepLinkOptions): Promise<void>
Open native subscription management UI.

Parameters:
- skuAndroid: string (required on Android)
- packageNameAndroid: string (required on Android)

---

# 4. iOS-Specific APIs

## Transaction Management
- `clearTransactionIOS()` — Clear pending transactions from queue
- `getPendingTransactionsIOS()` — Retrieve all pending transactions
- `syncIOS()` — Force StoreKit sync (iOS 15+)

## Subscription
- `subscriptionStatusIOS(groupID: string)` — Detailed subscription status
- `showManageSubscriptionsIOS()` — In-app subscription management UI
- `isEligibleForIntroOfferIOS(groupID: string)` — Check intro offer eligibility

## Transaction Details
- `currentEntitlementIOS(sku: string)` — Current StoreKit 2 entitlement
- `latestTransactionIOS(sku: string)` — Most recent transaction
- `isTransactionVerifiedIOS(sku: string)` — Verify transaction signature
- `getTransactionJwsIOS(sku: string)` — JWS for server validation
- `getReceiptDataIOS()` — Base64-encoded receipt (legacy)

## Refunds & Redemption
- `beginRefundRequestIOS(sku: string)` — Initiate refund request
- `presentCodeRedemptionSheetIOS()` — Show promo code redemption
- `getAppTransactionIOS()` — Fetch app transaction (iOS 16+)

## External Purchase (iOS 17.4+)
- `showExternalPurchaseNoticeIOS(token: string)` — Show external purchase notice
- `getExternalPurchaseCustomLinkIOS(type: TokenType)` — Get external purchase token

---

# 5. Android-Specific APIs

## Purchase Acknowledgment
- `acknowledgePurchaseAndroid(purchaseToken: string)` — Acknowledge non-consumable/subscription
- `consumePurchaseAndroid(purchaseToken: string)` — Consume consumable purchase (auto-acknowledges)

## Alternative Billing Flow (3-step)
1. `checkAlternativeBillingAvailabilityAndroid()` — Check availability
2. `showAlternativeBillingDialogAndroid()` — Show user consent dialog
3. `createAlternativeBillingTokenAndroid()` — Create token for Google Play reporting

## Billing Programs
- `isBillingProgramAvailableAsync(program: BillingProgramAndroid)` — Check program availability
- `createBillingProgramReportingDetailsAsync(program: BillingProgramAndroid)` — Get reporting details

---

# 6. Types & Data Structures

## Purchase

### Common Fields
- id: string — Purchase identifier
- productId: string — Product SKU
- ids?: string[] — Array of SKUs for bundled purchases
- transactionDate: number — Epoch milliseconds
- purchaseToken: string — JWS (iOS) or Play token (Android)
- store: 'apple' | 'google' | 'horizon'
- quantity: number
- purchaseState: PurchaseState
- isAutoRenewing: boolean
- currentPlanId: string

### PurchaseIOS Additional Fields
- quantityIOS: number
- originalTransactionDateIOS: number
- originalTransactionIdentifierIOS: string
- appAccountToken: string
- expirationDateIOS: number
- webOrderLineItemIdIOS: string
- environmentIOS: 'Sandbox' | 'Production'
- storefrontCountryCodeIOS: string

### PurchaseAndroid Additional Fields
- orderId: string
- packageName: string
- purchaseTime: number
- purchaseState: 'pending' | 'purchased' | 'unknown'
- autoRenewingAndroid: boolean
- acknowledgementState: 'unacknowledged' | 'acknowledged'
- obfuscatedAccountIdAndroid: string
- obfuscatedProfileIdAndroid: string

## Product

### Common Fields
- id: string — SKU
- title: string — Display name
- description: string — Full description
- localizedPrice: string — Formatted price (e.g., "$9.99")
- priceAmount: number — Numeric price value
- currency: string — ISO 4217 currency code
- type: ProductType ('inapp' | 'subs')
- platform: 'ios' | 'android'

### Subscription Product (extends Product)
- subscriptionPeriod: string — Duration (e.g., "P1M" = 1 month)
- introductoryPrice?: string
- introductoryPriceAmount?: number
- introductoryPricePeriod?: string
- introductoryPriceNumberOfPeriods?: number
- introductoryPaymentMode?: PaymentMode
- freeTrialPeriod?: string

### ActiveSubscription
- productId: string
- isActive: boolean
- expirationDateIOS: number
- autoRenewingAndroid: boolean
- transactionId: string
- purchaseToken: string
- transactionDate: number
- basePlanIdAndroid: string
- currentPlanId: string
- renewalInfoIOS: { willAutoRenew, pendingUpgradeProductId, renewalDate, expirationReason }

## Enums

### ProductType
- InApp — One-time purchase
- Subs — Subscription

### ProductQueryType
- InApp — Fetch in-app products only
- Subs — Fetch subscriptions only
- All — Fetch all products

### PurchaseState
- Pending
- Purchased
- Unknown

### IapStore
- unknown, apple, google, horizon

### PaymentMode
- FreeTrial, PayAsYouGo, PayUpFront

### SubscriptionPeriodUnit
- Day, Week, Month, Year

### BillingProgramAndroid
- UserChoice, ExternalContent, ExternalOffers, ExternalPayments

---

# 7. Events

## Event Types

### purchaseUpdatedListener(callback: (purchase: Purchase) => void): Subscription
Fires when purchase succeeds or pending purchase completes.
Handle: Validate receipt → Grant entitlement → finishTransaction()

### purchaseErrorListener(callback: (error: PurchaseError) => void): Subscription
Fires on purchase failure or user cancellation.
Handle based on error code.

### promotedProductIOS(callback: (productId: string) => void): Subscription
iOS promoted product action (iOS 11+). Triggered from App Store promotions.

### userChoiceBillingAndroid(callback: (details) => void): Subscription
User selected alternative billing method (Android 7.0+).

### developerProvidedBillingAndroid(callback: (details) => void): Subscription
User selected developer-provided billing (Android 8.3.0+).

---

# 8. Error Handling

## Error Structure
```
PurchaseError {
  code: ErrorCode       // Enum value (kebab-case string)
  message: string       // Human-readable message
  productId?: string    // Related product
  responseCode?: number // Platform-specific code
  debugMessage?: string // Additional debug info
}
```

## Error Codes (ErrorCode enum)

### User Action Errors
- user-cancelled — User cancelled purchase flow
- user-error — User account error
- deferred-payment — Payment deferred (family approval)
- interrupted — Purchase flow interrupted

### Product Errors
- item-unavailable — Product not available in store
- sku-not-found — SKU not found
- sku-offer-mismatch — SKU offer ID mismatch
- query-product — Failed to query product details
- already-owned — Item already owned
- item-not-owned — Item not owned

### Network & Service Errors
- network-error — No network connection
- service-error — Store service error
- remote-error — Remote server error
- init-connection — Failed to initialize connection
- service-disconnected — Store service disconnected
- connection-closed — Connection closed
- iap-not-available — IAP service not available
- billing-unavailable — Billing service unavailable
- feature-not-supported — Feature not supported
- sync-error — Synchronization error

### Validation Errors
- purchase-verification-failed — Purchase verification failed
- purchase-verification-finished — Verification already completed
- purchase-verification-finish-failed — Failed to finish verification
- transaction-validation-failed — Transaction validation failed
- empty-sku-list — Empty SKU list provided
- duplicate-purchase — Duplicate purchase update detected (use restorePurchases to recover)

### General
- not-prepared — Store not initialized
- developer-error — Invalid API usage
- unknown — Unexpected error

## Retry Strategy (Built-in)
- NetworkError: Exponential backoff (2^n seconds)
- ServiceError: Linear backoff (n * 5 seconds)
- RemoteError: Fixed delay (10 seconds)
- ConnectionClosed: Reinitialize and retry
- UserCancelled, AlreadyOwned: No retry

## Helper Functions
- `isUserCancelledError(error)` — Check if user cancellation
- `getUserFriendlyErrorMessage(error)` — Get display-safe message

---

# 9. Platform Usage Examples

## TypeScript (React Native)

```typescript
import {
  initConnection,
  endConnection,
  fetchProducts,
  requestPurchase,
  finishTransaction,
  purchaseUpdatedListener,
  purchaseErrorListener,
  ErrorCode,
  isUserCancelledError,
} from 'react-native-iap';

// Initialize
await initConnection();

// Fetch products
const products = await fetchProducts({ skus: ['premium', 'coins_100'] });

// Listen for events
const purchaseSub = purchaseUpdatedListener(async (purchase) => {
  // Validate on server, then:
  await finishTransaction(purchase, purchase.productId === 'coins_100');
});

const errorSub = purchaseErrorListener((error) => {
  if (isUserCancelledError(error)) return;
  console.error(error.code, error.message);
});

// Purchase
await requestPurchase({
  request: { apple: { sku: 'premium' }, google: { skus: ['premium'] } },
  type: 'inapp',
});

// Cleanup
purchaseSub.remove();
errorSub.remove();
await endConnection();
```

## TypeScript (React Native — useIAP Hook)

```typescript
import { useIAP, ErrorCode } from 'react-native-iap';

function PurchaseScreen() {
  const {
    products,
    fetchProducts,
    requestPurchase,
    activeSubscriptions,
    getActiveSubscriptions,
  } = useIAP({
    onPurchaseSuccess: (purchase) => {
      // Validate and finish
    },
    onPurchaseError: (error) => {
      if (error.code === ErrorCode.UserCancelled) return;
      Alert.alert('Error', error.message);
    },
  });

  useEffect(() => {
    fetchProducts({ skus: ['premium'] });
  }, []);
}
```

## TypeScript (Expo)

```typescript
import { useIAP, ErrorCode } from 'expo-iap';

// Same API as react-native-iap useIAP hook
const { products, fetchProducts, requestPurchase } = useIAP({
  onPurchaseSuccess: (purchase) => { /* ... */ },
  onPurchaseError: (error) => { /* ... */ },
});
```

## Dart (Flutter)

```dart
import 'package:flutter_inapp_purchase/flutter_inapp_purchase.dart';

final iap = FlutterInappPurchase.instance;

// Initialize
await iap.initConnection();

// Fetch products
final products = await iap.fetchProducts<Product>(
  skus: ['premium', 'coins_100'],
  type: ProductQueryType.InApp,
);

// Fetch subscriptions
final subs = await iap.fetchProducts<ProductSubscription>(
  skus: ['monthly_pro'],
  type: ProductQueryType.Subs,
);

// Listen for events
iap.purchaseUpdatedStream.listen((purchase) async {
  await iap.finishTransaction(purchase, isConsumable: true);
});

iap.purchaseErrorStream.listen((error) {
  print('${error.code}: ${error.message}');
});

// Purchase
await iap.requestPurchase(sku: 'premium');

// Cleanup
await iap.endConnection();
```

## GDScript (Godot)

```gdscript
const Types = preload("res://addons/godot-iap/types.gd")

func _ready():
    GodotIapPlugin.purchase_updated.connect(_on_purchase_updated)
    GodotIapPlugin.purchase_error.connect(_on_purchase_error)
    GodotIapPlugin.init_connection()

func _load_products():
    var request = Types.ProductRequest.new()
    request.skus = ["premium", "coins_100"]
    request.type = Types.ProductQueryType.InApp
    var products = GodotIapPlugin.fetch_products(request)

func _purchase(sku: String):
    var props = Types.RequestPurchaseProps.new()
    props.sku = sku
    GodotIapPlugin.request_purchase(props)

func _on_purchase_updated(purchase):
    GodotIapPlugin.finish_transaction(purchase, true)

func _on_purchase_error(error):
    print("Error: ", error.code, " - ", error.message)
```

## Kotlin (KMP)

```kotlin
import io.github.hyochan.kmpiap.KmpIAP

val kmpIAP = KmpIAP()

// Initialize
kmpIAP.initConnection()

// Fetch products
val products = kmpIAP.fetchProducts(skus = listOf("premium", "coins_100"))

// Listen for events
kmpIAP.purchaseUpdatedListener.collect { purchase ->
    // Validate receipt on server
    kmpIAP.finishTransaction(purchase = purchase, isConsumable = true)
}

kmpIAP.purchaseErrorListener.collect { error ->
    println("Error: ${error.code} - ${error.message}")
}

// Purchase
kmpIAP.requestPurchase(sku = "premium")

// Cleanup
kmpIAP.endConnection()
```

## Swift (iOS Native)

```swift
import OpenIAP

let store = OpenIapStore()

// Initialize
try await store.initConnection()

// Fetch products
let products = try await store.fetchProducts(skus: ["premium"])

// Purchase
let result = try await store.requestPurchase(sku: "premium")

// Finish
try await store.finishTransaction(purchase: result)
```

## Kotlin (Android Native)

```kotlin
import dev.hyo.openiap.OpenIapStore

val store = OpenIapStore(context)

// Initialize
store.initConnection()

// Fetch products
val products = store.fetchProducts(skus = listOf("premium"))

// Purchase
store.requestPurchase(activity = this, sku = "premium")

// Listen
store.purchaseUpdatedFlow.collect { purchase ->
    store.finishTransaction(purchase)
}
```

---

# 10. Naming Conventions

## Function Naming
- Cross-platform: No suffix (`initConnection`, `fetchProducts`)
- iOS-only: `IOS` suffix (`getStorefrontIOS`, `clearTransactionIOS`)
- Android-only: `Android` suffix (`acknowledgePurchaseAndroid`)

## Type Naming
- iOS types: `IOS` suffix (`PurchaseIOS`, `ProductIOS`)
- Android types: `Android` suffix (`PurchaseAndroid`, `ProductAndroid`)
- IAP prefix: Use `Iap` not `IAP` when followed by other words (`IapPurchase`)

## Field Naming
- ID fields: Always `Id` not `ID` (`productId`, `transactionId`)
- Platform fields: Suffix with `IOS` or `Android` (`quantityIOS`, `orderIdAndroid`)

## Error Codes
- Always kebab-case: `user-cancelled`, `network-error`
- Use `ErrorCode` enum, never string literals

## Commit Messages
- With tag: `feat: add new feature` (lowercase after tag)
- Without tag: `Add new feature` (uppercase first letter)
- Types: feat, fix, docs, style, refactor, perf, test, chore

---

## Links

- Documentation: https://openiap.dev
- GitHub: https://github.com/hyodotdev/openiap
- APIs: https://openiap.dev/docs/apis
- Types: https://openiap.dev/docs/types
- Events: https://openiap.dev/docs/events
- Errors: https://openiap.dev/docs/errors
- Discussions: https://github.com/hyodotdev/openiap/discussions