Tag Archives: billing

Restricting Payments account usage across manager account hierarchies

Starting September 9, 2019, we are rolling out a change to prevent the same Payments accounts in the Google Ads API (billing accounts in the AdWords API) from being used across manager account hierarchies. Only valid Payments accounts belonging to the Google Ads manager account hierarchy can be used to create and update billing setups in the Google Ads API.

How does this affect you?
For your authenticated Google Ads client account Therefore, you may get fewer results from those API calls than before.

What do you need to do?
Google Ads API
When creating/updating a new billing setup, you will need to select a valid Payments account returned by PaymentsAccountService.ListPaymentsAccounts(). If you use an invalid Payments account during the above processes, the INVALID_PAYMENTS_ACCOUNT error will be thrown.


AdWords API
When creating a new budget order, you will need to specify a valid billingAccountId (the ID of a valid billing account returned by BudgetOrderService.getBillingAccounts()). If you use an invalid billingAccountId during the above process, the BudgetOrderError.INVALID_BILLING_ACCOUNT error will be thrown.

As always, if you have any questions, feel free to post your questions on the Google Ads API forum.

Advanced in-app billing: handling alternative purchase flows

Posted by Oscar Rodriguez, Developer Advocate

When designing and developing an app or game, at some point you may ask yourself if you want to monetize it.

If you choose to do so by selling products via Google Play, you will most likely have a store screen that shows available items for sale, and use the Google Play Billing Library to display dialogs that allow your users to complete their purchase.

While there is a more detailed explanation in the documentation and in the Billing Library TrivialDrive samples, the general flow is as follows:

  1. Call the launchBillingFlow() method from the UI thread to launch the Google Play purchase dialog.
  2. If the purchase was successful, Google Play calls the onPurchasesUpdated() method to deliver the result of the purchase operation.
  3. If your app has a server, we strongly recommend that you verify the purchase from your server by using the Subscriptions and In-App Purchases API.
  4. Acknowledge the purchase either with consumeAsync() for consumable items or with acknowledgePurchase() for non-consumable items.
  5. Finally, grant entitlement to the purchased item inside the app.

If your app is still using the Google Play Billing AIDL API, it is also possible to perform the same task. Keep in mind that the AIDL API is now deprecated, so we strongly recommend you migrate to the Google Play Billing Library as soon as possible.

If you are using the AIDL API, the flow is very similar:

  1. Send a getBuyIntent() or getBuyIntentExtraParams() request to specify the item to purchase, and then call startIntentSenderForResult() to launch the Google Play purchase dialog.
  2. When the purchase dialog finishes, Google Play sends a response Intent to your onActivityResult() method, where you can verify if the purchase was successful.
  3. If your app has a server, we strongly recommend that you verify the purchase from your server by using the Subscriptions and In-App Purchases API.
  4. If the purchase was successful, call the getPurchases() method to retrieve a list of owned items that are still not consumed. For consumable items, call the consumePurchase() method to make the item available for purchase again.
  5. Finally, grant entitlement to the purchased item inside the app.

Nevertheless, just implementing the above mentioned flow is not enough to correctly handle all types of purchases. There are two main cases in which purchases will not be correctly handled by this flow.

The first case happens when the purchase flow is interrupted before it finishes. The app may have crashed, the user may have killed the app, or the user’s Internet connection may have been lost. In any case, it is possible for the app not to have delivered the item to the user even though Google Play has already processed the payment. In this case, the item is in limbo, because Google Play will not allow an item to be re-purchased until it is consumed, but the app or game won’t consume the item outside of the flow mentioned above.

The second case happens during alternative purchase flows, such as in-app promotions, the recently announced out-of-app subscription surfaces, promo codes for subscriptions, or other promotions in collaboration with Google. In these cases, a user gets an item directly on the Play Store app, while the target app or game may be paused, not running, or even not installed.

For these cases, the Google Play Billing Library and the Google Play Billing AIDL API offer a mechanism to detect purchases that are not acknowledged or consumed.

When using the Google Play Billing API, do the following:

  1. In your app’s onResume() callback, call the queryPurchases() method to retrieve a list of items, so you can determine which ones are unacknowledged.
  2. If your app has a server, we strongly recommend that you verify the purchase from your server by using the Subscriptions and In-App Purchases API.
  3. If there are owned but unacknowledged items, acknowledge the purchase either with consumeAsync() for consumable items or with acknowledgePurchase() for non-consumable items.
  4. Grant entitlement to the purchased item inside the app.

For the Google Play Billing AIDL API, do the following:

  1. In your app’s onResume() callback, call the getPurchases() method to retrieve a list of owned items that are still not consumed.
  2. If your app has a server, we strongly recommend that you verify the purchase from your server by using the Subscriptions and In-App Purchases API.
  3. For consumable items, call the consumePurchase() method to make the item available for purchase again.
  4. Finally, grant entitlement to the purchased item inside the app.

In either case, when you detect and process an unconsumed item in this manner, users will expect the app or game to communicate about it. We suggest that you display a dialog, message box, or notification that tells the user that they have successfully received their item.

Keep in mind that your app’s onResume() callback will be called when its process is started, as well as when it is brought to the foreground, regardless of which screen the app or game was in before it was paused. For example, a game with a home screen, a store screen, and a game screen might get its onResume() called from any of those screens. For an optimal user experience, we suggest you make it so your app or game handles unacknowledged or unconsumed items regardless of the screen you display when onResume() gets called. Thorough testing of this process in each screen is crucial to deliver a great user experience.

Finally, there is one more case your app must handle: when a user acquires an item from the Play Store app, and both the Play Store app and your app are visible at the same time with multi-window mode.

To support this scenario with the Google Play Billing Library, do the following:

  1. Google Play calls the onPurchasesUpdated() method to notify your app that there is a new pending item.
  2. If your app has a server, we strongly recommend that you verify the purchase from your server by using the Subscriptions and In-App Purchases API.
  3. Acknowledge the purchase either with consumeAsync() for consumable items or with acknowledgePurchase() for non-consumable items.
  4. Finally, grant entitlement to the purchased item inside the app.

For the Google Play Billing AIDL API, do the following:

  1. In your app’s onResume() callback, register a PurchasesUpdatedListener to receive the com.android.vending.billing.PURCHASES_UPDATED intent. Also, in your app’s onPause() callback, unregister the listener.
  2. If your app has a server, we strongly recommend that you verify the purchase from your server by using the Subscriptions and In-App Purchases API.
  3. Google Play calls your listener to notify your app that there is a new pending item. Inside it, call the getPurchases() method to retrieve a list of owned items that are still not consumed. For consumable items, call the consumePurchase() method to make the item available for purchase again.
  4. Finally, grant entitlement to the purchased item inside the app.

Just as before, you should display a dialog, message box, or notification that tells the user that they have successfully received their item.

If you follow these steps, your app or game will be better prepared to robustly handle purchase flow interruptions and alternative purchase flows.

A better way to track your promotions on Google Play Billing

Posted by Neto Marin, Developer Advocate

Promotions can be a valuable tool to increase user engagement or attract new users by offering content or features to a limited number of users free of charge.

We are happy to share an improvement in the Google Play Developer API that makes it easier to track your promotions from your own backend. Starting today, the API for Purchases.products will return "Promo" as a new value for the field purchaseType when the user redeems a promo code. Now, the possible values are:

  • 0. Test (test purchases)
  • 1. Promo (Promo code redemption purchase)

For purchases made using the standard in-app billing flow, the field will continue to not be set in the API response.

Please note: This state is only returned by the Purchases.products API. For subscriptions you may use Free Trials to offer free of charge subscription periods.

For more details about how to create and redeem promo codes, check the In-app Promotions documentation. For more details about the server-side API, check the Google Play Developer API documentation.

Read-only access for BudgetOrderService in AdWords API

Starting this week BudgetOrderService get requests are available for all users, regardless of API version.

Previously, usage of this service was allowed on a whitelist-only basis. Now, you can retrieve your budget orders without being added to the whitelist. This enables you to view the account-level spending limit.

You still need to be whitelisted to modify your budget orders via the API; this new access applies only to viewing existing budget orders. Keep in mind that BudgetOrderService will only work on accounts that have been set up for consolidated billing; otherwise you will get an error.

To get started, check out the BudgetOrderService guide. If you have any questions about this change or other API features, please post on the forum.