Skip to main content

14.4.12 - Alternative Billing Support

· 5 min read
Hyo
Hyo
React Native IAP Maintainer

React Native IAP Logo

React Native IAP 14.4.12 introduces comprehensive alternative billing support for both iOS and Android platforms, empowering developers to use external payment systems alongside or instead of platform billing—unlocking reduced fees and greater monetization flexibility.

👉 View the full release on GitHub

🚀 What's New​

Alternative Billing for Android & iOS​

Android - Two modes supported:

  • Alternative Billing Only: Exclusive use of your payment system
  • User Choice Billing: Users choose between Google Play or your payment system
  • Reduced Fees: 4% service fee reduction when using alternative billing
  • Regional Availability: South Korea, India, EEA

iOS - External purchase links:

  • External URLs: Redirect users to your website for payment (iOS 16.0+)
  • Notice Sheets: Required disclosure before external redirect (iOS 18.2+)
  • Reduced Commission: 27% (vs. 30%) for year 1, 12% for subsequent years
  • Regional Availability: US, EU, and approved countries

📱 New APIs​

Android​

import {
  initConnection,
  checkAlternativeBillingAvailabilityAndroid,
  showAlternativeBillingDialogAndroid,
  createAlternativeBillingTokenAndroid,
  userChoiceBillingListenerAndroid,
} from 'react-native-iap';

Core Methods:

Event Listener:

iOS​

import {
  canPresentExternalPurchaseNoticeIOS,
  presentExternalPurchaseNoticeSheetIOS,
  presentExternalPurchaseLinkIOS,
} from 'react-native-iap';

Core Methods:

🔧 Expo Config Plugin​

Automatic iOS setup with zero manual configuration:

// app.config.ts
export default {
  plugins: [
    [
      'react-native-iap',
      {
        iosAlternativeBilling: {
          countries: ['kr', 'nl'], // ISO 3166-1 alpha-2 codes
          links: {
            kr: 'https://your-site.com/kr/checkout',
            nl: 'https://your-site.com/nl/checkout',
          },
          enableExternalPurchaseLink: true,
        },
      },
    ],
  ],
};

The plugin automatically adds:

  • ✅ Required entitlements (com.apple.developer.storekit.external-purchase*)
  • ✅ Info.plist keys (SKExternalPurchase, SKExternalPurchaseLink, etc.)
  • ✅ URL validation and formatting

Advanced Configuration:

  • multiLinks - Multiple URLs per country (iOS 17.5+, up to 5 for music apps)
  • customLinkRegions - Custom link regions (iOS 18.1+)
  • streamingLinkRegions - Music streaming regions (iOS 18.2+)

See Expo Plugin Guide for complete configuration options.

🎨 useIAP Hook Integration​

Alternative billing is fully integrated into the useIAP hook:

import {useIAP} from 'react-native-iap';

const {connected} = useIAP({
  // Android billing mode
  alternativeBillingModeAndroid: 'user-choice', // or 'alternative-only'

  // User choice event handler
  onUserChoiceBillingAndroid: (details) => {
    console.log('User selected alternative billing');
    reportToBackend(details.externalTransactionToken);
  },
});

📚 Documentation & Examples​

Comprehensive Guides​

Working Example App​

Complete alternative billing implementation in the example app:

📍 Location: example/screens/AlternativeBilling.tsx

Features:

  • ✨ Platform-specific flows (iOS vs. Android)
  • 🔄 Android billing mode switcher (alternative-only ↔ user-choice)
  • 📱 Real-time status and result display
  • 📖 Step-by-step compliance guidance
  • 🔗 Deep linking recommendations (iOS)

Run Example:

cd example
yarn ios    # or yarn android
# Navigate to "Alternative Billing" from home screen

View source: AlternativeBilling.tsx on GitHub

🔨 Technical Implementation​

OpenIAP Upgrades​

  • openiap-apple → v1.2.10 - StoreKit external purchase support
  • openiap-google → v1.2.12 - Alternative billing APIs
  • openiap-gql → v1.0.12 - Updated type definitions

Android Architecture​

  • Native alternative billing API integration (Google Play Billing 7.0+)
  • Automatic service reconnection handling
  • Token creation and validation
  • User choice event deduplication

iOS Architecture​

  • StoreKit External Purchase API integration (iOS 16.0+)
  • Notice sheet support (iOS 18.2+)
  • Automatic entitlement management
  • URL validation and sanitization

Type Safety​

Full TypeScript support with comprehensive types:

type AlternativeBillingModeAndroid =
  | 'none'
  | 'alternative-only'
  | 'user-choice';

interface UserChoiceBillingDetails {
  products: string[];
  externalTransactionToken: string;
}

interface ExternalPurchaseNoticeResultIOS {
  result: 'continue' | 'cancel';
}

interface ExternalPurchaseLinkResultIOS {
  success: boolean;
  error?: string;
}

⚠️ Platform Requirements​

iOS​

  • Minimum Version: iOS 16.0+ (external links), iOS 18.2+ (notice sheets)
  • App Store Connect: External purchase entitlement approval required
  • Provisioning Profile: Must include StoreKit external purchase entitlements
  • URL Requirements: HTTPS only, no query parameters, ≤1,000 characters

📖 StoreKit External Purchase Documentation

Android​

  • Google Play Console: Alternative billing approval required
  • Token Reporting: Tokens must be reported to Google within 24 hours
  • Backend: Server-side token validation and reporting
  • Billing Library: Google Play Billing 7.0+

📖 Google Play Alternative Billing Documentation

Regional Availability​

PlatformRegions
iOSUS, EU countries, and approved regions (varies by feature)
AndroidSouth Korea, India, EEA (varies by app category)

📦 Installation​

npm install react-native-iap@14.4.12
# or
yarn add react-native-iap@14.4.12
# or
bun add react-native-iap@14.4.12

For Expo projects:

npx expo prebuild --clean  # Apply config plugin changes

For React Native CLI:

cd ios && pod install  # Install iOS dependencies

🚨 Breaking Changes​

None - This release is fully backward compatible. All changes are additive.

🙏 Acknowledgments​

This release builds on the alternative billing implementation from expo-iap, bringing the same powerful features to React Native CLI projects.

Special thanks to:

  • OpenIAP team for cross-platform alternative billing support
  • Community contributors for testing and feedback

🔗 Additional Resources​

💬 Feedback​

Questions or issues? Let us know via GitHub Issues.

Try out alternative billing in 14.4.12 and share your experience! 🎉