English | Site Directory

Google Checkout APIs

Understanding Google Checkout Support for Third-Party Conversion Tracking

Affiliate marketers, search engine marketers (SEMs) and web analytics providers enable merchants to track page views and conversions on their websites. To track information, merchants include 1x1 pixel images, known as web beacons, on their web pages. The pixels then relay information about a page view or order to the third-party provider.

This document explains an addition to the Google Checkout XML schema that lets merchants include these web beacons on Google Checkout order confirmation pages. The order confirmation page appears after a customer finishes placing an order.

Please note that Google only supports pixel-based tracking solutions. If you use another solution to track page views and conversions, please work directly with your vendor to determine whether a pixel-based version is available. In addition, Google wants to ensure that conversion tracking information is only sent to reputable providers. Please check our list of approved third-party conversion tracking vendors to verify that your vendor's solution will work with Google Checkout. If you have trouble integrating third-party conversion tracking with Google Checkout, please contact checkout-api-support@google.com.

This document contains the following sections:

Understanding API Changes for Third-Party Conversion Tracking

Google Checkout supports third-party conversion tracking by allowing merchants to include conversion tracking URLs in Checkout API requests. Merchants can pass two types of information about conversion tracking URLs:

  • The url attribute of the <parameterized-url> tag contains the base URL for a web beacon. The base URL may include query string parameters that have a fixed value, such as a partner ID that identifies you to the third-party tracking provider.

  • The optional <url-parameter> tag identifies variables that will be included in the web beacon URL even though the values of those variables are not known when the Checkout API request is submitted. For example, information about the billing and shipping address are not known when the Checkout API request is submitted. The <url-parameter> tag allows you to still include that information in the web beacon URL.

Using this data, Google Checkout will construct the URL for the web beacon by appending the variables with dynamic values to the base URL.

XML Examples

This section provides two XML examples that demonstrate how a merchant would include information about web beacons in a Checkout API request. The XML elements used in the examples are defined in the XML Element Definitions section.

  • Example 1 is a simple use case that does not identify dynamic variables that will to be added to the web beacon URL.

  • Example 2 is a more complex use case that uses four dynamic pixel variables.

Note: Both examples display the new XML elements that have been added to the Google Checkout XML schema to support dynamic pixel tracking as well as the <merchant-checkout-flow-support> tag, which encapsulates those elements. The remaining tags from the Checkout API request have been omitted and are represented in the examples by ellipses (...).

Note: All values must be XML-encoded. In addition the url attribute of the url-parameter has additional encoding requirements.

Example 1

...
<merchant-checkout-flow-support>
    <parameterized-urls>
        <parameterized-url url="http://www.example.com/tracking?partner=123&amp;partnerName=Bob&apos;s%20Big%20Stores"/>
    </parameterized-urls>
    ...
</merchant-checkout-flow-support>
...

Example 2

...
<merchant-checkout-flow-support>
    <parameterized-urls>
        <parameterized-url url="http://www.example.com/tracking?partner=12345&amp;partnerName=Bob&apos;s%20Big%20Stores">
            <parameters>
                <url-parameter name="orderID" type="order-id"/>
                <url-parameter name="totalCost" type="order-total"/>
                <url-parameter name="taxes" type="tax-amount"/>
                <url-parameter name="shipping" type="shipping-amount"/>
            </parameters>
        </parameterized-url>
    </parameterized-urls>
    ...
</merchant-checkout-flow-support>
...

XML Element Definitions

The Google Checkout XML schema uses the following tags to support third-party conversion tracking:

parameterized-urls
parameterized-url
parameters
url-parameter

parameterized-urls
Definition

The <parameterized-urls> tag contains information about all of the web beacons that the merchant wants to add to the Google Checkout order confirmation page. This tag encapsulates a list of one or more <parameterized-url> tags.
Subtag of merchant-checkout-flow-support
Subtags parameterized-url
Example <parameterized-urls>

parameterized-url
Definition

The <parameterized-url> tag contains information about an individual web beacon that will be included on the Google Checkout order confirmation page.

The <parameterized-url> tag has one required attribute, which identifies the base URL for the web beacon. This tag also has one optional subtag, which contains the list of dynamic variables that Google Checkout should add to the base URL.
Attributes
NameDescription
url

The url attribute identifies the base URL for a web beacon that will be included on the Google Checkout order confirmation page. The base URL may include some query string parameters that have a fixed value, such as a partner ID that identifies the merchant to the third-party tracking provider.

Note: Any parameter values in the base URL must be URL-encoded. In addition, the complete base URL must then be XML-encoded. In the example below, the base URL contains a parameter called "partnerName". The original parameter value for the example is Bob's Big Store. The URL-encoded version of the parameter is Bob's%20Big%20Store and the XML-encoded version of that value is Bob&apos;s%20Big%20Store.
Subtag of parameterized-urls
Subtags parameters
Example <parameterized-url
    url="http://www.example.com/tracking?partnerID=123&amp;partnerName=Bob&apos;s%20Big%20Store">
    ...
</parameterized-url>

parameters
Definition

The <parameters> tag encapsulates a list of URL parameters that will be added to the base URL for the web beacon. This tag has one subtag, <url-parameter>, which may appear multiple times.
Subtag of parameterized-url
Subtags url-parameter
Example <parameters>

url-parameter
Definition

The <url-parameter> tag contains information about an individual parameter that will be added to the base URL for a web beacon.

The <url-parameter> tag has two required attributes: the parameter key and the parameter value that Google should include in the web beacon URL.
Attributes
NameDescription
name The name attribute identifies the name of a query string parameter that will be included in a web beacon URL. The attribute's value is the name that the third-party tracking provider uses in its web beacon URLs.
type

The type attribute identifies the value that Google will dynamically substitute in the web beacon URL. The following list identifies the valid values for this attribute.

  • buyer-id - A Google-assigned value that uniquely identifies a customer email address.

  • order-id - A Google-assigned value that uniquely identifies an order. This value is displayed in the Merchant Center for each order. If you have implemented the Notification API, you will also see this value in all Google Checkout notifications.

  • order-subtotal - The total cost for all of the items in the order including coupons and discounts but excluding taxes and shipping charges.

  • order-subtotal-plus-tax - The total cost for all of the items in the order, including taxes, coupons and discounts, but excluding shipping charges.

  • order-subtotal-plus-shipping - The total cost for all of the items in the order, including shipping charges, coupons and discounts, but excluding taxes.

  • order-total - The total cost for all of the items in the order, including taxes, shipping charges, coupons and discounts.

  • tax-amount - The total amount of taxes charged for an order.

  • shipping-amount - The shipping cost associated with an order.

  • coupon-amount - The total amount of all coupons factored into the order total.

  • billing-city - The city associated with the order's billing address.

  • billing-region - The U.S. state associated with the order's billing address.

  • billing-postal-code - The five-digit U.S. zip code associated with the order's billing address.

  • billing-country-code - The two-letter ISO 3166 country code associated with the order's billing address.

  • shipping-city - The city associated with the order's shipping address.

  • shipping-region - The U.S. state associated with the order's shipping address.

  • shipping-postal-code - The five-digit U.S. zip code associated with the order's shipping address.

  • shipping-country-code - The two-letter ISO 3166 country code associated with the order's shipping address.
Subtag of parameters
Example <url-parameter name="taxes" type="tax-amount">

Using AdWords Conversion Tracking with Google Checkout

The following steps explain how merchants who use Google AdWords Conversion Tracking to track conversions can easily integrate this solution with Google Checkout.

  1. Log in to your Google AdWords account. Then click the Conversion Tracking subtab under the Campaign Management tab. If you have already set up conversion tracking for your AdWords account, click the Get conversion page code link outlined in Figure 1. If you have not already set up conversion tracking for your AdWords account, click the Start Tracking Conversions button that appears at the bottom of the page outlined in Figure 2.

    Figure 1: Retrieving AdWords Conversion Tracking Code

    Figure 2: Setting Up AdWords Conversion Tracking for the First Time

  2. The Conversion Tracking Setup page displays a table that asks you to select the types of conversions that you would like to track. Check the box next to the Purchase/Sale conversion type and then click the Continue button at the bottom of the page. The image below, which shows this table, highlights the box that you should check.

  3. The next page allows you to customize the text block that appears to indicate that the purchase was tracked using AdWords Conversion Tracking. Please note that this text block does not appear in Google Checkout, so any selections you make on this page will only affect other sites where you use AdWords Conversion Tracking. When you have completed the page, click the Continue button at the bottom of the page.

  4. The Insert Code page demonstrates how to insert AdWords Conversion Tracking code into your website. A textarea element displays near the bottom of the page with the relevant code snippet as shown in the image below. Please note that the image only displays the part of the page that displays the code snippet.

    To integrate AdWords Conversion Tracking with Google Checkout, you do not need the full code snippet. Instead, you need to extract a URL from the code snippet and use that URL as the value of the <parameterized-url> tag in Checkout API requests. Example 1 in the XML Examples section demonstrates how to use this XML tag. The example below shows a sample AdWords Conversion Tracking code snippet. The URL that you would need to extract from this code snippet is shown in bold, blue text.

    <!-- Google Code for purchase Conversion Page -->
<script language="JavaScript"
type="text/javascript">
<--
var google_conversion_id = 0062225003;
var google_conversion_language = "en_US";
var google_conversion_format = "1";
var google_conversion_color = "666666";
if (1) {
  var google_conversion_value = 1;
}
var google_conversion_label = "purchase";
//-->
</script>
<script language="JavaScript"
src="http://www.googleadservices.com/pagead/conversion.js">
</script>
<noscript>
<img height=1 width=1 border=0
src="http://www.googleadservices.com/pagead/conversion/0062225003/?value=1&label=purchase&script=0">
</noscript>

    Click the Continue button at the bottom of the page to complete your AdWords Conversion Tracking setup.

Note: Data for each of these pages is reported separately in Google Analytics reports.