Develop
Develop
Select your platform

Integrate Meta Horizon Billing Compatibility SDK

Updated: Jan 5, 2026
If you have an existing Android app that is integrated with the Google Play Billing Library, you can use the Meta Horizon Billing Compatibility SDK to port your app to the Meta Horizon Store with minimal changes (though there are known limitations). The SDK supports consumable, durable, and subscription in-app purchases (IAP). The Meta Horizon Billing Compatibility SDK is compatible with the Google Play Billing Library version 7.0.

Step 1. Add the SDK to your app

The Meta Horizon Billing Compatibility SDK is deployed to Maven Central so it can be added to your app. In this step, you will add it to your project by editing app/build.gradle.kts to include the correct dependencies.
If your app uses Groovy (build.gradle instead of build.gradle.kts), read the build dependencies page for Groovy syntax.
The following sections show you how to configure your dependencies to install a specific version of the SDK. Use version 2.0.0 or later to use the latest features.

Option A: Add the version 2.0.0 or later dependency to Gradle

  1. In app/build.gradle.kts, create variables for the SDK versions above the dependencies block:
     val horizonBillingCompatibilitySdkVersion = "2.0.0"
     val coreKotlinVersion = "0.2.0"
    
  2. At the end of the dependencies block, add the following packages:
     implementation("com.meta.horizon.billingclient.api:horizon-billing-compatibility:$horizonBillingCompatibilitySdkVersion")
     implementation("com.meta.horizon.platform.sdk:core-kotlin:$coreKotlinVersion")
    
    The variable declaration and dependencies block should now look like this:
     val horizonBillingCompatibilitySdkVersion = "2.0.0"
     val coreKotlinVersion = "0.2.0"
    
     dependencies {
     ...
     implementation("com.meta.horizon.billingclient.api:horizon-billing-compatibility:$horizonBillingCompatibilitySdkVersion")
     implementation("com.meta.horizon.platform.sdk:core-kotlin:$coreKotlinVersion")
     }
    
  3. Sync your project with Gradle to download the packages.

Option B: Add a version prior to 2.0.0 of the SDK dependency to Gradle

  1. In app/build.gradle.kts, create variables for the SDK versions above the dependencies block:
     val horizonBillingCompatibilitySdkVersion = "1.1.2"
     val androidPlatformSdkVersion = "72"
    
  2. At the end of the dependencies block, add the following packages:
     implementation("com.meta.horizon.billingclient.api:horizon-billing-compatibility:$horizonBillingCompatibilitySdkVersion")
     implementation("com.meta.horizon.platform.ovr:android-platform-sdk:$androidPlatformSdkVersion")
    
    The variable declaration and dependencies block should now look like this:
     val horizonBillingCompatibilitySdkVersion = "1.1.2"
     val androidPlatformSdkVersion = "72"
    
     dependencies {
     ...
     implementation("com.meta.horizon.billingclient.api:horizon-billing-compatibility:$horizonBillingCompatibilitySdkVersion")
     implementation("com.meta.horizon.platform.ovr:android-platform-sdk:$androidPlatformSdkVersion")
     }
    
  3. Sync your project with Gradle to download the packages.
GIF of the Gradle sync icon being clicked

Step 2. Add Kotlin support

Meta Horizon Billing Compatibility SDK is implemented in Kotlin and requires consuming apps to include the kotlin stdlib as a dependency. Android apps that have already integrated Kotlin may skip this step.
  1. Open your project folder’s build.gradle file and add the kotlin-gradle-plugin:
     buildscript {
     	dependencies {
         	classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:2.1.21"
     	}
     }
    
  2. Open your app folder’s build.gradle file and apply the kotlin-android plugin:
     apply plugin: 'kotlin-android'
    
  3. Add a dependency on org.jetbrains.kotlin:kotlin-stdlib-jdk7. For example:
     dependencies {
         implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:2.1.21"
     }
    
  4. Sync your project by selecting Sync Now at the top of your build.gradle file in your IDE.
If the build fails because “Starting in Kotlin 2.0, the Compose Compiler Gradle plugin is required when compose is enabled,” please refer to the “Composer Compiler Gradle plugin” on the Android developer site.

Step 3. Update import statements

Update Google Play Billing imports in your app’s codebase to use Meta Horizon Billing Compatibility SDK imports by replacing all instances of the com.android.billingclient.api prefix with the prefix com.meta.horizon.billingclient.api.
If any Meta Horizon Billing Compatibility SDK import statement is unresolved, that indicates it isn’t supported by the Meta Horizon Billing Compatibility SDK. Remove or modify its usage in the app to make it work with the Meta Horizon Store.

Step 4. Port Product Catalog from Google Play Store to Meta Horizon Store

Keep the SKUs for the in-app items on the Meta Horizon Developer Center the same as the product IDs on Google Play Console for the app. Otherwise, you will have to update the product IDs in your app as well.
You can follow the instructions available in Setting Up Add-Ons for more details on creating your Subscriptions, Consumables and Durables.

Step 5. Integrate User Age Category

Effective January 2024, for an app to be listed on the Meta Horizon Store, app owners are required to self-certify the intended user age group for their apps. Additionally, if your app is designed for mixed ages (under 13 or applicable age in user’s region, and 13+), you’re required to integrate the Get Age Category API. By complying with these requirements, you will meet the necessary criteria for listing your app on the Meta Horizon Store.
Integration of the User Age Category API requires use of the Platform SDK for Android.
You can use the queryAgeCategoryAsync method in the BillingClient class to get the user age category.
billingClient.queryAgeCategoryAsync(ageCategoryResponseListenerImpl)
Here is the AgeCategoryResponseListener that should be implemented.
public interface AgeCategoryResponseListener {
  // Called to notify that the query age category operation has finished.
  public void onQueryAgeCategoryResponse(
      BillingResult billingResult, @BillingClient.AgeCategory Integer ageCategory);
}
Here is an example implementation of AgeCategoryResponseListener.
public class AgeCategoryResponseListenerImpl implements AgeCategoryResponseListener {
  void onQueryAgeCategoryResponse(
      BillingResult billingResult, @BillingClient.AgeCategory Integer ageCategory) {
    if (billingResult.getResponseCode() != BillingResponseCode.OK) {
      // handle error
      return;
    }
    switch (ageCategory) {
      case CHILD:
        // handle children (10-12, or applicable age in user's region)
        break;
      case TEEN:
        // handle teens (13-17, or applicable age in user's region)
        break;
      case ADULT:
        // handle adults (18+, or applicable age in user's region)
        break;
      case UNKNOWN:
        // handle case where we don't know the age
        break;
    }
  }
}

Test with Meta Spatial Simulator

Starting with version 2.0.0, the Meta Horizon Billing Compatibility SDK can be used with the Meta Spatial Simulator. This allows you to test your billing integration in the simulator environment without needing a physical headset.
For details on how purchases and products work in the simulator environment, see the Spatial Simulator Sandbox Environment documentation.

Test with test users

When developing monetization features with the Horizon Billing Compatibility SDK, you should use test user accounts rather than your personal developer account. Test users provide a clean environment for testing purchase flows and allow you to:
  • Test purchase flows with test credit cards that simulate successful and failed transactions
  • Reset entitlements to repeat purchase testing without real transactions
  • Test with multiple accounts to verify multi-user scenarios

Prerequisites

Before testing monetization features, ensure you have:
  1. Uploaded an APK: Your app must have at least one APK uploaded to a release channel (Alpha, Beta, or RC). Monetization APIs require a package to function.
  2. Created in-app products: Set up your add-ons (consumables, durables, or subscriptions) in the Developer Dashboard.
  3. Created test users: Create test user accounts in the Developer Dashboard under Test Users. (If you don’t see this option, click View All at the top of the left navigation to open the Org Manager.) For detailed instructions, see Test Users.

Set up test payment methods

Test users can purchase in-app items without using real money. To set up test payment methods:
  1. Log in to your headset or the Meta Horizon mobile app as the test user.
  2. Add one of the following test credit card numbers:
    • 4111 1177 1155 2927: Always succeeds
    • 4111 1193 1540 5122: Fails at sale
When entering test credit cards, provide any 5-digit zip code, any future expiration date, and 111 for the security code.
Important: Do not use real credit cards with test users. Real credit cards will be charged as regular transactions. Always use the test credit card numbers provided.

Manage add-on entitlements

After testing purchases, you can reset a test user’s entitlements to repeat the purchase flow:
  1. Go to the Developer Dashboard and click on your app.
  2. Expand Development in the left-side navigation, and click Test Users.
  3. Click the ellipsis (...) menu on the test user.
  4. Click Manage Add-on Entitlements.
  5. Select your app to view current entitlements.
  6. Remove entitlements as needed to reset the test state.
For more information about managing test users, see Test Users.
For subscription specific testing (for example, renewal, expiration, cancellation), see Test Subscriptions.

Next steps

Did you find this page helpful?
Thumbs up icon
Thumbs down icon