Implementing the Notification XML API

Overview

This document applies to Google Checkout XML API version 2.5, you can find documentation for previous versions of the API here. Google Checkout uses the Notification API to inform you of a new order or to send you information about an existing order. Google Checkout first sends your server serial number notifications to inform you of order notifications. Your server then needs to request the order notification using the Notification History API . The Notification History API allows you to request specific order notifications from Google Checkout servers. The notifications returned constitute the Notification API.

The Notification API is one of two methods that Google Checkout offers for retrieving notifications. Depending on your needs, you might implement either or both the Notification API and the Polling API(beta):

• The Notification API lets you integrate Google Checkout with your internal order fulfillment systems by allowing those systems to receive order information from Google. The API lets Google send you information about new orders and status information on existing orders. To implement the Notification API, you must build and operate a callback service that listens for a serial number notification. Your server then needs to send a request to Google Checkout with the provided serial number to receive the notification. Your server can then process the order, storing details of synchronous return notifications to your internal order processing systems.

• The Polling API enables you to retrieve batches of notifications using a scheduled process. The actual notifications are identical to the ones that you could receive via the Notification API. However, instead of Google sending notifications automatically, the Polling API lets you set the schedule for retrieving notifications. Using the Polling API, you can retrieve all notifications that are less than 180 days old and that are at least 30 minutes old.

Typically, merchants choose to simultaneously integrate the Notification API and the Order Processing API, which allows you to send Google updated information about an order's financial state or its fulfillment state.

This document explains the process for receiving and processing notifications. This document also details the different types of notifications that Google Checkout sends and responds with, including an example for each type. Finally, this document defines the XML tags used in all of the different types of notifications.

The following list identifies the different types of notifications that the API supports. Each item in the list links to a section that describes the notification and provides sample XML for that notification.

• Serial Number Notifications inform you of new notifications for orders submitted through Google Checkout.

• New Order Notifications inform you of new order details.

• Risk Information Notifications provide financial information about a transaction to help you ensure that an order is not fraudulent.

• Order State Change Notifications signal an update to an order's financial status or its fulfillment status.

• Amount Notifications inform you that a credit card authorization, charge, refund or chargeback has been processed for an order. These notifications also identify the amount of the transaction.

Receiving and Processing Notifications

To implement the Notification API, you must establish a web service that receives and processes the Google Checkout serial number notification. Once you receive the serial number, you can then send Notification History requests to pull order information and Order Processing requests to process the order.

Google Checkout uses HTTP Basic Authentication only for requests. The following steps explain how to format HTTP request headers to use HTTP Basic Authentication. You would also use this process to send server-to-server Checkout API requests, Merchant Calculations API responses and Order Processing API commands.

1. Set the Authorization header using your Merchant ID as the username and your Merchant Key as the password. To obtain the header value for an order processing request, take your Merchant ID and then append a colon (:) and your Merchant Key. Finally, base64-encode the entire value. Please note that by base64-decoding the value of the Authorization header, you can confirm that the header value contains your merchant ID and merchant key.

2. Include the Content-Type header with the value application/xml; charset=UTF-8

3. Include the Accept header with the value application/xml; charset=UTF-8

For example, if your Merchant ID is 1234567890 and your Merchant Key is HsYXFoZfHAqyLcCRYeH8qQ, Google will base64-encode the value 1234567890:HsYXFoZfHAqyLcCRYeH8qQ. The example below shows how the base64-encoded value would appear in the request header:

Authorization: Basic MTIzNDU2Nzg5MDpIc1lYRm9aZkhBcXlMY0NSWWVIOHFR
Content-Type: application/xml;charset=UTF-8
Accept: application/xml;charset=UTF-8

After establishing your web service, log in to your Merchant Center account, click on the Settings tab and then click on the Integration link in the menu on the left side of the page. Enter the URL for your web service in the API callback URL field. (You need to enter your API callback URL in both your sandbox account and your production account.) You must also indicate the format you wish to receive notifications and the API version. This documentation covers "Notification as Serial Number" and API Version 2.5.

Responding to the Serial Number Notification

When your web application receives the serial number notification from Google, the application should attempt to parse and process the notification.

Using a notification handshake to confirm successful processing

The following guidelines explain how to respond to notifications using a process that enables Google to more reliably confirm that you successfully processed a notification.

• If your application parses and processes a notification successfully, the application needs to return an HTTP 200 response code as well as the serial number of the notification. You can parse this value from the notification's serial-number attribute. Together, the response code and the serial number signify that you received the notification and processed it successfully. Google will not resend a notification after receiving this type of response.

  To return the serial number in your HTTP response, send a <notification-acknowledgment> response. In that response, set the value of the <notification-acknowledgment> tag's serial-number attribute to the serial number of the notification.

  The following examples demonstrate how to identify and return the serial number for a notification. Example 1 shows how the serial number would be conveyed in a serial number notification Example 2 shows a <notification-acknowledgment> with the same serial number. In both examples, the serial number is shown in bold text.

  Example 1:
  serial-number=134827144342486-00001-7
      
  Example 2:
  <notification-acknowledgment xmlns="http://checkout.google.com/schema/2" 
      serial-number="134827144342486-00001-7" />
  

• If your application is unable to parse or process the notification, the application should return either a 4xx or 5xx response code (500, 501, etc.). These response codes indicate that your server has experienced an error or is incapable of performing the request. Please note that your application should return an error response code even in cases when you know the notification will continue to fail.

If you opt to use this feature, then you must return an HTTP 200 response code and the serial number for a successfully processed notification. Otherwise, Google will try to resend the notification, in accordance with our retry policy, for up to 14 days. Specifically, Google will resend a notification if you send any of the following responses to a notification:

• An HTTP 4xx or 5xx response code. (Google recommends this response for a notification that is not handled successfully.)

• An HTTP 200 response code that does not include the serial number of the processed notification.

• Any other HTTP 2xx or 3xx response code.

Requesting Notifications

Once you've successfully received the serial number notification, you need to use the Notification History API to request the associated notification.

To use the Notification History API, send an HTTP request that uses HTTP Basic Authentication to the appropriate URL:

Sandbox environment:
  https://sandbox.google.com/checkout/api/checkout/v2/reports/Merchant/MERCHANT_ID

Production environment:
  https://checkout.google.com/api/checkout/v2/reports/Merchant/MERCHANT_ID

Please remember to replace MERCHANT_ID with your merchant ID

The Notification History API HTTP request should contain the received serial number following the example below:

<notification-history-request xmlns="http://checkout.google.com/schema/2">
  <serial-number>SERIAL_NUMBER</serial-number>
</notification-history-request>'

Please remember to replace SERIAL_NUMBER with the appropriate serial number.

Google Checkout will respond with the associated order notification. Documentation on each of the notifications can be found below.

Types of Notifications

Serial Number Notifications

Google sends a serial number notification for every order notification. This notification is not in XML format and contains the serial number as a name value pair in the POST message body.

serial-number=134827144342486-00001-7

The serial number is then used in a Notification History API request to pull the associated Google Checkout notification such as the New Order Notification.

<notification-history-request xmlns="http://checkout.google.com/schema/2">
  <serial-number>134827144342486-00001-7</serial-number>
</notification-history-request>'

Order Summary

The order-summary element is not a notification but an important child element of all notifications. It encapsulates relevant order information to provide an easy-to-reference snapshot of order status.

The following XML provides an example of an order-summary element from a New Order Notification.

<order-summary>
  <google-order-number>134827144342486</google-order-number>
  <total-chargeback-amount currency="USD">0.0</total-chargeback-amount>
  <total-charge-amount currency="USD">0.0</total-charge-amount>
  <total-refund-amount currency="USD">0.0</total-refund-amount>
  <purchase-date>2010-04-14T19:01:08.000Z</purchase-date>
  <archived>false</archived>
  <shopping-cart>
    <items>
      <item>
        <item-name>Pizza</item-name>
        <item-description>Awesome pizza</item-description>
        <unit-price currency="USD">144.5</unit-price>
        <quantity>1</quantity>
        <merchant-item-id>1234567890</merchant-item-id>
      </item>
    </items>
  </shopping-cart>
  <order-adjustment>
    <merchant-codes />
    <total-tax currency="USD">14.45</total-tax>
    <shipping>
      <flat-rate-shipping-adjustment>
        <shipping-name>Standard Delivery</shipping-name>
        <shipping-cost currency="USD">4.95</shipping-cost>
      </flat-rate-shipping-adjustment>
    </shipping>
    <adjustment-total currency="USD">19.4</adjustment-total>
  </order-adjustment>
  <buyer-id>122414308041109</buyer-id>
  <buyer-marketing-preferences>
    <email-allowed>false</email-allowed>
  </buyer-marketing-preferences>
  <buyer-shipping-address>
    <email>john-b50abu3dud4@sandbox.google.com</email>
    <company-name></company-name>
    <contact-name>john doe</contact-name>
    <address1>1600 ampitheatre pkwy</address1>
    <address2></address2>
    <phone>800 555-5555</phone>
    <fax></fax>
    <structured-name>
      <first-name>john</first-name>
      <last-name>doe</last-name>
    </structured-name>
    <country-code>US</country-code>
    <postal-code>94043</postal-code>
    <city>mountain view</city>
    <region>CA</region>
  </buyer-shipping-address>
  <order-total currency="USD">163.9</order-total>
  <fulfillment-order-state>NEW</fulfillment-order-state>
  <financial-order-state>REVIEWING</financial-order-state>
</order-summary>  

New Order Notifications

A new order notification contains the following information:

• The <order-summary> element encapsulates relevant order status information at the time of the request. It's mimics the New Order Notification contents and is included in every notification to provide a snapshot of the order status.

• The <shopping-cart> element appears exactly as you sent it to Google in the Checkout API request for the order. The shopping cart contains the list of items in the buyer's order as well as the expiration date for the shopping cart if you provided one.

• The <order-adjustment> element encapsulates information about the shipping method that the buyer selected and the shipping cost. This element also contains the taxes charged to the customer as well as information about any coupons and gift certificates applied to the order. Finally, if you implemented the Merchant Calculations API, this part of the notification will indicate whether Google successfully received a response from your calculations service.

• The <buyer-billing-address> and <buyer-shipping-address> elements encapsulate the billing and shipping addresses for the order, respectively.

• The <order-total> element specifies the amount that the buyer will be charged for the order. Google determines the order total by adding the price of the items, shipping charges and taxes, and then subtracting adjustments for coupons and gift certificates.

• The <buyer-id> element contains an ID that Google uses to uniquely identify a user. The <buyer-marketing-preferences> element indicates whether the buyer would like to receive marketing emails from you.

• The <fulfillment-order-state> element defines the current order fulfillment status, such as NEW, PROCESSING, DELIVERED, etc.

• The <financial-order-state> element defines the current order financial state, such as CHARGEABLE, CHARGED, etc.

Before shipping the items in an order, you should wait until you have also received the risk information notification for that order as well as the order state change notification informing you that the order's financial state has been updated to CHARGEABLE.

The following XML shows a sample new order notification.

<?xml version="1.0" encoding="UTF-8"?>
<new-order-notification xmlns="http://checkout.google.com/schema/2"
    serial-number="85f54628-538a-44fc-8605-ae62364f6c71">
  
  <order-summary>
    ...
  </order-summary>
  <google-order-number>841171949013218</google-order-number>
  <buyer-shipping-address>
    <contact-name>Will Shipp-Toomey</contact-name>
    <email>willstoomey@example.com</email>
    <address1>10 Example Road</address1>
    <city>Sampleville</city>
    <region>CA</region>
    <postal-code>94141</postal-code>
    <country-code>US</country-code>
    <phone>5555551234</phone>
    <structured-name>
      <first-name>Will</first-name>
      <last-name>Shipp-Toomey</last-name>
    </structured-name>
  </buyer-shipping-address>
  <buyer-billing-address>
    <contact-name>Bill Hu</contact-name>
    <email>billhu@example.com</email>
    <address1>99 Credit Lane</address1>
    <city>Mountain View</city>
    <region>CA</region>
    <postal-code>94043</postal-code>
    <country-code>US</country-code>
    <phone>5555557890</phone>
    <structured-name>
      <first-name>Bill</first-name>
      <last-name>Hu</last-name>
    </structured-name>
  </buyer-billing-address>
  <buyer-id>294873009217523</buyer-id>
  <fulfillment-order-state>NEW</fulfillment-order-state>
  <financial-order-state>REVIEWING</financial-order-state>

  <shopping-cart>
    <cart-expiration>
        <good-until-date>2007-12-31T23:59:59-05:00</good-until-date>
    </cart-expiration>
    <items>
      <item>
        <merchant-item-id>GGLAA1453</merchant-item-id>
        <item-name>Dry Food Pack</item-name>
        <item-description>One pack of nutritious dried food for emergencies.</item-description>
        <quantity>1</quantity>
        <tax-table-selector>food</tax-table-selector>
        <unit-price currency="USD">4.99</unit-price>
      </item>
      <item>
        <merchant-item-id>MGS2GBMP3</merchant-item-id>
        <item-name>Megasound 2GB MP3 Player</item-name>
        <item-description>This portable MP3 player stores 500 songs.</item-description>
        <quantity>1</quantity>
        <unit-price currency="USD">179.99</unit-price>
        <merchant-private-item-data>
          <merchant-product-id>1234567890</merchant-product-id>
        </merchant-private-item-data>
      </item>
    </items>
  </shopping-cart>
  <order-adjustment>
    <merchant-calculation-successful>true</merchant-calculation-successful>
    <merchant-codes>
      <coupon-adjustment>
        <applied-amount currency="USD">5.00</applied-amount>
        <code>FirstVisitCoupon</code>
        <calculated-amount currency="USD">5.00</calculated-amount>
        <message>You saved $5.00 for your first visit!</message>
      </coupon-adjustment>
      <gift-certificate-adjustment>
        <applied-amount currency="USD">10.00</applied-amount>
        <code>GiftCert12345</code>
        <calculated-amount currency="USD">10.00</calculated-amount>
        <message>You saved $10.00 with this gift certificate!</message>
      </gift-certificate-adjustment>
    </merchant-codes>
    <total-tax currency="USD">11.05</total-tax>
    <shipping>
      <merchant-calculated-shipping-adjustment>
        <shipping-name>SuperShip</shipping-name>
        <shipping-cost currency="USD">9.95</shipping-cost>
      </merchant-calculated-shipping-adjustment>
    </shipping>
  </order-adjustment>
  <order-total currency="USD">190.98</order-total>
  <buyer-marketing-preferences>
    <email-allowed>false</email-allowed>
  </buyer-marketing-preferences>
  <timestamp>2007-03-19T15:06:26.051Z</timestamp>
</new-order-notification>

Risk Information Notifications

Google Checkout sends a risk information notification after completing its risk analysis on a new order. A risk-information-notification includes financial information such as the customer's billing address, a partial credit card number and other values that help you verify that an order is not fraudulent.

Note: Before shipping the items in the order, you should wait until you have also received the new order notification for the order and the authorization amount notification

informing you of the amount authorized and risk check responses.

The following XML shows a sample risk information notification.

<?xml version="1.0" encoding="UTF-8"?>
<risk-information-notification xmlns="http://checkout.google.com/schema/2"
    serial-number="0b95f758-0332-45d5-aced-5da64c8fc5b9">
  <google-order-number>841171949013218</google-order-number>
  <risk-information>
    <eligible-for-protection>true</eligible-for-protection>
    <billing-address>
      <contact-name>John Smith</contact-name>
      <email>johnsmith@example.com</email>
      <address1>10 Example Road</address1>
      <city>Sampleville</city>
      <region>CA</region>
      <postal-code>94141</postal-code>
      <country-code>US</country-code>
    </billing-address>
    <avs-response>Y</avs-response>
    <cvn-response>M</cvn-response>
    <partial-cc-number>3719</partial-cc-number>
    <ip-address>10.11.12.13</ip-address>
    <buyer-account-age>6</buyer-account-age>
  </risk-information>
  <timestamp>2007-03-19T15:06:26.051Z</timestamp>
  <order-summary>
      ...
  </order-summary>
</risk-information-notification>

Order State Change Notifications

Google sends an order state change notification to notify you that an order's financial status or its fulfillment status has changed. The notification identifies the new financial and fulfillment statuses for the order as well as the previous statuses for that order.

These status changes can be triggered by Order Processing API commands that you send to Google Checkout. For example, if you send Google Checkout a <cancel-order> request, Google will respond both synchronously and through the Notification API to inform you that Google Checkout changed the order's status to CANCELLED.

Note: Before you ship the items in an order, you should ensure that you have already received the new order notification for the order, the risk information notification for the order and an authorization amount notification identifying the chargeable amount.

The following XML shows a sample order state change notification:

<?xml version="1.0" encoding="UTF-8"?>
<order-state-change-notification xmlns="http://checkout.google.com/schema/2"
  serial-number="c821426e-7caa-4d51-9b2e-48ef7ecd6423">
  <google-order-number>841171949013218</google-order-number>
  <new-financial-order-state>CHARGING</new-financial-order-state>
  <new-fulfillment-order-state>NEW</new-fulfillment-order-state>
  <previous-financial-order-state>CHARGEABLE</previous-financial-order-state>
  <previous-fulfillment-order-state>NEW</previous-fulfillment-order-state>
  <timestamp>2007-03-19T15:06:29.051Z</timestamp>
  <order-summary>
      ...
  </order-summary>
</order-state-change-notification>

Amount Notifications

Google defines a set of notifications that report information about financial transactions for an order. These notifications inform you when an order is authorized, charged, refunded or charged back to be charged. The following subsections contain information about each of these notifications:

• Authorization Amount Notifications
• Charge Amount Notifications
• Refund Amount Notifications
• Chargeback Amount Notifications

Authorization Amount Notifications

An <authorization-amount-notification> contains information on the credit card authorized amount and the result of the AVS and CVV checks. The <authorization-amount-notification> is sent after Google Checkout attempts to authorize a buyer's credit card for a new order.

The following XML shows a sample authorization amount notification:

<?xml version="1.0" encoding="UTF-8"?>
<authorization-amount-notification xmlns="http://checkout.google.com/schema/2"
  serial-number="bea6bc1b-e1e2-44fe-80ff-2391b25c2510">
  <google-order-number>841171949013218</google-order-number>
  <authorization-amount currency="USD">226.06</authorization-amount>
  <authorization-expiration-date>2007-03-26T15:06:26.000Z</authorization-expiration-date>
  <avs-response>Y</avs-response>
  <cvn-response>Y</cvn-response>
  <timestamp>2007-03-19T15:06:26.051Z</timestamp>
  <order-summary>
      ...
  </order-summary>
</authorization-amount-notification>

Charge Amount Notifications

Google Checkout responds with a <charge-amount-notification> synchronously after a charge-order request. If you have not selected the option to only receive new order notifications, authorization amount notifications and order state change notifications, Google Checkout will also send you a charge-amount-notification anytime an order has been charged.

You can also instruct Google to automatically charge customers when they submit new orders. To set this preference, log in to your Checkout account and click the Settings tab. Then click the Preferences link in the menu on the left side of the page. Finally, select the option to "Automatically authorize and charge the buyer's credit card."

Note: You should not assume that Google has charged your customer until you have received the <charge-amount-notification> either synchronously or asynchronously.

The following XML shows a sample charge amount notification:

<?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">226.06</latest-charge-amount>
  <total-charge-amount currency="USD">226.06</total-charge-amount>
  <timestamp>2007-03-19T15:12:26.051Z</timestamp>
  <order-summary>
      ...
  </order-summary>
</charge-amount-notification>

Refund Amount Notifications

Google Checkout responds with a <refund-amount-notification> synchronously to a <refund-order> request. Google Checkout will also send this notification asynchronously for any order refund. You should not assume that Google has granted a refund until you receive this notification either synchronously or asynchronously.

The following XML shows a sample refund amount notification:

<?xml version="1.0" encoding="UTF-8"?>
<refund-amount-notification xmlns="http://checkout.google.com/schema/2"
  serial-number="d669f8c7-6d75-4ad6-9278-d2fc997d15f2">
  <google-order-number>841171949013218</google-order-number>
  <latest-refund-amount currency="USD">226.06</latest-refund-amount>
  <total-refund-amount currency="USD">226.06</total-refund-amount>
  <timestamp>2007-03-29T15:06:26.051Z</timestamp>
  <order-summary>
      ...
  </order-summary>
</refund-amount-notification>

Chargeback Amount Notifications

Google Checkout sends a serial number notification to inform you of a <chargeback-amount-notification> when a customer initiates a chargeback against an order and Google approves the chargeback.

The following XML shows a sample chargeback amount notification:

<?xml version="1.0" encoding="UTF-8"?>
<chargeback-amount-notification xmlns="http://checkout.google.com/schema/2"
  serial-number="bea6bc1b-e1e2-44fe-80ff-0180e33a2614">
  <google-order-number>841171949013218</google-order-number>
  <latest-chargeback-amount currency="USD">226.06</latest-chargeback-amount>
  <total-chargeback-amount currency="USD">226.06</total-chargeback-amount>
  <timestamp>2007-04-19T15:06:26.051Z</timestamp>
  <timestamp>2007-03-29T15:06:26.051Z</timestamp>
  <order-summary>
      ...
  </order-summary>
</chargeback-amount-notification>

XML Tag Definitions

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

API Tags for All Notifications

google-order-number
Definition	The <google-order-number> tag contains an ID, which Google generates, that uniquely identifies an order. In a Notification History API request, when the <google-order-number> tag appears as a subtag of <order-numbers>, it specifies an order for which you are requesting notifications. When the tag appears as a subtag of <invalid-order-numbers> in a Notification History API response, it specifies an order that did not match one of your orders in the Checkout database even though you requested notifications for that order.
Subtag of	order-summary, new-order-notification, order-state-change-notification, risk-information-notification, charge-amount-notification, refund-amount-notification, chargeback-amount-notification, authorization-amount-notification, order-numbers, invalid-order-numbers
Content Format	String
Example	<google-order-number>6014423719</google-order-number>

order-summary
Definition	The <order-summary> tag mimics the new order notification and contains information about the current status of an order, such as the billing address or fulfillment status order. Every notification from Google Checkout includes order-summary to provide a snapshot of the order status.
Subtag of	new-order-notification, order-state-change-notification, risk-information-notification, charge-amount-notification, refund-amount-notification, chargeback-amount-notification, authorization-amount-notification
Subtags	google-order-number, buyer-billing-address, buyer-id, buyer-marketing-preferences, buyer-shipping-address, financial-order-state, fulfillment-order-state, google-order-number, order-adjustment, order-total, promotions?, shopping-cart, timestamp
Content Format	Container
Example	<order-summary>...<order-summary>

timestamp
Definition	The <timestamp> tag contains a date and time in ISO 8601 format.
Subtag of	new-order-notification, order-state-change-notification, risk-information-notification, charge-amount-notification, refund-amount-notification, chargeback-amount-notification, authorization-amount-notification
Content Format	Date
Example	<timestamp>2007-03-19T15:06:26.051Z</timestamp>

Order Summary Tags

archived
Definition	The <archived> tag contains a boolean to define if the order has been archived
Subtag of	order-summary
Content Format	Boolean
Example	<archived>false</archived>

purchase-date
Definition	The <purchase-date> tag contains a date and time in ISO 8601 format.
Subtag of	order-summary
Content Format	Date
Example	<purchase-date>2007-03-19T15:06:26.051Z</purchase-date>

New Order Notification Tags

address1
Definition	The <address1> tag identifies the first line of the address to which an order is being shipped.
Subtag of	buyer-billing-address, buyer-shipping-address, billing-address
Content Format	String
Example	<address1>1600 Amphitheatre Parkway</address1>

address2
Definition	The <address2> tag identifies the second line of the address to which an order is being shipped.
Subtag of	buyer-billing-address, buyer-shipping-address, billing-address
Content Format	String
Example	<address2>Building 41</address2>

adjustment-total
Definition	The <adjustment-total> tag contains the total adjustment to an order total based on tax, shipping, gift certificates and coupon codes.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	order-adjustment
Content Format	Decimal
Example	<adjustment-total currency="USD">11.05</adjustment-total>

applied-amount
Definition	The <applied-amount> tag contains the amount of a coupon or gift certificate that was applied to an order total.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	coupon-adjustment, gift-certificate-adjustment
Content Format	Decimal
Example	<applied-amount currency="USD">11.05</applied-amount>

buyer-billing-address
Definition	The <buyer-billing-address> tag contains the billing address associated with an order.
Subtag of	new-order-notification
Subtags	address1, address2?, city, company-name?, contact-name?, country-code, email?, fax?, phone?, postal-code, region
Content Format	Complex
Example	<buyer-billing-address>

buyer-id
Definition	The <buyer-id> tag contains an ID that uniquely identifies the user to Google.
Subtag of	order-summary, new-order-notification, merchant-calculation-callback
Content Format	Long
Example	<buyer-id>294873009217523</buyer-id>

buyer-marketing-preferences
Definition	The <buyer-marketing-preferences> tag contains information about the customer's contact preferences.
Subtag of	order-summary, new-order-notification
Subtags	email-allowed
Content Format	Container
Example	<buyer-marketing-preferences>

buyer-shipping-address
Definition	The <buyer-shipping-address> tag contains the shipping address for an order.
Subtag of	order-summary, new-order-notification
Subtags	address1, address2?, city, company-name?, contact-name?, country-code, email?, fax?, phone?, postal-code, region
Content Format	Complex
Example	<buyer-shipping-address>

calculated-amount
Definition	The <calculated-amount> tag contains the calculated amount of a coupon or gift certificate.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	coupon-adjustment, gift-certificate-adjustment, coupon-result, gift-certificate-result
Content Format	Decimal
Example	<calculated-amount currency="USD">11.05</calculated-amount>

cart-expiration
Definition	The <cart-expiration> tag encapsulates information about the date that the cart expires.
Subtag of	shopping-cart
Subtags	good-until-date
Content Format	Container
Example	<cart-expiration>

city
Definition	The <city> tag identifies the city associated with an order's billing or shipping address.
Subtag of	buyer-billing-address, buyer-shipping-address, anonymous-address, billing-address
Content Format	String
Example	<city>Mountain View</city>

code
Definition	The <code> tag contains the code for a coupon or gift certificate that was applied to an order.
Subtag of	coupon-adjustment, gift-certificate-adjustment, coupon-result, gift-certificate-result
Content Format	String
Example	<code>GiftCert12345</code>

company-name
Definition	The <company-name> tag identifies the company to which an order is being shipped. Please note that Google does not currently request this information from customers but may do so in the future. However, until then, this tag will contain an empty value.
Subtag of	buyer-billing-address, buyer-shipping-address, billing-address
Content Format	String
Example	<company-name>Example.com Industries</company-name>

contact-name
Definition	The <contact-name> tag identifies the person to whom an order is being shipped.
Subtag of	buyer-billing-address, buyer-shipping-address, billing-address
Content Format	String
Example	<contact-name>John McShopalot</contact-name>

country-code
Definition	As a subtag of <postal-area>, the <country-code> tag specifies a country associated with a tax area, shipping restriction or address filter Note that Google Checkout does not allow you to ship orders to countries that are export-embargoed for the United States. Google Checkout will return an error if your shipping restrictions or address filters include one of these countries in a shipping area. For example, Iran (IR) and North Korea (KP) may not be included in a shipping area. In all other contexts, the <country-code> tag identifies the country code associated with an order's billing address or shipping address. The value of this tag must be a two-letter ISO 3166 country code.
Subtag of	buyer-billing-address, buyer-shipping-address, anonymous-address, billing-address, postal-area
Content Format	String
Example	<country-code>US</country-code>

coupon-adjustment
Definition	The <coupon-adjustment> tag contains information about a coupon that was applied to an order total.
Subtag of	merchant-codes
Subtags	code, calculated-amount?, applied-amount, message?
Content Format	Container
Example	<coupon-adjustment>

description
Definition	As a subtag of <digital-content>, the <description> tag contains instructions for downloading a digital content item. Please use the <item-description> tag to provide the description of the item being purchased. Note: This field has a maximum length of 1024 characters and may contain HTML tags. (HTML tags must be XML-escaped as described in the Google Checkout Developer's Guide.) As a subtag of <promotion>, the <description> tag contains information about a promotion that Google applied to an order.
Subtag of	digital-content, promotion
Content Format	String
Example	<description>To download this item, link to the URL below and follow the instructions there. When prompted, enter the software key provided below.</description>

email
Definition	The <email> tag identifies an email address that could be used to contact the person to be billed for an order or the order recipient.
Subtag of	buyer-billing-address, buyer-shipping-address, billing-address
Content Format	String
Example	<email>johnm@example.com</email>

email-allowed
Definition	The <email-allowed> tag indicates whether the customer is willing to receive marketing emails from the merchant.
Subtag of	buyer-marketing-preferences
Content Format	Boolean
Example	<email-allowed>true</email-allowed>

fax
Definition	The <fax> tag identifies a fax number that can be used to contact the person to be billed for an order or the order recipient. Please note that Google does not currently request this information from customers but may do so in the future. However, until then, this tag will contain an empty value.
Subtag of	buyer-billing-address, buyer-shipping-address, billing-address
Content Format	String
Example	<fax>800-555-1212</fax>

financial-order-state
Definition	The <financial-order-state> tag identifies the financial status of an order. Valid values for this tag are: REVIEWING - Google Checkout is reviewing the order. CHARGEABLE - The order is ready to be charged. CHARGING - The order is being charged; you may not refund or cancel an order until is the charge is completed. CHARGED - The order has been successfully charged; if the order was only partially charged, the buyer's account page will reflect the partial charge. PAYMENT_DECLINED - The charge attempt failed. CANCELLED - Either the buyer or the seller canceled the order. An order's financial state cannot be changed after the order is canceled. Learn more about when an order may be canceled. CANCELLED_BY_GOOGLE - Google canceled the order. Google may cancel orders due to a failed charge without a replacement credit card being provided within a set period of time or due to a failed risk check. If Google cancels an order, you will be notified of the reason the order was canceled in the <reason> tag of an <order-state-change-notification>. Please see the Financial Commands in the Order Processing API document for more information about these states.
Subtag of	order-summary, new-order-notification
Content Format	String
Example	<financial-order-state>REVIEWING</financial-order-state>

first-name
Definition	The <first-name> tag contains the first name of the buyer or recipient of an order. Please see the Matching Names in Notifications to Names in Your Database section for details about Google Checkout's name-splitting algorithm.
Subtag of	structured-name
Content Format	String
Example	<first-name>John</first-name

flat-rate-shipping-adjustment
Definition	The <flat-rate-shipping-adjustment> tag contains shipping and handling costs for items that have flat-rate shipping costs.
Subtag of	shipping
Subtags	shipping-name, shipping-cost
Content Format	Container
Example	<flat-rate-shipping-adjustment>

fulfillment-order-state
Definition	The <fulfillment-order-state> tag indicates the status of an order in the order handling process. Valid values for this tag are: NEW - The order has been received but not prepared for shipping. PROCESSING - The order is being prepared for shipping. DELIVERED - The seller has shipped the order. WILL_NOT_DELIVER - The seller will not ship the order; this status is used for canceled orders.
Subtag of	order-summary, new-order-notification
Content Format	String
Example	<fulfillment-order-state>PROCESSING</fulfillment-order-state>

gift-certificate-adjustment
Definition	The <gift-certificate-adjustment> tag contains information about a gift certificate that was applied to an order total.
Subtag of	merchant-codes
Subtags	code, calculated-amount?, applied-amount, message?
Content Format	Container
Example	<gift-certificate-adjustment>

good-until-date
Definition	The <good-until-date> tag identifies the date that the order in a Checkout API request expires. The date must be specified using the ISO 8601 Date and Time Format. The time must include the time-zone designator for UTC (Coordinated Universal Time), which is "Z", or you may specify a local time along with a time-zone offset in hours and minutes. A time zone offset of "+hh:mm" indicates that the date/time uses a local time zone which is "hh" hours and "mm" minutes ahead of UTC. A time zone offset of "-hh:mm" indicates that the date/time uses a local time zone which is "hh" hours and "mm" minutes behind UTC. The examples show dates formatted using the UTC time-zone designator and using time-zone offsets. Note: If you specify a value for this element, Google Checkout will reject the shopping cart if the user submits the cart after the specified date.
Subtag of	cart-expiration
Content Format	Date/Time
Example	<good-until-date>2008-01-01T04:59:59Z</good-until-date> <good-until-date>2007-12-31T11:59:59-05:00</good-until-date>

id
Definition	The <id> tag specifies a value that uniquely identifies a Google Checkout promotion.
Subtag of	promotion
Content Format	String
Example	<id>4910</id>

item
Definition	The <item> tag contains information about an individual item listed in the customer's shopping cart.
Subtag of	items
Subtags	item-name, item-description, unit-price, quantity, merchant-item-id?, tax-table-selector?, digital-content?, merchant-private-item-data?
Content Format	Container
Example	<item>

item-description
Definition	The <item-description> tag contains a description of an item.
Subtag of	item
Content Format	String
Example	<item-description>Easy-to-use MP3 Player</item-description>

item-name
Definition	The <item-name> tag identifies the name of an item.
Subtag of	item
Content Format	String
Example	<item-name>HelloWorld 2GB MP3 Player</item-name>

items
Definition	The <items> tag contains the list of items in the customer's shopping cart.
Subtag of	shopping-cart
Subtags	item*
Content Format	Container
Example	<items>

last-name
Definition	The <last-name> tag contains the last name of the buyer or recipient of an order. Please see the Matching Names in Notifications to Names in Your Database section for details about Google Checkout's name-splitting algorithm.
Subtag of	structured-name
Content Format	String
Example	<last-name>Smith</last-name>

merchant-calculated-shipping-adjustment
Definition	The <merchant-calculated-shipping-adjustment> tag contains shipping and handling costs that were calculated by the merchant using a custom process.
Subtag of	shipping
Subtags	shipping-name, shipping-cost
Content Format	Container
Example	<merchant-calculated-shipping-adjustment>

merchant-calculation-successful
Definition	The <merchant-calculation-successful> tag indicates whether Google Checkout successfully received a <merchant-calculation-results> response from your Merchant Calculations URL.
Subtag of	new-order-notification
Content Format	Boolean
Example	<merchant-calculation-successful>true</merchant-calculation-successful>

merchant-codes
Definition	The <merchant-codes> tag contains a list of gift certificate codes and coupon codes that were applied to an order total.
Subtag of	new-order-notification
Subtags	gift-certificate-adjustment*, coupon-adjustment*
Content Format	Container
Example	<merchant-codes>

merchant-item-id
Definition	The <merchant-item-id> tag contains a value, such as a stock keeping unit (SKU), that you use to uniquely identify an item. Google Checkout will include this value in the merchant calculation callbacks and the new order notification for the order. This value also appears in the order information displayed in the Merchant Center. Note: To use the <merchant-item-id> to modify the shipping information for an item in an order, you must have provided the same <merchant-item-id> for that item in the Checkout API request for the order.
Subtag of	item, item-id
Content Format	String
Example	<merchant-item-id>1234abcd</merchant-item-id>

merchant-private-data
Definition	The <merchant-private-data> tag contains any well-formed XML sequence that should accompany an order. Google Checkout will return this XML in the <merchant-calculation-callback> and the <new-order-notification> for the order.
Subtag of	shopping-cart
Content Format	Container
Example	<merchant-private-data>    <merchant-note>my order number 76543</merchant-note> </merchant-private-data>

merchant-private-item-data
Definition	The <merchant-private-item-data> tag contains any well-formed XML sequence that should accompany an individual item in an order. Google Checkout will return this XML in the <merchant-calculation-callback> and the <new-order-notification> for the order.
Subtag of	item
Content Format	Container
Example	<merchant-private-item-data>    <item-data>Popular item - order more if needed</item-data> </merchant-private-item-data>

message
Definition	The <message> tag contains a message associated with a coupon or gift certificate or, when used in a <send-buyer-message> request, a message that you want to communicate to a buyer about a specific order. The maximum accepted length for the tag value is 255 characters.
Subtag of	coupon-adjustment, gift-certificate-adjustment, coupon-result, gift-certificate-result, send-buyer-message
Content Format	String
Example	<message>You saved $10.00 with this gift certificate.</message>

name
Definition	The <name> tag identifies the name that Google uses to identify a promotion in the Merchant Center.
Subtag of	promotion
Content Format	String
Example	<name>Google 10 off 50</name>

new-order-notification
Definition	The <new-order-notification> tag contains information about a new order, including the billing address and shipping address associated with the order.
Attributes	Name Format Description serial-number String The serial-number attribute contains an ID that uniquely identifies a Google Checkout notification.
Subtags	google-order-number, buyer-billing-address, buyer-id, buyer-marketing-preferences, buyer-shipping-address, financial-order-state, fulfillment-order-state, google-order-number, order-adjustment, order-total, promotions?, shopping-cart, timestamp
Content Format	Container
Example	<new-order-notification xmlns="http://checkout.google.com/schema/2" serial-number="8571632143">

order-adjustment
Definition	The <order-adjustment> tag contains information about adjustments to an order's total cost due to taxes, shipping, coupons and gift certificates.
Subtag of	order-summary, new-order-notification
Subtags	adjustment-total?, merchant-calculation-successful?, merchant-codes?, shipping?, total-tax?
Content Format	Container
Example	<order-adjustment>

order-total
Definition	The <order-total> tag contains the total cost of an order, including taxes and shipping costs as well as discounts from coupons and gift certificates.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	order-summary, new-order-notification
Content Format	Decimal
Example	<order-total currency="USD">321.98</order-total>

phone
Definition	The <phone> tag identifies a phone number that can be used to contact the person to be billed for an order or the order recipient. To receive either the phone number for the buyer or the order recipient, you must set a preference in your Google Checkout merchant account. To set this preference, log in to your merchant account and click the Settings tab. Then click the Integration link on the left side of the page. Expand the list of advanced settings and, depending on your preferences, check the box next to either or both of the following preferences: Return the buyer's ship-to phone number in the new order notification Return the buyer's billing phone number in the new order notification Then click the Save button to update your settings.
Subtag of	buyer-billing-address, buyer-shipping-address, billing-address
Content Format	String
Example	<phone>800-555-1212</phone>

pickup-shipping-adjustment
Definition	The <pickup-shipping-adjustment> tag contains shipping and handling costs for items that will be picked up by the buyer.
Subtag of	shipping
Subtags	shipping-name, shipping-cost
Content Format	Container
Example	<pickup-shipping-adjustment>

postal-code
Definition	The <postal-code> tag identifies the zip code or postal code associated with either a billing address or a shipping address.
Subtag of	buyer-billing-address, buyer-shipping-address, anonymous-address, billing-address
Content Format	String
Example	<postal-code>94043</postal-code>

price
Definition	The <price> tag contains the cost to ship an order using a particular shipping method. This tag has one required attribute, which identifies the currency of the price.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	flat-rate-shipping, pickup, merchant-calculated-shipping
Content Format	Decimal
Example	<price currency="USD">8.54</price>

promotion
Definition	The <promotion> tag contains information about a single promotion that was applied to the cost of an order.
Subtag of	promotions
Subtags	description?, id, name, total-amount
Content Format	Container
Example	<promotion>

promotions
Definition	The <promotions> tag contains a list of promotions that were applied to the cost of an order.
Subtag of	new-order-notification
Subtags	promotion*
Content Format	Container
Example	<promotions>

quantity
Definition	The <quantity> tag identifies how many units of a particular item are included in the customer's shopping cart.
Subtag of	item
Content Format	Integer
Example	<quantity>2</quantity>

region
Definition	The <region> tag identifies the state or province associated with a billing address or shipping address.
Subtag of	buyer-billing-address, buyer-shipping-address, anonymous-address, billing-address
Content Format	String
Example	<region>CA</region>

shipping
Definition	The <shipping> tag contains information about the shipping method and costs associated with an order. When the <shipping> tag appears in a new order notification (as a subtag of <order-adjustment>), it has three possible subtags: <flat-rate-shipping-adjustment>, <merchant-calculated-shipping-adjustment> and <pickup-shipping-adjustment>. When the <shipping> tag appears in a merchant calculation callback (as a subtag of <calculate>), its only subtag is <method>, but that tag may occur multiple times.
Subtag of	order-adjustment, calculate
Subtags	carrier-calculated-shipping-adjustment?, flat-rate-shipping-adjustment?, merchant-calculated-shipping-adjustment?, pickup-shipping-adjustment?, method*
Content Format	Container
Example	<shipping>

shipping-cost
Definition	The <shipping-cost> tag identifies the shipping and handling amount that has been added to an order total.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	merchant-calculated-shipping-adjustment, flat-rate-shipping-adjustment, pickup-shipping-adjustment
Content Format	Decimal
Example	<shipping-cost>9.95</shipping-cost>

shipping-name
Definition	The <shipping-name> tag contains the name of the shipping method that the buyer selected for an order.
Subtag of	merchant-calculated-shipping-adjustment, flat-rate-shipping-adjustment, pickup-shipping-adjustment
Content Format	String
Example	<shipping-name>UPS</shipping-name>

shopping-cart
Definition	The <shopping-cart> tag contains the list of items in a customer order and some other basic order information.
Subtag of	checkout-shopping-cart, order-summary, new-order-notification, merchant-calculation-callback
Subtags	cart-expiration?, items, merchant-private-data?
Content Format	Container
Example	<shopping-cart>

structured-name
Definition	The <structured-name> tag contains the first name and last name of the buyer or recipient of an order. To receive first and last names in notifications, you must set a preference in your Google Checkout merchant account. To set this preference, log in to your merchant account and click the Settings tab. Then click the Integration link on the left side of the page. Expand the list of advanced settings and check the box next to the setting that says, "Provide the first name, last name and full name of the buyer and order recipient in separate fields in the new order notification." Then click the Save button to update your settings.
Subtag of	buyer-shipping-address, buyer-billing-address
Subtags	first-name, last-name
Content Format	Container
Example	<structured-name>

total-amount
Definition	The <total-amount> tag specifies the amount that Google contributed to the cost of an order as a part of an ongoing promotion.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	promotion
Content Format	Decimal
Example	<total-amount currency="USD">10.00</total-amount>

total-tax
Definition	The <total-tax> tag contains the total tax amount for an order.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	order-adjustment, result
Content Format	Decimal
Example	<total-tax currency="USD">11.05</total-tax>

unit-price
Definition	The <unit-price> tag identifies the cost of the item. This tag has one required attribute, which identifies the currency of the price.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	item
Content Format	Decimal
Example	<unit-price currency="USD">159.99</unit-price>

Risk Information Notification Tags

address1
Definition	The <address1> tag identifies the first line of the address to which an order is being shipped.
Subtag of	buyer-billing-address, buyer-shipping-address, billing-address
Content Format	String
Example	<address1>1600 Amphitheatre Parkway</address1>

address2
Definition	The <address2> tag identifies the second line of the address to which an order is being shipped.
Subtag of	buyer-billing-address, buyer-shipping-address, billing-address
Content Format	String
Example	<address2>Building 41</address2>

avs-response
Definition	The <avs-response> tag contains an Address Verification System (AVS) response. Possible values for this tag are: Y - Full AVS match (address and postal code) P - Partial AVS match (postal code only) A - Partial AVS match (address only) N - no AVS match U - AVS not supported by issuer
Subtag of	risk-information, authorization-amount-notification
Content Format	String
Example	<avs-response>Y</avs-response>

billing-address
Definition	The <billing-address> tag contains information about the buyer's billing address.
Subtag of	risk-information
Subtags	address1, address2?, city, company-name?, contact-name, country-code, email?, fax?, phone?, postal-code, region
Content Format	Complex?
Example	<billing-address>

buyer-account-age
Definition	The <buyer-account-age> tag identifies the age, in days, of the buyer's Google Checkout account.
Subtag of	risk-information
Content Format	Integer
Example	<buyer-account-age>6</buyer-account-age>

city
Definition	The <city> tag identifies the city associated with an order's billing or shipping address.
Subtag of	buyer-billing-address, buyer-shipping-address, anonymous-address, billing-address
Content Format	String
Example	<city>Mountain View</city>

company-name
Definition	The <company-name> tag identifies the company to which an order is being shipped. Please note that Google does not currently request this information from customers but may do so in the future. However, until then, this tag will contain an empty value.
Subtag of	buyer-billing-address, buyer-shipping-address, billing-address
Content Format	String
Example	<company-name>Example.com Industries</company-name>

contact-name
Definition	The <contact-name> tag identifies the person to whom an order is being shipped.
Subtag of	buyer-billing-address, buyer-shipping-address, billing-address
Content Format	String
Example	<contact-name>John McShopalot</contact-name>

country-code
Definition	As a subtag of <postal-area>, the <country-code> tag specifies a country associated with a tax area, shipping restriction or address filter Note that Google Checkout does not allow you to ship orders to countries that are export-embargoed for the United States. Google Checkout will return an error if your shipping restrictions or address filters include one of these countries in a shipping area. For example, Iran (IR) and North Korea (KP) may not be included in a shipping area. In all other contexts, the <country-code> tag identifies the country code associated with an order's billing address or shipping address. The value of this tag must be a two-letter ISO 3166 country code.
Subtag of	buyer-billing-address, buyer-shipping-address, anonymous-address, billing-address, postal-area
Content Format	String
Example	<country-code>US</country-code>

cvn-response
Definition	The <cvn-response> tag contains a credit verification value for the order. Possible values for this tag are: M - CVN match N - No CVN match U - CVN not available E - CVN error
Subtag of	risk-information, authorization-amount-notification
Content Format	String
Example	<cvn-response>M</cvn-response>

eligible-for-protection
Definition	The <eligible-for-protection> tag indicates whether an order is eligible for Google Checkout's payment guarantee policy.
Subtag of	risk-information
Content Format	Boolean
Example	<eligible-for-protection>true</eligible-for-protection>

email
Definition	The <email> tag identifies an email address that could be used to contact the person to be billed for an order or the order recipient.
Subtag of	buyer-billing-address, buyer-shipping-address, billing-address
Content Format	String
Example	<email>johnm@example.com</email>

fax
Definition	The <fax> tag identifies a fax number that can be used to contact the person to be billed for an order or the order recipient. Please note that Google does not currently request this information from customers but may do so in the future. However, until then, this tag will contain an empty value.
Subtag of	buyer-billing-address, buyer-shipping-address, billing-address
Content Format	String
Example	<fax>800-555-1212</fax>

ip-address
Definition	The <ip-address> tag contains the buyer's IP address, which Google uses to assess the risk that the order is fraudulent.
Subtag of	risk-information
Content Format	String
Example	<ip-address>10.10.10.10</ip-address>

partial-cc-number
Definition	The <partial-cc-number> tag contains the last four digits of the buyer's credit card number.
Subtag of	risk-information
Content Format	String
Example	<partial-cc-number>1234</partial-cc-number>

phone
Definition	The <phone> tag identifies a phone number that can be used to contact the person to be billed for an order or the order recipient. To receive either the phone number for the buyer or the order recipient, you must set a preference in your Google Checkout merchant account. To set this preference, log in to your merchant account and click the Settings tab. Then click the Integration link on the left side of the page. Expand the list of advanced settings and, depending on your preferences, check the box next to either or both of the following preferences: Return the buyer's ship-to phone number in the new order notification Return the buyer's billing phone number in the new order notification Then click the Save button to update your settings.
Subtag of	buyer-billing-address, buyer-shipping-address, billing-address
Content Format	String
Example	<phone>800-555-1212</phone>

postal-code
Definition	The <postal-code> tag identifies the zip code or postal code associated with either a billing address or a shipping address.
Subtag of	buyer-billing-address, buyer-shipping-address, anonymous-address, billing-address
Content Format	String
Example	<postal-code>94043</postal-code>

region
Definition	The <region> tag identifies the state or province associated with a billing address or shipping address.
Subtag of	buyer-billing-address, buyer-shipping-address, anonymous-address, billing-address
Content Format	String
Example	<region>CA</region>

risk-information
Definition	The <risk-information> tag contains information about the buyer that can be used to detect the risk, including the possibility of fraud, associated with an order.
Subtag of	risk-information-notification
Subtags	avs-response, billing-address, buyer-account-age, cvn-response, eligible-for-protection, ip-address, partial-cc-number
Content Format	Container
Example	<risk-information>

risk-information-notification
Definition	The <risk-information-notification> tag contains information that Google uses to ensure that an order is not fraudulent. The <risk-information-notification> tag is the root tag in a risk information notification.
Attributes	Name Format Description serial-number String The serial-number attribute contains an ID that uniquely identifies a Google Checkout notification.
Subtags	google-order-number, risk-information, timestamp
Content Format	Container
Example	<risk-information-notification xmlns="http://checkout.google.com/schema/2" serial-number="8571632143">

Order State Change Notification Tags

new-financial-order-state
Definition	The <new-financial-order-state> tag identifies the financial-order-state for an order following a status change. The <new-financial-order-state> tag is included in an order state change notification along with a previous-financial-order-state, which identifies the financial-order-state for the order prior to the status change. Please see the Financial Commands in the Order Processing API document or the financial-order-state element definition for a complete list of valid values for this tag.
Subtag of	order-state-change-notification
Content Format	String
Example	<new-financial-order-state>CHARGED</new-financial-order-state>

new-fulfillment-order-state
Definition	The <new-fulfillment-order-state> tag identifies the fulfillment-order-state for an order following a status change. The <new-fulfillment-order-state> tag is included in an <order-state-change-notification> along with a previous-fulfillment-order-state, which identifies the fulfillment-order-state for the order prior to the status change. Please see the fulfillment-order-state element definition for a complete list of valid values for this tag.
Subtag of	order-state-change-notification
Content Format	String
Example	<new-fulfillment-order-state>PROCESSING</new-fulfillment-order-state>

order-state-change-notification
Definition	The <order-state-change-notification> tag contains information about an order that has an updated financial-order-state or fulfillment-order-state.
Attributes	Name Format Description serial-number String The serial-number attribute contains an ID that uniquely identifies a Google Checkout notification.
Subtags	google-order-number, new-fulfillment-order-state, new-financial-order-state, previous-financial-order-state, previous-fulfillment-order-state, reason?, timestamp
Content Format	Complex
Example	<order-state-change-notification xmlns="http://checkout.google.com/schema/2" serial-number="8571632143">

previous-financial-order-state
Definition	The <previous-financial-order-state> tag identifies the financial-order-state for an order prior to a status change. The <previous-financial-order-state> tag is included in an <order-state-change-notification> along with a new-financial-order-state, which identifies the financial-order-state for the order following the status change. Please see the Financial Commands in the Order Processing API document or the financial-order-state element definition for a complete list of valid values for this tag.
Subtag of	order-state-change-notification
Content Format	String
Example	<previous-financial-order-state>CHARGING</previous-financial-order-state>

previous-fulfillment-order-state
Definition	The <previous-fulfillment-order-state> tag identifies the fulfillment-order-state for an order prior to a status change. The <previous-fulfillment-order-state> tag is included in an order-state-change-notification along with a new-fulfillment-order-state, which identifies the fulfillment-order-state for the order following the status change. Please see the fulfillment-order-state element definition for a complete list of valid values for this tag.
Subtag of	order-state-change-notification
Content Format	String
Example	<previous-fulfillment-order-state>NEW</previous-fulfillment-order-state>

reason
Definition	As a subtag of <cancel-order> or <refund-order>, the <reason> tag contains the reason that you are canceling or refunding an order. As a subtag of <order-state-change-notification>, the <reason> tag, if provided, will contain a description of the reason that Google canceled a particular order. For example, Google would cancel an order if the buyer's credit card authorization failed and the buyer did not provide updated credit card information within 168 hours (7 days). This element may be included in an order-state-change notification when an order's financial state is changed to CANCELLED_BY_GOOGLE. Note: The maximum accepted length for the tag value is 140 characters.
Subtag of	cancel-order, cancel-items, order-state-change-notification, refund-order
Content Format	String
Example	<reason>Failed risk check</reason>

Amount Notification Tags

Charge Amount Notification Tags

charge-amount-notification
Definition	The <charge-amount-notification> tag contains information about a successful charge for an order.
Attributes	Name Format Description serial-number String The serial-number attribute contains an ID that uniquely identifies a Google Checkout notification.
Subtags	google-order-number, latest-charge-amount, latest-charge-fee?, latest-promotion-charge-amount?, total-charge-amount, timestamp
Content Format	Container
Example	<charge-amount-notification xmlns="http://checkout.google.com/schema/2" serial-number="dc66f8c7">

flat
Definition	The <flat> tag contains the flat fee amount that applies to a particular order.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	latest-charge-fee
API Commands	Charge Amount Notification
Content Format	Decimal
Example	<flat currency="USD">0.30</flat>

latest-charge-amount
Definition	The <latest-charge-amount> tag contains the amount most recently charged for a particular order.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	charge-amount-notification
Content Format	Decimal
Example	<latest-charge-amount currency="USD">50.00</latest-charge-amount>

latest-charge-fee
Definition	The <latest-charge-fee> tag contains the flat rate fee and percentage fee rate as well as the total cost of the fee associated with this order.
Subtag of	charge-amount-notification
Subtags	percentage, flat, total
API Commands	Charge Amount Notification
Content Format	Container
Example	<latest-charge-fee>

latest-promotion-charge-amount
Definition	The <latest-promotion-charge-amount> tag indicates how much Google contributed to the latest charge amount as a part of an ongoing promotion. For example, suppose Google offered a promotion in which a buyer who completed an order through Google Checkout received $10 off any purchase of $100 or more. If a merchant charged the customer the full amount of a $100 order, then the <latest-charge-amount> value would be $100 and the <latest-promotion-charge-amount> would be $10.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	charge-amount-notification
Content Format	Decimal
Example	<latest-promotion-charge-amount currency="USD">10.00</latest-promotion-charge-amount>

percentage
Definition	The <percentage> tag contains the percentage fee rate that applies to a particular order.
Subtag of	latest-charge-fee
API Commands	Charge Amount Notification
Content Format	Decimal
Example	<percentage>2.90</percentage>

total
Definition	The <total> tag contains the total fee amount that applies to a particular order.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	latest-charge-fee
API Commands	Charge Amount Notification
Content Format	Decimal
Example	<total currency="USD">4.60</flat>

total-charge-amount
Definition	The <total-charge-amount> tag contains the total amount charged for a particular order.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	order-summary, charge-amount-notification
Content Format	Decimal
Example	<total-charge-amount currency="USD">99.99</total-charge-amount>

Refund Amount Notification Tags

latest-fee-refund-amount
Definition	The <latest-fee-refund-amount> tag contains the amount of the transaction fee that has been refunded to the merchant for this order.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	chargeback-amount-notification, refund-amount-notification
API Commands	Chargeback Amount Notification, Refund Amount Notification
Content Format	Decimal
Example	<latest-fee-refund-amount currency="USD">4.30</latest-fee-refund-amount>

latest-promotion-refund-amount
Definition	The <latest-promotion-refund-amount> tag indicates that a portion of the latest refund amount was originally paid by Google as a part of a promotion and is therefore being refunded to Google rather than to the customer. For example, suppose Google offered a promotion in which a buyer who completed an order through Google Checkout received $10 off any purchase of $100 or more. If a merchant refunded the customer the full amount of a $100 order, then the <latest-refund-amount> value would be $100 and the <latest-promotion-refund-amount> would be $10. Accordingly, the buyer would receive a $90 refund ($100 - $10).
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	refund-amount-notification
Content Format	Decimal
Example	<latest-promotion-refund-amount currency="USD">10.00</latest-promotion-refund-amount>

latest-refund-amount
Definition	The <latest-refund-amount> tag contains the most recent refund amount for a particular order.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	refund-amount-notification
Content Format	Decimal
Example	<latest-refund-amount currency="USD">50.00</latest-refund-amount>

refund-amount-notification
Definition	The <refund-amount-notification> tag contains information about a refund that Google Checkout granted to a customer.
Attributes	Name Format Description serial-number String The serial-number attribute contains an ID that uniquely identifies a Google Checkout notification.
Subtags	google-order-number, latest-fee-refund-amount?, latest-refund-amount, latest-promotion-refund-amount?, total-refund-amount, timestamp
Content Format	Container
Example	<refund-amount-notification xmlns="http://checkout.google.com/schema/2" serial-number="dc66f8c7">

total-refund-amount
Definition	The <total-refund-amount> tag contains the total refund amount for a particular order.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	order-summary, refund-amount-notification
Content Format	Decimal
Example	<total-refund-amount currency="USD">99.99</total-refund-amount>

Chargeback Amount Notification Tags

chargeback-amount-notification
Definition	The <chargeback-amount-notification> tag contains information about a chargeback that Google Checkout processed for an order.
Attributes	Name Format Description serial-number String The serial-number attribute contains an ID that uniquely identifies a Google Checkout notification.
Subtags	google-order-number, latest-chargeback-amount, latest-chargeback-fee-amount?, latest-fee-refund-amount?, latest-promotion-chargeback-amount?, total-chargeback-amount, timestamp
Content Format	Container
Example	<chargeback-amount-notification xmlns="http://checkout.google.com/schema/2" serial-number="dc66f8c7">

latest-chargeback-amount
Definition	The <latest-chargeback-amount> tag contains the amount most recently charged back against a particular order.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	chargeback-amount-notification
Content Format	Decimal
Example	<latest-chargeback-amount currency="USD">50.00</latest-chargeback-amount>

latest-chargeback-fee-amount
Definition	The <latest-chargeback-fee-amount> tag contains the amount of the chargeback fee that applies to a particular order.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	chargeback-amount-notification
API Commands	Chargeback Amount Notification
Content Format	Decimal
Example	<latest-chargeback-fee-amount currency="USD">10.00</latest-chargeback-fee-amount>

latest-fee-refund-amount
Definition	The <latest-fee-refund-amount> tag contains the amount of the transaction fee that has been refunded to the merchant for this order.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	chargeback-amount-notification, refund-amount-notification
API Commands	Chargeback Amount Notification, Refund Amount Notification
Content Format	Decimal
Example	<latest-fee-refund-amount currency="USD">4.30</latest-fee-refund-amount>

latest-promotion-chargeback-amount
Definition	The <latest-promotion-chargeback-amount> tag indicates that a portion of the latest chargeback amount was originally paid by Google as a part of a promotion and is therefore being recouped by Google rather than by the customer. For example, suppose Google offered a promotion in which a buyer who completed an order through Google Checkout received $10 off any purchase of $100 or more. If a buyer had completed a $100 order, then the buyer would have paid $90 and Google would have paid $10 of the order total. If the buyer then disputed the charge, then the <latest-chargeback-amount> value would be $100 and the <latest-promotion-chargeback-amount> would be $10.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	chargeback-amount-notification
Content Format	Decimal
Example	<latest-promotion-chargeback-amount currency="USD">10.00</latest-promotion-chargeback-amount>

total-chargeback-amount
Definition	The <total-chargeback-amount> tag contains the total amount charged back against a particular order.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	order-summary, chargeback-amount-notification
Content Format	Decimal
Example	<total-chargeback-amount currency="USD">99.99</total-chargeback-amount>

Authorization Amount Notification Tags

authorization-amount
Definition	The <authorization-amount> tag contains the amount that was reauthorized to be charged to the customer's credit card. Google guarantees that these funds will be available for seven days – 168 hours – from the time that the reauthorization takes place.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	authorization-amount-notification
Content Format	Decimal
Example	<authorization-amount currency="USD">50.00</authorization-amount>

authorization-amount-notification
Definition	The <authorization-amount-notification> tag contains information about a successful reauthorization for an order.
Attributes	Name Format Description serial-number String The serial-number attribute contains an ID that uniquely identifies a Google Checkout notification.
Subtags	google-order-number, authorization-amount, authorization-expiration-date, avs-response, cvn-response, google-order-number, timestamp
Content Format	Container
Example	<authorization-amount-notification xmlns="http://checkout.google.com/schema/2" serial-number="dc66f8c7">

authorization-expiration-date
Definition	The <authorization-expiration-date> tag identifies the time that a credit card authorization for an order expires.
Subtag of	authorization-amount-notification
Content Format	Date/Time
Example	<authorization-expiration-date>2007-03-26T15:06:26.000Z</authorization-expiration-date>

avs-response
Definition	The <avs-response> tag contains an Address Verification System (AVS) response. Possible values for this tag are: Y - Full AVS match (address and postal code) P - Partial AVS match (postal code only) A - Partial AVS match (address only) N - no AVS match U - AVS not supported by issuer
Subtag of	risk-information, authorization-amount-notification
Content Format	String
Example	<avs-response>Y</avs-response>

cvn-response
Definition	The <cvn-response> tag contains a credit verification value for the order. Possible values for this tag are: M - CVN match N - No CVN match U - CVN not available E - CVN error
Subtag of	risk-information, authorization-amount-notification
Content Format	String
Example	<cvn-response>M</cvn-response>

Responding to Notifications

notification-acknowledgment
Definition	Your application must return an HTTP 200 response code when it receives and successfully processes a notification from Google Checkout. We recommend that, in the process of returning the HTTP 200 response code, your application return a <notification-acknowledgment> response, but this is not a required action.
Attributes	Name Format Description serial-number String The serial-number attribute contains an ID that uniquely identifies a Google Checkout notification.
Content Format	Empty
Example	<notification-acknowledgment xmlns="http://checkout.google.com/schema/2" serial-number="dc66f8c7"/>