| Note: This is the latest documentation. The previous version of this page is identical — only the left nav differs. |
The Order Processing API lets you integrate Google Checkout with your donation processing systems by allowing those systems to send information about a donation to Google Checkout. The following list identifies the functions that this API provides for managing donations made through Google Checkout. The Order Processing API Commands section defines and provides an XML example for each of these requests. The XML Tag Definitions section also defines the XML elements used in any of these commands.
The <refund-order> command enables you to refund a donation to a donor. For example, this command could be useful in cases where a donor inadvertently submitted the wrong donation amount or submitted a donation twice.
The <cancel-order> command enables you to mark a donation as canceled. Please note that you must completely refund a donor before canceling a donation.
The <archive-order> and <unarchive-order> commands enable you to manage the list of donations in your Merchant Center inbox. Archiving commands do not affect a donation's status or the information that is communicated to the donor about the donation.
The <add-merchant-order-number> command lets you associate a value that you use to uniquely identify a donation with its associated Google Checkout order.
The <send-buyer-message> command instructs Google to place a message in the donor's Google Checkout account and may also instruct Google to email the message to the donor.
Organizations that use the Order Processing API can also still use the Merchant Center to refund, cancel or archive donations.
Order Processing API requests must meet the following requirements:
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 <refund-order> command instructs Google Checkout to refund the buyer for a particular order. You may issue a <refund-order> command after an order has been charged and is in the CHARGED financial order state.
Note: Even after you have issued a <refund-order> command, you should not assume that Google has refunded your customer until you receive a refund-amount-notification confirming that the refund has been processed.
The following XML shows a sample <refund-order> command:
<?xml version="1.0" encoding="UTF-8"?> <refund-order xmlns="http://checkout.google.com/schema/2" google-order-number="6014423719"> <amount currency="USD">15.00</amount> <comment>Discount for inconvenience; ship replacement item</comment> <reason>Damaged Merchandise</reason> </refund-order>
Requests to refund an order could generate the following errors:
Invalid Argument Errors
Invalid State 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
Certain symbols may be displayed next to some subtags in the definitions below. These symbols, and their meanings, are:
The <archive-order> command instructs Google Checkout to remove an order from your Merchant Center Inbox. We recommend that you only archive orders after they have been delivered or canceled.
<?xml version="1.0" encoding="UTF-8"?> <archive-order xmlns="http://checkout.google.com/schema/2" google-order-number="841171949013218" />
The <unarchive-order> command instructs Google Checkout to return a previously archived order to your Merchant Center Inbox.
The following XML shows a sample <unarchive-order> request:
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>
| 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"> | ||||||
| amount | |||||||
| Definition | The <amount> tag identifies the amount of money to charge or refund for an order. The tag's value may either be the full amount of the order or a partial amount. If this tag is omitted and as a part of a charge-order command, Google will charge the customer for the full amount of the order. If this tag is omitted as a part of a refund-order command, Google will refund the full order amount to the customer. This tag has one required attribute, which identifies the currency of the amount to be charged or refunded. |
||||||
| Attributes |
|
||||||
| Subtag of | charge-order, refund-order | ||||||
| Content Format | Currency | ||||||
| Example | <amount currency="USD">129.43</amount> | ||||||
| archive-order | |||||||
| Definition | The <archive-order> tag indicates a request to archive a particular order. You would archive an order to remove it from your Merchant Center Inbox, indicating that the order has been delivered. |
||||||
| Attributes |
|
||||||
| Content Format | Empty | ||||||
| Example | <archive-order 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"> | ||||||
| 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> |
| error | |||||||
| Definition | The <error> tag contains information about an invalid API request. This information is intended to help you debug the problem causing the error. |
||||||
| Attributes |
|
||||||
| Subtags | error-message, warning-messages? | ||||||
| Content Format | Container | ||||||
| Example | <error xmlns="http://checkout.google.com/schema/2" serial-number="3c394432-8270-411b-9239-98c2c499f87f"> | ||||||
| error-message | |
| Definition | The <error-message> tag contains a message that describes why an API request caused an error. |
| Subtag of | error |
| Content Format | Container |
| Example | <error-message>Error: Illegal Argument</error-message> |
| 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 seven 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> |
| refund-order | |||||||
| Definition | The <refund-order> tag identifies an order that should be refunded. The <refund-order> tag may specify whether the buyer should be refunded the full amount of the order or a partial amount. |
||||||
| Attributes |
|
||||||
| Subtags | amount?, comment?, reason | ||||||
| Content Format | Container | ||||||
| Example | <refund-order xmlns="http://checkout.google.com/schema/2" google-order-number="6014423719"> | ||||||
| request-received | |||||||
| Definition | The <request-received> tag confirms that Google received a properly formed request to change an order's status and that the merchant requested a valid status change. Note: This tag does not indicate that your request was successfully completed. |
||||||
| Attributes |
|
||||||
| Content Format | Empty | ||||||
| Example | <request-received xmlns="http://checkout.google.com/schema/2" serial-number="dc66f8c7"/> | ||||||
| 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> |
| string | |
| Definition | The <string> tag contains a description of a warning generated by an API request. |
| Subtag of | warnings, warning-messages |
| Content Format | String |
| Example | <string>Sample warning message here</string> |
| unarchive-order | |||||||
| Definition | The <unarchive-order> tag indicates a request to unarchive a particular order. You would use this command to return an order to your Merchant Center Inbox after the order had previously been archived. |
||||||
| Attributes |
|
||||||
| Content Format | Complex | ||||||
| Example | <unarchive-order xmlns="http://checkout.google.com/schema/2" google-order-number="6014423719"/> | ||||||
|
