= []
if let quantity = props.quantity, quantity > 1 {
options.insert(.quantity(quantity))
@@ -377,6 +377,90 @@ enum StoreKitTypesBridge {
}
options.insert(option)
}
+ // Win-back offers (iOS 18+)
+ // Used to re-engage churned subscribers
+ if #available(iOS 18.0, macOS 15.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *) {
+ if let winBackInput = props.winBackOffer {
+ guard let product = product else {
+ OpenIapLog.error("❌ Win-back offer requires product context")
+ throw PurchaseError.make(
+ code: .developerError,
+ productId: props.sku,
+ message: "Win-back offer requires product context. Fetch the product before calling requestPurchase."
+ )
+ }
+ // Find the win-back offer from the product's promotional offers
+ if let subscription = product.subscription {
+ let winBackOffer = subscription.promotionalOffers.first { offer in
+ offer.id == winBackInput.offerId && offer.type == .winBack
+ }
+ if let offer = winBackOffer {
+ options.insert(.winBackOffer(offer))
+ OpenIapLog.debug("✅ Added win-back offer: \(winBackInput.offerId)")
+ } else {
+ OpenIapLog.error("❌ Win-back offer not found: \(winBackInput.offerId)")
+ throw PurchaseError.make(
+ code: .developerError,
+ productId: props.sku,
+ message: "Win-back offer not found: \(winBackInput.offerId). Ensure the user is eligible and the offer ID is correct."
+ )
+ }
+ } else {
+ OpenIapLog.error("❌ Win-back offer requires a subscription product")
+ throw PurchaseError.make(
+ code: .developerError,
+ productId: props.sku,
+ message: "Win-back offers can only be applied to subscription products"
+ )
+ }
+ }
+ } else if props.winBackOffer != nil {
+ // Fail fast when win-back offers are used on unsupported OS versions
+ OpenIapLog.error("❌ Win-back offers require iOS 18+ / macOS 15+ / tvOS 18+ / watchOS 11+ / visionOS 2+")
+ throw PurchaseError.make(
+ code: .developerError,
+ productId: props.sku,
+ message: "Win-back offers are only supported on iOS 18+ / macOS 15+ / tvOS 18+ / watchOS 11+ / visionOS 2+."
+ )
+ }
+ // JWS Promotional Offer (iOS 15+, WWDC 2025)
+ // New signature format using compact JWS string for promotional offers
+ // Back-deployed to iOS 15, but requires Xcode 16.4+ / Swift 6.1+ to compile
+ if let jwsOffer = props.promotionalOfferJWS {
+ #if swift(>=6.1)
+ // Swift 6.1+ implementation
+ options.insert(.promotionalOffer(jwsOffer.jws))
+ OpenIapLog.debug("✅ Added JWS promotional offer: \(jwsOffer.offerId)")
+ #else
+ // Swift < 6.1: API not available, throw error to fail fast
+ OpenIapLog.error("❌ JWS promotional offers require Xcode 16.4+ / Swift 6.1+")
+ throw PurchaseError.make(
+ code: .developerError,
+ productId: props.sku,
+ message: "JWS promotional offers require Xcode 16.4+ / Swift 6.1+. Use withOffer with signature-based promotional offers instead."
+ )
+ #endif
+ }
+
+ // Introductory Offer Eligibility Override (iOS 15+, WWDC 2025)
+ // Allows overriding the system's eligibility check for introductory offers
+ // Back-deployed to iOS 15, but requires Xcode 16.4+ / Swift 6.1+ to compile
+ if let eligibility = props.introductoryOfferEligibility {
+ #if swift(>=6.1)
+ // Swift 6.1+ implementation
+ options.insert(.introductoryOfferEligibility(eligibility))
+ OpenIapLog.debug("✅ Added introductory offer eligibility override: \(eligibility)")
+ #else
+ // Swift < 6.1: API not available, throw error to fail fast
+ OpenIapLog.error("❌ Introductory offer eligibility override requires Xcode 16.4+ / Swift 6.1+")
+ throw PurchaseError.make(
+ code: .developerError,
+ productId: props.sku,
+ message: "Introductory offer eligibility override requires Xcode 16.4+ / Swift 6.1+. The system will determine eligibility automatically."
+ )
+ #endif
+ }
+
// Advanced Commerce Data (iOS 15+)
// Used with StoreKit 2's Product.PurchaseOption.custom API for passing
// campaign tokens, affiliate IDs, or other attribution data
diff --git a/packages/apple/Sources/Models/Types.swift b/packages/apple/Sources/Models/Types.swift
index 656e0b20..f176fbf0 100644
--- a/packages/apple/Sources/Models/Types.swift
+++ b/packages/apple/Sources/Models/Types.swift
@@ -299,6 +299,21 @@ public enum ProductQueryType: String, Codable, CaseIterable {
case all = "all"
}
+/// Status code for individual products returned from queryProductDetailsAsync (Android)
+/// Prior to 8.0, products that couldn't be fetched were simply not returned.
+/// With 8.0+, these products are returned with a status code explaining why.
+/// Available in Google Play Billing Library 8.0.0+
+public enum ProductStatusAndroid: String, Codable, CaseIterable {
+ /// Product was successfully fetched
+ case ok = "ok"
+ /// Product not found - the SKU doesn't exist in the Play Console
+ case notFound = "not-found"
+ /// No offers available for the user - product exists but user is not eligible for any offers
+ case noOffersAvailable = "no-offers-available"
+ /// Unknown error occurred while fetching the product
+ case unknown = "unknown"
+}
+
public enum ProductType: String, Codable, CaseIterable {
case inApp = "in-app"
case subs = "subs"
@@ -321,9 +336,23 @@ public enum PurchaseVerificationProvider: String, Codable, CaseIterable {
case iapkit = "iapkit"
}
+/// Sub-response codes for more granular purchase error information (Android)
+/// Available in Google Play Billing Library 8.0.0+
+public enum SubResponseCodeAndroid: String, Codable, CaseIterable {
+ /// No specific sub-response code applies
+ case noApplicableSubResponseCode = "no-applicable-sub-response-code"
+ /// User's payment method has insufficient funds
+ case paymentDeclinedDueToInsufficientFunds = "payment-declined-due-to-insufficient-funds"
+ /// User doesn't meet subscription offer eligibility requirements
+ case userIneligible = "user-ineligible"
+}
+
public enum SubscriptionOfferTypeIOS: String, Codable, CaseIterable {
case introductory = "introductory"
case promotional = "promotional"
+ /// Win-back offer type (iOS 18+)
+ /// Used to re-engage churned subscribers with a discount or free trial.
+ case winBack = "win-back"
}
public enum SubscriptionPeriodIOS: String, Codable, CaseIterable {
@@ -463,6 +492,18 @@ public struct BillingProgramReportingDetailsAndroid: Codable {
public var externalTransactionToken: String
}
+/// Extended billing result with sub-response code (Android)
+/// Available in Google Play Billing Library 8.0.0+
+public struct BillingResultAndroid: Codable {
+ /// Debug message from the billing library
+ public var debugMessage: String?
+ /// The response code from the billing operation
+ public var responseCode: Int
+ /// Sub-response code for more granular error information (8.0+).
+ /// Provides additional context when responseCode indicates an error.
+ public var subResponseCode: SubResponseCodeAndroid?
+}
+
/// Details provided when user selects developer billing option (Android)
/// Received via DeveloperProvidedBillingListener callback
/// Available in Google Play Billing Library 8.3.0+
@@ -668,6 +709,12 @@ public struct ProductAndroid: Codable, ProductCommon {
public var oneTimePurchaseOfferDetailsAndroid: [ProductAndroidOneTimePurchaseOfferDetail]?
public var platform: IapPlatform = .android
public var price: Double?
+ /// Product-level status code indicating fetch result (Android 8.0+)
+ /// OK = product fetched successfully
+ /// NOT_FOUND = SKU doesn't exist
+ /// NO_OFFERS_AVAILABLE = user not eligible for any offers
+ /// Available in Google Play Billing Library 8.0.0+
+ public var productStatusAndroid: ProductStatusAndroid?
/// @deprecated Use subscriptionOffers instead for cross-platform compatibility.
public var subscriptionOfferDetailsAndroid: [ProductSubscriptionAndroidOfferDetails]?
/// Standardized subscription offers.
@@ -751,6 +798,12 @@ public struct ProductSubscriptionAndroid: Codable, ProductCommon {
public var oneTimePurchaseOfferDetailsAndroid: [ProductAndroidOneTimePurchaseOfferDetail]?
public var platform: IapPlatform = .android
public var price: Double?
+ /// Product-level status code indicating fetch result (Android 8.0+)
+ /// OK = product fetched successfully
+ /// NOT_FOUND = SKU doesn't exist
+ /// NO_OFFERS_AVAILABLE = user not eligible for any offers
+ /// Available in Google Play Billing Library 8.0.0+
+ public var productStatusAndroid: ProductStatusAndroid?
/// @deprecated Use subscriptionOffers instead for cross-platform compatibility.
public var subscriptionOfferDetailsAndroid: [ProductSubscriptionAndroidOfferDetails]
/// Standardized subscription offers.
@@ -1280,19 +1333,47 @@ public struct ProductRequest: Codable {
}
}
+/// JWS promotional offer input for iOS 15+ (StoreKit 2, WWDC 2025).
+/// New signature format using compact JWS string for promotional offers.
+/// This provides a simpler alternative to the legacy signature-based promotional offers.
+/// Back-deployed to iOS 15.
+public struct PromotionalOfferJWSInputIOS: Codable {
+ /// Compact JWS string signed by your server.
+ /// The JWS should contain the promotional offer signature data.
+ /// Format: header.payload.signature (base64url encoded)
+ public var jws: String
+ /// The promotional offer identifier from App Store Connect
+ public var offerId: String
+
+ public init(
+ jws: String,
+ offerId: String
+ ) {
+ self.jws = jws
+ self.offerId = offerId
+ }
+}
+
public typealias PurchaseInput = Purchase
public struct PurchaseOptions: Codable {
/// Also emit results through the iOS event listeners
public var alsoPublishToEventListenerIOS: Bool?
+ /// Include suspended subscriptions in the result (Android 8.1+).
+ /// Suspended subscriptions have isSuspendedAndroid=true and should NOT be granted entitlements.
+ /// Users should be directed to the subscription center to resolve payment issues.
+ /// Default: false (only active subscriptions are returned)
+ public var includeSuspendedAndroid: Bool?
/// Limit to currently active items on iOS
public var onlyIncludeActiveItemsIOS: Bool?
public init(
alsoPublishToEventListenerIOS: Bool? = nil,
+ includeSuspendedAndroid: Bool? = nil,
onlyIncludeActiveItemsIOS: Bool? = nil
) {
self.alsoPublishToEventListenerIOS = alsoPublishToEventListenerIOS
+ self.includeSuspendedAndroid = includeSuspendedAndroid
self.onlyIncludeActiveItemsIOS = onlyIncludeActiveItemsIOS
}
}
@@ -1336,10 +1417,23 @@ public struct RequestPurchaseIosProps: Codable {
public var andDangerouslyFinishTransactionAutomatically: Bool?
/// App account token for user tracking
public var appAccountToken: String?
+ /// Override introductory offer eligibility (iOS 15+, WWDC 2025).
+ /// Set to true to indicate the user is eligible for introductory offer,
+ /// or false to indicate they are not. When nil, the system determines eligibility.
+ /// Back-deployed to iOS 15.
+ public var introductoryOfferEligibility: Bool?
+ /// JWS promotional offer (iOS 15+, WWDC 2025).
+ /// New signature format using compact JWS string for promotional offers.
+ /// Back-deployed to iOS 15.
+ public var promotionalOfferJWS: PromotionalOfferJWSInputIOS?
/// Purchase quantity
public var quantity: Int?
/// Product SKU
public var sku: String
+ /// Win-back offer to apply (iOS 18+)
+ /// Used to re-engage churned subscribers with a discount or free trial.
+ /// Note: Win-back offers only apply to subscription products.
+ public var winBackOffer: WinBackOfferInputIOS?
/// Discount offer to apply
public var withOffer: DiscountOfferInputIOS?
@@ -1347,15 +1441,21 @@ public struct RequestPurchaseIosProps: Codable {
advancedCommerceData: String? = nil,
andDangerouslyFinishTransactionAutomatically: Bool? = nil,
appAccountToken: String? = nil,
+ introductoryOfferEligibility: Bool? = nil,
+ promotionalOfferJWS: PromotionalOfferJWSInputIOS? = nil,
quantity: Int? = nil,
sku: String,
+ winBackOffer: WinBackOfferInputIOS? = nil,
withOffer: DiscountOfferInputIOS? = nil
) {
self.advancedCommerceData = advancedCommerceData
self.andDangerouslyFinishTransactionAutomatically = andDangerouslyFinishTransactionAutomatically
self.appAccountToken = appAccountToken
+ self.introductoryOfferEligibility = introductoryOfferEligibility
+ self.promotionalOfferJWS = promotionalOfferJWS
self.quantity = quantity
self.sku = sku
+ self.winBackOffer = winBackOffer
self.withOffer = withOffer
}
}
@@ -1514,23 +1614,43 @@ public struct RequestSubscriptionIosProps: Codable {
public var advancedCommerceData: String?
public var andDangerouslyFinishTransactionAutomatically: Bool?
public var appAccountToken: String?
+ /// Override introductory offer eligibility (iOS 15+, WWDC 2025).
+ /// Set to true to indicate the user is eligible for introductory offer,
+ /// or false to indicate they are not. When nil, the system determines eligibility.
+ /// Back-deployed to iOS 15.
+ public var introductoryOfferEligibility: Bool?
+ /// JWS promotional offer (iOS 15+, WWDC 2025).
+ /// New signature format using compact JWS string for promotional offers.
+ /// Back-deployed to iOS 15.
+ public var promotionalOfferJWS: PromotionalOfferJWSInputIOS?
public var quantity: Int?
public var sku: String
+ /// Win-back offer to apply (iOS 18+)
+ /// Used to re-engage churned subscribers with a discount or free trial.
+ /// The offer is available when the customer is eligible and can be discovered
+ /// via StoreKit Message (automatic) or subscription offer APIs.
+ public var winBackOffer: WinBackOfferInputIOS?
public var withOffer: DiscountOfferInputIOS?
public init(
advancedCommerceData: String? = nil,
andDangerouslyFinishTransactionAutomatically: Bool? = nil,
appAccountToken: String? = nil,
+ introductoryOfferEligibility: Bool? = nil,
+ promotionalOfferJWS: PromotionalOfferJWSInputIOS? = nil,
quantity: Int? = nil,
sku: String,
+ winBackOffer: WinBackOfferInputIOS? = nil,
withOffer: DiscountOfferInputIOS? = nil
) {
self.advancedCommerceData = advancedCommerceData
self.andDangerouslyFinishTransactionAutomatically = andDangerouslyFinishTransactionAutomatically
self.appAccountToken = appAccountToken
+ self.introductoryOfferEligibility = introductoryOfferEligibility
+ self.promotionalOfferJWS = promotionalOfferJWS
self.quantity = quantity
self.sku = sku
+ self.winBackOffer = winBackOffer
self.withOffer = withOffer
}
}
@@ -1735,6 +1855,21 @@ public struct VerifyPurchaseWithProviderProps: Codable {
}
}
+/// Win-back offer input for iOS 18+ (StoreKit 2)
+/// Win-back offers are used to re-engage churned subscribers.
+/// The offer is automatically presented via StoreKit Message when eligible,
+/// or can be applied programmatically during purchase.
+public struct WinBackOfferInputIOS: Codable {
+ /// The win-back offer ID from App Store Connect
+ public var offerId: String
+
+ public init(
+ offerId: String
+ ) {
+ self.offerId = offerId
+ }
+}
+
// MARK: - Unions
public enum Product: Codable, ProductCommon {
diff --git a/packages/apple/Sources/OpenIapModule.swift b/packages/apple/Sources/OpenIapModule.swift
index d91fa5f8..2741bcd2 100644
--- a/packages/apple/Sources/OpenIapModule.swift
+++ b/packages/apple/Sources/OpenIapModule.swift
@@ -218,7 +218,7 @@ public final class OpenIapModule: NSObject, OpenIapModuleProtocol {
let iosProps = try resolveIosPurchaseProps(from: params)
let sku = iosProps.sku
let product = try await storeProduct(for: sku)
- let options = try StoreKitTypesBridge.purchaseOptions(from: iosProps)
+ let options = try StoreKitTypesBridge.purchaseOptions(from: iosProps, product: product)
// Check if subscription is already owned before attempting purchase
// This prevents iOS from showing "You're already subscribed" alert
@@ -1275,8 +1275,11 @@ public final class OpenIapModule: NSObject, OpenIapModuleProtocol {
advancedCommerceData: ios.advancedCommerceData,
andDangerouslyFinishTransactionAutomatically: ios.andDangerouslyFinishTransactionAutomatically,
appAccountToken: ios.appAccountToken,
+ introductoryOfferEligibility: ios.introductoryOfferEligibility,
+ promotionalOfferJWS: ios.promotionalOfferJWS,
quantity: ios.quantity,
sku: ios.sku,
+ winBackOffer: ios.winBackOffer,
withOffer: ios.withOffer
)
}
diff --git a/packages/docs/public/llms-full.txt b/packages/docs/public/llms-full.txt
index bda0fb02..4b8d40cf 100644
--- a/packages/docs/public/llms-full.txt
+++ b/packages/docs/public/llms-full.txt
@@ -3,7 +3,7 @@
> OpenIAP: Unified in-app purchase specification for iOS & Android
> Documentation: https://openiap.dev
> Quick Reference: https://openiap.dev/llms.txt
-> Generated: 2026-01-18T10:51:44.321Z
+> Generated: 2026-01-18T13:00:35.102Z
## Table of Contents
1. Installation
@@ -430,13 +430,25 @@ await endConnection();
# Google Play Billing Library API Reference
-> Reference documentation for Google Play Billing Library 7.x
+> Reference documentation for Google Play Billing Library 8.x
> Adapt all patterns to match OpenIAP internal conventions.
## Overview
Google Play Billing Library enables in-app purchases and subscriptions on Android devices.
+## Version History
+
+| Version | Release Date | Key Features |
+|---------|--------------|--------------|
+| 8.0 | 2025-06-30 | Auto-reconnect, product-level status codes, one-time products with multiple offers, sub-response codes |
+| 8.1 | 2025-11-06 | Suspended subscriptions (`isSuspended`), `includeSuspended` parameter, pre-order details, product-level subscription replacement, `KEEP_EXISTING` mode |
+| 8.2 | 2025-12-09 | Billing Programs API (external content links, external offers), deprecates old External Offers API |
+| 8.2.1 | 2025-12-15 | Bug fix for `isBillingProgramAvailableAsync()` and `createBillingProgramReportingDetailsAsync()` |
+| 8.3 | 2025-12-23 | External Payments program (Japan only), developer billing options |
+
+**Current Version**: 8.3.0 (as of January 2026)
+
## Core Classes
### BillingClient
@@ -447,9 +459,24 @@ The main interface for communicating with Google Play Billing.
val billingClient = BillingClient.newBuilder(context)
.setListener(purchasesUpdatedListener)
.enablePendingPurchases()
+ // New in 8.0: Auto-reconnect on service disconnect
+ .enableAutoServiceReconnection()
+ .build()
+```
+
+### Auto Service Reconnection (8.0+)
+
+```kotlin
+// Enables automatic reconnection when service disconnects
+BillingClient.newBuilder(context)
+ .enableAutoServiceReconnection()
.build()
```
+When enabled, the library automatically re-establishes the connection if an API call is made while disconnected. This reduces `SERVICE_DISCONNECTED` errors.
+
+> **OpenIAP Note**: Auto-reconnection is **always enabled** internally since OpenIAP uses Billing Library 8.3.0+. No configuration needed.
+
### Connection Management
```kotlin
@@ -667,13 +694,126 @@ if (result.responseCode == BillingClient.BillingResponseCode.OK) {
- `PRICE_CHANGE_CONFIRMATION` - Price change confirmation
- `PRODUCT_DETAILS` - Product details API
+## Product-Level Status Codes (8.0+)
+
+In Billing Library 8.0+, `queryProductDetailsAsync()` returns products that couldn't be fetched with a status code explaining why.
+
+```kotlin
+billingClient.queryProductDetailsAsync(params) { billingResult, productDetailsList ->
+ productDetailsList.forEach { productDetails ->
+ when (productDetails.productStatus) {
+ ProductDetails.ProductStatus.OK -> {
+ // Product fetched successfully
+ }
+ ProductDetails.ProductStatus.NOT_FOUND -> {
+ // SKU doesn't exist in Play Console
+ }
+ ProductDetails.ProductStatus.NO_OFFERS_AVAILABLE -> {
+ // User not eligible for any offers
+ }
+ }
+ }
+}
+```
+
+| Status | Description |
+|--------|-------------|
+| `OK` | Product fetched successfully |
+| `NOT_FOUND` | SKU doesn't exist in Play Console |
+| `NO_OFFERS_AVAILABLE` | User not eligible for any offers |
+
+## Suspended Subscriptions (8.1+)
+
+```kotlin
+val purchase: Purchase
+
+// Check if subscription is suspended due to billing issue
+if (purchase.isSuspended) {
+ // User's payment method failed
+ // Do NOT grant entitlements
+ // Direct user to subscription center to fix payment
+}
+```
+
+### Query Suspended Subscriptions (8.1+)
+
+```kotlin
+// Include suspended subscriptions in query results
+val params = QueryPurchasesParams.newBuilder()
+ .setProductType(BillingClient.ProductType.SUBS)
+ .setIncludeSuspended(true) // New in 8.1
+ .build()
+
+billingClient.queryPurchasesAsync(params) { billingResult, purchases ->
+ purchases.forEach { purchase ->
+ if (purchase.isSuspended) {
+ // Handle suspended subscription
+ }
+ }
+}
+```
+
+> **OpenIAP Note**: Use `includeSuspendedAndroid: true` in `PurchaseOptions` when calling `getAvailablePurchases()`. The `isSuspendedAndroid` field on purchases indicates suspension status.
+
+## Sub-Response Codes (8.0+)
+
+`BillingResult` includes a sub-response code for more granular error information:
+
+```kotlin
+val result = billingClient.launchBillingFlow(activity, params)
+when (result.subResponseCode) {
+ BillingResult.SUB_RESPONSE_CODE_INSUFFICIENT_FUNDS -> {
+ // User's payment method has insufficient funds
+ }
+ BillingResult.SUB_RESPONSE_CODE_USER_INELIGIBLE -> {
+ // User doesn't meet offer eligibility requirements
+ }
+}
+```
+
+| Sub-Response Code | Description |
+|-------------------|-------------|
+| `PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS` | User's payment method has insufficient funds |
+| `USER_INELIGIBLE` | User doesn't meet subscription offer eligibility |
+| `NO_APPLICABLE_SUB_RESPONSE_CODE` | No specific sub-code applies |
+
+## Subscription Product Replacement (8.1+)
+
+Product-level replacement parameters for subscription upgrades/downgrades:
+
+```kotlin
+val replacementParams = SubscriptionProductReplacementParams.newBuilder()
+ .setOldProductId("old_subscription_id")
+ .setReplacementMode(ReplacementMode.WITH_TIME_PRORATION)
+ .build()
+
+val productDetailsParams = BillingFlowParams.ProductDetailsParams.newBuilder()
+ .setProductDetails(newProductDetails)
+ .setOfferToken(offerToken)
+ .setSubscriptionProductReplacementParams(replacementParams) // New in 8.1
+ .build()
+```
+
+### Replacement Modes
+
+| Mode | Description |
+|------|-------------|
+| `WITH_TIME_PRORATION` | Immediate, expiration time prorated |
+| `CHARGE_PRORATED_PRICE` | Immediate, same billing cycle |
+| `CHARGE_FULL_PRICE` | Immediate, full price charged |
+| `WITHOUT_PRORATION` | Takes effect on old plan expiration |
+| `DEFERRED` | Deferred, no charge |
+| `KEEP_EXISTING` | Keep existing payment schedule (8.1+) |
+
## Best Practices
1. **Always acknowledge purchases** within 3 days or they will be refunded
2. **Verify purchases server-side** using Google Play Developer API
3. **Handle pending purchases** for payment methods that require additional steps
-4. **Reconnect on disconnect** - billing service can disconnect anytime
-5. **Cache product details** to avoid repeated queries
+4. **Auto-reconnect is enabled by default** in OpenIAP (8.0+)
+5. **Check product status codes** (8.0+) to understand why products weren't fetched
+6. **Check isSuspended** (8.1+) before granting entitlements
+7. **Cache product details** to avoid repeated queries
---
@@ -681,7 +821,7 @@ if (result.responseCode == BillingClient.BillingResponseCode.OK) {
# Meta Horizon IAP API Reference
> External reference for Meta Horizon Store in-app purchase APIs.
-> Source: https://developers.meta.com/horizon/documentation/
+> Source: [Meta Horizon Documentation](https://developers.meta.com/horizon/documentation/)
## Overview
@@ -694,12 +834,17 @@ Meta Horizon provides IAP functionality for Quest VR applications. There are two
| Library | Version | Compatible With |
|---------|---------|-----------------|
-| horizon-billing-compatibility | 1.1.1 | Google Play Billing **7.0** API |
-| Google Play Billing (Play flavor) | 8.3.0 | N/A |
-| react-native-iap | v14+ | Billing 7.0+ |
-| expo-iap | latest | Billing 7.0+ |
+| horizon-billing-compatibility | **1.1.1** (latest) | Google Play Billing **7.0** API |
+| Google Play Billing (Play flavor) | **8.3.0** (latest) | N/A |
+| react-native-iap | v14+ | Billing 7.0+, RN 0.79+, Kotlin 2.0+ |
+| expo-iap | latest | Billing 7.0+, Kotlin 2.0+ |
+
+**CRITICAL**: Horizon Billing Compatibility SDK implements Google Play Billing **7.0** API surface, NOT 8.x.
-**IMPORTANT**: Horizon Billing Compatibility SDK implements Google Play Billing **7.0** API surface, NOT 8.x. When writing shared code for both Play and Horizon flavors, use only APIs that exist in both Billing 7.0 and 8.x.
+When writing shared code for both Play and Horizon flavors:
+- Use only APIs that exist in **both** Billing 7.0 and 8.x
+- Horizon SDK does NOT support Billing 8.x features like auto-reconnect, product status codes, or `includeSuspended`
+- OpenIAP handles this automatically with flavor-specific implementations
### APIs Available in Both (Safe to use in shared code)
@@ -712,9 +857,15 @@ Meta Horizon provides IAP functionality for Quest VR applications. There are two
### APIs Only in Billing 8.x (DO NOT use in shared code)
-- `enableAutoServiceReconnection()` - Auto reconnect feature
-- Product-level status codes in `queryProductDetailsAsync()` response
-- One-time products with multiple offers
+- `enableAutoServiceReconnection()` - Auto reconnect feature (8.0+)
+- Product-level status codes in `queryProductDetailsAsync()` response (8.0+)
+- One-time products with multiple offers (8.0+)
+- Sub-response codes in `BillingResult` (8.0+)
+- `isSuspended` on Purchase (8.1+)
+- `includeSuspended` parameter in `QueryPurchasesParams` (8.1+)
+- `SubscriptionProductReplacementParams` (8.1+)
+- Billing Programs API (`isBillingProgramAvailableAsync`, etc.) (8.2+)
+- External Payments / Developer Billing Options (8.3+)
## Billing Compatibility SDK
@@ -764,7 +915,8 @@ Access token format: `OC|App_ID|App_Secret`
Verify that a user owns an item (app or add-on).
**Endpoint:**
-```
+
+```http
POST https://graph.oculus.com/$APP_ID/verify_entitlement
```
@@ -772,7 +924,7 @@ POST https://graph.oculus.com/$APP_ID/verify_entitlement
| Parameter | Type | Description |
|-----------|------|-------------|
-| `access_token` | string | `OC|App_ID|App_Secret` format |
+| `access_token` | string | `OC\|App_ID\|App_Secret` format |
| `user_id` | string | The user ID to verify |
| `sku` | string | (Optional) SKU for add-on verification |
@@ -803,7 +955,8 @@ curl -d "access_token=OC|$APP_ID|$APP_SECRET" \
Refund a DURABLE or CONSUMABLE entitlement (not yet consumed).
**Endpoint:**
-```
+
+```http
POST https://graph.oculus.com/$APP_ID/refund_iap_entitlement
```
@@ -811,7 +964,7 @@ POST https://graph.oculus.com/$APP_ID/refund_iap_entitlement
| Parameter | Type | Description |
|-----------|------|-------------|
-| `access_token` | string | `OC|App_ID|App_Secret` format |
+| `access_token` | string | `OC\|App_ID\|App_Secret` format |
| `user_id` | string | The user ID |
| `sku` | string | SKU of item to refund |
@@ -1349,6 +1502,30 @@ export default withIAPContext(Store);
This document provides external API reference for Apple's StoreKit 2 framework.
+## iOS 18+ Features
+
+| Feature | iOS Version | Description |
+|---------|-------------|-------------|
+| Win-back offers | iOS 18.0 | Re-engage churned subscribers |
+| Consumable transaction history | iOS 18.0 | History includes finished consumables |
+| Billing issue messages | iOS 18.0 | Automatic billing issue notifications via StoreKit Message |
+| UI context for purchases | iOS 18.2 | Required for proper payment sheet display |
+| External purchase notice | iOS 18.2 | `presentExternalPurchaseNoticeSheetIOS` |
+| `appTransactionID` | iOS 18.4 | Globally unique app transaction identifier (back-deployed to iOS 15) |
+| `originalPlatform` | iOS 18.4 | Original purchase platform (back-deployed to iOS 15) |
+| `Offer.Period` | iOS 18.4 | Offer period information |
+| `advancedCommerceInfo` | iOS 18.4 | Advanced Commerce API data |
+| Expanded offer codes | iOS 18.4 | For consumables/non-consumables |
+| JWS promotional offers | WWDC 2025 | New `promotionalOffer` purchase option with JWS format |
+| `introductoryOfferEligibility` | WWDC 2025 | Set eligibility via purchase option |
+
+### WWDC 2025 Updates
+
+- **SubscriptionStatus by Transaction ID**: Query subscription status using any transaction ID
+- **JWS-based promotional offers**: New `promotionalOffer` purchase option with compact JWS string
+- **Introductory offer eligibility**: Override eligibility check with `introductoryOfferEligibility` purchase option
+- Both new purchase options are back-deployed to iOS 15
+
## Product
A type that describes an in-app purchase product.
@@ -1456,6 +1633,124 @@ static func beginRefundRequest(for transactionID: UInt64, in scene: UIWindowScen
Begins a refund request for a transaction.
+## Win-Back Offers (iOS 18+)
+
+Win-back offers are a new offer type to re-engage churned subscribers.
+
+### Automatic Presentation
+
+StoreKit Message automatically presents win-back offers when a user is eligible:
+
+```swift
+// Message reason for win-back offers
+StoreKit.Message.Reason.winBackOffer
+```
+
+### Manual Application
+
+Apply a win-back offer during purchase:
+
+```swift
+let product: Product
+let winBackOffer: Product.SubscriptionOffer
+
+let result = try await product.purchase(options: [
+ .winBackOffer(winBackOffer)
+])
+```
+
+### Checking Eligibility
+
+```swift
+// Win-back offers are available in subscription.promotionalOffers
+// with type == .winBack
+let winBackOffers = product.subscription?.promotionalOffers.filter {
+ $0.type == .winBack
+}
+```
+
+### RenewalInfo
+
+Win-back offer information is available in renewal info:
+
+```swift
+let renewalInfo: Product.SubscriptionInfo.RenewalInfo
+
+// Check if win-back offer is applied to next renewal
+if renewalInfo.renewalOfferType == .winBack {
+ // Win-back offer will be applied
+}
+```
+
+## UI Context for Purchases (iOS 18.2+)
+
+Beginning in iOS 18.2, purchase methods require a UI context to properly display payment sheets:
+
+```swift
+// iOS/iPadOS/tvOS/visionOS: UIViewController
+let result = try await product.purchase(confirmIn: viewController)
+
+// macOS: NSWindow
+let result = try await product.purchase(confirmIn: window)
+
+// watchOS: No UI context required
+```
+
+> **OpenIAP Note**: UI context is handled automatically in OpenIAP using the active window scene.
+
+## AppTransaction Updates (iOS 18.4+)
+
+```swift
+let appTransaction = try await AppTransaction.shared
+
+// New in iOS 18.4 (back-deployed to iOS 15)
+let appTransactionID = appTransaction.appTransactionID // Globally unique per Apple Account
+let originalPlatform = appTransaction.originalPlatform // Original purchase platform
+```
+
+### appTransactionID
+
+- Globally unique identifier for each Apple Account that downloads your app
+- Remains consistent across redownloads, refunds, repurchases, and storefront changes
+- Works with Family Sharing (each family member gets unique ID)
+- Back-deployed to iOS 15
+
+## Advanced Commerce API (iOS 18.4+)
+
+For apps with large product catalogs:
+
+```swift
+// Check if product has advanced commerce info
+if let advancedInfo = product.advancedCommerceInfo {
+ // Handle large catalog monetization
+}
+```
+
+## External Purchase Support (iOS 18.2+)
+
+### Present External Purchase Notice
+
+```swift
+// Check if external purchase notice can be presented
+if await ExternalPurchase.canPresent {
+ let result = try await ExternalPurchase.presentNoticeSheet()
+ switch result {
+ case .continue:
+ // User wants to continue to external purchase
+ case .dismissed:
+ // User dismissed the notice
+ }
+}
+```
+
+### Present External Purchase Link
+
+```swift
+let result = try await ExternalPurchase.open(url: externalURL)
+```
+
+> **OpenIAP Note**: `presentExternalPurchaseNoticeSheetIOS` and `presentExternalPurchaseLinkIOS` are available in the iOS package.
+
---
diff --git a/packages/docs/public/llms.txt b/packages/docs/public/llms.txt
index 8c4ce8da..3e545b9a 100644
--- a/packages/docs/public/llms.txt
+++ b/packages/docs/public/llms.txt
@@ -3,7 +3,7 @@
> OpenIAP: Unified in-app purchase specification for iOS & Android
> Documentation: https://openiap.dev
> Full Reference: https://openiap.dev/llms-full.txt
-> Generated: 2026-01-18T10:51:44.321Z
+> Generated: 2026-01-18T13:00:35.102Z
## Installation
diff --git a/packages/docs/src/pages/docs/types/offer.tsx b/packages/docs/src/pages/docs/types/offer.tsx
index 8063bb65..0871b6fb 100644
--- a/packages/docs/src/pages/docs/types/offer.tsx
+++ b/packages/docs/src/pages/docs/types/offer.tsx
@@ -125,7 +125,7 @@ function TypesOffer() {
DiscountOfferType!
|
- Type of offer (Introductory, Promotional, OneTime) |
+ Type of offer: Introductory, Promotional, WinBack (iOS 18+), or OneTime |
@@ -268,6 +268,7 @@ function TypesOffer() {
enum DiscountOfferType {
Introductory = 'Introductory',
Promotional = 'Promotional',
+ WinBack = 'WinBack', // iOS 18+
OneTime = 'OneTime',
}`}
),
@@ -296,6 +297,7 @@ enum DiscountOfferType {
enum DiscountOfferType: String, Codable {
case introductory = "Introductory"
case promotional = "Promotional"
+ case winBack = "WinBack" // iOS 18+
case oneTime = "OneTime"
}`}
),
@@ -324,6 +326,7 @@ enum DiscountOfferType: String, Codable {
enum class DiscountOfferType {
Introductory,
Promotional,
+ WinBack, // iOS 18+
OneTime
}`}
),
@@ -370,6 +373,7 @@ enum class DiscountOfferType {
enum DiscountOfferType {
introductory,
promotional,
+ winBack, // iOS 18+
oneTime,
}`}
),
@@ -398,6 +402,7 @@ var rental_details_android: RentalDetailsAndroid
enum DiscountOfferType {
INTRODUCTORY,
PROMOTIONAL,
+ WIN_BACK, # iOS 18+
ONE_TIME
}`}
),
@@ -470,7 +475,7 @@ enum DiscountOfferType {
DiscountOfferType!
|
- Introductory or Promotional |
+ Introductory, Promotional, or WinBack (iOS 18+) |
diff --git a/packages/docs/src/pages/docs/types/product.tsx b/packages/docs/src/pages/docs/types/product.tsx
index 3e808696..5bba51a9 100644
--- a/packages/docs/src/pages/docs/types/product.tsx
+++ b/packages/docs/src/pages/docs/types/product.tsx
@@ -250,6 +250,25 @@ function TypesProduct() {
offerToken, pricingPhases
|
+
+
+ productStatusAndroid
+ |
+
+ Product fetch status code. Values: OK (success),{' '}
+ NOT_FOUND (SKU doesn't exist),{' '}
+ NO_OFFERS_AVAILABLE (user not eligible for any offers),{' '}
+ UNKNOWN.
+ Requires{' '}
+
+ Billing Library 8.0+
+
+ |
+
diff --git a/packages/docs/src/pages/docs/updates/notes.tsx b/packages/docs/src/pages/docs/updates/notes.tsx
index 48f29599..0f315d6a 100644
--- a/packages/docs/src/pages/docs/updates/notes.tsx
+++ b/packages/docs/src/pages/docs/updates/notes.tsx
@@ -26,6 +26,91 @@ function Notes() {
useScrollToHash();
const allNotes: Note[] = [
+ // GQL 1.3.13 / Google 1.3.24 / Apple 1.3.11 - Jan 18, 2026
+ {
+ id: 'gql-1-3-13-google-1-3-24-apple-1-3-11',
+ date: new Date('2026-01-18'),
+ element: (
+
+
+ 📅 openiap-gql v1.3.13 / openiap-google v1.3.24 / openiap-apple v1.3.11 - Platform API Gap Analysis
+
+
+
iOS - Win-Back Offers (iOS 18+):
+
+ Added support for win-back offers to re-engage churned subscribers.
+
+
+ winBackOffer - New field in RequestPurchaseIosProps and RequestSubscriptionIosPropsWinBackOfferInputIOS - Input type with offerId fieldSubscriptionOfferTypeIOS.WinBack - New enum value
+
+{`// Apply win-back offer to subscription purchase
+requestSubscription({
+ sku: 'premium_monthly',
+ winBackOffer: { offerId: 'winback_50_off' }
+});`}
+
+
+
iOS - JWS Promotional Offers (iOS 15+, WWDC 2025):
+
+ New signature format using compact JWS string for promotional offers. Back-deployed to iOS 15.
+
+
+ promotionalOfferJWS - New field in purchase propsPromotionalOfferJWSInputIOS - Input type with offerId and jws fields
+
+ Note: Requires Xcode 16.4+ to compile. Falls back to legacy signature-based offers until then.
+
+
+
iOS - Introductory Offer Eligibility Override (iOS 15+, WWDC 2025):
+
+ introductoryOfferEligibility - Override system eligibility check for intro offers- Set
true to indicate eligible, false for not eligible, nil for system default
+
+
+ Note: Requires Xcode 16.4+ to compile. System determines eligibility automatically until then.
+
+
+
+
+
Android - Product Status Codes (Billing 8.0+):
+
+ Product-level status codes indicating why products couldn't be fetched.
+
+
+ ProductStatusAndroid - New enum with values: Ok, NotFound, NoOffersAvailable, UnknownproductStatusAndroid - New field on ProductAndroid and ProductSubscriptionAndroid
+
+{`// Check product fetch status
+val product = fetchProducts(skus).firstOrNull()
+when (product?.productStatusAndroid) {
+ ProductStatusAndroid.Ok -> { /* Success */ }
+ ProductStatusAndroid.NotFound -> { /* SKU doesn't exist */ }
+ ProductStatusAndroid.NoOffersAvailable -> { /* User not eligible */ }
+ ProductStatusAndroid.Unknown -> { /* Unknown status */ }
+ null -> { /* No product or status */ }
+}`}
+
+
+
Android - Auto Service Reconnection:
+
+ enableAutoServiceReconnection() is now always enabled internally since OpenIAP uses Billing Library 8.3.0+.
+ No configuration needed - the library automatically re-establishes connection if disconnected.
+
+
+
References:
+
+