Google Apps Platform

Billing Overview

Note: There's a new Google Apps Marketplace experience! Beginning November 19, 2013, new listings may only be created using the new version: existing developers may need to create a new Chrome Web Store account to publish new listings. Refer to the new documentation for more information.

Warning: The billing API has been deprecated and should no longer be used. The License API is still available for use.

The Google Apps Marketplace billing and licensing APIs enable Marketplace applications to integrate with Google's billing services, providing customers with a consistent billing experience and centralized management of the billing for their web applications. Please see the Payment Policy for requirements around Billing. All monetary transactions in this preview API are handled by Google Checkout.

This document gives an overview of billing for developers who are creating applications for the Marketplace.

Contents

What are the billing and licensing APIs?

The Google Apps Marketplace billing and licensing APIs enable Marketplace applications to integrate with Google's billing services, providing customers with a consistent billing experience and centralized management of the billing for their web applications. All monetary transactions are handled by Google Checkout.

Supported features

With the Marketplace billing and licensing APIs, you can:

  • Associate your application with a Google Checkout account to receive payments
  • Turn some of your application extensions on or off to create different editions of your product
  • Give buyers the choice of a variety of differently-priced subscription levels
  • Have the choice of offering per-seat or site-wide licensing (or a mix of the two)
  • Subscribe buyers to applications on a fixed monthly or yearly billing plan, including an introductory free trial period if desired
  • Check the status of customer licenses and subscriptions
  • Obtain a list of users and domains that have licenses and subscriptions, and obtain notifications when the status of these licenses and subscriptions change
  • Handle customer requests to upgrade the application or add user seats
  • Leave the actual billing to Google — Google automatically charges the customer's credit card based on the defined monthly or yearly recurrence cycle.

Unsupported features

The following features are currently unsupported by the Marketplace billing and licensing APIs:

  • Metered (also known as pay-as-you-go) payment, where the application charges a fee for a given amount of usage and tracks the user's decreasing remaining allotment, is currently unsupported.
  • Invoicing — Credit cards are the only currently-supported billing instruments.
  • Per-group or Organizational Unit (OU)-based licensing — Licensing is currently for a specific set of named users. We do not currently support assigning licenses to a group or OU.

What are licenses, editions and subscriptions?

A license represents permission of a customer (a domain, in a site license), or a user (an individual, in a seat license) to access a specific version (an edition) of your application. With the billing and licensing APIs you can allow domain administrators to purchase licenses for a subset of their users or the entire domain (via a subscription), and charge a subscription fee for these licenses.

Editions provide a way to enumerate which extensions (such as a link in Google's universal navigation or a Gmail contextual gadget) should be accesible for different licenses. For example, you may wish to provide a "standard" edition with only a link in Google's universal navigation, in addition to a "premium" edition that also includes a Gmail contextual gadget. Google will also automatically control access to these extensions based on the subscription status of the customer. Using the previous example of a premium edition, if a customer that has purchased this edition allows it to expire, he or she will automatically lose access to premium extensions until payment is resumed.

A subscription is a pairing of one or more licenses with the fees required to maintain them. A subscription may be free or paid, and an may be composed of both free and paid components. For example, a subscription may contain a site license for a free edition of a product as well as 5 seats of a premium edition. Subscriptions are recurring, regardless of whether or not they are free, and recur on either monthly or yearly intervals. When subscriptions recur, the customer's credit card will be automatically be charged for the price of the subscription.

Billing plan selection

User experience summary

This section describes what users will typically see once you have added billing functionality to your Marketplace application.

Typical initial purchase

The buyer sees the "Add it now" button on your Marketplace listing page, accompanied by one or more product choices which you have specified. You might offer only a single choice which will feed the buyer through to your own web page, where you can show as many application editions and pricing plans as you care to offer. Or you might list every available choice right under the "Add it now" button.

This illustration shows an example for an application, using the first style of listing described above. If there are multiple pricing plans for the application, they are shown in a separate shopping page.

What happens next depends on whether the application is free, how you have set up the purchase flow, and what options the buyer selects. Here is a basic summary:

  • If no further immediate input is needed from the buyer (for example, the application is free, or you take the buyer's payment information only after a free trial period), the Google Apps administrator control panel appears and the buyer can immediately configure and use the application.
  • Otherwise, the buyer is redirected to your own shopping web page, which can display whatever choices you wish to offer. For example, you can list the different editions of your product and let the buyer choose one or more of them. After filling out your page, the buyer pays through Google Checkout. Finally, the Google Apps administrator control panel is displayed so the buyer can finish configuring the application in their domain. For example, the administrator might need to grant your application access to some of the domain's Google Apps data.

Typical upgrade

The buyer clicks an Upgrade link inside your application or a "Purchase More Licenses" link in the Google Apps administrator control panel. This displays the upgrade page on your own website, which shows the choices that are available to the current customer. After filling out this upgrade page, the buyer pays through Google Checkout, and the Google Apps administrator control panel is displayed so the buyer can finish configuring the application in their domain.

More info

To find out more about what happens behind the scenes, see the next section, How does it work?

To find out more about the different types of billing flows you can offer, see Choosing your billing scenario.

How does it work?

This section describes the behind-the-scenes sequence of events that your application and Google's servers will go through during a purchase or upgrade interaction with a buyer.

During an initial purchase:

  1. The buyer clicks the "Add it now" button in your Marketplace listing, then logs in as a Google Apps administrator. If the application is free, steps 2 through 4 are skipped.
  2. If the buyer needs to provide additional information, your own web page is presented, and the buyer makes choices and clicks "Submit." The choices might include selecting an edition of your application, specifying the number of user seats, or whatever other information you want to gather. Your web page should check the buyer's current subscription and license status to confirm that this is a new purchase request and not an upgrade. Then your page sends the shopping cart to Google.
  3. Google's Marketplace Billing servers process the shopping cart as a subscription request, then send your application a redirect URL that will direct the buyer to the next step in the payment flow.
  4. You display the page at the redirect URL to the buyer, and the buyer pays through Google Checkout. Google Checkout checks the order for fraud risk, verifies the buyer's credit card, and other payment processing steps. When the order is complete, Checkout emails a receipt to the buyer.
  5. The Google Apps administrator console is displayed so that the buyer can finish any additional configuration steps. For example, the administrator might be required to grant your application access to some of the Apps data in the domain. Your application can also insert a step in the control panel configuration flow, directing the administrator to your own website to perform any additional setup steps that you require. (For information about how to do this, see the description of the <Link> tag in the Application Manifest.)
  6. The domain administrator clicks "Enable app now."
  7. Users in the domain can begin enjoying your application!

During an upgrade:

  1. The Google Apps administrator starts the upgrade process in one of these ways:
    • From the Marketplace listing: The administrator selects a different edition than what is already installed in the domain, clicks click "Add it now," and logs in.
    • From the Google Apps administrator control panel: The administrator clicks the "Purchase more licenses" link. This link is defined in the application manifest.
    • From the Marketplace application itself: The administrator clicks an upgrade link which you have created in your own application, leading to a shopping page.
  2. The subscription implementation code in your shopping page checks the domain's current subscription and license, and detects that this is an upgrade request.
  3. The page displays the appropriate text and controls to the administrator ("Welcome back, Sergey. Would you like to: Add __ seats [current seats: 100]" etc.)
  4. The page constructs a subscription upgrade request and sends it to Google in the same way that an initial purchase request is sent.
  5. The process continues as if it were an initial purchase.

Where does it work?

The API currently allows sellers in the US to accept purchases in US dollars, from the following countries:

  • Argentina
  • Australia
  • Austria
  • Belgium
  • Brazil
  • Bulgaria
  • Canada
  • Cyprus
  • Czech Republic
  • Denmark
  • Estonia
  • Finland
  • France
  • Germany
  • Ghana
  • Greece
  • Hong Kong
  • Hungary
  • Iceland
  • India
  • Ireland
  • Israel
  • Italy
  • Japan
  • Kenya
  • Latvia
  • Lithuania
  • Luxembourg
  • Malta
  • Mexico
  • Netherlands
  • New Zealand
  • Nicaragua
  • Norway
  • Philipines
  • Poland
  • Portugal
  • Romania
  • Russia
  • Senegal
  • Singapore
  • Slovakia
  • Slovenia
  • South Africa
  • Spain
  • Sweden
  • Switzerland
  • Taiwan
  • Thailand
  • Ukraine
  • United Kingdom
  • United States

Money matters

This section describes the details of how funds are handled between the APIs, the Marketplace, Google Checkout, and the vendor.

Required fees

Every listing in the Marketplace is required to pay a listing fee, which is described in the Payment Policy.

Google Checkout test account

If your application is not free, you'll need to set up a sandbox account on Google Checkout for testing purposes. We provide a sandbox where you can get a Checkout account that is not attached to any real bank account. To create an account:

  1. Visit the Checkout sandbox signup page.
  2. Follow the prompts. When asked for a credit card number, use one of the test numbers from Credit Card Test Cases.

You will use this test account to receive test payments from test customers of your application. Since it is not possible to purchase an application with the same account that sells the application, you should create a second checkout sandbox account that you will use when you wish to make test purchases. To create a second account, repeat the above process with a different Google account.

Google Checkout live account

If your application is not free, you will need a live Google Checkout merchant account once you are ready to launch your application. Obtain an account by visting the signup page.

Caution: You must complete the above process even if you already have a Checkout seller account. You need a new-style Checkout seller account, and old accounts will not work with the Marketplace.

Overview of funds processing

All the monetary transactions that pass through the API are handled by Google Checkout. Let's look again at the sequence of events during a Marketplace purchase, with more details about exactly how the money part is handled, assuming the application is not free. We will start at the point where the Google Checkout page is displayed to the shopper.

  1. Buyers must have a Google Checkout account in order to make payments. When viewing an order in Checkout, a buyer has the option of either signing in to an existing Checkout account or creating a new one.
  2. The buyer finalizes the order by clicking a "Place order now" (or similarly labeled) button.
  3. Google Checkout puts the order through a series of steps, including a risk check to see whether the order appears fraudulent, and a credit card authorization.
  4. The buyer gets an emailed receipt or, if the credit card authorization fails, a note asking for a better credit card.
  5. When the order has passed all of Checkout's safety steps and the buyer's payment method is verified, the vendor gets a notification of the order in his or her Checkout Merchant account and the buyer gets an emailed receipt.
  6. The vendor's portion of the funds (minus transaction fees) will be deposited in the bank account that is attached to his or her Checkout merchant account. For more information about how long that will take and what limits might apply, see Receiving payouts in the Google Apps for Developers Help Center.

Caution: You must specify bank account information in your Google Checkout accounts in order to get paid. If you do not provide valid bank account information, you will be unable to receive payments from Google Checkout.

Newly-created Google Checkout accounts are subject to a different payout schedule than accounts verified to be in good standing. Details on these payout periods are described in the Help Center.

Understanding Google Checkout

The Google Apps Marketplace for Developers Help Center has lots of useful details about what you should expect as a Marketplace seller. The Help Center contains information about refunds, payouts, chargebacks, dispute resolution, fraud protection, order management, and more. Some articles of particular interest:

Auditing and financial reporting

You can use the Google Checkout Merchant Center to get data about orders in order to create reports such as monthly sales and other auditing information. See the Google Checkout Merchant help center for more information.

Choosing your billing scenario

The exact process for implementing an integration with the billing and licensing APIs will depend on the billing scenario that will be followed by your application. The following sections will aid you in selecting and implementing an appropriate billing scenario.

First, read Setting up your test environment to learn how to configure a test environment for the billing and licensing APIs. This test environment will enable you to implement and test the entire end-to-end flow of purchasing your application from the Marketplace, without using real funds.

After you've set up your test environment, learn more about the supported billing scenarios:

Setting up your test environment

The following steps will provide you with a test environment for the billing and licensing APIs. This test environment will enable you to implement and test the entire end-to-end flow of purchasing your application from the Marketplace, without using real funds.

  1. If you have not already done so, complete the steps for creating Google Checkout test accounts.
  2. Create a test Google Apps domain that you will dedicate to testing Marketplace applications.

    Caution: Make sure you verify your test domain. Some services and features may be disabled until your domain is verified.

  3. Enable the sandbox for your test domain: http://www.google.com/a/<domain>/SandboxDomainWhitelist.
  4. Log into your new domain. In the Apps Administrator Control Panel, click on the Domain Settings tab. In the section "New Services and Pre-Release Features" click "Next Generation."

Generic implementation

A generic billing implementation proceeds as follows:

  1. Set up your test environment.
  2. Configure different editions of your application in the application manifest.
  3. Register your Google Checkout account and configure product prices using the listing manifest.
  4. Create a web page to user's can visit to configure their shopping cart. This page will present the user options for configuring their subscription. After submitting the form, your server will use the user's configuration to construct a subscription cart that will be sent to Google, including things like the application ID, number of seats that were purchased, and the price. Google will return a URL that you may use to redirect the user so that he or she may confirm the order.
    Creating a web page is not required when your application is free and provides a site license. In cases where you do not need the user to configure the cart, you may simply have your server redirect the user to the confirmation page without displaying a UI.
  5. Check the subscription and license using the customer and user license APIs. You will use the customer license whenever you want to query the current licensing information for a domain (such as when you are peforming an upgrade and want to know the domain's current licensing status). You will use the user license API when a user visits your application (to ensure the user should be granted access.)

Free application

If your application starts out free and stays free forever (or until the buyer decides to upgrade), you are in the least complicated billing situation of all. You do not have to use the Marketplace Billing API. Just follow the steps to develop and list your application as described in the Google Apps Marketplace Developer's Overview. You can skip constructing a shopping web page — all transactions will go straight from the Marketplace listing to the Google Apps administrator control panel.

Multi-edition free application

There is one case where you would still use the Billing API with a free application, and that is if there are several different editions of your application to choose from. (For an overview of what editions are and how to set them up, see Multiple Editions.)

As always, begin by Setting up your test environment.

What Where How
Provide several application versions Application manifest
  • Multiple <Edition> tags
Create a listing Listing manifest
  • Multiple <SubListing> tags
  • Include an <EditionId> in each <SubListing> tag
  • Set <PaymentMethod> to FREE in each tag
  • Don't use <PurchaseUrl> or <Merchant> tags

The following is an example application manifest to set up several free editions.

<Edition id="free_standard">
  <Extension ref="exampleLink"/>
  <Extension ref="exampleRealm"/>
</Edition>
<Edition id="free_premium">
  <Extension ref="exampleLink"/>
  <Extension ref="exampleRealm"/>
  <Extension ref="exampleGadget"/>
  <Extension ref="exampleExtractor"/>
</Edition>
<Edition id="free_deluxe">
  <Extension ref="exampleLink"/>
  <Extension ref="exampleRealm"/>
  <Extension ref="exampleGadget"/>
  <Extension ref="exampleExtractor"/>
  <Extension ref="exampleSite"/>
</Edition>

...

<Extension id="exampleLink" type="link">
  <Name>ExampleApp</Name>
  <Url>http://test.example.com/${DOMAIN_NAME}/myapp?from=google</Url>
</Extension>

...

This is the corresponding listing manifest for the above editions.

<ListingManifest>
  <SubListings>
    <SubListing>
      <DisplayName>Example App: Free standard version</DisplayName>
      <EditionId>free_standard</EditionId>
      <PaymentModel>FREE</PaymentModel>
    </SubListing>
    <SubListing>
      <DisplayName>Example App: Free premium version</DisplayName>
      <EditionId>free_premium</EditionId>
      <PaymentModel>FREE</PaymentModel>
    </SubListing>
    <Sublisting>
      <DisplayName>Example App: Free deluxe version</DisplayName>
      <EditionId>free_deluxe</EditionId>
      <PaymentModel>FREE</PaymentModel>
    </Sublisting>    
  </SubListings>
</ListingManifest>

Multiple editions with tiered pricing

Within a single product, you can create several editions (not to be confused with Google Apps editions). This is usually done to provide increasing functionality for higher price points. This can be expressed as free vs. paid editions, basic and premier editions, Freemium, or even several different free editions.

In the most typical case, each edition includes a different set of the Google Apps extensions you have implemented. For example, you might include a simple Gmail contextual gadget in the base edition and add a specialized CRM gadget in the Sales edition. The diagram shows how extensions are grouped into editions within the Marketplace application manifest. Notice that a given extension can be included in more than one edition.

Another possibility is to create two editions containing the same group of extensions, but provide different levels of functionality to different users by invoking different code at your backend depending on the user identity.

The buyer can purchase more than one edition of your product and assign seats separately. For example, there might be 100 users of a free version and 10 users of a Pro version within a single domain.

If you have more than one edition, you have the choice of where to display the edition choices to the buyer:

  • Display editions in your shopping web page
    You can keep your listing uncluttered by including a single choice under the "Add it now" button which always directs buyers to your own shopping web page. This page can handle the work of showing all the pricing levels and different editions of your application. By using this technique, you will have a free hand to add design elements and descriptive text to best present the merits and advantages of each option.
  • Display editions in your Marketplace listing
    If you prefer, you can list all the available options right in your Marketplace listing. In this case, the buyer will have to select the right radio button before clicking "Add it now."

Implementation

This section shows the implementation steps to set up multiple editions with a variety of price points. In these steps, it is assumed that at least one of the editions is not free of charge. If all the editions are free, use the technique described in Free application.

As always, begin by Setting up your test environment.

What Where How
Provide several different bundles of features Application manifest
  • Multiple <Edition> tags
Create a listing Listing manifest
  • Multiple <SubListing> tags
  • Set <PaymentMethod> to PAID in at least one <SubListing>
  • In the PAID <SubListing>, set <PaymentUrl> to your shopping web page
Create a shopping cart and send it to Google Shopping page
  • Check for an existing license for the customer
  • Create and send the cart to Google
  • Redirect the customer to the redirect URL provided by Google

Configuring the editions

In the application manifest, use the <Edition> tag to specify which Apps extensions are available in each edition of your product. This example sets up three editions:

<Edition id="free">
  <Extension ref="exampleLink"/>
  <Extension ref="exampleRealm"/>
</Edition>
<Edition id="standard">
  <Extension ref="exampleLink"/>
  <Extension ref="exampleRealm"/>
  <Extension ref="exampleGadget"/>
</Edition>
<Edition id="premium">
  <Extension ref="exampleLink"/>
  <Extension ref="exampleRealm"/>
  <Extension ref="exampleGadget"/>
  <Extension ref="exampleSite"/>
</Edition>

...

<Extension id="exampleLink" type="link">
  <Name>ExampleApp</Name>
  <Url>http://test.example.com/${DOMAIN_NAME}/myapp?from=google</Url>
</Extension>

...

Configure your product listing

If your application is not totally free, you need to configure the options that will appear below the "Add It Now" button in your Marketplace product listing. You can can show several pricing levels or else pass shoppers through to your own shopping page to let them choose between editions there. Either way, you need to write a listing manifest, a new file separate from the application manifest. When you are setting up your Marketplace listing, you will paste the listing manifest in its own field in the application listing form.

This example shows a simple, clean way to display multiple editions in the Marketplace listing: one free sublisting mapped to the free edition of an application, and one paid sublisting to cover all other editions. Buyers will use your shopping web page to choose between the paid editions, and those who choose the free edition will skip the shopping page and go directly to the Google Apps administrator control panel to configure and enable the application.

<ListingManifest>
  <SubListings>
    <SubListing>
      <DisplayName>Example App: Free version</DisplayName>
      <EditionId>free</EditionId>
      <PaymentModel>FREE</PaymentModel>
    </SubListing>
    <SubListing>
      <DisplayName>Example App: from just $5/year</DisplayName>
      <PaymentModel>PAID</PaymentModel>
      <PurchaseUrl>http://test.example.com/purchase</PurchaseUrl>
    </SubListing>
  </SubListings>
  <Merchants>
    <Merchant>
      <CurrencyCode>USD</CurrencyCode>
      <MerchantEmailAddress>admin@example.com</MerchantEmailAddress>
    </Merchant>
  </Merchants>
</ListingManifest>

This example displays every edition in the Marketplace listing for an application called Invoicer. It passes the edition IDs in the shopping page URL so that the shopping page will know which edition is being requested.

<ListingManifest>
  <SubListings>
    <SubListing>
      <DisplayName>Invoicer Free</DisplayName>
      <EditionId>free</EditionId>
      <PaymentModel>FREE</PaymentModel>
    </SubListing>
    <SubListing>
      <DisplayName>Invoicer Standard $5/year</DisplayName>
      <PaymentModel>PAID</PaymentModel>
      <PurchaseUrl>http://test.example.com/purchase?edition=standard</PurchaseUrl>
    </SubListing>
    <SubListing>
      <DisplayName>Invoicer Premium $10/year</DisplayName>
      <PaymentModel>PAID</PaymentModel>
      <PurchaseUrl>http://test.example.com/purchase?edition=premium</PurchaseUrl>
    </SubListing>
  </SubListings>
  <Merchants>
    <Merchant>
      <CurrencyCode>USD</CurrencyCode>
      <MerchantEmailAddress>admin@example.com</MerchantEmailAddress>
    </Merchant>
  </Merchants>
</ListingManifest>

Show your own shopping page and send the cart to Google

Before submitting the order, you need to get the buyer's edition choices, display the total price, and let the buyer pay for the purchase. For details on how to construct such a page and submit your cart to Google, see Handling orders on your shopping page.

When customers access your application

When customers visit your application, use the user license API to determine the licensing status and edition that the user should see.

Caution: If you do not check the licensing status and edition for the current user, you may be permitting free (or reduced cost) access to your application.

Subscription with free trial period

You can set up the buyer's license so that it expires at regular intervals (say, every 30 days) and must be renewed with a periodic subscription fee. The buyer agrees to this recurring charge at the outset, and the charge is then made automatically without further intervention from the buyer until the buyer cancels the subscription.

If you are charging a recurring subscription fee, you can also include a free trial period or a one-time setup fee, but not both.

A free trial period is well worth considering. Experience shows that when buyers can try an application before they buy, sales are increased. It's only natural that by lowering the barrier that delays a browsing shopper from actually interacting with your application, you increase engagement and excitement.

If you do offer a free trial period, you can choose whether or not to collect the buyer's payment details up front. If you do, the first subscription payment can be made automatically and on time, but the customer needs to do more before trying your application. If you don't, the customer has a much lower barrier to trying your application, but you need to get the customer to revisit your site before the trial period ends in order to collect payment.

Below is an example of providing a free trial that collects payment information up front. Instructions on how to peform a trial without collecting payment details follow directly after.

As always, begin by Setting up your test environment.

What Where How
Set up the subscription Shopping cart
  • Include a recurringCart that contains one lineItem for each regular subscription; the cart can contain more than one lineItem if, for example, the buyer has chosen to purchase several editions at the same time
  • In the lineItem, set price to the periodic subscription fee
Set up the billing cycle Shopping cart
  • In the recurringCart, set frequency to the length of the subscription renewal period: MONTHLY or YEARLY
Specify the length of the trial period Shopping cart
  • In the recurringCart, set firstChargeDays to the length of the free trial period. A value of 0 omits the trial period
Send the cart to Google Shopping page
  • Check for an existing license for the customer
  • Create and send the cart to Google
  • Redirect the customer to the redirect URL provided by Google

The following example shows (using Google-provided client libraries) how to set up an example subscription request with a free trial period. Consult the developer's guide to learn more.

import com.google.api.client.http.HttpResponseException;
import com.google.api.client.sample.appsmarket.model.Cart;
import com.google.api.client.sample.appsmarket.model.LineItem;
import com.google.api.client.sample.appsmarket.model.RecurringCart;
import com.google.api.client.sample.appsmarket.model.Subscription;

import java.util.ArrayList;

AppsMarketService service = new AppsMarketService();
service.appId = YOUR_APPLICATION_ID;
service.consumerSecret = YOUR_CONSUMER_SECRET;

// Assumes you are connecting to the sandbox. Use http://www.googleapis.com/appsmarket/v2/ to connect to production.
service.endpoint = "https://www.googleapis.com/appsmarket/v2sandbox/";

service.appName = YOUR_APP_NAME;
service.consumerKey = service.appId + ".apps.googleusercontent.com";
service.authorize();

// Constructs a subscription request. In a complete application, this would be based on details the
// customer has supplied on a product purchasing page.
Subscription sub = new Subscription();
sub.applicationId = service.appId;
sub.customerId = customerId;
sub.purchaseToken = purchaseToken;
sub.name = "SaaSy App Subscription";
sub.description = "SaaSy App Subscription";
sub.purchaseToken = purchaseToken;
sub.currencyCode = "USD";

// Sets up the information for recurring charges to the buyer.
// In this example, the first future billing occurs 30 days from now
// and repeated billings will occur every month thereafter.
sub.recurringCart = new RecurringCart();
sub.recurringCart.cart = new Cart();
sub.recurringCart.cart.receiptName = "Monthly subscription";
sub.recurringCart.cart.receiptDescription = "Recurring charge to maintain subscription";
item = new LineItem();
item.name = "My Subscription";
item.description = "Subscription billing for SaaSy App";
item.editionId = "standard";
item.developerSku = "standard";
item.seatCount = 1; // Set this to -1 for a site license.
item.price = 1000000L;
sub.recurringCart.cart.items = new ArrayList();
sub.recurringCart.cart.items.add(item);
sub.recurringCart.firstChargeDays = 30;
sub.recurringCart.frequency = "MONTHLY";

Subscription response = service.insertSubscription(sub);
from apiclient.discovery import build
from apiclient.oauth import OAuthCredentials

import httplib2
import oauth2 as oauth

http = httplib2.Http()
consumer = oauth.Consumer(YOUR_CONSUMER_KEY, YOUR_CONSUMER_SECRET)
token = oauth.Token('', '')
credentials = OAuthCredentials(consumer, token, YOUR_APP_NAME)
http = credentials.authorize(http)

# Assumes you are connecting to the sandbox. Use version='v2' to connect to production.
service = build(serviceName='appsmarket', version='v2sandbox', http=http)

# Constructs a subscription request. In a complete application, this would be based on details the
# customer has supplied on a product purchasing page.
subscription = {
  'applicationId': YOUR_APPLICATION_ID,
  'customerId': customer_id,
  'purchaseToken': purchase_token,
  'name': 'SaaSy App Subscription',
  'description': 'SaaSy App Subscription',
  'currencyCode': 'USD',

# Sets up the information for recurring charges to the buyer.
# In this example, the first future billing occurs 30 days from now
# and repeated billings will occur every month thereafter.
  'recurringCart': {
    'cart': {
      'items': [{
        'name': 'My Subscription',
        'description': 'Subscription billing for SaaSy App',
        'editionId': 'standard',
        'developerSku': 'standard',
        'seatCount': 1, # Set this to -1 for a site license.
        'price': 1000000
      }],
      "receiptName": "Monthly subscription",
      "receiptDescription": "Recurring charge to maintain subscription"
    },
    'firstChargeDays': 30,
    'frequency': 'MONTHLY'
  }
}

subscription = service.subscription().insert(body=subscription).execute()
require 'rubygems'
require 'google/api_client'

client = Google::APIClient.new(:authorization => :two_legged_oauth_1)
client.authorization.client_credential_key = YOUR_APPLICATION_ID + '.apps.googleusercontent.com'
client.authorization.client_credential_secret = YOUR_CONSUMER_SECRET
client.discovery_uri = 'http://www.googleapis.com/discovery/0.1/describe?api=appsmarket'

# Assumes you are connecting to the sandbox. Use 'v2' for production.
service = client.discovered_service('appsmarket', 'v2sandbox')

# Constructs a subscription request. In a complete application, this would be based on details the
# customer has supplied on a product purchasing page.
subscription = {
  'applicationId' => YOUR_APPLICATION_ID,
  'customerId' => customer_id,
  'purchaseToken' => purchase_token,
  'name' => 'SaaSy App Subscription',
  'description' => 'SaaSy App Subscription',
  'currencyCode' => 'USD',

# Sets up the information for recurring charges to the buyer.
# In this example, the first future billing occurs 30 days from now
# and repeated billings will occur every month thereafter.
  'recurringCart' => {
    'cart' => {
      'items' => [{
        'name' => 'My Subscription',
        'description' => 'Subscription billing for SaaSy App',
        'editionId' => 'standard',
        'developerSku' => 'standard',
        'seatCount' => 1, # Set this to -1 for a site license.
        'price' => 1000000
      }],
      "receiptName" => "Monthly subscription",
      "receiptDescription" => "Recurring charge to maintain subscription"
    },
    'firstChargeDays' => 30,
    'frequency' => 'MONTHLY'
  }
}

json = JSON.dump(subscription)

status, headers, body = client.execute(service.subscription.insert, {}, json, {'Content-Type' => 'application/json'})
subscription = JSON.parse(body.join)

When customers access your application

When customers visit your application, use the user license API to determine the licensing status and edition that the user should see.

Caution: If you do not check the licensing status and edition for the current user, you may be permitting free (or reduced cost) access to your application.

Offering a trial without collecting payment information

To offer a trial without collecting payment information, you should treat initial purchases as if they are for a free application, but with one distinction. On your servers, keep track of how long a particular customer has had access to the free version of your application. When the customer has had access for almost the complete duration of your trial period, prompt administrative users (either in the UI or via some other notification channel such as email) to upgrade to to the full application. If the domain administrator visits your site, perform an upgrade of the existing license to a full license. The domain administrator will enter payment details and confirm the purchase. If the domain administrator does not visit your site, and the free trial period has expired, you may block access to users of the domain from using your application in accordance with the terms of your trial.

Loosely coupled

If you would prefer a loosely coupled scenario, where you handle the logistics of provisioning seats and licensing customers yourself, you may use the billing API exclusively to charge customers.

As always, begin by Setting up your test environment.

What Where How
Provide a single bundles of features Application manifest
  • One (optional) <Edition> tags, or the default_edition that will be created by the Marketplace
Create a listing Listing manifest
  • One <SubListing> tag
  • Set <PaymentMethod> to PAID in the <SubListing>
  • In the PAID <SubListing>, set <PaymentUrl> to your shopping web page
Create a shopping cart and send it to Google Shopping page
  • Consult with your own licensing database whether or not the domain already has a license
  • Calculate how much the customer owes for the editions/seats that have been selected
  • Store the seat and edition preferences for the license in your database
  • Create and send the cart to Google, including:
    • A single recurring item, a site license for the entire domain (set seat count to -1), priced to encompass the entire subscription fee
    • Optionally, one or more initial items (one-time fees)
  • Redirect the customer to the redirect URL provided by Google to complete the purchase
Handle domain configuration and seat assignment Your application
  • Provide domain administrators with the option to grant application access to specific users

When customers access your application

When customers visit your application, instead of using the user license API to determine if they have access, you may consult with your own database of seat assignments.

Caution: You should at least occasionally check that a domain still has an active subscription to your application, using either the customer license API or the license notification API. If you fail to do this and the customer's license expires (eg. if the credit card is no longer valid), you may be permitting free access to your application.

Handling existing customers

In addition to configuring your application to support your desired billing scenario, if you are upgrading an application that has existing customers, pay special attention to the following points. Failure to do so may cause a distruption in service to your existing customers.

Editions for existing customers

When a Marketplace application is upgraded to support billing, all existing customers of the application (any domains that have installed the application prior to when the application supported billing) will be treated as though they have a site license with the edition name of default_edition. If your application manifest does not define any Edition tags, customers in the default_edition will have access to all extensions defined by your application manifest. In addition, any new customers of your application will also be placed into the default_edition.

If your application does define one or more Edition tags in the application manifest, you must explicitely add an Edition tag for default_edition. Otherwise, existing customers will no longer have access to any extensions, including but not limited to: the link to your application in Google's universal navigation or Gmail contextual gadgets.

Note: It is always advised to explicitly create a default_edition for applications with existing customers.

See Application Manifest: Modifications for Billing Support for an example of extending an existing application manifest to handle existing and new users.

Licensing for existing customers

Existing customers, in addition to being placed into a default_edition are treated as though they have a free, recurring site license, with no expiration. You may choose to migrate these customers to the new billing scenario that you have selected by having them perform an upgrade. Alternatively, you can continue to service modifications to the customer's subscription by exempting payment in the subscription.

Exempting payment

Occasionally, you will need to exempt a customer from using the Google Checkout payment process:

  • If it's an existing customer that already pays through a different mechanism
  • If it's a customer that requires a payment method not offered via the billing APIs (such as a purchase order)

In these cases, you may provide the exemptPayment flag in your subscription, which will skip processing of the subscription by Google Checkout. The Marketplace purchase UI will continue to treat the subscription as if it is for a free purchase.

Use the following code to add the exemptPayment flag to your subscription:

Subscription sub = new Subscription();
sub.exemptPayment = true;
subscription = {
  ...
  'exemptPayment': True
}
subscription = {
  ...
  'exemptPayment' => true
}

Handling orders on your shopping page

Create a shopping web page where buyers can configure and and submit orders. This page can show more details about each available edition, plus any additional material you'd like to include, such as videos, testimonials, and more. The visuals and content are up to you. In a typical shopping page, the buyer can:

  • Tell which edition of your application they want (if not already selected through the Marketplace listing)
  • Tell how many seats they want to buy or specify a site license
  • Select any other options you want to provide
  • See the total purchase price (without sales tax, which is unsupported at this time)

The page should contain code to perform these steps:

  1. Check for the existance of a valid purchase token in the URL. This purchase token may be used to retrieve details on the purchasing customer, and is a required component of the subscription.
    • If the visitor came from the Marketplace listing page, the Marketplace should provide the query parameter appsmarket.purchaseToken in the URL
    • If the visitor came from a "Purchase More Licenses" link, the Marketplace should provide the query parameter appsmarket.purchaseToken in the URL
    • If the visitor came from a link on your site, first, redirect the user to a URL of the form http://google.com/enterprise/marketplace/redirectWithSignature?productListingId=YOUR_PRODUCT_LISTING_ID&domain=CUSTOMER_DOMAIN&supportLink=add-seats, where add-seats is a link defined in the application manifest. When the user returns to site at the URL you provided, the URL will contain the appsmarket.purchaseToken query parameter. The productListingId referenced in this URL is the same ID provided in the link to your application's listing, not your application ID, eg: 123+12345678.
  2. Check for a current subscription and license assigned to the buyer (see the developer's guide) to see whether you are dealing with an existing or new customer, and adjust the page content accordingly. You might like to do this step before rendering the page.
  3. Gather the buyer's choices that are needed to populate the shopping cart, such as which edition and how many seats. You can provide controls and input fields to let shoppers make the appropriate choices for an initial purchase, a request to upgrade to another edition of your application, or a request to add user seats. Assemble this information into a shopping cart and send it to Google's Marketplace Billing servers (see the developer's guide). You would probably attach this code to a "Submit Order" button.
  4. Receive the return message from the Google servers, which contains a redirect URL. Display the redirect URL to the buyer. This starts the Google Checkout portion of the flow. Even when the buyer has signed up for a free trial period, Marketplace will need to collect the payment details up front, so that the first subscription payment can be made on time.

Check whether the order is new, or an upgrade

Your shopping web page can handle both initial purchases and modification requests from existing customers, such as to upgrade to another edition of your application or add user seats. To find out which type of order you're dealing with, check the subscription and license status (see the developer's guide) and, depending on the status, display the right page to the customer:

  • If license=ACTIVE and subscription=ACTIVE, this is an existing customer who wants to make a change to their subscription. See Upgrades and other subscription changes.
  • If license=ACTIVE and subscription=LOCKED, an update is in progress — display a "try again later" page.
  • Otherwise, the customer treat as new — display a page with all the choices for an initial purchase.

Assemble and send the shopping cart

When the buyer clicks "Submit," send the shopping cart to Google using the shopping cart. The example scenario Subscription with free trial period has a code example that shows how to assemble and send a shopping cart. You may also consult the developer's guide.

Send the buyer to complete the purchase

Google's subscription server will send a JSON response to you that includes a generated redirect URL, which is constructed from the user ID and app ID you passed in, plus a generated, unique subscription ID. For example:

http://www.google.com/a/cpanel/example.com/DomainAppInstall?cartId=12906776957968243981.09766949214840694025.649174748903.4601789013362769820&appId=123456

Redirect the customer's browser to this URL so that he or she may confirm the order and complete the purchase.

Upgrades and other subscription changes

To provide ongoing service to customers, you'll need to handle their changing needs throughout the lifetime of their engagement with your application. A customer might want to change to a different edition of your application, purchase licenses for additional users, or both. For a description of how the customer initiates a subscription change, see the description of the upgrade process in How does it work?

Whenever a customer visits your purchase page, you will need to determine whether or not a purchase is a new, or an upgrade. The following process will help you take the right course of action:

  1. When a visitor arrives at your shopping page, check the visitor's license state (see the developer's guide).
    • If the license is ACTIVE, the visitor is a returning customer. Go on to step 2 to find out more about the customer's situation.
    • If the license has any other status, treat the visitor as a new customer.
  2. If the visitor's license is ACTIVE, check the subscription state. If the subscription state is:
    • ACTIVE — You're dealing with a current customer who wants to make a subscription change. Go on to step 3.
    • TRIAL — This is a current customer who is in the middle of a free trial period. Go on to step 3.
    • LOCKED — The Google servers are busy working on this subscription, and its state is not firm at this time. Tell the user to try again later.
    • Any other status — Treat the visitor as a new customer.
  3. If the license is ACTIVE and the subscription is ACTIVE or TRIAL, help the visitor do the update:
    • It's helpful to pre-populate the form using information from the customer's existing subscription (number of seats, etc.) to make the user experience easier.
    • If the subscription status is ACTIVE, update the initial cart. Use the initialCart for a prorated charge (calculated from now until the nextRenewalTimestamp) for the upgrade. If the subscription status is TRIAL, do not update the initial cart; any changes to the subscription should remain free of charge for the time being.
    • Update the recurringCart to start charging the higher subscription fee starting at the next renewal.
    • If the customer is buying additional user licenses, set the new seatCount.
    • Do not set firstChargeDays or frequency. If a customer adds seats or upgrades their app edition, they still need to keep the same billing cycle, and their free trial period still needs to expire at the same time as originally intended.

The following table summarizes the tasks required to perform a subscription update.

What Where How
Check for a current customer license Shopping page
  • Check the customer's license using the API (see the developer's guide)
  • If the license is ACTIVE subscription is ACTIVE or TRIAL, proceed with the upgrade
Obtain a purchase token for use in constructing the subscription Shopping page
  • If the visitor came from the Marketplace listing page, the Marketplace should provide the query parameter appsmarket.purchaseToken in the URL
  • If the visitor came from a "Purchase More Seats" link, the Marketplace should provide the query parameter appsmarket.purchaseToken in the URL
  • If the visitor came from a link on your site, first, redirect the user to a URL of the form http://google.com/enterprise/marketplace/redirectWithSignature?productListingId=YOUR_PRODUCT_LISTING_ID&domain=CUSTOMER_DOMAIN&supportLink=add-seats, where add-seats is a link defined in the application manifest. When the user returns to site at the URL you provided, the URL will contain the appsmarket.purchaseToken query parameter. The productListingId referenced in this URL is the same ID provided in the link to your application's listing, not your application ID, eg: 123+12345678.
If the subscription is not in a free trial period, set up an immediate, prorated upgrade charge Shopping cart
  • In initialCart set price
  • If the buyer has changed their edition, set editionId
  • If the buyer has changed the number of seats, set seatCount
Set up recurring charges Shopping cart
  • In recurringCart, set price
  • If the buyer has changed their edition, set editionId
  • If the buyer has changed the number of seats, set seatCount
  • Do not set firstChargeDays or frequency, these cannot be changed during an upgrade

The following example shows (using Google-provided client libraries) how to set up an example subscription upgrade, using the example from Subscription with free trial as the basis. Consult the developer's guide to learn more.

import com.google.api.client.http.HttpResponseException;
import com.google.api.client.sample.appsmarket.model.Cart;
import com.google.api.client.sample.appsmarket.model.LineItem;
import com.google.api.client.sample.appsmarket.model.RecurringCart;
import com.google.api.client.sample.appsmarket.model.Subscription;

import java.util.ArrayList;

AppsMarketService service = new AppsMarketService();
service.appId = YOUR_APPLICATION_ID;
service.consumerSecret = YOUR_CONSUMER_SECRET;

// Assumes you are connecting to the sandbox. Use http://www.googleapis.com/appsmarket/v2/ to connect to production.
service.endpoint = "https://www.googleapis.com/appsmarket/v2sandbox/";

service.appName = YOUR_APP_NAME;
service.consumerKey = service.appId + ".apps.googleusercontent.com";
service.authorize();

// Constructs a subscription request. In a complete application, this would be based on details the
// customer has supplied on a product purchasing page.
Subscription sub = new Subscription();
sub.applicationId = service.appId;
sub.customerId = customerId;
sub.purchaseToken = purchaseToken;
sub.name = "SaaSy App Subscription Update";
sub.description = "SaaSy App Subscription Update";
sub.purchaseToken = purchaseToken;
sub.currencyCode = "USD";

// Sets up the information to immediately charge the buyer a prorated upgrade amount.
sub.initialCart = new InitialCart();
sub.initialCart.cart = new Cart();
sub.initialCart.cart.receiptName = "Prorated upgrade fee";
sub.initialCart.cart.receiptDescription = "15 days remaining until next regularly scheduled subscription payment";
LineItem item = new LineItem();
item.name = "My Prorated Upgrade Fee";
item.description = "Mid-term upgrade for SaaSy App";
item.editionId = "premium"
item.developerSku = "premium";
item.price = 3000000L;
item.seatCount = 3;
sub.initialCart.cart.items = new ArrayList();
sub.initialCart.cart.items.add(item);

// Sets up the information for recurring charges to the buyer.
// In this example, the first future billing occurs 30 days from now
// and repeated billings will occur every month thereafter.
sub.recurringCart = new RecurringCart();
sub.recurringCart.cart = new Cart();
sub.recurringCart.cart.receiptName = "Monthly subscription";
sub.recurringCart.cart.receiptDescription = "Recurring charge to maintain subscription";
item = new LineItem();
item.name = "My Subscription";
item.description = "Subscription billing for SaaSy App";
item.editionId = "premium";
item.developerSku = "premium";
item.seatCount = 3; // Set this to -1 for a site license.
item.price = 6000000L;
sub.recurringCart.cart.items = new ArrayList();
sub.recurringCart.cart.items.add(item);

Subscription response = service.insertSubscription(sub);
from apiclient.discovery import build
from apiclient.oauth import OAuthCredentials

import httplib2
import oauth2 as oauth

http = httplib2.Http()
consumer = oauth.Consumer(YOUR_CONSUMER_KEY, YOUR_CONSUMER_SECRET)
token = oauth.Token('', '')
credentials = OAuthCredentials(consumer, token, YOUR_APP_NAME)
http = credentials.authorize(http)

# Assumes you are connecting to the sandbox. Use version='v2' to connect to production.
service = build(serviceName='appsmarket', version='v2sandbox', http=http)

# Constructs a subscription request. In a complete application, this would be
# based on details the customer has supplied on a product purchasing page.
subscription = {
  'applicationId': YOUR_APPLICATION_ID,
  'customerId': customer_id,
  'purchaseToken': purchase_token,
  'name': 'SaaSy App Subscription Update',
  'description': 'SaaSy App Subscription Update',
  'currencyCode': 'USD',  

# Sets up the information to immediately charge the buyer a prorated upgrade amount.
  'initialCart': {
    'cart': {
      'items': [{
        'name': 'My Prorated Upgrade Fee',
        'description': 'Mid-term upgrade for SaaSy App',
        'editionId': 'premium',
        'developerSku': 'premium',
        'seatCount': 3,
        'price': 3000000
      }],
      "receiptName": "Prorated upgrade fee",
      "receiptDescription": "15 days remaining until next regularly scheduled subscription payment"
    }
  }
# Sets up the information for recurring charges to the buyer at the new price.
  'recurringCart': {
    'cart': {
      'items': [{
        'name': 'My Subscription',
        'description': 'Subscription billing for SaaSy App',
        'editionId': 'premium',
        'developerSku': 'premium',
        'seatCount': 3, # Set this to -1 for a site license.
        'price': 6000000
      }],
      "receiptName": "Monthly premium subscription",
      "receiptDescription": "Recurring charge to maintain premium subscription"
    }
  }
}

subscription = service.subscription().insert(body=subscription).execute()
require 'rubygems'
require 'google/api_client'

client = Google::APIClient.new(:authorization => :two_legged_oauth_1)
client.authorization.client_credential_key = YOUR_APPLICATION_ID + '.apps.googleusercontent.com'
client.authorization.client_credential_secret = YOUR_CONSUMER_SECRET
client.discovery_uri = 'http://www.googleapis.com/discovery/0.1/describe?api=appsmarket'

# Assumes you are connecting to the sandbox. Use 'v2' for production.
service = client.discovered_service('appsmarket', 'v2sandbox')

# Constructs a subscription request. In a complete application, this would be
# based on details the customer has supplied on a product purchasing page.
subscription = {
  'applicationId' => YOUR_APPLICATION_ID,
  'customerId' => customer_id,
  'purchaseToken' => purchase_token,
  'name' => 'SaaSy App Subscription Update',
  'description' => 'SaaSy App Subscription Update',
  'currencyCode' => 'USD',  

# Sets up the information to immediately charge the buyer a prorated upgrade amount.
  'initialCart' => {
    'cart' => {
      'items' => [{
        'name' => 'My Prorated Upgrade Fee',
        'description' => 'Mid-term upgrade for SaaSy App',
        'editionId' => 'premium',
        'developerSku' => 'premium',
        'seatCount' => 3,
        'price' => 3000000
      }],
      "receiptName" => "Prorated upgrade fee",
      "receiptDescription" => "15 days remaining until next regularly scheduled subscription payment"
    }
  }
# Sets up the information for recurring charges to the buyer at the new price.
  'recurringCart' => {
    'cart' => {
      'items' => [{
        'name' => 'My Subscription',
        'description' => 'Subscription billing for SaaSy App',
        'editionId' => 'premium',
        'developerSku' => 'premium',
        'seatCount' => 3, # Set this to -1 for a site license.
        'price' => 6000000
      }],
      "receiptName" => "Monthly premium subscription",
      "receiptDescription" => "Recurring charge to maintain premium subscription"
    }
  }
}

json = JSON.dump(subscription)

status, headers, body = client.execute(service.subscription.insert, {}, json, {'Content-Type' => 'application/json'})
subscription = JSON.parse(body.join)

Refunding a customer's money

Refunds are handled through the Checkout Merchant Center. See Refunds in the Google Merchant Help.

Testing

This section explains how to create a test listing and test the billing functionality. These steps assume you have already configured your test environment.

  1. Visit the Google Apps Marketplace sandbox and log in using the ID and password for your test domain.
  2. Click Become a Vendor (first time only) and fill out the forms.
  3. Create a listing or edit an existing listing. Paste in the new application manifest and listing manifest along with any other required fields in the Listing form.
  4. In the Apps Administrator Control Panel, click the Domain Settings tab. In the section "New Services and Pre-Release Features," click "Next Generation."
  5. Go to the sandbox, view the listing, and click the "Add" button. You should see your payment page.
  6. Fill out the payment page (make sure to pay with a different sandbox Google Checkout account than the one that receives payments for your application) and click Submit. You should land back in the Google Apps administrator console.

Using the clock skew

During your testing you will almost certainly want to verify how your subscription works when it's time to renew. With this in mind we have created a clock skew API that may be used to skew the clock forward on a subscription. For example, let's say your application bills monthly, and you just installed it on your test domain (within the last minute). To test renewal in a month with 30 days, you would use the clock skew API to adjust the skew forward by 29 days, 23 hours, and 55 minutes. In less than 5 minutes, your subscription will be up for renewal and trigger the normal renewal flow.

Several important caveats apply when using the clock skew:

  • Clock skews are only available in the sandbox. You cannot test using the clock skew in production.
  • Clock skews apply to all test applications on a domain. If you have multiple test applications installed on a single domain, when you set a clock skew it will apply to all applications on that domain.
  • You may skew in either direction, but if you wish to skew to a time prior to the current skew, you must do the following:
    • Cancel all active subscriptions on the test domain.
    • Delete all installed applications.
    • Delete the clock skew for the test domain.

For details on how to use the clock skew, see the developer's guide.

Licensing notifications

fter your application has been installed by users, you may use the license notifications query to retrieve updates to the status of your application customer domains. The license notifications API provides you with details on four kinds of updates:

  • provisions — A new license of the application has been provisioned.
  • expiries — A license of the application has expired.
  • deletions — An application has been deleted from a domain.
  • reassignments — An administrator has assigned or revoked a seat license for the application on the provided domain.

There are a number of scenarios when you might want to use the license notification API and a background process that polls the API:

  • Provisioning new accounts — you can trigger the provisioning of new accounts on your servers by observing 'provision' and 'reassignment' notifications.
  • Deleting accounts — you can trigger the deletion of accounts on your servers by observing 'reassignment' and 'expiry' notifications.
  • Deleting data — you can trigger the deletion of data on your servers (according to your data retention policies) by observing 'expiry' and 'deletion' notifications.

In general, by polling the license notifications API and responding to the relevant notifications, you can ensure that the accounts and data on your servers properly reflect the current license and seat assignments of your customers.

Caution: This API is not intended to be queried when users are logging into your application or upgrading/downgrading subscriptions. For these purposes, use the user and customer license APIs, respectively.

For details on how to use the license notification API, see the developer's guide.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.