Multi-product for one-time products

This document describes how you can integrate your app with the multi-product feature of Play Billing Library (PBL).

The multi-product for one-time product (OTP) feature lets you combine several one-time products into a single unit. These bundled products can then be purchased, billed, and managed collectively. You can also create discount offers for these bundled OTPs to incentivize product purchases.

Considerations

When you create one-time product bundles, note the following considerations:

• You can't have subscriptions in a one-time product bundle.
• You can't have a combination of digital content and service in the same one-time product bundle.
• The bundled one-time products must be available for immediate download. For example, a one-time product bundle can't have a pre-order purchase because it's not available for immediate download.
• The multi-product for one-time products doesn't support the rent purchase option.

Integrate with Play Billing Library

This section assumes that you are familiar with the initial PBL integration steps such as, adding the PBL dependency to your app, initializing the BillingClient, and connecting to Google Play. This section focuses on the PBL integration aspects that are specific to the multi-product OTP purchases.

Launch a purchase flow

To launch a purchase flow for multi-product one-time products, do the following steps:

1. Create a product list having all the one-time products by using the QueryProductDetailsParams.Builder.setProductList method.

2. Fetch all your one-time products by using the BillingClient.queryProductDetailsAsync method.

   The following sample shows how to fetch all your one-time products:

   Java

   billingClient.queryProductDetailsAsync(
   queryProductDetailsParams,
   new ProductDetailsResponseListener() {
     public void onProductDetailsResponse(
         BillingResult billingResult, QueryProductDetailsResult productDetailsResult) {
       // check billingResult
       // …
       // process productDetailsList returned by QueryProductDetailsResult
       ImmutableList productDetailsList = productDetailsResult.getProductDetailsList();
       for (ProductDetails productDetails : productDetailsList) {
         for (OneTimePurchaseOfferDetails oneTimePurchaseOfferDetails :
             productDetails.getOneTimePurchaseOfferDetailsList()) {
                // …
         }
       }
     }
   });

3. Set the ProductDetails object for each one-time product.

4. Specify the one-time product details in the BillingFlowParams.Builder.setProductDetailsParamsList method. The BillingFlowParams class specifies the details of a purchase flow.

   The following sample shows how to launch the billing flow for a multi-product OTP purchase:

   Java

   BillingClient billingClient =
      BillingClient.newBuilder()
       // set other options
       .build();
   // ProductDetails obtained from queryProductDetailsAsync().
   ProductDetails productDetails1 = ...;
   ProductDetails productDetails2 = ...;
   ArrayList productDetailsList = new ArrayList<>();
   productDetailsList.add(productDetails1);
   productDetailsList.add(productDetails2);
   BillingFlowParams billingFlowParams =
   BillingFlowParams.newBuilder()
       .setProductDetailsParamsList(productDetailsList)
       .build();
   billingClient.launchBillingFlow(billingFlowParams);

Process purchases

Processing multi-product OTP purchases is the same as for existing single-item purchases as described in Integrate the Google Play Billing Library into your app. The only difference is that you need to grant entitlement for all products instead of only one for multi-product OTP purchases so that the user can receive multiple entitlements with a single purchase. A multi-product OTP purchase returns multiple items which can be retrieved by using Purchase.getProducts() in the Google Play Billing Library, and then the lineItems list in purchases.products.get of the Google Play Developer API.

Real-time developer notifications

The sku field isn't provided in RTDN for multi-product OTP purchases. The multi-product OTP purchases represent more than one product. Therefore, you can use the Play Developer APIs to get the purchase data, and see all the items in it.

Refunds

In a multi-product OTP purchase, users can't request refunds for individual items, and you too can't issue refunds for individual items. However, request and issue of refunds for the entire multi-product OTP purchase is permitted. If you are cancelling a multi-product OTP purchase for a user, all the entitlements associated with the purchase are cancelled.

Financial reporting and reconciliation

Use the Earnings report to reconcile your active multi-product OTP purchases with Google Payoffs and transactions on Play. Each transaction line item has an Order ID. For a multi-product OTP purchase, the Earnings and Estimated sales reports will include separate rows (with the same Order ID) for each transaction such as charge, fee, tax, and refund, for each item involved.

For dashboards in the Play Console:

• The revenue statistics presented in the Financial reporting section of the console are broken down by individual products.

• Order management reflects multi-product OTP purchases, and show itemized lists of what was purchased. From order management, you may revoke, cancel or fully refund a user's purchase.