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 HTML Parameter Definitions section includes definitions of the HTML parameters 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 the following parameters, which collectively contain information about a single promotion that is being applied to the order. Since an order could conceivably qualify for more than one promotion, these parameters may appear more than once in a new order notification. For that reason, the promotion element in the full parameter names will be numbered to allow you to identify all of the information associated with each promotion.

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

The following example shows the basic structure of a new order notification. Several parameters have been removed from the example to highlight the change described in this document. Omitted parameters are represented by ellipses (...).

_type=new-order-notification
  &serial-number=85f54628-44fc-8605-ae62364f6c71
  ...
  &promotions.promotion-1.id=4910
  &promotions.promotion-1.name=Google+10+off+50
  &promotions.promotion-1.total-amount=10
  &promotions.promotion-1.total-amount.currency=10
  ...

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 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.

_type=new-order-notification
  &serial-number=95d44287-12b1-4722-bc56-cfaa73f4c0d1
  &google-order-number=841171949013218
  &latest-charge-amount=50
  &latest-charge-amount.currency=USD
  &latest-promotion-charge-amount=10
  &latest-promotion-charge-amount.currency=USD
  &total-charge-amount=50
  &total-charge-amount.currency=USD
  ×tamp=2007-03-19T15%3A06%3A26.051Z

As shown in the example, the additional promotion-related parameter identifies the portion of the charge that is associated with the promotion. Similarly, refund amount notifications include the latest-promotion-refund-amount parameter and chargeback amount notifications include the latest-promotion-chargeback-amount parameter. Since these parameters all contain monetary values, the currency parameter will also specify the currency associated with the promotion amount.

HTML Parameter Definitions