Types
Comprehensive type definitions for kmp-iap v1.0.0-rc following OpenIAP specification. All types are fully documented with Kotlin data classes for complete type safety and cross-platform compatibility.
OpenIAP Base Interfaces
ProductCommon (OpenIAP Base)
Base interface following OpenIAP specification for all product types.
interface ProductCommon {
val id: String // Unified product identifier
val title: String // Product title
val description: String // Product description
val type: ProductType // "inapp" or "subs"
val displayName: String? // Optional display name
val displayPrice: String // Formatted price for display
val currency: String // ISO currency code
val price: Double? // Numeric price value
val debugDescription: String?
val platform: String? // Platform identifier
}
PurchaseCommon (OpenIAP Base)
Base interface following OpenIAP specification for all purchase types.
interface PurchaseCommon {
val id: String // Transaction identifier
val productId: String // Product that was purchased
val ids: List<String>? // Multiple product IDs (Android)
val transactionId: String? // @deprecated - use id instead
val transactionDate: Double // Unix timestamp
val transactionReceipt: String
val purchaseToken: String? // Unified token field
val platform: String?
}
Platform-Specific Implementations
ProductIOS
iOS product implementation with platform-specific fields.
data class ProductIOS(
// ProductCommon fields
override val id: String,
override val title: String,
override val description: String,
override val type: ProductType,
override val displayPrice: String,
override val currency: String,
override val price: Double?,
override val debugDescription: String?,
override val displayName: String?,
override val platform: String = "ios",
// iOS-specific fields
val displayNameIOS: String,
val isFamilyShareableIOS: Boolean,
val jsonRepresentationIOS: String,
val subscriptionInfoIOS: SubscriptionInfoIOS? = null
) : ProductCommon
ProductAndroid
Android product implementation with Google Play Billing fields.
data class ProductAndroid(
// ProductCommon fields
override val id: String,
override val title: String,
override val description: String,
override val type: ProductType,
override val displayPrice: String,
override val currency: String,
override val price: Double?,
override val debugDescription: String?,
override val displayName: String?,
override val platform: String = "android",
// Android-specific fields
val nameAndroid: String,
val oneTimePurchaseOfferDetailsAndroid: List<ProductAndroidOneTimePurchaseOfferDetail>? = null,
val subscriptionOfferDetailsAndroid: List<ProductSubscriptionAndroidOfferDetail>? = null
) : ProductCommon
PurchaseIOS
iOS purchase implementation with StoreKit fields.
data class PurchaseIOS(
// PurchaseCommon fields
override val id: String,
override val productId: String,
override val ids: List<String>? = null,
override val transactionId: String? = null, // @deprecated
override val transactionDate: Double,
override val transactionReceipt: String,
override val purchaseToken: String? = null,
override val platform: String = "ios",
// iOS-specific fields
val jwsRepresentationIOS: String? = null,
val originalTransactionDateIOS: Double? = null,
val originalTransactionIdentifierIOS: String? = null,
val transactionState: TransactionStateIOS? = null
) : PurchaseCommon
PurchaseAndroid
Android purchase implementation with Google Play Billing fields.
data class PurchaseAndroid(
// PurchaseCommon fields
override val id: String,
override val productId: String,
override val ids: List<String>? = null,
override val transactionId: String? = null, // @deprecated
override val transactionDate: Double,
override val transactionReceipt: String,
override val purchaseToken: String? = null,
override val platform: String = "android",
// Android-specific fields
val purchaseStateAndroid: AndroidPurchaseState? = null,
val acknowledgedAndroid: Boolean? = null,
val autoRenewingAndroid: Boolean? = null,
val obfuscatedAccountIdAndroid: String? = null,
val obfuscatedProfileIdAndroid: String? = null,
val orderIdAndroid: String? = null,
val packageNameAndroid: String? = null,
val purchaseTimeAndroid: Double? = null,
val purchaseTokenAndroid: String? = null, // @deprecated
val signatureAndroid: String? = null,
// New in v1.2.0 (Google Play Billing 8.1.0+)
val isSuspendedAndroid: Boolean? = null // Subscription suspended due to payment issues
) : PurchaseCommon
When isSuspendedAndroid is true, the subscription is suspended due to payment issues. Direct users to fix their payment method:
if (purchase.isSuspendedAndroid == true) {
// Show UI to direct user to fix payment method
showPaymentIssueDialog()
}
Type Aliases for Convenience
OpenIAP-compliant type aliases for backward compatibility and ease of use.
// Union types
typealias Product = ProductCommon
typealias Purchase = PurchaseCommon
typealias SubscriptionProduct = ProductCommon
typealias ProductPurchase = PurchaseCommon
typealias SubscriptionPurchase = PurchaseCommon
Request Types (OpenIAP-Compliant)
RequestPurchaseProps
OpenIAP-compliant purchase request structure with platform-specific options.
data class RequestPurchaseProps(
val ios: RequestPurchaseIosProps? = null,
val android: RequestPurchaseAndroidProps? = null
)
RequestPurchaseIosProps
iOS-specific purchase request parameters.
data class RequestPurchaseIosProps(
val sku: String,
val andDangerouslyFinishTransactionAutomatically: Boolean? = null,
val appAccountToken: String? = null,
val quantity: Int? = null,
val withOffer: PaymentDiscountIOS? = null,
// New in v1.3.7 (openiap-apple)
val advancedCommerceData: String? = null
)
advancedCommerceData (v1.3.7)
Support for StoreKit 2's Product.PurchaseOption.custom API to pass attribution data during purchases.
Use Cases:
- Campaign attribution tracking
- Affiliate marketing integration
- Promotional code tracking
Example:
kmpIapInstance.requestPurchase {
ios {
sku = "com.example.premium"
advancedCommerceData = "campaign_summer_2025"
}
}
The data is formatted as JSON internally: {"signatureInfo": {"token": "<value>"}}
RequestPurchaseAndroidProps
Android-specific purchase request parameters.
data class RequestPurchaseAndroidProps(
val skus: List<String>,
val obfuscatedAccountIdAndroid: String? = null,
val obfuscatedProfileIdAndroid: String? = null,
val isOfferPersonalized: Boolean? = null
)
Starting from openiap-google v1.3.15, you can use the google field instead of android for purchase requests. The android field is still supported for backward compatibility but is deprecated.
// Recommended (new)
kmpIapInstance.requestPurchase {
google {
skus = listOf("sku_id")
}
}
// Still supported (deprecated)
kmpIapInstance.requestPurchase {
android {
skus = listOf("sku_id")
}
}
RequestSubscriptionProps
OpenIAP-compliant subscription request structure.
data class RequestSubscriptionProps(
val ios: RequestSubscriptionIosProps? = null,
val android: RequestSubscriptionAndroidProps? = null
)
RequestSubscriptionIosProps
iOS-specific subscription request parameters. Similar to RequestPurchaseIosProps but for subscriptions.
data class RequestSubscriptionIosProps(
val sku: String,
val andDangerouslyFinishTransactionAutomatically: Boolean? = null,
val appAccountToken: String? = null,
val quantity: Int? = null,
val withOffer: PaymentDiscountIOS? = null,
// New in v1.3.7 (openiap-apple)
val advancedCommerceData: String? = null
)
The advancedCommerceData field works the same way as in RequestPurchaseIosProps.
ActiveSubscription
Represents an active subscription with platform-specific details following OpenIAP specification.
data class ActiveSubscription(
val productId: String, // Product identifier
val isActive: Boolean, // Always true for active subscriptions
// iOS-specific fields
val expirationDateIOS: Long? = null, // Expiration timestamp (iOS only)
val environmentIOS: String? = null, // "Sandbox" | "Production" (iOS only)
val daysUntilExpirationIOS: Int? = null, // Days remaining until expiration (iOS only)
// Android-specific fields
val autoRenewingAndroid: Boolean? = null, // Auto-renewal status (Android only)
// Cross-platform fields
val willExpireSoon: Boolean? = null // True if expiring within 7 days
)
Platform-Specific Behavior:
- iOS: Provides exact expiration dates, environment info, and calculated days until expiration
- Android: Provides auto-renewal status. When
false, the subscription will not renew - Cross-platform:
willExpireSoonwarns if subscription expires within 7 days
Use Cases:
- Feature gating based on subscription status
- Showing expiration warnings
- Managing subscription renewals
- Environment-specific testing (iOS Sandbox vs Production)
ProductRequest
Request parameters for loading products.
data class ProductRequest(
val skus: List<String>,
val type: ProductType
)
iOS-Specific Types
SubscriptionInfoIOS
iOS subscription information from StoreKit.
data class SubscriptionInfoIOS(
val subscriptionGroupId: String,
val subscriptionPeriod: SubscriptionOfferPeriod
)
SubscriptionOfferPeriod
iOS subscription period definition.
data class SubscriptionOfferPeriod(
val unit: String, // "DAY", "WEEK", "MONTH", "YEAR"
val value: Int // Number of units
)
PaymentDiscountIOS
iOS promotional offer payment discount.
data class PaymentDiscountIOS(
val identifier: String,
val keyIdentifier: String,
val nonce: String,
val signature: String,
val timestamp: Double
)
DiscountIOS
iOS product discount information.
data class DiscountIOS(
val identifier: String,
val type: String,
val numberOfPeriods: String,
val price: String,
val localizedPrice: String,
val paymentMode: String,
val subscriptionPeriod: String
)
Android-Specific Types
ProductAndroidOneTimePurchaseOfferDetail
Android one-time purchase offer details from Google Play Billing. Updated in v1.2.0 with discount support.
oneTimePurchaseOfferDetailsAndroid is now a List instead of a single object to support multiple offers with discounts.
// Before (v1.0.0)
val price = product.oneTimePurchaseOfferDetailsAndroid?.formattedPrice
// After (v1.2.0)
val price = product.oneTimePurchaseOfferDetailsAndroid?.firstOrNull()?.formattedPrice
data class ProductAndroidOneTimePurchaseOfferDetail(
val formattedPrice: String,
val priceAmountMicros: String,
val priceCurrencyCode: String,
// New fields in v1.2.0 (Google Play Billing 7.0+)
val offerId: String? = null,
val offerTags: List<String>? = null,
val offerToken: String? = null,
val discountDisplayInfo: DiscountDisplayInfoAndroid? = null,
val limitedQuantityInfo: LimitedQuantityInfoAndroid? = null,
val validTimeWindow: ValidTimeWindowAndroid? = null,
val preorderDetails: PreorderDetailsAndroid? = null,
val rentalDetails: RentalDetailsAndroid? = null
)
DiscountDisplayInfoAndroid
Display information for one-time product discounts (Google Play Billing 7.0+).
data class DiscountDisplayInfoAndroid(
val percentageDiscount: Int? = null,
val discountAmount: DiscountAmountAndroid? = null
)
DiscountAmountAndroid
Discount amount details for Android.
data class DiscountAmountAndroid(
val discountAmountMicros: String,
val formattedDiscountAmount: String
)
LimitedQuantityInfoAndroid
Limited quantity information for offers.
data class LimitedQuantityInfoAndroid(
val maximumQuantity: Int,
val remainingQuantity: Int
)
ValidTimeWindowAndroid
Validity period for offers.
data class ValidTimeWindowAndroid(
val startTimeMillis: String,
val endTimeMillis: String
)
PreorderDetailsAndroid
Pre-order details for products (Google Play Billing 8.1.0+).
data class PreorderDetailsAndroid(
val preorderReleaseTimeMillis: String,
val preorderPresaleEndTimeMillis: String
)
RentalDetailsAndroid
Rental details for products.
data class RentalDetailsAndroid(
val rentalPeriod: String,
val rentalExpirationPeriod: String? = null
)
ProductSubscriptionAndroidOfferDetail
Android subscription offer details.
data class ProductSubscriptionAndroidOfferDetail(
val basePlanId: String,
val offerId: String?,
val offerToken: String,
val pricingPhases: List<PricingPhaseAndroid>,
val offerTags: List<String>
)
PricingPhaseAndroid
Android subscription pricing phase.
data class PricingPhaseAndroid(
val formattedPrice: String,
val priceCurrencyCode: String,
val billingPeriod: String,
val billingCycleCount: Int,
val priceAmountMicros: String,
val recurrenceMode: Int
)
SubscriptionOfferAndroid
Android subscription offer for purchase requests.
data class SubscriptionOfferAndroid(
val basePlanId: String,
val offerId: String?,
val offerToken: String
)
RequestSubscriptionAndroidProps
Android-specific subscription request parameters.
data class RequestSubscriptionAndroidProps(
val skus: List<String>,
val obfuscatedAccountIdAndroid: String? = null,
val obfuscatedProfileIdAndroid: String? = null,
val isOfferPersonalized: Boolean? = null,
val purchaseTokenAndroid: String? = null,
val replacementModeAndroid: Int? = null,
val subscriptionOffers: List<SubscriptionOfferAndroid>
)
Enums
IapPlatform
Platform identifier for cross-platform compatibility.
enum class IapPlatform {
IOS,
ANDROID
}
Store
Store type identifier.
enum class Store {
NONE,
PLAY_STORE,
AMAZON,
APP_STORE
}
ProductType
Product type for queries.
enum class ProductType {
INAPP, // One-time purchases
SUBS // Subscriptions
}
TransactionStateIOS
iOS transaction states from StoreKit.
enum class TransactionStateIOS {
PURCHASING,
PURCHASED,
FAILED,
RESTORED,
DEFERRED
}
