| Note: This is the latest documentation. The previous version of this page is identical — only the left nav differs. |
Google Checkout uses the Notification API to inform you of a new order or to send you information about an existing order. Each Google Checkout notification sent via this API is an XML document that constitutes the body of an HTTP POST request. 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 of these methods:
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 or about updates to existing orders. To implement the Notification API, you must build and operate a callback service that listens for Google Checkout notifications and then communicates the details of those notifications to your internal order processing systems.
The Notification History API lets you retrieve notifications for a particular order or date range. If you have implemented the Notification API, Google will automatically send you new orders and updates as they occur. On the other hand, if you have implemented the Notification History API, you can retrieve notifications in a data-pull model.
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 explains how you should respond to notifications to indicate whether you handled each notification successfully. This document proceeds to explain the different types of notifications that Google Checkout sends, including an XML 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.
New Order Notifications inform you of new orders that have been submitted through Google Checkout.
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 charge, refund, chargeback or credit card authorization has been processed for an order. These notifications also identify the amount of the transaction.
To implement the Notification API, you must establish a web service that receives and processes Google Checkout notifications. Your web service must be secured by SSL v3 or TLS and must use a valid SSL certificate. The API callback URL that you use for your production account must use port 443, which is the default port for HTTPS. The API callback URL that you use for your Sandbox account may use either port 443 or port 80.
Google Checkout uses HTTP Basic Authentication to send notifications. The following steps explain how Google formats 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.
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.
Include the Content-Type header with the value application/xml; charset=UTF-8
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
When your web service receives a request, the service should verify that the request is authenticated with your Merchant ID and Merchant Key. The notification itself will be an XML document that constitutes the body of the request. Your service should not process a notification unless your service can authenticate the notification.
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 whether you would like to receive notifications in XML format or HTML format. Please note that this document explains the XML notification format.
When your web application receives a notification from Google, the application should attempt to parse and process the notification. Google allows you to choose one of the following processes for responding to notifications. Google recommends that you select the second method because it enables Google to more reliably confirm that you successfully processed a notification.
The following list explains Google Checkout's default policy for notification responses:
If your application parses and processes the notification successfully, the application needs to return an HTTP 200 response code, which indicates that the notification was received and processed successfully. Google will not resend a notification after receiving an HTTP 200 response code.
If your application is unable to parse or process the notification, the application needs to return either a 4xx or 5xx HTTP response code (500, 501, etc.). These response codes indicate that your server has experienced an error or is incapable of performing the request. Your application must not return an HTTP 200 response code.
If you return an error response code, Google will try resending the notification, according to our retry policy, for up to 30 days. Your application should return an error response code even in cases when you know the notification will continue to fail. If Google is unable to successfully send a new order notification to your API callback URL, Google will send you an email to notify you of the new order.
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. This feature is only available on an opt-in basis because it may not be backward-compatible with Google Checkout integrations completed before October 2007. Instructions for opting in to this feature follow the guidelines below.
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 new order notification. (All other types of notifications use the serial-number attribute in the same way.) Example 2 shows a <notification-acknowledgment> with the same serial number. In both examples, the serial number is shown in bold text.
|
Example 1:
<new-order-notification xmlns="http://checkout.google.com/schema/2"
serial-number="85f54628-538a-44fc-8605-ae62364f6c71">
...
</new-order-notification>
Example 2:
<notification-acknowledgment xmlns="http://checkout.google.com/schema/2"
serial-number="85f54628-538a-44fc-8605-ae62364f6c71" />
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 30 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. Please note that this policy represents a significant change from option 1, which describes Google's original policy for notification responses. Under that policy, Google will interpret any HTTP 200 response code as an indication that a notification was successfully processed.
Any other HTTP 2xx or 3xx response code.
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:
Google sends a new order notification when a buyer places an order through Google Checkout. This notification contains the following information:
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.
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. Please note that you must modify the settings in your merchant account if you want to receive the buyer's billing phone number, ship-to phone number, or parsed first and last name. Please see the definitions of the <phone> and <structured-name> tags for more information about enabling these features.
<?xml version="1.0" encoding="UTF-8"?> <new-order-notification xmlns="http://checkout.google.com/schema/2" serial-number="85f54628-538a-44fc-8605-ae62364f6c71"> <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>
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 order state change notification informing you that the order's financial state has been updated to CHARGEABLE.
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> </risk-information-notification>
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 through the Notification API to inform you that it 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 order state change notification informing you that the order's financial state has been updated to CHARGEABLE.
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-state-change-notification>
Google defines a set of notifications that report information about financial transactions for an order. These notifications inform you when an order is charged, refunded, charged back, or authorized to be charged. The following subsections contain information about each of these notifications:
Google Checkout sends a <charge-amount-notification> after successfully charging a customer for an order. Google Checkout will attempt to charge a customer if you send a <charge-order> order processing command requesting a charge. 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>. This notification is typically sent within seconds of the corresponding <charge-order> request.
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> </charge-amount-notification>
Google Checkout sends a <refund-amount-notification> after successfully executing a <refund-order> order processing command. You should not assume that Google has granted a refund until you receive this notification. Typically, this notification is sent within seconds of the corresponding <refund-order> request.
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> </refund-amount-notification>
Google Checkout sends 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> </chargeback-amount-notification>
Google Checkout sends an <authorization-amount-notification> in response to a successful request for an explicit credit card reauthorization.
You can also modify your Checkout API request so that Google sends an <authorization-amount-notification> after Google authorizes the buyer's credit card for a new order. The following XML snippet shows how to modify a Checkout API request in this manner.
<checkout-shopping-cart> ... <order-processing-support> <request-initial-auth-details>true</request-initial-auth-details> </order-processing-support> <checkout-shopping-cart>
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> </authorization-amount-notification>
Certain symbols may be displayed next to some subtags in the definitions below. These symbols, and their meanings, are:
| 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 | 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> |
| 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> |
| 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 |
|
||||||
| 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 |
|
||||||
| 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 | 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 | 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 | 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 |
|
||||||
| 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> |
| 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 | 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 | 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 |
|
||||||
| 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 | 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 |
|
||||||
| Subtag of | 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:
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 |
|
||||||
| 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 |
|
||||||
| 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, 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 |
|
||||||
| 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 |
|
||||||
| 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 |
|
||||||
| Subtag of | item | ||||||
| Content Format | Decimal | ||||||
| Example | <unit-price currency="USD">159.99</unit-price> | ||||||
| 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> |
| 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:
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 |
|
||||||
| Subtags | google-order-number, risk-information, timestamp | ||||||
| Content Format | Container | ||||||
| Example | <risk-information-notification xmlns="http://checkout.google.com/schema/2" serial-number="8571632143"> | ||||||
| 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 |
|
||||||
| 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> |
| charge-amount-notification | |||||||
| Definition | The <charge-amount-notification> tag contains information about a successful charge for an order. |
||||||
| Attributes |
|
||||||
| 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 |
|
||||||
| 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 |
|
||||||
| 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 |
|
||||||
| 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 |
|
||||||
| 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 |
|
||||||
| Subtag of | charge-amount-notification | ||||||
| Content Format | Decimal | ||||||
| Example | <total-charge-amount currency="USD">99.99</total-charge-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 |
|
||||||
| 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 |
|
||||||
| 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 |
|
||||||
| 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 |
|
||||||
| 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 |
|
||||||
| Subtag of | refund-amount-notification | ||||||
| Content Format | Decimal | ||||||
| Example | <total-refund-amount currency="USD">99.99</total-refund-amount> | ||||||
| chargeback-amount-notification | |||||||
| Definition | The <chargeback-amount-notification> tag contains information about a chargeback that Google Checkout processed for an order. |
||||||
| Attributes |
|
||||||
| 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 |
|
||||||
| 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 |
|
||||||
| 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 |
|
||||||
| 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 |
|
||||||
| 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 |
|
||||||
| Subtag of | chargeback-amount-notification | ||||||
| Content Format | Decimal | ||||||
| Example | <total-chargeback-amount currency="USD">99.99</total-chargeback-amount> | ||||||
| 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 |
|
||||||
| 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 |
|
||||||
| 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> |
| 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 |
|
||||||
| Content Format | Empty | ||||||
| Example | <notification-acknowledgment xmlns="http://checkout.google.com/schema/2" serial-number="dc66f8c7"/> | ||||||