XML API Commands for Line-Item Shipping

Overview

This document explains a Google Checkout feature that enables merchants to specify different shipping information for individual items in an order. In addition, merchants can identify specific items that have been placed on backorder, canceled or returned. This feature offers several benefits to Google Checkout merchants and their customers.

• This feature lets merchants more accurately convey shipment tracking information to customers. Merchants can specify multiple shipments for an order and identify the items included in each shipment.

• Merchants who drop-ship items from multiple warehouses can easily relay tracking information to Google Checkout for individual shipments.

• Merchants can now correct tracking information for an individual item if the item is mistakenly marked as shipped or associated with the wrong shipment tracking number.

• Merchants can identify items that are out-of-stock as well as items that have been canceled from an order or returned by the customer.

This document explains how merchants can convey shipment tracking information for individual items in an order. It also describes how line-item shipping information will be communicated to customers who complete purchases using Google Checkout.

Providing Shipping Information for Items in an Order

With the introduction of the line-item shipping API commands, you can set the shipping status of each item in an order. The default status for each item is not yet shipped. You can then set the status for individual items to shipped, backordered, cancelled or returned.

When you use the line-item shipping commands, Google will group items into shipments based on the shipping information that you provide. Those shipments will be identified in the Merchant Center and on the customer's Order History page. For example, if two items in an order have the same order tracking information, Google will group those items into a single shipment. Google will display information about the shipment in the Merchant Center and to the customer. Please note that all shipped items that do not have tracking information will be grouped into a single shipment marked as not yet shipped.

The image below shows an order containing two items that are each shipped separately. The merchant has associated a tracking number with the first shipped item but has not sent a tracking number for the second item. Since both items cannot be grouped under the same tracking number, Google displays them as two separate shipments.

Identifying the Items in an Order

All of the API commands for line-item shipping require you to be able to identify items in your order using merchant item IDs. The <merchant-item-id> tag contains a value, such as a SKU, that you use to uniquely identify an item in an order. If you plan to use the line-item shipping API commands, you must include merchant item IDs in the Checkout API request for an order so that you can use the same IDs to specify shipping information for the items in that order.

Please note that Google will accept Checkout API requests in which multiple items have the same merchant item ID. However, each item in an order must have a unique merchant item ID if you are using the line-item shipping commands described in this document.

Note: You must include merchant item IDs in Checkout API requests before you implement the API commands for line-item shipping. We recommend that you begin populating the <merchant-item-id> tag as early as possible in your production systems. Google Checkout will return an error if you try to send line-item shipping commands for an order and the Checkout API request originally associated with the order did not include merchant item IDs.

XML Commands for Line-Item Shipping

This document defines several new XML commands that are used to relay the shipping status of individual items in an order.

• The <ship-items> command specifies shipping information for one or more items in an order. You can specify one or more shipment tracking numbers for each item. You can also indicate whether Google Checkout should send an email notification to the customer with the line-item shipping information.

  Each item that you specify in a <ship-items> command will be marked as shipped in the Merchant Center and on the customer's purchase history page.

• The <backorder-items>, <cancel-items> and <return-items> commands allow you to update the status of one or more items. Each command also lets you opt whether Google Checkout should notify the customer of the status changes.

• The <reset-items-shipping-information> command lets you remove shipping information for one or more items in an order. Each item that you specify in a <reset-items-shipping-information> will have its status reset to not yet shipped. This command will also remove the shipment tracking information associated with any of those items.

Line-Item Shipping and Order State Change Notifications

Each Google Checkout order has a financial order state and a fulfillment order state, and Google Checkout sends an <order-state-change-notification> each time one of these states changes. The possible states for an order are listed in the Order States section of the XML API Developer's Guide.

The following rules explain how an order's fulfillment state is determined.

• An order will be have a fulfillment state of NEW as long as 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.

• An order will have a fulfillment state of WILL_NOT_DELIVER if all of its items have been cancelled.

• An order will have a fulfillment state of DELIVERED if all of the items in the order have either been shipped, returned or cancelled. The only exception to this rule occurs when all of the items in an order are cancelled, as described in the previous bullet point.

• Google will update an order's state to NEW if you reset the shipping status of any items in the order. By resetting the shipping status of an item, you will remove any tracking information associated with that item. After its shipping status is reset, the item's status will be not yet shipped.

The list below explains how shipping commands can cause an order's state to change.

• Google will update an order's state to DELIVERED if you send any number of <ship-items> requests that indicate that all of the items in the order have been shipped.

• Google will update an order's state to DELIVERED if you send a <deliver-order> request for that order.

• Google will not update an order's state from DELIVERED to NEW if you send a <return-items> request for an item in that order. If you receive a returned item, and you plan to replace the returned item, you can reset the shipping status of that item.

• Google will update an order's state to WILL_NOT_DELIVER if you send any number of <cancel-items> requests that indicate that all of the items in the order have been cancelled. By cancelling all of the items in an order, you will also change the order's financial state to CANCELLED. Please note that you will not be able to cancel all of the items in an order unless you have already issued a full refund for that order.

Changing the Shipping Status of an Item

Each item can only have one shipping status at any given time. An item's shipping status will update each time you submit a <ship-items>, <backorder-items>, <cancel-items> or <return-items> request that specifies that item.

Note: You should use the backordered status to identify out-of-stock items that have not yet been shipped. In the Merchant Center and on the buyer's receipt page, backordered items should appear grouped with other items that have not yet shipped. In addition, you should use the returned status to identify items that have already been shipped. Returned items will appear grouped with other shipped items unless you reset the shipping status of the returned item. The following section explains how to reset an item's shipping status.

Resetting an Order's Shipping Status

The <reset-items-shipping-information> command lets you remove the shipping status associated with one or more items and return those items to the Not yet shipped state. This command will also remove any shipment tracking data you have associated with those items. The <reset-items-shipping-information> command can be used to remove tracking information incorrectly associated with an item. It can also be used if you need to replace a returned item and want to remove the tracking information associated with that item before adding tracking information for the replacement.

If an order is in the DELIVERED fulfillment state and you reset the shipping information for an item in that order, the order will transition back to the NEW fulfillment state. When you reset the shipping status of an item, the item will appear in the Merchant Center and the buyer's receipt page to be grouped with other items that are not yet shipped.

Google Checkout does allow you to reset the status of a cancelled item. However, you can not use the <reset-items-shipping-information> command to move an order out of the WILL_NOT_DELIVER fulfillment state. As such, you should not try to reset the status of a cancelled item if all of the other items in the order have also been cancelled.

The following XML example shows a sample <reset-items-shipping-information> request.

<?xml version="1.0" encoding="UTF-8"?>
<reset-items-shipping-information xmlns="http://checkout.google.com/schema/2"
  google-order-number="841171949013218">
    <item-ids>
        <item-id>
            <merchant-item-id>A1</merchant-item-id>
        </item-id>
        <item-id>
            <merchant-item-id>B2</merchant-item-id>
        </item-id>
    </item-ids>
    <send-email>false</send-email>
</reset-items-shipping-information>

Understanding the <ship-items> Command

As noted earlier, the <ship-items> command lets you specify shipping information for one or more items in an order. When you send a <ship-items> request, the shipping information in that request will be appended to the existing shipping records for the specified order.

The XML below shows the basic structure of a <ship-items> request:

<?xml version="1.0" encoding="UTF-8"?>
<ship-items xmlns="http://checkout.google.com/schema/2"
  google-order-number="841171949013218">
    <item-shipping-information-list>
        <item-shipping-information>
            <item-id>
                <merchant-item-id>A1</merchant-item-id>
            </item-id>
            <tracking-data-list>
                <tracking-data>
                    <carrier>UPS</carrier>
                    <tracking-number>55555555</tracking-number>
                </tracking-data>
            </tracking-data-list>
        </item-shipping-information>
    </item-shipping-information-list>
    <send-email>true</send-email>
</ship-items>

The following list describes key elements of this request. Please see Appendix A for several XML examples that show how to use the <ship-items> command for different types of use cases.

• The google-order-number attribute of the <ship-items> tag identifies the order for which you are providing shipping information.

• The <item-id> tag encapsulates a value that uniquely identifies an item in an order. You must use merchant item IDs to identify the items in your order. To learn more about merchant item IDs, please see the Identifying the Items in an Order section of this document.

• The <item-shipping-information> XML block contains the shipping information for a single item in an order. A <ship-items> request may contain shipping information for multiple items, and the request must include an <item-shipping-information> block for each item.

• The <tracking-data> XML block identifies the carrier responsible for shipping the item and you have the option of also providing the order tracking number for the shipment. Since a single item may ship in multiple packages – for example, a merchant may ship a single stereo system in multiple boxes – you may provide multiple <tracking-data> blocks for each item.

Grouping Items into Shipments

As noted earlier, Google will group items into shipments based on the shipping information provided by the merchant. Google will then display those shipments in the Merchant Center and on the customer's Order History page.

For example, suppose a buyer purchases a shirt, a wallet and a belt. The merchant ships the shirt from a different location than the wallet and belt. When the shirt is shipped, the merchant sends a <ship-items> request with the relevant tracking information for the shirt. Then, when the wallet and belt are shipped, the merchant sends another <ship-items> request with the additional tracking information for those two items. In this example, the order contains three items, and one item is shipped from a different location and in a separate package than the other two items. The Merchant Center and the customer's Order History page would both specify two shipments for the order.

Backordered, Cancelled and Returned Items

The line-item shipping API commands include three methods that let you identify backordered, cancelled and returned items. To help ensure a consistent buyer experience, please use the following basic definitions for these terms.

• Backordered items are out of stock.

• Cancelled items are items that are being removed from an order, whether the removal is initiated by the merchant or by a request from the buyer. (If the buyer wants to cancel an item, the merchant must actually cancel the item on the buyer's behalf.) For example, a buyer might contact the merchant to cancel an item that was mistakenly included in an order, or a merchant might cancel a discontinued item.

• Returned items are items that were shipped and sent back to the merchant for a replacement product or a refund.

The list below identifies the API commands for changing item statuses. Requests using any of these commands all follow the same format. The request identifies a list of one or more items that are being updated and also indicates whether Google Checkout should notify the customer of the status change. By default, Google will notify the customer of any shipping status changes. The following subsections provide an example for each of these commands.

<backorder-items>

The <backorder-items> command lets you identify one or more out-of-stock items in an order.

<?xml version="1.0" encoding="UTF-8"?>
<backorder-items xmlns="http://checkout.google.com/schema/2"
  google-order-number="841171949013218">
    <item-ids>
        <item-id>
            <merchant-item-id>A1</merchant-item-id>
        </item-id>
        <item-id>
            <merchant-item-id>B2</merchant-item-id>
        </item-id>
    </item-ids>
    <send-email>false</send-email>
</backorder-items>

<cancel-items>

The <cancel-items> command lets you identify one or more items that are being removed from an order. Please note that if an order has already been charged, you must issue a full refund for that order before submitting a <cancel-items> command that results in all of the items in the order being cancelled. However, Google does not require you to issue a refund before canceling items from a previously charged order if you are not canceling all of the items in the order.

• If you cancel all of the items in an order, Google will update the order's financial state to CANCELLED and the order's fulfillment state to WILL_NOT_DELIVER.

• If you try to cancel all of the items in a charged (or partially charged) order before you issue a full refund for the order, Google will return an error in response to your <cancel-items> request.

<?xml version="1.0" encoding="UTF-8"?>
<cancel-items xmlns="http://checkout.google.com/schema/2"
  google-order-number="841171949013218">
    <reason>This item is no longer manufactured.</reason>
    <comment>Suggested replacement is model XBR2700.</comment>
    <item-ids>
        <item-id>
            <merchant-item-id>A1</merchant-item-id>
        </item-id>
        <item-id>
            <merchant-item-id>B2</merchant-item-id>
        </item-id>
    </item-ids>
    <send-email>false</send-email>
</cancel-items>

<return-items>

The <return-items> command lets you identify one or more items that were shipped to the customer and then sent back to you. The following XML shows a sample <return-items> request.

<?xml version="1.0" encoding="UTF-8"?>
<return-items xmlns="http://checkout.google.com/schema/2"
  google-order-number="841171949013218">
    <item-ids>
        <item-id>
            <merchant-item-id>A1</merchant-item-id>
        </item-id>
        <item-id>
            <merchant-item-id>B2</merchant-item-id>
        </item-id>
    </item-ids>
    <send-email>false</send-email>
</return-items>

When you send a <return-items> request, information about the returned item displays in the Order History and Order Details sections of the buyer's receipt page. The images below show how the information about the returned item appears in these two sections.

Order History

Order Details

Use Cases for Processing Returned Items

• If the customer returns an item for a refund, then the final state of the item will be Returned. You must send a separate <refund-order> API request to instruct Google Checkout to issue the refund. In addition, if all of the other items in the order have already been shipped, cancelled or returned, then the order's status will be DELIVERED.

• If the customer returns an item and you need to send a replacement, then the Returned status is a temporary one. (After you ship the replacement for the returned item, you should reset the item's shipping information and then send a <ship-items> with the new tracking information. As such, the final status of the item will be Shipped.)

  On the buyer's receipt page, the returned item will be grouped in a shipment and the word Returned will appear next to the item as shown in the Order Details image above. If all of the other items in the order have already been shipped, cancelled or returned, then the order's status will remain at DELIVERED unless you reset the shipping status of the returned item. Resetting the item's shipping status will change the order's fulfillment state to NEW. In addition, after you reset the returned item's shipping status, that item will display with other items that have not yet shipped and the Returned text will no longer display next to the item. However, the order history will still indicate that the item had been returned.

Additional API Commands for Line-Item Shipping

The following commands are relevant for merchants that are using either line-item shipping or order-level shipping.

<add-merchant-order-number>

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>

<send-buyer-message>

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>

Order-Level Shipping Commands

This section explains how the existing <deliver-order> and <cancel-order> commands relate to line-item shipping. The following list identifies the API commands for order-level shipping.

• The <deliver-order> command is an alias for a <ship-items> command that specifies all of the items in an order. Google will take three actions in response to a <deliver-order> request.

  • Google will mark all of the items in the order as shipped.

  • If the request specifies shipment tracking information, Google will associate that tracking data with all of the items in the order. Please note that a <deliver-order> request may only specify a single tracking number. If you want to provide multiple tracking numbers that apply to all of the items in an order, you can submit one <deliver-order> request for each tracking number.

  • Google will update the order's fulfillment state to DELIVERED.

• The <cancel-order> command is an alias for a <cancel-items> command that specifies all of the items in an order. Google will take two actions in response to a <cancel-order> request.

  • Google will mark all of the items in the order as cancelled. Google will not allow you to cancel all of the items in an order unless you have already issued a full refund on the order.

  • Google will update the order's fulfillment state to WILL_NOT_DELIVER.

  • Google will update the order's financial state to CANCELLED.

Deprecated Commands

With the introduction of the line-item shipping feature, Google will be deprecating two commands – <add-tracking-data> and <process-order> – that are already documented in the XML API Developer's Guide.

Please note that Google will continue to support these commands. However, we discourage you from using these commands in conjunction with the line-item shipping commands described in this document.

Appendixes

Appendix A - XML Examples for the <ship-items> Command

The XML examples below explain how to use the <ship-items> command to convey several different shipping scenarios for an order.

Note: These examples demonstrate how to send shipping information to the API using a minimal number of API requests. You can also implement this API functionality so that your system sends one API request per item, with each request only containing the shipping information for that one item. In such an implementation, for an order with three items, your system would send at least three API requests. (For example, your system might send more than one request per item if you shipped a single item in multiple boxes and configured your system to send an API request each time a box was shipped.)

Example 1: Two items ship in separate boxes

This example describes an order that contains two items, which are identified by the merchant-item-ids A1 and B2. In this example, each of the items in the order ships at the same time, but in a separate box. Each <item-shipping-information> XML block in the example specifies a different shipment tracking number. For this order, the Merchant Center and the buyer's receipt page would display two shipments for the order, and each shipment would contain one item.

<?xml version="1.0" encoding="UTF-8"?>
<ship-items xmlns="http://checkout.google.com/schema/2"
  google-order-number="841171949013218">
    <item-shipping-information-list>
        <item-shipping-information>
            <item-id>
                <merchant-item-id>A1</merchant-item-id>
            </item-id>
            <tracking-data-list>
                <tracking-data>
                    <carrier>UPS</carrier>
                    <tracking-number>55555555</tracking-number>
                </tracking-data>
            </tracking-data-list>
        </item-shipping-information>
        <item-shipping-information>
            <item-id>
                <merchant-item-id>B2</merchant-item-id>
            </item-id>
            <tracking-data-list>
                <tracking-data>
                    <carrier>UPS</carrier>
                    <tracking-number>77777777</tracking-number>
                </tracking-data>
            </tracking-data-list>
        </item-shipping-information>
    </item-shipping-information-list>
    <send-email>true</send-email>
</ship-items>

Example 2: Two items ship in the same box

This example describes an order that contains two items, which are identified by the merchant-item-ids A1 and B2. In this example, both of the items in the order ship at the same time and in the same box. Each <item-shipping-information> XML block in the example specifies the same shipment tracking number. For this order, the Merchant Center and the buyer's receipt page would display one shipment for the order, and that shipment would contain both items in the order.

<?xml version="1.0" encoding="UTF-8"?>
<ship-items xmlns="http://checkout.google.com/schema/2"
  google-order-number="841171949013218">
    <item-shipping-information-list>
        <item-shipping-information>
            <item-id>
                <merchant-item-id>A1</merchant-item-id>
            </item-id>
            <tracking-data-list>
                <tracking-data>
                    <carrier>UPS</carrier>
                    <tracking-number>55555555</tracking-number>
                </tracking-data>
            </tracking-data-list>
        </item-shipping-information>
        <item-shipping-information>
            <item-id>
                <merchant-item-id>B2</merchant-item-id>
            </item-id>
            <tracking-data-list>
                <tracking-data>
                    <carrier>UPS</carrier>
                    <tracking-number>55555555</tracking-number>
                </tracking-data>
            </tracking-data-list>
        </item-shipping-information>
    </item-shipping-information-list>
    <send-email>true</send-email>
</ship-items>

Example 3: Four items ship at two different times in a total of three boxes

This example describes an order that contains four items, which are identified by the merchant-item-ids A1, B2, C3 and D4. In this example, two items (A1 and B2) ship in separate boxes. The merchant sends this shipping information to Google, at which point the buyer's Order History page will indicate that those items have shipped, while items C3 and D4 have not yet shipped. At a later time, the merchant ships the two remaining items in the same box.

In this example, the merchant would send two API requests. The first request would be formatted identically to the request in example 1, and the second request would be formatted identically to the request in example 2. After the first request, the Merchant Center and the buyer's receipt page would display two shipments for the order, each of which contained one item, and a group of two items that had not yet shipped. After the second request, the Merchant Center would display a total of three shipments for the order. Those shipments would include the two shipments from the first request and a third shipment containing two items.

Request 1:

<?xml version="1.0" encoding="UTF-8"?>
<ship-items xmlns="http://checkout.google.com/schema/2"
  google-order-number="841171949013218">
    <item-shipping-information-list>
        <item-shipping-information>
            <item-id>
                <merchant-item-id>A1</merchant-item-id>
            </item-id>
            <tracking-data-list>
                <tracking-data>
                    <carrier>UPS</carrier>
                    <tracking-number>55555555</tracking-number>
                </tracking-data>
            </tracking-data-list>
        </item-shipping-information>
        <item-shipping-information>
            <item-id>
                <merchant-item-id>B2</merchant-item-id>
            </item-id>
            <tracking-data-list>
                <tracking-data>
                    <carrier>UPS</carrier>
                    <tracking-number>77777777</tracking-number>
                </tracking-data>
            </tracking-data-list>
        </item-shipping-information>
    </item-shipping-information-list>
    <send-email>true</send-email>
</ship-items>

Request 2:

<?xml version="1.0" encoding="UTF-8"?>
<ship-items xmlns="http://checkout.google.com/schema/2"
  google-order-number="841171949013218">
    <item-shipping-information-list>
        <item-shipping-information>
            <item-id>
                <merchant-item-id>C3</merchant-item-id>
            </item-id>
            <tracking-data-list>
                <tracking-data>
                    <carrier>UPS</carrier>
                    <tracking-number>99999999</tracking-number>
                </tracking-data>
            </tracking-data-list>
        </item-shipping-information>
        <item-shipping-information>
            <item-id>
                <merchant-item-id>D4</merchant-item-id>
            </item-id>
            <tracking-data-list>
                <tracking-data>
                    <carrier>UPS</carrier>
                    <tracking-number>99999999</tracking-number>
                </tracking-data>
            </tracking-data-list>
        </item-shipping-information>
    </item-shipping-information-list>
    <send-email>true</send-email>
</ship-items>

Example 4: One item ships in two boxes

This example shows how you would handle an order where one item ships in two separate boxes. The XML below contains one <item-shipping-information> block, which specifies two different shipment tracking numbers. For this order, the Merchant Center and the buyer's receipt page would display multiple tracking numbers next to the shipped item.

<?xml version="1.0" encoding="UTF-8"?>
<ship-items xmlns="http://checkout.google.com/schema/2"
  google-order-number="841171949013218">
    <item-shipping-information-list>
        <item-shipping-information>
            <item-id>
                <merchant-item-id>A1</merchant-item-id>
            </item-id>
            <tracking-data-list>
                <tracking-data>
                    <carrier>UPS</carrier>
                    <tracking-number>55555555</tracking-number>
                </tracking-data>
                <tracking-data>
                    <carrier>UPS</carrier>
                    <tracking-number>77777777</tracking-number>
                </tracking-data>
            </tracking-data-list>
        </item-shipping-information>
    </item-shipping-information-list>
    <send-email>true</send-email>
</ship-items>

Appendix B - XML Tag Definitions

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	Name Format Description google-order-number String The google-order-number attribute contains an ID that uniquely identifies an order.
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	Name Format Description google-order-number String The google-order-number attribute contains an ID that uniquely identifies an order.
Subtags	tracking-data
Content Format	Container
Example	<add-tracking-data xmlns="http://checkout.google.com/schema/2" google-order-number="6014423719">

backorder-items
Definition	The <backorder-items> command lets you specify that one or more specific items in an order are out of stock.
Attributes	Name Format Description google-order-number String The google-order-number attribute contains an ID that uniquely identifies an order.
Subtags	item-ids, send-email?
Content Format	Container
Example	<backorder-items xmlns="http://checkout.google.com/schema/2" google-order-number="6014423719">

cancel-items
Definition	The <cancel-items> command lets you specify that one or more specific items in an order have been cancelled, meaning they will not be delivered to the customer. You might cancel items from an order for a variety of reasons. For example, an item might be discontinued or a customer might request to remove an item that was mistakenly included in an order.
Attributes	Name Format Description google-order-number String The google-order-number attribute contains an ID that uniquely identifies an order.
Subtags	reason, comment?, item-ids, send-email?
Content Format	Container
Example	<cancel-items 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>

item-id
Definition	The <item-id> tag contains one or more values that uniquely identify an item in an order.
Subtag of	item-ids, item-shipping-information
Subtags	merchant-item-id
Content Format	Container
Example	<item-id>

item-ids
Definition	The <item-ids> tag encapsulates a list of items that you are marking as backordered, cancelled or returned. The <item-ids> tag may also specify a list of items for which you want to reset shipping information.
Subtag of	backorder-items, cancel-items, reset-items-shipping-information, return-items
Subtags	item-id*
Content Format	Container
Example	<item-ids>

item-shipping-information
Definition	The <item-shipping-information> tag encapsulates information about a shipped item.
Subtag of	item-shipping-information-list
Subtags	item-id, tracking-data-list?
Content Format	Container
Example	<item-shipping-information>

item-shipping-information-list
Definition	The <item-shipping-information-list> tag contains a list of <item-shipping-information> elements, each of which identifies an item in an order and may also provide shipment tracking information for that item.
Subtag of	ship-items
Subtags	item-shipping-information*
Content Format	Container
Example	<item-shipping-information-list>

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-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>

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. Note: 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>

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 72 hours. 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>

reset-items-shipping-information
Definition	The <reset-items-shipping-information> command allows you to reset the shipping status for specific items in an order to "Not yet shipped". This command removes shipment tracking information for an item that has already been marked as shipped. It also removes any indication that the item has been backordered, cancelled or returned.
Attributes	Name Format Description google-order-number String The google-order-number attribute contains an ID that uniquely identifies an order.
Subtags	item-ids, send-email?
Content Format	Container
Example	<reset-items-shipping-information xmlns="http://checkout.google.com/schema/2" google-order-number="6014423719">

return-items
Definition	The <return-items> command lets you specify that your customer returned one or more specific items in an order.
Attributes	Name Format Description google-order-number String The google-order-number attribute contains an ID that uniquely identifies an order.
Subtags	item-ids, send-email?
Content Format	Container
Example	<return-items xmlns="http://checkout.google.com/schema/2" google-order-number="6014423719">

send-buyer-message
Definition	The <send-buyer-message> command instructs Google to send a message to a customer about a particular order.
Attributes	Name Format Description google-order-number String The google-order-number attribute contains an ID that uniquely identifies an order.
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>

ship-items
Definition	The <ship-items> command lets you specify that you have shipped one or more specific items in an order. You can also use the <ship-items> command to specify shipment tracking information for each shipped item.
Attributes	Name Format Description google-order-number String The google-order-number attribute contains an ID that uniquely identifies an order.
Subtags	item-shipping-information-list, send-email
Content Format	Container
Example	<ship-items xmlns="http://checkout.google.com/schema/2" google-order-number="6014423719">

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-data-list
Definition	The <tracking-data-list> tag contains a list of <tracking-data> elements, each of which contains shipment tracking information for an item.
Subtag of	item-shipping-information
Subtags	tracking-data*
Content Format	Container
Example	<tracking-data-list>

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>

Appendix C - Screenshots for Buyer's Order History Page

The following screenshots illustrate how your customer's Order History page will display the shipping statuses of individual items in an order. The list below identifies the different use cases shown in the screenshots.

Items shipped in separate shipments

The image below shows an order containing three items that have been sent in two separate shipments.

Order containing a backordered item

The image below shows an order containing three items, one of which is on backorder.

Order containing a cancelled item

The image below shows an order containing three items, one of which has been cancelled.

Order containing a returned item

The image below shows an order containing three items, one of which has been returned.

Appendix D - Screenshots for Merchant Center

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  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.

Ship column values  None of the items in the order have been shipped.  Some items in the order have been shipped.*  The order has been fully shipped.  The order has been canceled.

* The partial shipment icon only displays for merchants that are using line-item shipping commands.

The screenshot below shows the order details for an order containing three items. One of the three items is backordered, one has been returned and the third was cancelled. The screenshot shows that the order has been divided into two shipments.

Merchant Center Order Details