react-native-iap 15.4.0-rc.3 → 15.4.1

package/lib/typescript/src/types.d.ts

@@ -21,6 +21,7 @@ export interface ActiveSubscription {
      * pending upgrades/downgrades, and auto-renewal preferences.
      */
     renewalInfoIOS?: (RenewalInfoIOS | null);
+    /** Unix timestamp in milliseconds since January 1, 1970 UTC. */
     transactionDate: number;
     transactionId: string;
     /**
@@ -105,10 +106,33 @@ export interface AppTransaction {
     signedDate: number;
 }
 /**
- * Billing program types for external content links, external offers, and external payments (Android)
- * Available in Google Play Billing Library 8.2.0+, EXTERNAL_PAYMENTS added in 8.3.0
+ * Play Billing choice image layout (Android)
+ * Available in OpenIAP Spec 2.1.0 / openiap-google 2.3.0 (requires Play Billing 9.1.0+).
  */
-export type BillingProgramAndroid = 'unspecified' | 'user-choice-billing' | 'external-content-link' | 'external-offer' | 'external-payments';
+export type BillingChoiceImageLayoutAndroid = 'rectangular-four-by-one' | 'rectangular-three-by-one' | 'rectangular-two-by-two';
+/**
+ * Display information for developer-rendered Billing Choice screens (Android)
+ * Available in OpenIAP Spec 2.1.0 / openiap-google 2.3.0 (requires Play Billing 9.1.0+).
+ */
+export interface BillingChoiceInfoAndroid {
+    /** URL for the Play Billing choice image matching the requested layout. */
+    playBillingChoiceImageUrl: string;
+    /** Play Loyalty information for the user. */
+    playBillingLoyaltyInfo?: (string | null);
+}
+/**
+ * Choice screen renderer for Billing Choice availability (Android)
+ * Available in OpenIAP Spec 2.1.0 / openiap-google 2.3.0 (requires Play Billing 9.1.0+).
+ */
+export type BillingChoiceScreenTypeAndroid = 'unspecified' | 'developer-rendered' | 'google-rendered';
+/**
+ * Billing program types for Google Play Billing Programs (Android)
+ * Available in Google Play Billing Library 8.2.0 (External Offer and External Content Link
+ * integrations require 8.2.1+), EXTERNAL_PAYMENTS added in 8.3.0,
+ * BILLING_CHOICE added in OpenIAP Spec 2.1.0 / openiap-google 2.3.0
+ * (requires Play Billing 9.1.0+).
+ */
+export type BillingProgramAndroid = 'unspecified' | 'user-choice-billing' | 'external-content-link' | 'external-offer' | 'external-payments' | 'billing-choice';
 /**
  * Result of checking billing program availability (Android)
  * Available in Google Play Billing Library 8.2.0+
@@ -116,8 +140,29 @@ export type BillingProgramAndroid = 'unspecified' | 'user-choice-billing' | 'ext
 export interface BillingProgramAvailabilityResultAndroid {
     /** The billing program that was checked */
     billingProgram: BillingProgramAndroid;
+    /**
+     * Billing Choice screen renderer. Populated only for available BILLING_CHOICE results.
+     * Available in OpenIAP Spec 2.1.0 / openiap-google 2.3.0.
+     */
+    choiceScreenType?: (BillingChoiceScreenTypeAndroid | null);
     /** Whether the billing program is available for the user */
     isAvailable: boolean;
+    /**
+     * Whether external-link payment is available for Billing Choice.
+     * Populated only for available BILLING_CHOICE results.
+     * Available in OpenIAP Spec 2.1.0 / openiap-google 2.3.0.
+     */
+    isExternalLinkAvailable?: (boolean | null);
+}
+/**
+ * Parameters for showing a billing program information dialog (Android)
+ * Available in OpenIAP Spec 2.1.0 / openiap-google 2.3.0 (requires Play Billing 9.1.0+).
+ */
+export interface BillingProgramInformationDialogParamsAndroid {
+    /** Billing program. Currently only BILLING_CHOICE is supported. */
+    billingProgram?: BillingProgramAndroid;
+    /** External transaction token returned by the Billing Choice reporting-details flow. */
+    externalTransactionToken: string;
 }
 /**
  * Reporting details for transactions made outside of Google Play Billing (Android)
@@ -129,7 +174,8 @@ export interface BillingProgramReportingDetailsAndroid {
     billingProgram: BillingProgramAndroid;
     /**
      * External transaction token used to report transactions made outside of Google Play Billing.
-     * This token must be used when reporting the external transaction to Google.
+     * Do not cache it for a later redirect session. For External Offer, the same token may report
+     * multiple purchases made during the session that generated it.
      */
     externalTransactionToken: string;
 }
@@ -161,18 +207,36 @@ export interface DeepLinkOptions {
  */
 export type DeveloperBillingLaunchModeAndroid = 'unspecified' | 'launch-in-external-browser-or-app' | 'caller-will-launch-link';
 /**
- * Parameters for developer billing option in purchase flow (Android)
- * Used with BillingFlowParams to enable external payments flow
- * Available in Google Play Billing Library 8.3.0+
+ * Parameters for a developer billing option in a purchase flow (Android).
+ * Used with BillingFlowParams for external payments (8.3.0+) and Billing Choice
+ * (OpenIAP Spec 2.1.0 / openiap-google 2.3.0; requires Play Billing 9.1.0+).
+ * Only billingProgram is required; link fields are used when the selected program
+ * links outside the app.
  */
 export interface DeveloperBillingOptionParamsAndroid {
-    /** The billing program (should be EXTERNAL_PAYMENTS for external payments flow) */
+    /** The billing program. Use EXTERNAL_PAYMENTS or BILLING_CHOICE. */
     billingProgram: BillingProgramAndroid;
-    /** The launch mode for the external payment link */
-    launchMode: DeveloperBillingLaunchModeAndroid;
-    /** The URI where the external payment will be processed */
-    linkUri: string;
+    /**
+     * A pre-generated external transaction token for a Billing Choice external-link
+     * flow. Omit it when Google Play should provide the token in the callback.
+     */
+    externalTransactionToken?: (string | null);
+    /**
+     * The launch mode for the external payment link.
+     * Required only when the selected billing program links outside the app.
+     */
+    launchMode?: (DeveloperBillingLaunchModeAndroid | null);
+    /**
+     * The URI where the external payment will be processed.
+     * Required only when the selected billing program links outside the app.
+     */
+    linkUri?: (string | null);
 }
+/**
+ * Developer-provided billing destination type for Billing Program reporting details (Android)
+ * Available in OpenIAP Spec 2.1.0 / openiap-google 2.3.0 (requires Play Billing 9.1.0+).
+ */
+export type DeveloperBillingTypeAndroid = 'developer-billing-type-unspecified' | 'in-app' | 'external-link';
 /**
  * Details provided when user selects developer billing option (Android)
  * Received via DeveloperProvidedBillingListener callback
@@ -181,14 +245,34 @@ export interface DeveloperBillingOptionParamsAndroid {
 export interface DeveloperProvidedBillingDetailsAndroid {
     /**
      * External transaction token used to report transactions made through developer billing.
-     * This token must be used when reporting the external transaction to Google Play.
-     * Must be reported within 24 hours of the transaction.
+     * Nullable for flows such as external payments where no token is returned.
      */
-    externalTransactionToken: string;
+    externalTransactionToken?: (string | null);
+    /**
+     * URI to launch for an external-link Billing Choice flow, when provided by
+     * Google Play.
+     */
+    linkUri?: (string | null);
+    /**
+     * Original external transaction ID when replacing a subscription that was
+     * purchased through developer billing.
+     */
+    originalExternalTransactionId?: (string | null);
+    /** Products selected for the developer billing flow. */
+    products: DeveloperProvidedBillingProductAndroid[];
+}
+/** Product selected for developer-provided billing (Android 9.0+). */
+export interface DeveloperProvidedBillingProductAndroid {
+    /** Product identifier. */
+    id: string;
+    /** Subscription offer token, when applicable. */
+    offerToken?: (string | null);
+    /** Google Play product type (in-app or subscription). */
+    type: ProductType;
 }
 /**
  * Discount amount details for one-time purchase offers (Android)
- * Available in Google Play Billing Library 7.0+
+ * Available in Google Play Billing Library 8.0+
  */
 export interface DiscountAmountAndroid {
     /** Discount amount in micro-units (1,000,000 = 1 unit of currency) */
@@ -198,7 +282,7 @@ export interface DiscountAmountAndroid {
 }
 /**
  * Discount display information for one-time purchase offers (Android)
- * Available in Google Play Billing Library 7.0+
+ * Available in Google Play Billing Library 8.0+
  */
 export interface DiscountDisplayInfoAndroid {
     /**
@@ -231,7 +315,7 @@ export interface DiscountIOS {
  * Standardized one-time product discount offer.
  * Provides a unified interface for one-time purchase discounts across platforms.
  *
- * Currently supported on Android (Google Play Billing 7.0+).
+ * Currently supported on Android (Google Play Billing 8.0+).
  * iOS does not support one-time purchase discounts in the same way.
  *
  * @see https://openiap.dev/docs/features/discount
@@ -287,7 +371,7 @@ export interface DiscountOffer {
     /**
      * [Android] Purchase option ID for this offer.
      * Used to identify which purchase option the user selected.
-     * Available in Google Play Billing Library 7.0+
+     * Available in Google Play Billing Library 8.0+
      */
     purchaseOptionIdAndroid?: (string | null);
     /** [Android] Rental details if this is a rental offer. */
@@ -383,7 +467,8 @@ export declare enum ErrorCode {
 /**
  * Launch mode for external link flow (Android)
  * Determines how the external URL is launched
- * Available in Google Play Billing Library 8.2.0+
+ * Introduced in Google Play Billing Library 8.2.0. External Offer and External Content Link
+ * integrations require 8.2.1+ and fresh details immediately before every redirect session.
  */
 export type ExternalLinkLaunchModeAndroid = 'unspecified' | 'launch-in-external-browser-or-app' | 'caller-will-launch-link';
 /**
@@ -465,11 +550,55 @@ export interface ExternalPurchaseNoticeResultIOS {
     result: ExternalPurchaseNoticeAction;
 }
 export type FetchProductsResult = ProductOrSubscription[] | Product[] | ProductSubscription[] | null;
+/**
+ * Parameters for fetching Billing Choice display information (Android)
+ * Available in OpenIAP Spec 2.1.0 / openiap-google 2.3.0 (requires Play Billing 9.1.0+).
+ */
+export interface GetBillingChoiceInfoParamsAndroid {
+    /** Billing program. Currently only BILLING_CHOICE is supported. */
+    billingProgram?: BillingProgramAndroid;
+    /** Desired Play Billing choice image layout. */
+    playBillingChoiceImageLayout?: BillingChoiceImageLayoutAndroid;
+    /** BCP 47 locale tag. If omitted, Play Billing uses the user's default locale. */
+    userLocale?: (string | null);
+}
 export type IapEvent = 'purchase-updated' | 'purchase-error' | 'promoted-product-ios' | 'user-choice-billing-android' | 'developer-provided-billing-android' | 'subscription-billing-issue';
 export type IapPlatform = 'ios' | 'android';
 export type IapStore = 'unknown' | 'apple' | 'google' | 'horizon' | 'amazon';
 /** Unified purchase states from IAPKit verification response. */
 export type IapkitPurchaseState = 'entitled' | 'pending-acknowledgment' | 'pending' | 'canceled' | 'expired' | 'ready-to-consume' | 'consumed' | 'unknown' | 'inauthentic';
+/**
+ * High-level in-app message category (Android)
+ * Available in OpenIAP Spec 2.1.0 / openiap-google 2.3.0
+ * (upstream API available since Play Billing 4.1.0).
+ */
+export type InAppMessageCategoryAndroid = 'unknown-in-app-message-category-id' | 'transactional';
+/**
+ * Parameters for showing Play billing in-app messages (Android)
+ * Available in OpenIAP Spec 2.1.0 / openiap-google 2.3.0
+ * (upstream API available since Play Billing 4.1.0).
+ */
+export interface InAppMessageParamsAndroid {
+    /** In-app message categories to show. Defaults to transactional messages. */
+    categories?: (InAppMessageCategoryAndroid[] | null);
+}
+/**
+ * Response code from Play billing in-app messages (Android)
+ * Available in OpenIAP Spec 2.1.0 / openiap-google 2.3.0
+ * (upstream API available since Play Billing 4.1.0).
+ */
+export type InAppMessageResponseCodeAndroid = 'no-action-needed' | 'subscription-status-updated';
+/**
+ * Result from showing Play billing in-app messages (Android)
+ * Available in OpenIAP Spec 2.1.0 / openiap-google 2.3.0
+ * (upstream API available since Play Billing 4.1.0).
+ */
+export interface InAppMessageResultAndroid {
+    /** Purchase token returned when a subscription status changed. */
+    purchaseToken?: (string | null);
+    /** Response code for the in-app messaging flow. */
+    responseCode: InAppMessageResponseCodeAndroid;
+}
 /** Connection initialization configuration */
 export interface InitConnectionConfig {
     /**
@@ -479,13 +608,25 @@ export interface InitConnectionConfig {
      * Use USER_CHOICE_BILLING for user choice billing, EXTERNAL_OFFER for alternative only.
      */
     alternativeBillingModeAndroid?: (AlternativeBillingModeAndroid | null);
+    /**
+     * Billing Choice renderer configured in Play Console. Available in OpenIAP
+     * Spec 2.1.0 / openiap-google 2.3.0 (requires Play Billing 9.1.0+).
+     * GOOGLE_RENDERED registers the developer-provided billing listener so OpenIAP
+     * can emit the selection event. DEVELOPER_RENDERED omits that listener so the
+     * app can render its own choice screen and use the reporting/dialog/link APIs.
+     * Must match choiceScreenType returned by isBillingProgramAvailableAndroid.
+     * Defaults to GOOGLE_RENDERED.
+     */
+    billingChoiceScreenTypeAndroid?: (BillingChoiceScreenTypeAndroid | null);
     /**
      * Enable a specific billing program for Android (7.0+)
      * When set, enables the specified billing program for external transactions.
      * - USER_CHOICE_BILLING: User can select between Google Play or alternative (7.0+)
-     * - EXTERNAL_CONTENT_LINK: Link to external content (8.2.0+)
-     * - EXTERNAL_OFFER: External offers for digital content (8.2.0+)
+     * - EXTERNAL_CONTENT_LINK: Link to external content (introduced in 8.2.0; use 8.2.1+)
+     * - EXTERNAL_OFFER: External offers for digital content (introduced in 8.2.0; use 8.2.1+)
      * - EXTERNAL_PAYMENTS: Developer provided billing, Japan only (8.3.0+)
+     * - BILLING_CHOICE: Google-rendered or developer-rendered billing choice
+     *   (OpenIAP Spec 2.1.0 / openiap-google 2.3.0; requires Play Billing 9.1.0+)
      */
     enableBillingProgramAndroid?: (BillingProgramAndroid | null);
 }
@@ -511,12 +652,19 @@ export interface InstallmentPlanDetailsAndroid {
 }
 /**
  * Parameters for launching an external link (Android)
- * Used with launchExternalLink to initiate external offer or app install flows
+ * Used with launchExternalLink to initiate external offer, app install, or
+ * developer-rendered Billing Choice flows
  * Available in Google Play Billing Library 8.2.0+
  */
 export interface LaunchExternalLinkParamsAndroid {
-    /** The billing program (EXTERNAL_CONTENT_LINK or EXTERNAL_OFFER) */
+    /** The billing program (EXTERNAL_CONTENT_LINK, EXTERNAL_OFFER, or BILLING_CHOICE) */
     billingProgram: BillingProgramAndroid;
+    /**
+     * External transaction token for a developer-rendered Billing Choice external-link
+     * flow. Available in OpenIAP Spec 2.1.0 / openiap-google 2.3.0
+     * (requires Play Billing 9.1.0+). Generate it with createBillingProgramReportingDetailsAndroid.
+     */
+    externalTransactionToken?: (string | null);
     /** The external link launch mode */
     launchMode: ExternalLinkLaunchModeAndroid;
     /** The type of the external link */
@@ -526,7 +674,7 @@ export interface LaunchExternalLinkParamsAndroid {
 }
 /**
  * Limited quantity information for one-time purchase offers (Android)
- * Available in Google Play Billing Library 7.0+
+ * Available in Google Play Billing Library 8.0+
  */
 export interface LimitedQuantityInfoAndroid {
     /** Maximum quantity a user can purchase */
@@ -547,7 +695,6 @@ export interface Mutation {
     beginRefundRequestIOS?: Promise<(string | null)>;
     /**
      * Check whether alternative billing is available for the user. Step 1 of the alternative billing flow.
-     *
      * Returns true if available, false otherwise.
      * Throws OpenIapError.NotPrepared if billing client not ready.
      * See: https://openiap.dev/docs/apis/android/check-alternative-billing-availability-android
@@ -567,17 +714,23 @@ export interface Mutation {
      * Create a reporting token for an alternative billing flow. Step 3 of the alternative billing flow.
      * Must be called AFTER successful payment in your payment system.
      * Token must be reported to Google Play backend within 24 hours.
-     *
      * Returns token string, or null if creation failed.
      * Throws OpenIapError.NotPrepared if billing client not ready.
      * See: https://openiap.dev/docs/apis/android/create-alternative-billing-token-android
      */
     createAlternativeBillingTokenAndroid?: Promise<(string | null)>;
     /**
-     * Create the reporting payload Google requires after a Developer-Provided Billing transaction (Play Billing 8.3.0+).
+     * Create the reporting details and external transaction token required by a billing program.
+     * Introduced in Play Billing 8.2.0. External Offer and External Content Link integrations
+     * must use 8.2.1+ and create fresh details immediately before every redirect session;
+     * do not cache the token for a later redirect. The same token may report multiple purchases
+     * made during one External Offer session.
      * Replaces the deprecated createExternalOfferReportingDetailsAsync API.
-     *
      * Returns external transaction token needed for reporting external transactions.
+     * developerBillingType is optional. When program is BILLING_CHOICE and developerBillingType is omitted,
+     * native Android defaults it to IN_APP.
+     * The Billing Choice extension is available in OpenIAP Spec 2.1.0 /
+     * openiap-google 2.3.0 (requires Play Billing 9.1.0+).
      * Throws OpenIapError.NotPrepared if billing client not ready.
      * See: https://openiap.dev/docs/apis/android/create-billing-program-reporting-details-android
      */
@@ -605,17 +758,20 @@ export interface Mutation {
     /**
      * Check whether a billing program (e.g., External Payments) is available for the current user.
      * Replaces the deprecated isExternalOfferAvailableAsync API.
-     *
-     * Available in Google Play Billing Library 8.2.0+.
+     * Introduced in Google Play Billing Library 8.2.0. External Offer and External
+     * Content Link integrations must use 8.2.1+ because 8.2.1 fixes this API.
      * Returns availability result with isAvailable flag.
      * Throws OpenIapError.NotPrepared if billing client not ready.
      * See: https://openiap.dev/docs/apis/android/is-billing-program-available-android
      */
     isBillingProgramAvailableAndroid: Promise<BillingProgramAvailabilityResultAndroid>;
     /**
-     * Launch an external content/offer link from inside the Billing Programs flow (Play Billing 8.2.0+).
+     * Launch an external content/offer link from inside the Billing Programs flow (introduced in
+     * Play Billing 8.2.0; External Offer and External Content Link require 8.2.1+),
+     * including developer-rendered Billing Choice external-link flows.
+     * Billing Choice availability: OpenIAP Spec 2.1.0 / openiap-google 2.3.0
+     * (requires Play Billing 9.1.0+).
      * Replaces the deprecated showExternalOfferInformationDialog API.
-     *
      * Shows Play Store dialog and optionally launches external URL.
      * Throws OpenIapError.NotPrepared if billing client not ready.
      * See: https://openiap.dev/docs/apis/android/launch-external-link-android
@@ -661,12 +817,19 @@ export interface Mutation {
     /**
      * Display Google's alternative billing information dialog. Step 2 of the alternative billing flow.
      * Must be called BEFORE processing payment in your payment system.
-     *
      * Returns true if user accepted, false if user canceled.
      * Throws OpenIapError.NotPrepared if billing client not ready.
      * See: https://openiap.dev/docs/apis/android/show-alternative-billing-dialog-android
      */
     showAlternativeBillingDialogAndroid: Promise<boolean>;
+    /**
+     * Show Google's mandatory information dialog before a developer-rendered,
+     * in-app Billing Choice screen.
+     * OpenIAP availability: Spec 2.1.0 / openiap-google 2.3.0 (requires Play Billing 9.1.0+).
+     * Throws OpenIapError.NotPrepared if billing client not ready.
+     * See: https://openiap.dev/docs/apis/android/show-billing-program-information-dialog-android
+     */
+    showBillingProgramInformationDialogAndroid: Promise<BillingResultAndroid>;
     /**
      * Present the disclosure sheet required before linking out via ExternalPurchaseCustomLink (iOS 18.1+).
      * Call this after a deliberate customer interaction before linking out to external purchases.
@@ -674,6 +837,15 @@ export interface Mutation {
      * See: https://openiap.dev/docs/apis/ios/show-external-purchase-custom-link-notice-ios
      */
     showExternalPurchaseCustomLinkNoticeIOS: Promise<ExternalPurchaseCustomLinkNoticeResultIOS>;
+    /**
+     * Overlay Play billing in-app messages, such as payment issues or subscription price-change confirmations.
+     * OpenIAP availability: Spec 2.1.0 / openiap-google 2.3.0
+     * (upstream API available since Play Billing 4.1.0).
+     * Returns a response code and, when the subscription status changes, the related purchase token.
+     * Throws OpenIapError.NotPrepared if billing client not ready.
+     * See: https://openiap.dev/docs/apis/android/show-in-app-messages-android
+     */
+    showInAppMessagesAndroid: Promise<InAppMessageResultAndroid>;
     /**
      * Present the manage-subscriptions sheet and return changed purchases (iOS 15+).
      * See: https://openiap.dev/docs/apis/ios/show-manage-subscriptions-ios
@@ -710,7 +882,10 @@ export interface Mutation {
 export type MutationAcknowledgePurchaseAndroidArgs = string;
 export type MutationBeginRefundRequestIosArgs = string;
 export type MutationConsumePurchaseAndroidArgs = string;
-export type MutationCreateBillingProgramReportingDetailsAndroidArgs = BillingProgramAndroid;
+export interface MutationCreateBillingProgramReportingDetailsAndroidArgs {
+    developerBillingType?: (DeveloperBillingTypeAndroid | null);
+    program: BillingProgramAndroid;
+}
 export type MutationDeepLinkToSubscriptionsArgs = (DeepLinkOptions | null) | undefined;
 export interface MutationFinishTransactionArgs {
     isConsumable?: (boolean | null);
@@ -733,7 +908,9 @@ export type MutationRequestPurchaseArgs = {
     /** Use alternative billing (Google Play alternative billing, Apple external purchase link) */
     useAlternativeBilling?: boolean | null;
 };
+export type MutationShowBillingProgramInformationDialogAndroidArgs = BillingProgramInformationDialogParamsAndroid;
 export type MutationShowExternalPurchaseCustomLinkNoticeIosArgs = ExternalPurchaseCustomLinkNoticeTypeIOS;
+export type MutationShowInAppMessagesAndroidArgs = (InAppMessageParamsAndroid | null) | undefined;
 export type MutationValidateReceiptArgs = VerifyPurchaseProps;
 export type MutationVerifyPurchaseArgs = VerifyPurchaseProps;
 export type MutationVerifyPurchaseWithProviderArgs = VerifyPurchaseWithProviderProps;
@@ -806,7 +983,7 @@ export interface ProductAndroid extends ProductCommon {
     nameAndroid: string;
     /**
      * One-time purchase offer details including discounts (Android)
-     * Returns all eligible offers. Available in Google Play Billing Library 7.0+
+     * Returns all eligible offers. Available in Google Play Billing Library 8.0+
      * @deprecated Use discountOffers instead for cross-platform compatibility.
      * @deprecated Use discountOffers instead
      */
@@ -837,7 +1014,7 @@ export interface ProductAndroid extends ProductCommon {
 }
 /**
  * One-time purchase offer details (Android).
- * Available in Google Play Billing Library 7.0+
+ * Available in Google Play Billing Library 8.0+
  * @deprecated Use the standardized DiscountOffer type instead for cross-platform compatibility.
  * @see https://openiap.dev/docs/types#discount-offer
  */
@@ -871,7 +1048,7 @@ export interface ProductAndroidOneTimePurchaseOfferDetail {
     /**
      * Purchase option ID for this offer (Android)
      * Used to identify which purchase option the user selected.
-     * Available in Google Play Billing Library 7.0+
+     * Available in Google Play Billing Library 8.0+
      */
     purchaseOptionId?: (string | null);
     /** Rental details for rental offers */
@@ -954,7 +1131,7 @@ export interface ProductSubscriptionAndroid extends ProductCommon {
     nameAndroid: string;
     /**
      * One-time purchase offer details including discounts (Android)
-     * Returns all eligible offers. Available in Google Play Billing Library 7.0+
+     * Returns all eligible offers. Available in Google Play Billing Library 8.0+
      * @deprecated Use discountOffers instead for cross-platform compatibility.
      * @deprecated Use discountOffers instead
      */
@@ -1102,6 +1279,7 @@ export interface PurchaseAndroid extends PurchaseCommon {
     signatureAndroid?: (string | null);
     /** Store where purchase was made */
     store: IapStore;
+    /** Unix timestamp in milliseconds since January 1, 1970 UTC. */
     transactionDate: number;
     transactionId?: (string | null);
 }
@@ -1125,6 +1303,7 @@ export interface PurchaseCommon {
     quantity: number;
     /** Store where purchase was made */
     store: IapStore;
+    /** Unix timestamp in milliseconds since January 1, 1970 UTC. */
     transactionDate: number;
 }
 export interface PurchaseError {
@@ -1136,6 +1315,7 @@ export interface PurchaseError {
     productIds?: (string[] | null);
     productType?: (string | null);
     responseCode?: (number | null);
+    subResponseCodeAndroid?: (SubResponseCodeAndroid | null);
 }
 export interface PurchaseIOS extends PurchaseCommon {
     /**
@@ -1180,6 +1360,7 @@ export interface PurchaseIOS extends PurchaseCommon {
     store: IapStore;
     storefrontCountryCodeIOS?: (string | null);
     subscriptionGroupIdIOS?: (string | null);
+    /** Unix timestamp in milliseconds since January 1, 1970 UTC. */
     transactionDate: number;
     transactionId: string;
     transactionReasonIOS?: (string | null);
@@ -1238,7 +1419,7 @@ export interface Query {
     getActiveSubscriptions: Promise<ActiveSubscription[]>;
     /**
      * List every StoreKit transaction (finished + unfinished) for the current user.
-     * Requires the SK2ConsumableTransactionHistory Info.plist key in the host app
+     * Requires the SKIncludeConsumableInAppPurchaseHistory Info.plist key in the host app
      * for finished consumables to be included (iOS 18+).
      * Unlike getAvailablePurchases, always returns the iOS-specific PurchaseIOS shape.
      * See: https://openiap.dev/docs/apis/ios/get-all-transactions-ios
@@ -1254,6 +1435,13 @@ export interface Query {
      * See: https://openiap.dev/docs/apis/get-available-purchases
      */
     getAvailablePurchases: Promise<Purchase[]>;
+    /**
+     * Fetch Play Billing assets and loyalty text for developer-rendered Billing Choice screens.
+     * OpenIAP availability: Spec 2.1.0 / openiap-google 2.3.0 (requires Play Billing 9.1.0+).
+     * Throws OpenIapError.NotPrepared if billing client is not ready.
+     * See: https://openiap.dev/docs/apis/android/get-billing-choice-info-android
+     */
+    getBillingChoiceInfoAndroid: Promise<BillingChoiceInfoAndroid>;
     /**
      * Fetch a token for Apple's External Purchase Server reporting API (iOS 18.1+).
      * Use this token to report transactions made through ExternalPurchaseCustomLink.
@@ -1277,12 +1465,15 @@ export interface Query {
      */
     getReceiptDataIOS?: Promise<(string | null)>;
     /**
-     * Return the user's storefront country code.
+     * Return the store-authoritative country code: ISO 3166-1 alpha-3 on Apple
+     * platforms and alpha-2 on Android. The operation fails when the store cannot
+     * provide a value; implementations must not synthesize a locale fallback.
      * See: https://openiap.dev/docs/apis/get-storefront
      */
     getStorefront: Promise<string>;
     /**
-     * Deprecated. Get the current App Store storefront country code — use cross-platform getStorefront instead.
+     * Deprecated. Get the current App Store storefront ISO 3166-1 alpha-3 country
+     * code — use cross-platform getStorefront instead.
      * See: https://openiap.dev/docs/apis/ios/get-storefront-ios
      * @deprecated Use getStorefront
      */
@@ -1335,6 +1526,7 @@ export type QueryCurrentEntitlementIosArgs = string;
 export type QueryFetchProductsArgs = ProductRequest;
 export type QueryGetActiveSubscriptionsArgs = (string[] | null) | undefined;
 export type QueryGetAvailablePurchasesArgs = (PurchaseOptions | null) | undefined;
+export type QueryGetBillingChoiceInfoAndroidArgs = GetBillingChoiceInfoParamsAndroid;
 export type QueryGetExternalPurchaseCustomLinkTokenIosArgs = ExternalPurchaseCustomLinkTokenTypeIOS;
 export type QueryGetTransactionJwsIosArgs = string;
 export type QueryHasActiveSubscriptionsArgs = (string[] | null) | undefined;
@@ -1377,7 +1569,7 @@ export interface RenewalInfoIOS {
     gracePeriodExpirationDate?: (number | null);
     /**
      * True if subscription failed to renew due to billing issue and is retrying
-     * Note: Not directly available in RenewalInfo, available in Status
+     * StoreKit exposes this directly as RenewalInfo.isInBillingRetry.
      */
     isInBillingRetry?: (boolean | null);
     jsonRepresentation?: (string | null);
@@ -1409,7 +1601,7 @@ export interface RenewalInfoIOS {
 }
 /**
  * Rental details for one-time purchase products that can be rented (Android)
- * Available in Google Play Billing Library 7.0+
+ * Available in Google Play Billing Library 8.0+
  */
 export interface RentalDetailsAndroid {
     /**
@@ -1422,9 +1614,9 @@ export interface RentalDetailsAndroid {
 }
 export interface RequestPurchaseAndroidProps {
     /**
-     * Developer billing option parameters for external payments flow (8.3.0+).
-     * When provided, the purchase flow will show a side-by-side choice between
-     * Google Play Billing and the developer's external payment option.
+     * Developer billing option parameters for external payments and Billing Choice.
+     * Billing Choice is available in OpenIAP Spec 2.1.0 / openiap-google 2.3.0
+     * (requires Play Billing 9.1.0+).
      */
     developerBillingOption?: (DeveloperBillingOptionParamsAndroid | null);
     /**
@@ -1437,7 +1629,7 @@ export interface RequestPurchaseAndroidProps {
     /** Obfuscated profile ID */
     obfuscatedProfileId?: (string | null);
     /**
-     * Offer token for one-time purchase discounts (7.0+).
+     * Offer token for one-time purchase discounts (8.0+).
      * Pass the offerToken from oneTimePurchaseOfferDetailsAndroid or discountOffers
      * to apply a discount offer to the purchase.
      */
@@ -1502,9 +1694,9 @@ export interface RequestPurchasePropsByPlatforms {
 export type RequestPurchaseResult = Purchase | Purchase[] | null;
 export interface RequestSubscriptionAndroidProps {
     /**
-     * Developer billing option parameters for external payments flow (8.3.0+).
-     * When provided, the purchase flow will show a side-by-side choice between
-     * Google Play Billing and the developer's external payment option.
+     * Developer billing option parameters for external payments and Billing Choice.
+     * Billing Choice is available in OpenIAP Spec 2.1.0 / openiap-google 2.3.0
+     * (requires Play Billing 9.1.0+).
      */
     developerBillingOption?: (DeveloperBillingOptionParamsAndroid | null);
     /**
@@ -1516,6 +1708,12 @@ export interface RequestSubscriptionAndroidProps {
     obfuscatedAccountId?: (string | null);
     /** Obfuscated profile ID */
     obfuscatedProfileId?: (string | null);
+    /**
+     * Original external transaction ID for replacing a subscription that was
+     * purchased through developer billing. Available in OpenIAP Spec 2.1.0 /
+     * openiap-google 2.3.0 (requires Play Billing 9.1.0+).
+     */
+    originalExternalTransactionId?: (string | null);
     /** Purchase token for upgrades/downgrades */
     purchaseToken?: (string | null);
     /**
@@ -1530,6 +1728,9 @@ export interface RequestSubscriptionAndroidProps {
     /**
      * Product-level replacement parameters (8.1.0+)
      * Use this instead of replacementMode for item-level replacement
+     * This singular form requires skus to contain exactly one target product.
+     * Multi-item subscription changes need a per-target replacement mapping and
+     * are rejected rather than applying one oldProductId to multiple products.
      */
     subscriptionProductReplacementParams?: (SubscriptionProductReplacementParamsAndroid | null);
 }
@@ -1642,11 +1843,11 @@ export interface RequestVerifyPurchaseWithIapkitResult {
 export type SubResponseCodeAndroid = 'no-applicable-sub-response-code' | 'payment-declined-due-to-insufficient-funds' | 'user-ineligible';
 export interface Subscription {
     /**
-     * Fires when a user selects developer billing in the External Payments flow (Android only)
-     * Triggered when the user chooses to pay via the developer's external payment option
-     * instead of Google Play Billing in the side-by-side choice dialog.
-     * Contains the externalTransactionToken needed to report the transaction.
-     * Available in Google Play Billing Library 8.3.0+
+     * Fires when a user selects developer billing in an External Payments or
+     * Billing Choice flow (Android only). The payload can contain an external
+     * transaction token, link URI, original transaction ID, and selected products.
+     * Billing Choice payload fields are available in OpenIAP Spec 2.1.0 /
+     * openiap-google 2.3.0 (requires Play Billing 9.1.0+).
      */
     developerProvidedBillingAndroid: DeveloperProvidedBillingDetailsAndroid;
     /** Fires when the App Store surfaces a promoted product (iOS only) */
@@ -1661,14 +1862,17 @@ export interface Subscription {
      */
     purchaseUpdated: Purchase;
     /**
-     * Fires when an active subscription enters a billing-issue state that needs user action
+     * Fires when a subscription enters a billing-issue state that needs user action
      * (payment method failed, card expired, etc.). Cross-platform unification:
      *
-     * - iOS 18+: delivered via StoreKit 2 `Message.Reason.billingIssue`.
+     * - iOS 16.4+ / Mac Catalyst 16.4+ / visionOS 1.0+: delivered via StoreKit 2
+     *   `Message.Reason.billingIssue`.
      * - Android (Play flavor, Billing 8.1+): emitted when `isSuspended == true` is first detected
      *   on a previously healthy subscription. Requires Google Play Billing Library 8.1.0 or newer.
      * - Android (Horizon flavor): NOT emitted. The Horizon Billing Compatibility SDK implements
      *   the Play Billing 7.0 API surface which does not expose a suspended-subscription signal.
+     * - Android (Amazon flavor): NOT emitted. Amazon Appstore IAP does not expose an
+     *   equivalent subscription billing-issue signal.
      *
      * Listeners should not assume the event will fire on every store. Direct users to the
      * platform subscription management UI (`deepLinkToSubscriptions`) to resolve the issue.
@@ -1846,12 +2050,25 @@ export interface TransactionCommitmentInfoIOS {
 export interface UserChoiceBillingDetails {
     /** Token that must be reported to Google Play within 24 hours */
     externalTransactionToken: string;
+    /**
+     * External transaction ID of the originating subscription when the user is
+     * upgrading or downgrading a developer-billed subscription. Available in
+     * OpenIAP Spec 2.3.0 / openiap-google 2.3.1 (requires Play Billing 9.1+).
+     */
+    originalExternalTransactionId?: (string | null);
+    /**
+     * Structured product details selected in the user-choice flow, including the
+     * product type and offer token. Legacy payloads may omit this field; use
+     * products as the product-ID fallback. Available in OpenIAP Spec 2.3.0 /
+     * openiap-google 2.3.1 (requires Play Billing 9.1+).
+     */
+    productDetailsAndroid?: (DeveloperProvidedBillingProductAndroid[] | null);
     /** List of product IDs selected by the user */
     products: string[];
 }
 /**
  * Valid time window for when an offer is available (Android)
- * Available in Google Play Billing Library 7.0+
+ * Available in Google Play Billing Library 8.0+
  */
 export interface ValidTimeWindowAndroid {
     /** End time in milliseconds since epoch */
@@ -2055,6 +2272,7 @@ export type QueryArgsMap = {
     getAllTransactionsIOS: never;
     getAppTransactionIOS: never;
     getAvailablePurchases: QueryGetAvailablePurchasesArgs;
+    getBillingChoiceInfoAndroid: QueryGetBillingChoiceInfoAndroidArgs;
     getExternalPurchaseCustomLinkTokenIOS: QueryGetExternalPurchaseCustomLinkTokenIosArgs;
     getPendingTransactionsIOS: never;
     getPromotedProductIOS: never;
@@ -2095,7 +2313,9 @@ export type MutationArgsMap = {
     requestPurchaseOnPromotedProductIOS: never;
     restorePurchases: never;
     showAlternativeBillingDialogAndroid: never;
+    showBillingProgramInformationDialogAndroid: MutationShowBillingProgramInformationDialogAndroidArgs;
     showExternalPurchaseCustomLinkNoticeIOS: MutationShowExternalPurchaseCustomLinkNoticeIosArgs;
+    showInAppMessagesAndroid: MutationShowInAppMessagesAndroidArgs;
     showManageSubscriptionsIOS: never;
     syncIOS: never;
     validateReceipt: MutationValidateReceiptArgs;