Integrating your support

This section describes the support workflow when you intend to provide support as a part of your product.

Your system needs to be integrated with Google's so that you can provide support to your customers who have purchased your products through Google. The integration is based on Google providing you with the following:

  • A key that you will use to verify a user's support eligibility as part of the sign-up process.

  • An API (the subscriptions API) to which you can pass the key to periodically poll the status of a user's support eligibility.

Obtain the user's support ID

The support integration focuses around an external account ID, which your users see as their support ID.

To get the support ID of your users, you create a support workflow and provide a URL to the start of the workflow. Then, Google sends you the external account ID in the URL.

If you implement the support workflow, it must accept the external account ID as part of the URL. The external account ID can be part of the URL path, or as a query parameter value, as in the examples below:

# External account ID in path{external_account_id}?someparameter=yes

# External account ID as a query parameter{external_account_id}&something_else

The text {external_account_id} in the URL gets replaced with the external account ID. If you have multiple products listed in Google Cloud Marketplace, you might want to include a query parameter to identify the product that the URL is for.

Use the subscriptions API

After you have the user's external account ID, you can use the Google-provided subscriptions API to verify the support eligibility for their account at any time. Eligibility is tracked by checking for entities called subscriptions.

Each subscription has a unique subscription ID number, and a unique subscription is created per customer for every product that you list in Cloud Marketplace, so you can also query a subscription by subscription ID to get additional details about a customer's history with your product, such as their start date, end date, and so on.

Access the subscriptions API

The subscriptions API is a non-public API, so developers and projects needing access must be allowlisted.

To get allowlisted and setup, follow these steps:

  1. Send a list of email addresses for developers who need to access the API documentation to your Google Cloud Marketplace Partner Engineer, or to These must be the exact email addresses the developers will use to log in to These developers will be added to the group that grants permission to access the subscriptions API's documentation.

  2. Send your product's project ID to your Google Cloud Marketplace Partner Engineer and request that it be granted permission to call the API. Multiple projects can be allowlisted if needed.

  3. Enable the cloud billing API by expanding the menu near the upper left side of, clicking APIs & Services, and then searching for and enabling the Cloud Billing API.

  4. Create an OAuth2 service account associated with your project, and send the email address for this account to your Google Cloud Marketplace Partner Engineer. This user will be allowlisted to read all subscriptions for you, and will be used to authorize all requests except for those made by requesting the customer's permission using an OAuth dialog.

Because the subscriptions API is not a public API, it is not included in the Python client library by default. If you plan to use the Python client library with this API, you must also contact your Google Partner Engineer for help with accessing the discovery file.

In the example initialization below, the discovery filename is set to the path the discovery file downloaded to.

   # Load the local copy of the discovery document
   f = file(os.path.join(os.path.dirname(__file__),
         "cloudbilling-subscriptions_discovery.json"), "r")
   discovery =

   # Construct a service from the local documents
   service = build_from_document(discovery,

The client library also supports OAuth authentication, both for customer credentials and OAuth2 service accounts. For more information, see the OAuth 2.0 documentation in the Google API Client Library for Python.

Query the subscriptions API

To get permission to access subscriptions data, you need to create an OAuth2 service account and tell us the account you intend to use to authorize API requests. Google will then grant that service account access to read your subscriptions for all customers. For more information, see Using OAuth 2.0 for Server to Server Applications.

The API is a read-only RESTful API that returns subscription resources, which can be used to get the following info:

  • name—An identifier for a single subscription resource.
  • externalAccountId—An identifier for a single billing account.
  • version—A version number that updates every time the record is modified. This can be used to easily detect any changes since the last read.
  • status—One of the following values:
    • ACTIVE—The subscription is currently active and the customer should be able to receive support from you. A subscription is considered active if the account has had an active VM in the last 30 days.
    • COMPLETE—The subscription is no longer active, because the customer does not have any active VMs running with your product, and has not for the last 30 days.

  • subscribedResources—A list of resources covered by this subscription.
  • startDate—The date the subscription began, formatted as a string in RFC 3339 format.
  • endDate—The date the subscription has ended (if it has ended), formatted as a string in RFC 3339 format.
  • Label for last heartbeat timestamp (with key)—The value of this label indicates the timestamp of the last heartbeat of any VM running the product. For example:

When a customer clicks the link to access your site from the Google Cloud console, you need to verify that the customer is authorized to use the link by making the following requests:

  1. List the subscriptions for the external account ID
  2. Find the active subscription for the product
  3. Get the subscription information using the subscription ID

If the customer is an authorized user, the request will succeed. If the customer is not an authorized user for the subscription, the call will return an unauthorized error code (HTTP 403).

This requires you to request the customer's permission to read their subscriptions data during the signup process, using a standard OAuth request flow.

Later requests to refresh subscription data use your previously-created service account.

Customer support registration flow

After a customer has deployed your product through Cloud Marketplace or through Compute Engine APIs, the Google Cloud console shows them a link to your site to complete registration for support. The link will include the external account ID to be used for that account.

Your site should allow the customer to create an account and supply any contact information they need; Google will not provide any personally identifiable information about the customer to you. You are responsible for maintaining a mapping between their account and the Google-supplied external account ID.