| Note: This is the latest documentation. The previous version of this page is identical — only the left nav differs. |
This document describes the Notification History API, which enables you to retrieve a list of previously sent Google Checkout notifications. The Notification History 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 Google send you information about new orders or 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. Compared to the Notification API, the Notification History API can simplify your efforts to retrieve notifications in the following ways:
You do not need your own SSL certificate to implement the Notification History API.
You do not need to open your firewall to support or test notifications in a development environment.
You do not need to operate a web service that is always available to receive and process notifications.
Using the Notification History API, you can retrieve all notifications that are less than 450 days old and that are at least 30 minutes old. The following list presents several use cases in which you could use the Notification History API to ensure that your database accurately reflects the status of your Google Checkout orders.
You discover a coding error that prevents you from handling notifications properly. After fixing the error, you need to retrieve past notifications to make sure they are reflected in your database.
You receive a charge amount notification for an order but do not have a database record for the order, which indicates that either you did not receive or did not properly handle the new order notification for that order. Instead of processing the charge amount notification, you use the Notification History API to request a complete history of the notifications that Google Checkout sent for the order.
You need to retrieve the shipping address for a particular order. The shipping address would have been sent in the new order notification for the order, so this use case presents another example in which you did not receive or did not properly handle that notification.
Your database crashes, and you need to repopulate the database.
You use Google Checkout for political contributions and you have not implemented the Notification API. You need to retrieve demographic data about your contributors that is included in new order notifications.
This document contains the following information:
The Sending a Notification History API Request section explains how to submit a request to retrieve Checkout notifications matching a set of request parameters. This section explains how to request notifications for specific orders or for a date range. It also explains how to only retrieve particular types of notifications, such as new order notifications, or to retrieve additional notifications for a query.
The XML Examples section provides several sample API requests for retrieving notifications.
The Handling a Notification History API Response section describes new XML tags used in the Notification History API response. This section also provides a sample XML response.
The XML Tag Definitions section provides detailed definitions of all of the new XML tags that are being introduced to the Google Checkout schema for the Notification History API.
To request a list of notifications from the Notification History API server, send an HTTP request that uses HTTP Basic Authentication to one of the following URLs:
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
The guidelines below explain how to ensure the security of Notification History API requests and responses:
All Notification History API requests use HTTP Basic Authentication to securely transmit information. The XML Developer's Guide explains how to format HTTP request headers to use HTTP Basic Authentication.
All Notification History API responses are secured with SSL. Even though you do not need your own SSL certificate to implement the Notification History API, we still recommend that you verify the authenticity of the server certificate that is presented to you when you make the HTTPS connection with Google. Please verify the items in the checklist below before processing any information in an API response:
The following guidelines explain how to structure your API request. The root XML tag for this request is <notification-history-request>. All of the following tags are optional. However, each API request must include at least one of the four tags marked with an asterisk (*).
The <order-numbers>* tag encapsulates a list of one or more <google-order-number> tags. Each <google-order-number> tag identifies an order for which notifications will be returned in the API response. You can specify up to 16 order numbers for a request. If you do not specify one or more order numbers in your API request, the API response will include notifications for all orders.
The <start-time>* tag identifies the earliest date and time that a notification could have been sent to be included in the API response. The time may not be within 30 minutes of the time that the API request is submitted or more than 450 days earlier than the time that the API request is submitted. If you do specify a start time, you must also specify an end time. If you do not specify a start time, the default start time will be 450 days earlier than the time that the API request was submitted.
The <end-time>* tag identifies the time before which a notification must have been sent to be included in the API response. The time may not be within 30 minutes of the time that the API request is submitted. For example, if the <end-time> value is 2009-01-05T15:00:00, the API will return notifications sent any time between the start time and 2009-01-05T14:59:59. If you specify an end time, you must also specify a start time. If you do not specify an end time, the default end time will be 30 minutes prior to the time that the API request was submitted.
The <next-page-token>* tag contains a value that identifies an additional set of results for an API request. For example, the token could indicate that the API response should contain the third page of results.
The <notification-types> tag encapsulates a list of one or more <notification-type> tags, each of which specifies a type of notification that will be returned in the API response. For example, you could confirm that you had correctly processed all new orders by requesting to only receive new order notifications. If you do not specify one or more notification types, the API will return all notifications matching your request.
The following guidelines explain how these tags may be combined in a Notification History API request:
If your request specifies a next-page token, then it should not specify a start time, an end time, order numbers or notification types.
If your request does not specify a next-page-token, then it must specify either (a) a start time and an end time, or (b) one or more order numbers.
API requests can specify a start time, an end time and one or more order numbers.
API requests can specify notification types as long as the API request specifies either (a) a start time and an end time, (b) one or more order numbers, or (c) a start time, an end time and one or more order numbers.
The following XML examples demonstrate how these tags are used.
The following example demonstrates how a merchant in New York would request all notifications sent in January 2008. Please note that the "Z" in the <start-time> and <end-time> tags indicates that those tags specify UTC dates.
<?xml version="1.0" encoding="UTF-8"?> <notification-history-request xmlns="http://checkout.google.com/schema/2"> <start-time>2008-01-01T05:00:00Z</start-time> <end-time>2008-02-01T05:00:00Z</end-time> </notification-history-request>
The following pseudo-code illustrates the process of submitting this API request and handling the API response.
1 Send <notification-history-request> with start time and end time 2 processNotifications (response.notifications) /* * foreach notification in response <notifications>, handle notification */ 3 while response contains a <next-page-token> tag 4 Send <notification-history-request> with <next-page-token> tag from response 5 processNotifications (response.notifications)
The following example shows an API request for risk information notifications, charge amount notifications and order state change notifications for two specific orders. The Sample Notification History API Response section shows a response to this request.
<?xml version="1.0" encoding="UTF-8"?> <notification-history-request xmlns="http://checkout.google.com/schema/2"> <order-numbers> <google-order-number>841171949013218</google-order-number> <google-order-number>123</google-order-number> </order-numbers> <notification-types> <notification-type>risk-information</notification-type> <notification-type>charge-amount</notification-type> <notification-type>order-state-change</notification-type> </notification-types> </notification-history-request>
The following example shows an API request that specifies the particular set of results that should be included in the API response. For example, the token might indicate to Google that you had already received the first page of results matching your request and that Google should, therefore, return the second page of results. A notification history response will contain a next-page token if additional results matching the API request are available.
<?xml version="1.0" encoding="UTF-8"?> <notification-history-request xmlns="http://checkout.google.com/schema/2"> <next-page-token>CID066LsIjAAGAA</next-page-token> </notification-history-request>
This section explains the format of the Notification History API response. The root XML tag for the response is <notification-history-response>. That tag contains the following elements:
The <notifications> tag encapsulates a list of notifications matching the API request. The different types of notifications that you might receive are described in the Implementing the Notification XML API document.
The <invalid-order-numbers> tag encapsulates a list of one or more <google-order-number> tags. Each <google-order-number> tag identifies an invalid order number that was specified in the API request.
The <next-page-token>* tag contains a value that identifies an additional set of results for an API request. You will need to provide this token in an additional request for more results matching the original request. For example, if 70 notifications match your original request, the response to that request would contain 50 notifications and a <next-page-token> tag. You would need to submit a second request specifying the token value to retrieve the remaining 20 notifications.
The following XML shows a sample Notification History API response. This response corresponds to the request in Example 2 in the sample requests section. In this response, the notifications tag contains a risk information notification, a charge amount notification and an order state change notification for an order. The response also notes that the request also asked for notifications for an invalid order number.
Note: The API request associated with this response specified that the response should only include notifications for specific orders. As such, this response will include all notifications for those orders and will not include a <next-page-token> tag.
<?xml version="1.0" encoding="UTF-8"?> <notification-history-response> <notifications> <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 id="BuyerBillingAddress"> <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-02T10:44:06</timestamp> </risk-information-notification> <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> <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>CHARGED</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> </notifications> <invalid-order-numbers> <google-order-number>123</google-order-number> </invalid-order-numbers> </notification-history-response>
This document defines the following XML tags, which are used in Notification History API requests. The <notification-history-request> tag is the only required element. The Sending a Notification History API Request section explains rules for including optional tags in your request.
The <notification-history-request> tag is the root element for a Notification History API request.
The <start-time> tag specifies the earliest time a notification could have been sent to be included in the API response.
The <end-time> tag specifies the time before which a notification must have been sent to be included in the API response.
The <order-numbers> tag encapsulates a list of orders for which you are requesting notifications.
The <google-order-number> tag identifies a specific order for which you are requesting notifications.
The <notification-types> tag encapsulates a list of notification types for which you are requesting notifications.
The <notification-type> tag identifies a specific type of notification that should be included in the API response.
The <next-page-token> tag contains a value that you can use to request additional notifications matching your query parameters.
Certain symbols may be displayed next to some subtags in the definitions below. These symbols, and their meanings, are:
| end-time | |
| Definition | Optional. The <end-time> tag identifies the time before which a notification must have been sent to be included in the API response. The time may not be within 30 minutes of the time that the API request is submitted. For example, if the <end-time> value is 2007-06-30T15:00:00, the API will return notifications sent any time between the start time and 2007-06-30T14:59:59. Note: The <end-time> value is exclusive, meaning the API response will include all notifications generated prior to, but not exactly at, the end time that you specify. In addition, if you specify an end time, you must also specify a start time. |
| Content Format | Date formatted as YYYY-MM-DDThh:mm:ss or YYYY-MM-DDThh:mm:ssTZD. |
| Example | <end-time>2008-05-19T15:06:26Z</end-time> <end-time>2008-05-19T17:06:26-02:00</end-time> |
| 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 |
| API Commands | New Order Notification, Risk Information Notification, Order State Change Notification, Charge Amount Notification, Refund Amount Notification, Chargeback Amount Notification, Authorization Amount Notification |
| Content Format | String |
| Example | <google-order-number>6014423719</google-order-number> |
| next-page-token | |
| Definition | As a subtag of <notification-history-request>, the <next-page-token> tag contains a value that identifies the set of results that should be included in the API response. For example, the <next-page-token> tag might indicate that your application had already received the first 50 notifications queued up since the start time and that the response to the next request should therefore begin with the fifty-first notification sent after the start time. Note: If your API request specifies a next-page token, then it should not specify a start time, end time, google order numbers or notification types. The token is an encrypted value that includes any filtering criteria specified in the original API request associated with that token. As a subtag of <notification-history-response>, the <next-page-token> tag contains the token that you must submit in a subsequent notification-history-request to retrieve additional notifications matching your query parameters. Note that an API response will not include a <next-page-token> tag if either of the following conditions are true:
Note: The token can be up to 511 characters long and does not have a fixed length. As such, the length of the token may vary from one request to another. |
| Content Format | String |
| Example | <next-page-token>CPeFhvuBIxDxwp6Jn4w6GAI</next-page-token> |
| notification-history-request | |
| Definition | The <notification-history-request> command lets you retrieve a list of notifications from Google Checkout. You can request notifications for particular google order numbers or for a particular date range. In addition, you can also filter your response to only include particular types of notifications. |
| Subtags | next-page-token?, start-time?, end-time?, order-numbers?, notification-types? |
| Content Format | Container |
| Example | <notification-history-request> |
| notification-type | |
| Definition | The <notification-type> tag identifies a type of notification that you would like returned in the API's notification history response. You may request more than one type of notification by adding one <notification-type> tag for each type of notification that you would like returned in the API response. If you do not specify a notification type, the API will return all notifications matching your request. The following list identifies valid values for this tag. Each value clearly maps to a notification defined in the Google Checkout Developer's Guide.
|
| Subtag of | notification-types |
| Content Format | String |
| Example | <notification-type>new-order</notification-type> |
| notification-types | |
| Definition | The <notification-types> tag encapsulates a list of <notification-type> tags, each of which identifies a type of notification that will be included in the API's notification history response. If you specify that only particular types of notifications should be included in the API response, then you must also specify either a start time and end time or a specific set of Google order numbers for which notifications should be returned. |
| Subtags | notification-type* |
| Content Format | Container |
| Example | <notification-types> |
| order-numbers | |
| Definition | The <order-numbers> tag encapsulates a list of google order numbers for which you are requesting a notification history. You can specify up to 16 order numbers per request. The following list explains how the presence of the <order-numbers> tag affects the content of the API response:
|
| Subtags | google-order-number* |
| Content Format | Container |
| Example | <order-numbers> |
| start-time | |
| Definition | Optional. The <start-time> tag identifies the earliest time that a notification could have been sent to be included in the API response. The time may not be within 30 minutes of the time that the API request is submitted or more than 450 days earlier than the time that the API request is submitted. Note: If you specify a start time, you must also specify an end time. |
| Content Format | Date formatted as YYYY-MM-DDThh:mm:ss or YYYY-MM-DDThh:mm:ssTZD. |
| Example | <start-time>2008-05-10T15:06:26</start-time> <start-time>2008-05-10T17:06:26-02:00</start-time> |
This document defines the following XML tags, which are used in Notification History API responses.
The <notification-history-response> tag is the root element for a Notification History API response.
The <next-page-token> tag contains a value that you can use to request additional notifications matching your query parameters.
The <notifications> tag encapsulates the list of notifications in the API response.
The <invalid-order-numbers> tag encapsulates a list of requested order numbers that did not match one of your orders in the Checkout database.
The <google-order-number> tag identifies a specific invalid order for which you requested 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 | 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 |
| API Commands | New Order Notification, Risk Information Notification, Order State Change Notification, Charge Amount Notification, Refund Amount Notification, Chargeback Amount Notification, Authorization Amount Notification |
| Content Format | String |
| Example | <google-order-number>6014423719</google-order-number> |
| invalid-order-numbers | |
| Definition | The <invalid-order-numbers> tag encapsulates a list of google order numbers for which you requested a notification history but that are not valid Google Checkout order numbers. |
| Content Format | Container |
| Example | <invalid-order-numbers> |
| next-page-token | |
| Definition | As a subtag of <notification-history-request>, the <next-page-token> tag contains a value that identifies the set of results that should be included in the API response. For example, the <next-page-token> tag might indicate that your application had already received the first 50 notifications queued up since the start time and that the response to the next request should therefore begin with the fifty-first notification sent after the start time. Note: If your API request specifies a next-page token, then it should not specify a start time, end time, google order numbers or notification types. The token is an encrypted value that includes any filtering criteria specified in the original API request associated with that token. As a subtag of <notification-history-response>, the <next-page-token> tag contains the token that you must submit in a subsequent notification-history-request to retrieve additional notifications matching your query parameters. Note that an API response will not include a <next-page-token> tag if either of the following conditions are true:
Note: The token can be up to 511 characters long and does not have a fixed length. As such, the length of the token may vary from one request to another. |
| Content Format | String |
| Example | <next-page-token>CPeFhvuBIxDxwp6Jn4w6GAI</next-page-token> |
| notification-history-response | |||||||
| Definition | The <notification-history-response> tag contains a response to a notification history request. |
||||||
| Attributes |
|
||||||
| Content Format | Container | ||||||
| Example | <notification-history-response xmlns="http://checkout.google.com/schema/2" serial-number="8571632143"> | ||||||
| notifications | |
| Definition | The <notifications> tag encapsulates the list of notifications returned in the API response. |
| Subtags | authorization-amount-notification*, charge-amount-notification*, chargeback-amount-notification*, new-order-notification*, order-state-change-notification*, refund-amount-notification*, risk-information-notification* |
| Content Format | Container |
| Example | <notifications> |
|
