Order Report API

Overview

The Order Report API allows you to download a list of Google Checkout orders into a comma-separated file. The API will return a list of orders for a period of up to 31 days, and you can limit results to orders that have specific financial or fulfillment order states.

This document explains the <order-list-request> API command, provides sample API requests for retrieving order reports and defines the XML tags used in an Order Report API request. This document also defines the fields in the report output. The appendixes provide an overview of HTTP Basic Authentication, which you must use to send an API request, and of the XML schema changes associated with this feature.

Sending an Order Report API request

To request an order report, send an <order-list-request> command to Google Checkout using HTTP Basic Authentication. Send your request to one of the following URLs, which are for the sandbox and production environments. In both URLs, you must replace the string MERCHANT_ID with the merchant ID for your sandbox or production account, as appropriate.

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

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

The request must specify a start date and end date for the report. By default, the report will include information about orders with any financial or fulfillment status, but you can also limit the report to only include orders with specific statuses. In addition, you can specify a time zone that should be associated with your start and end dates. The default time zone is UTC.

The following sample request is for all orders submitted in September 2007 in the "America/New_York" time zone:

<order-list-request xmlns="http://checkout.google.com/schema/2"
  start-date="2007-09-01T00:00:00" end-date="2007-09-30T23:59:59">
  <date-time-zone>America/New_York</date-time-zone>
</order-list-request>

The following sample request is for an order report for the same time period that specifies that orders must have a financial status of CHARGED and a fulfillment status of NEW. This type of report might help to identify orders that may not have been shipped even though the customers were charged for the orders.

<order-list-request xmlns="http://checkout.google.com/schema/2"
  start-date="2007-09-01T00:00:00" end-date="2007-09-30T23:59:59">
  <financial-state>CHARGED</financial-state>
  <fulfillment-state>NEW</fulfillment-state>
  <date-time-zone>America/New_York</date-time-zone>
</order-list-request>

A request for an order report could generate the following errors:

• Start date should be before end date.

• You can only download up to 31 days of orders.

• America/Mountain_View is not a valid DateTimeZone id.

XML Tag Definitions

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

Understanding the Report Output

The Order Report API returns a comma-separated file (.csv). Please note that if any of the amount fields contains a comma, then the value in that field will be returned in double quotes. For example, the value 1,223.92 will be returned as "1,223.92" in the .csv file. The example below shows a sample report listing one order that has been partially charged but not shipped:

Google Order Number,Merchant Order Number,Order Creation Date,Currency of Transaction,Order Amount,Amount Charged,Financial Status, Fulfillment Status
552406916759246,,"Sep 17, 2007 7:20:58 PM",USD,198.20,5.55,CHARGED,NEW

The report contains the following fields:

• Google Order Number – This field contains an ID, which Google generated, that uniquely identifies a Checkout order.

• Merchant Order Number – This field identifies the merchant-assigned order number associated with the order. The <add-merchant-order-number> command enables you to attach your internal order number to a Checkout order.

• Order Creation Date – This field specifies the date and time that an order was submitted. The date and time will be presented in the following format:

  Mar 19, 2007 7:20:58 PM.

• Currency of Transaction – This field specifies the unit of currency associated with the order amount. The value will be a three-letter ISO 4217 currency code such as USD or GBP.

• Order Amount – This field contains the total cost of an order, including taxes and shipping costs as well as discounts from coupons and gift certificates.

• Amount Charged – This field specifies the amount of the order that has been charged.

• Financial Status – This field identifies the financial state of an order. The field will contain one of the following values: REVIEWING, CHARGEABLE, CHARGING, CHARGED, PAYMENT_DECLINED, CANCELLED or CANCELLED_BY_GOOGLE. Please see the definition of the <financial-state> tag for more information about each of these states.

• Fulfillment Status – This field identifies the financial state of an order. The field will contain one of the following values: NEW, PROCESSING, DELIVERED or WILL_NOT_DELIVER. Please see the definition of the <fulfillment-state> tag for more information about each of these states.

Appendixes

Appendix A - Authentication

Order Report API requests must meet the following requirements:

• Order report requests must use an HTTPS connection secured by 128-bit SSL v3 or TLS connection using a valid certificate from a major certifying authority. (SSL v2 is not allowed.)
• Order report requests must use HTTP Basic Authentication, using your Merchant ID and Merchant Key as the username and password.

We also strongly 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 sending any data or doing HTTP Basic Authentication.

• The server certificate belongs to checkout.google.com or sandbox.google.com.
• The server certificate was signed by the appropriate Certifying Authority.
• The certificate has not expired.

The following instructions explain how to format HTTP request headers to use HTTP Basic Authentication. As described in the Developer's Guide, you use the same process to authenticate Merchant Calculations API responses and Order Processing API requests.

1. Create a properly formatted XML file for the command being executed. The Google Checkout XML schema defines an XML structure for each type of API request.

2. Follow these steps to create the HTTPS header for your request:

   • Create the Authorization header for your request.

     1. Append a colon to your Google Checkout Merchant ID. Then append your Google Checkout Merchant Key to this value. (The value has the format MERCHANT_ID:MERCHANT_KEY.)

     2. Base64-encode the value you produced in the previous step to generate your authorization key.

     3. Provide the Authorization header for your request using the following format. Replace the text Authorization_Key in this header with your authorization key:

        Authorization: Basic Authorization_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, you would base64-encode the value 1234567890:HsYXFoZfHAqyLcCRYeH8qQ. The example below shows how the base64-encoded value would appear in your request header:

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

3. Post the XML structure created in step 1 to Google Checkout. This URL is constructed using your Google-assigned Merchant ID.

   https://checkout.google.com/api/checkout/v2/request/Merchant/MERCHANT_ID

   Note: You must replace the string MERCHANT_ID with your Google Checkout Merchant ID.

Appendix B - XML Schema Changes

This following elements have been added to the publicly available Google Checkout XML schema to support the Order Report API:

<xs:complexType name="OrderListRequest">
  <xs:all>
    <xs:element name="financial-state" type="tns:FinancialOrderState" minOccurs="0" />
    <xs:element name="fulfillment-state" type="tns:FulfillmentOrderState" minOccurs="0" />
    <xs:element name="date-time-zone" type="xs:string" minOccurs="0" />
  </xs:all>
  <xs:attribute name="start-date" type="xs:dateTime" use="required" />
  <xs:attribute name="end-date" type="xs:dateTime" use="required" />
</xs:complexType>

<xs:element name="order-list-request" type="tns:OrderListRequest" />