| Note: This is the latest documentation. The previous version of this page is identical — only the left nav differs. |
Note: The information in this document is intended for the following merchants:
Merchants who implemented the Order Processing API before August 2007 will have used the commands described in this document to complete their integrations. If you are implementing the Order Processing API for the first time, Google recommends that you use the API commands that let you specify the fulfillment state of each item in an order. Those commands are defined in a separate document titled XML API Commands for Line-Item Shipping.
Merchants who cannot assign merchant item IDs to the items that they sell cannot use the line-item shipping features of the Order Processing API. These merchants must use order-level shipping as described in this document.
Each Google Checkout order has a financial order state and a fulfillment order state. The fulfillment order state enables you to track orders through the fulfillment process and to convey the fulfillment status to the buyer. Valid fulfillment states are NEW, PROCESSING, DELIVERED and WILL_NOT_DELIVER.
The Order Processing API allows you to either associate a fulfillment status with an entire order or to define a fulfillment state for each item in the order. If you define fulfillment states for each item, then Google Checkout will deduce the fulfillment status for the order. For example, if all of the items in an order have been shipped, then the order's fulfillment status will be DELIVERED. As noted above, if you are implementing the Order Processing API for the first time, Google recommends that you use the XML API commands for line-item shipping.
The Order Processing API provides the following commands to enable you to change an order's fulfillment state, track an order using an internal order number, or communicate information about an order to your customer:
* The <cancel-order> command also changes an order's financial state. As such, the <cancel-order> command is also described in the discussion of the API's financial commands.
This page describes the different fulfillment states that can characterize a Google Checkout order. It also explains each of the API commands that let you change an order's fulfillment state. In addition, this document provides a sample API request for each command as well as a list of errors that the API request may generate. Finally, this page defines the XML tags that these API commands use.
The following table lists the possible fulfillment states for an order. It also provides a description of each state and identifies the actions that place an order in that state.
| Fulfillment State | Action that Places an Order in this State | Description |
| NEW | Buyer submits new order. |
NEW is the default fulfillment state for all new orders. If you are using item-level shipping commands, an order will remain in the new state as long as at least one item in the order is either not yet shipped or backordered. In other words, an order will not be NEW if all of the items in the order are either shipped, cancelled or returned. Similarly, Google will update an order's status to NEW if you reset the shipping status of any item in the order. |
| PROCESSING | process-order |
Even though this order state is still supported, it has effectively been deprecated. To change the fulfillment state for an order to PROCESSING by issuing a process-order order processing command. However, Google specifically recommends against using the process-order command if you are also using item-level shipping commands. With that caveat in mind, the PROCESSING fulfillment state indicates that you are in the process of filling the customer's order. |
| DELIVERED | deliver-order ship-items* (see description) return-items* (see description) cancel-items* (see description) |
The DELIVERED fulfillment state indicates that you have shipped the order and it has been delivered.
|
| WILL_NOT_DELIVER | cancel-order |
The WILL_NOT_DELIVER fulfillment state indicates that you will not ship the items to the customer. An order will automatically update to this state if Google cancels an order for any reason.
|
The <process-order> command instructs Google Checkout to update an order's fulfillment state from NEW to PROCESSING.
<?xml version="1.0" encoding="UTF-8"?> <process-order xmlns="http://checkout.google.com/schema/2" google-order-number="841171949013218"/>
When you issue a <process-order> request, Google Checkout displays a note in the buyer's inbox indicating that you are processing the order. This command is optional. If you do not send a <process-order> request, Google will not display the message.
The <deliver-order> command instructs Google Checkout to update an order's fulfillment state from either NEW or PROCESSING to DELIVERED. You would send this command after the order has been charged and shipped.
Note: The <deliver-order> command effectively marks all of the items in an order as shipped. You can use the <ship-items> command for line-item shipping to specify only those items in an order that really have been shipped.
The following XML shows a sample <deliver-order> request:
<?xml version="1.0" encoding="UTF-8"?> <deliver-order xmlns="http://checkout.google.com/schema/2" google-order-number="841171949013218"> <tracking-data> <carrier>UPS</carrier> <tracking-number>Z5498W45987123684</tracking-number> </tracking-data> <send-email>true</send-email> </deliver-order>
The <add-tracking-data> command instructs Google Checkout to associate a shipper's tracking number with an order. The Google Checkout Program Policies and Guidelines state that you must provide shipment tracking information for your orders as that information becomes available. This command does not impact the order's fulfillment state.
The following XML shows a sample <add-tracking-data> request:
<?xml version="1.0" encoding="UTF-8"?> <add-tracking-data xmlns="http://checkout.google.com/schema/2" google-order-number="841171949013218"> <tracking-data> <carrier>UPS</carrier> <tracking-number>Z9842W69871281267</tracking-number> </tracking-data> </add-tracking-data>
Requests to add tracking data to an order could generate the following errors:
Invalid Argument Errors
The <cancel-order> command instructs Google Checkout to cancel a particular order. If the customer has already been charged, you must refund the customer's money before you can cancel the order. You may issue a <cancel-order> command for an order that is in either of the following financial order states:
The <cancel-order> command effectively marks all of the items in an order as canceled. An order cannot be removed from the CANCELLED state. However, you can use the <cancel-items> command for line-item shipping to specify that only specific items in an order have been canceled. When you cancel specific items in an order, that order will not transition to the CANCELLED state unless you actually cancel all of the items in the order.
Note: Even after you have issued a <cancel-order> command, you should not assume that Google has canceled the order until you receive an order-state-change-notification confirming that the financial order state was updated to CANCELLED.
The following XML shows a sample <cancel-order> command:
<?xml version="1.0" encoding="UTF-8"?> <cancel-order xmlns="http://checkout.google.com/schema/2" google-order-number="841171949013218"> <reason>Buyer cancelled the order.</reason> <comment>Buyer ordered another item.</comment> </cancel-order>
Requests to cancel an order could generate the following errors:
Invalid State Errors
The <add-merchant-order-number> command instructs Google Checkout to associate a merchant-assigned order number with an order. This command does not impact the order's fulfillment state.
The following XML shows a sample <add-merchant-order-number> request:
<?xml version="1.0" encoding="UTF-8"?> <add-merchant-order-number xmlns="http://checkout.google.com/schema/2" google-order-number="841171949013218"> <merchant-order-number>P6502-53-7861SBJD</merchant-order-number> </add-merchant-order-number>
The <send-buyer-message> command instructs Google Checkout to place a message in the buyer's Google Checkout account. It may also include an optional argument instructing Google Checkout to also email the message to the buyer. This command does not impact the order's fulfillment state.
The following XML shows a sample <send-buyer-message> request. In this request, the optional <send-email> element indicates that Google should email the customer in addition to displaying the message in the customer's Google Checkout account.
<?xml version="1.0" encoding="UTF-8"?> <send-buyer-message xmlns="http://checkout.google.com/schema/2" google-order-number="841171949013218"> <message>Due to high volume, your order will ship next week. Thank you for your patience.</message> <send-email>true</send-email> </send-buyer-message>
The screenshot below shows how the Merchant Center will display financial and fulfillment states for an order. In the Merchant Center, the Chrg column identifies the financial status of the order. The Ship column identifies the fulfillment status of the order.
Merchant Center Inbox
The Merchant Center Inbox displays the following icons in the Chrg and Ship columns:
|
Chrg column values
|
Ship column values
|
* The partial shipment icon only displays for merchants that are using line-item shipping commands.
Certain symbols may be displayed next to some subtags in the definitions below. These symbols, and their meanings, are:
| add-merchant-order-number | |||||||
| Definition | The <add-merchant-order-number> tag instructs Google Checkout to attach a merchant-assigned order number to an order. |
||||||
| Attributes |
|
||||||
| Subtags | merchant-order-number | ||||||
| Content Format | Container | ||||||
| Example | <add-merchant-order-number xmlns="http://checkout.google.com/schema/2" google-order-number="6014423719"> | ||||||
| add-tracking-data | |||||||
| Definition | The <add-tracking-data> tag contains a request to add a shipper's tracking number to an order. |
||||||
| Attributes |
|
||||||
| Subtags | tracking-data | ||||||
| Content Format | Container | ||||||
| Example | <add-tracking-data xmlns="http://checkout.google.com/schema/2" google-order-number="6014423719"> | ||||||
| cancel-order | |||||||
| Definition | The <cancel-order> tag identifies an order that should be canceled. A <cancel-order> command sets the financial-order-state and the fulfillment-order-state to canceled. |
||||||
| Attributes |
|
||||||
| Subtags | comment?, reason | ||||||
| Content Format | Container | ||||||
| Example | <cancel-order xmlns="http://checkout.google.com/schema/2" google-order-number="6014423719"> | ||||||
| carrier | |
| Definition | The <carrier> tag contains the name of the company responsible for shipping the item. Valid values for this tag are DHL, FedEx, UPS, UPS MI, UPS Mail Innovations, USPS and Other. Please note that UPS MI and UPS Mail Innovations both refer to the same UPS service. |
| Subtag of | tracking-data |
| Content Format | String |
| Example | <carrier>UPS MI</carrier> |
| comment | |
| Definition | The <comment> tag contains a comment related to a refunded or canceled order. Note: The maximum accepted length for the tag value is 140 characters. |
| Subtag of | refund-order, cancel-order, cancel-items |
| Content Format | String |
| Example | <comment>Refund processed by Bob Smith</comment> |
| deliver-order | |||||||
| Definition | The <deliver-order> tag indicates that Google should update an order's fulfillment order state to DELIVERED. This tag has one required attribute, which identifies the order to be updated. |
||||||
| Attributes |
|
||||||
| Subtags | tracking-data?, send-email? | ||||||
| Content Format | Container | ||||||
| Example | <deliver-order xmlns="http://checkout.google.com/schema/2" google-order-number="6014423719"> | ||||||
| merchant-order-number | |
| Definition | The <merchant-order-number> tag contains the order number that you have assigned to an order. This number appears in the reconciliation report available in the Merchant Center. |
| Subtag of | add-merchant-order-number |
| Content Format | String (Limit 255 characters) |
| Example | <merchant-order-number>1234abcd</merchant-order-number> |
| 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> |
| process-order | |||||||
| Definition | The <process-order> tag indicates that Google should update an order's fulfillment-order-state to PROCESSING. |
||||||
| Attributes |
|
||||||
| Content Format | Complex | ||||||
| Example | <process-order xmlns="http://checkout.google.com/schema/2" google-order-number="6014423719"/> | ||||||
| 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> |
| send-buyer-message | |||||||
| Definition | The <send-buyer-message> command instructs Google to send a message to a customer about a particular order. |
||||||
| Attributes |
|
||||||
| Subtags | send-email?, message | ||||||
| Content Format | Container | ||||||
| Example | <send-buyer-message xmlns="http://checkout.google.com/schema/2" google-order-number="6014423719"> | ||||||
| send-email | |
| Definition | The <send-email> tag indicates whether Google Checkout should email the buyer with updated information about the shipping status of the items in an order. Google's default behavior is to send an email. To prevent Google Checkout from sending this email, your command must include this element with a value of false. |
| Subtag of | deliver-order, send-buyer-message, backorder-items, cancel-items, reset-items-shipping-information, return-items, ship-items |
| Content Format | Boolean |
| Example | <send-email>true</send-email> |
| tracking-data | |
| Definition | The <tracking-data> tag contains information used to track a package through the carrier. |
| Subtag of | add-tracking-data, deliver-order, tracking-data-list |
| Subtags | carrier, tracking-number |
| Content Format | Container |
| Example | <tracking-data> |
| tracking-number | |
| Definition | The <tracking-number> tag contains the shipper's tracking number that is associated with an order. |
| Subtag of | tracking-data |
| Content Format | String |
| Example | <tracking-number>Z5498W45987123684</tracking-number> |
|
The order has not been charged.
The order has been partially charged.
The order has been fully charged.
The order has been canceled.
The buyer's credit card has been declined.