English | Site Directory

Google Checkout APIs

HTML API Commands for Order-Level Shipping

Overview
Fulfillment Order States
Order Processing API Commands
Order States in the Merchant Center
HTML Parameter Definitions

Overview


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 HTML 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 HTML API commands for item-level 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:

process-order
deliver-order
add-tracking-data
cancel-order*
add-merchant-order-number
send-buyer-message

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

Fulfillment Order States

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.

  • * If you are using item-level shipping commands, an order will have a fulfillment state of DELIVERED if all of the items in the order have been shipped, returned or cancelled. (The only exception to this rule occurs when all of the items in the order have been cancelled, in which case the order's status will be WILL_NOT_DELIVER.)

  • If you are using order-level shipping commands, you can change the fulfillment state for an order to DELIVERED by issuing a deliver-order order processing command.
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.

  • If you are using item-level shipping commands, an order will have a fulfillment status of WILL_NOT_DELIVER if all of the items in the order have been cancelled.

  • If you are using order-level shipping commands, you can change the fulfillment state for an order to WILL_NOT_DELIVER by issuing a cancel-order order processing command.

Order Processing API Commands

process-order

The process-order command instructs Google Checkout to update an order's fulfillment state from NEW to PROCESSING.

The following parameters show a sample process-order request:

POST https://checkout.google.com/api/checkout/v2/requestForm/Merchant/MERCHANT_ID
_type=process-order
  &google-order-number=6014423719

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.

deliver-order

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 parameters show a sample deliver-order request:

POST https://checkout.google.com/api/checkout/v2/requestForm/Merchant/MERCHANT_ID
_type=deliver-order
  &google-order-number=6014423719
  &tracking-data.carrier=UPS
  &tracking-data.tracking-number=Z5498W45987123684
  &send-email=true

add-tracking-data

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 parameters show a sample add-tracking-data request:

POST https://checkout.google.com/api/checkout/v2/requestForm/Merchant/MERCHANT_ID
_type=add-tracking-data
  &google-order-number=6014423719
  &tracking-data.carrier=UPS
  &tracking-data.tracking-number=Z5498W45987123684

Requests to add tracking data to an order could generate the following errors:

  • Invalid Argument Errors

    • The value of the carrier tag in your request is not valid. Valid values for the carrier tag are DHL, FedEx, UPS, USPS and Other.

cancel-order

The cancel-order command instructs Google Checkout to cancel a particular order. You may issue a cancel-order command for an order that is in either of the following financial order states:

CHARGEABLE
PAYMENT_DECLINED

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 parameters show a sample cancel-order request:

POST https://checkout.google.com/api/checkout/v2/requestForm/Merchant/MERCHANT_ID
_type=cancel-order
  &google-order-number=6014423719
  &reason=Buyer%20canceled%20the%20order.
  &comment=Buyer%20ordered%20another%20item.

Requests to cancel an order could generate the following errors:

  • Invalid State Errors

    • The order can not be canceled in its current financial order state.

add-merchant-order-number

The add-merchant-order-number command instructs Google Checkout to associate

The following XML shows a sample add-merchant-order-number request:

_type=add-merchant-order-number
  &google-order-number=841171949013218
  &merchant-order-number=P6502-53-7861SBJD

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.

_type=send-buyer-message
  &google-order-number=841171949013218
  &message=Due%20to%20high%20volume%2C%20your%20order%20will%20ship%20soon.
  &send-email=true

Order States in the 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 is under review.

 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

 The order is under review.

 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.

HTML Parameter Definitions

_type

The _type parameter identifies the type of API request that is being submitted. Google will send this parameter in any API transaction, including synchronous responses and notifications. You must also send this parameter for all API requests other than Checkout API requests, including all Order Processing API commands.

Valid values for this parameter are:

add-merchant-order-number
add-tracking-data
archive-order
authorization-amount-notification
authorize-order
backorder-items
cancel-items
cancel-order
charge-amount-notification
chargeback-amount-notification
charge-order
checkout-redirect
deliver-order
demo-failure
diagnosis		error
new-order-notification
notification-acknowledgment
order-state-change-notification
process-order
refund-amount-notification
refund-order
request-received
reset-items-shipping-information
return-items
risk-information-notification
send-buyer-message
ship-items
unarchive-order

Note: The value of the type parameter corresponds to the root tag of an XML API request.

Content format for parameter value


String

Sample use(s)


_type=new-order-notification
_type=ship-items

carrier

The carrier parameter contains the name of the company responsible for shipping the item. Valid values for this parameter 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.

Associated recurring elements


In a ship-items request, the item-shipping-information and tracking-data elements must both be numbered.

API commands


Content format for parameter value


String

Sample use(s)


In a ship-items request:
item-shipping-information-list.item-shipping-information-#.tracking-data-list.tracking-data-#.carrier=UPS

In a deliver-order or add-tracking-data request:
tracking-data.carrier=UPS

comment

The comment parameter contains a comment related to a refunded or canceled order.

Note: The maximum accepted length for the parameter value is 140 characters.

API commands


Content format for parameter value


String

Sample use(s)


comment=Refund+processed+by+Bob+Smith

google-order-number

The google-order-number parameter contains an ID, which Google generates, that uniquely identifies an order.

API commands


Content format for parameter value


String

Sample use(s)


google-order-number=6014423719

merchant-order-number

The merchant-order-number parameter contains the order number that you have assigned to an order. This number appears in the reconciliation report available in the Merchant Center.

API commands


Content format for parameter value


String (Limit 255 characters)

Sample use(s)


merchant-order-number=1234abcd

message

The message parameter contains a message associated with a coupon 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 parameter value is 255 characters.

When associated with a demo-failure response, the message parameter contains a short note that Google Checkout will return in an error message. In this context, the message parameter has a maximum length of 25 characters.

Associated recurring elements


In a new order notification, the message parameter must contain the coupon-adjustment element, and that element must be numbered.

API commands


Content format for parameter value


String

Sample use(s)


In a send-buyer-message request:
message=Your+order+has+shipped.

In a demo-failure command:
message=test+error+handling

reason

As a subtag of cancel-order or refund-order, the reason parameter contains the reason that you are canceling or refunding an order.

As a subtag of order-state-change-notification, the reason parameter, 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 parameter value is 140 characters.

API commands


Content format for parameter value


String

Sample use(s)


reason=Failed%20risk%20check

send-email

The send-email parameter 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.

API commands


Content format for parameter value


Boolean

Sample use(s)


send-email=true

tracking-number

The tracking-number parameter contains the shipper's tracking number that is associated with an order.

Associated recurring elements


In a ship-items request, the item-shipping-information and tracking-data elements must both be numbered.

API commands


Content format for parameter value


String

Sample use(s)


In a ship-items request:
item-shipping-information-list.item-shipping-information-#.tracking-data-list.tracking-data-#.tracking-number=Z5498W45987123684

In a deliver-order or add-tracking-data request:
tracking-data.tracking-number=Z5498W45987123684