Google Checkout Promotion Notifications

Overview

This document explains a Google Checkout feature that enables merchants to receive information about Google promotions in notifications. From time to time, Google runs promotions in which it may contribute a portion of the cost of an order on the buyer's behalf. For example, Google might contribute $10 toward the cost of an order of $50 or more.

This feature is designed to help you to understand whether any portion of an order's total will be paid by a party other than the buyer. By clearly communicating this information to you, you will be able to accurately reflect the amount actually charged to the buyer in any emails or receipts that you send for your Checkout orders.

This feature does not affect the way that you charge or refund orders. If an order does include a promotion, you do not need to charge the buyer and Google separately for that order. Similarly, if you need to issue a refund for an order, you do not need to issue separate refunds to the buyer and to Google.

This document contains the following sections:

• The Enabling the Promotion Notification Feature section explains how to modify your account settings to receive promotion information in your notifications.
• The Promotion Information in New Order Notifications section explains Google will communicate information about promotions in new order notifications.
• The Promotion Information in Amount Notifications section explains how Google will communicate information about promotions in charge amount notifications, refund amount notifications and chargeback amount notifications.
• The XML Tag Definitions section includes definitions of the XML tags used to provide promotion-related information in Google Checkout notifications.

Enabling the Promotion Notification Feature

The following instructions explain how to enable this feature for your account. Please note that you must complete these steps for your sandbox and production accounts.

• Log in to your merchant account.
• Click on the Settings tab.
• Click the Integration link on the left side of the page.
• Expand the list of advanced settings and check the box next to the settings that says, "Notifications must include any amounts involving a Google promotion."
• Click the Save button to update your settings.

After you enable this setting, Google will include information about Google promotions that affect your orders in new order notifications, charge amount notifications, refund amount notifications and chargeback amount notifications.

Promotion Information in New Order Notifications

Google will send information about any promotions applied to an order in the new order notification for that order. Please note that to receive new order notifications, you must have implemented the Notification API.

If you opt to receive information about promotions, your new order notifications may contain a <promotions> tag within the <new-order-notification> tag. (Please note that the <promotions> tag will only appear in a new order notification if there is at least one promotion being applied to the corresponding order.

The <promotions> tag, in turn, contains one or more <promotion> tags, each of which contains information about a single promotion that is being applied to the order. Each promotion tag contains the following information:

• The <id> tag specifies a value that Google uses to uniquely identify a promotion.
• The <name> tag identifies the name of the promotion.
• The <total-amount> tag identifies the amount and currency associated with the promotion. For example, if Google ran a promotion for $10 off any $50 order, then the a href="#tag_total-amount"><total-amount> for any qualifying order would specify a value of $10.
• The <description> tag, which is optional, contains a description of the promotion.

The following XML example shows the basic structure of a new order notification. Several tags have been removed from the example to highlight the change described in this document. Omitted tags are represented by ellipses (...). In addition, new tags that contain promotion information are shown in bold text.

<xml version="1.0" encoding="UTF-8"?>
<new-order-notification xmlns="http://checkout.google.com/schema/"
    serial-number="85f54628-44fc-8605-ae62364f6c71">
    ...
    <promotions>
        <promotion>
            <id>4910</id>
            <name>Google 10 off 50</name>
            <total-amount currency="USD">10</total-amount>
        </promotion>
    </promotions>
    ...
</new-order-notification>

Promotion Information in Amount Notifications

If you enable this feature, Google will also send promotion information in the following amount notifications:

• Charge amount notifications
• Refund amount notifications
• Chargeback amount notifications

For orders that use promotions, each of these notifications will include one new tag that indicates whether a portion of the charge, refund or chargeback is associated with a promotion.

The XML example below shows a charge amount notification for an order that uses a promotion in which Google contributes $10 toward any order of $50 or more. In this case, the merchant requested to fully charge an order of exactly $50.

<xml version="1.0" encoding="UTF-8"?>
<charge-amount-notification xmlns="http://checkout.google.com/schema/2"
    serial-number="95d44287-12b1-4722-bc56-cfaa73f4c0d1">
    <google-order-number>841171949013218</google-order-number>
    <latest-charge-amount currency="USD">50</latest-charge-amount>
    <latest-promotion-charge-amount currency="USD">10</latest-promotion-charge-amount>
    <total-charge-amount currency="USD">50</total-charge-amount>
    <timestamp>2007-03-19T15:06:26.051Z</timestamp>
</charge-amount-notification>

As shown in the example, the additional promotion-related tag identifies the portion of the charge that is associated with the promotion. Similarly, refund amount notifications include the <latest-promotion-refund-amount> tag and chargeback amount notifications include the <latest-promotion-chargeback-amount> tag.

XML Tag Definitions

Certain symbols may be displayed next to some subtags in the definitions below. These symbols, and their meanings, are: