| 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 contribution processing systems by allowing those systems to send information about a contribution to Google Checkout. The following list identifies the functions that this API provides for managing contributions 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 contributor for a contribution. For example, this command could be useful in cases where a contributor inadvertently submitted the wrong contribution amount or submitted a contribution twice.
The <cancel-order> command enables you to mark a contribution as canceled. Please note that you must completely refund a contributor before canceling a contribution.
The <archive-order> and <unarchive-order> commands enable you to manage the list of contributions in your Merchant Center inbox. Archiving commands do not affect a contribution's status or the information that is communicated to the contributor about the contribution.
The <add-merchant-order-number> command lets you associate a value that you use to uniquely identify a contribution with its associated Google Checkout order.
The <send-buyer-message> command instructs Google to place a message in the contributor's Google Checkout account and may also instruct Google to email the message to the contributor.
Organizations that use the Order Processing API can also still use the Merchant Center to refund, cancel or archive contributions.
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 contributor for a particular contribution. 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 the contributor 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 a contribution could generate the following errors:
Invalid Argument Errors
Invalid State Errors
The <cancel-order> command instructs Google Checkout to cancel a particular contribution. You must fully refund a contribution before you can cancel that contribution. You may issue a <cancel-order> command for a contribution that is in either of the following financial order states:
The <cancel-order> command effectively marks an entire contribution as canceled. A contribution 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 a contribution have been canceled. When you cancel specific items in a contribution, that contribution will not transition to the CANCELLED state unless you actually cancel all of the items in the contribution.
Note: Even after you have issued a <cancel-order> command, you should not assume that Google has canceled the contribution 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>Contributor canceled the contribution.</reason> <comment>Contributor inadvertently submitted the contribution twice.</comment> </cancel-order>
Requests to cancel a contribution could generate the following errors:
Invalid State Errors
The <archive-order> command instructs Google Checkout to remove a contribution from your Merchant Center Inbox.
<?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 contribution to your Merchant Center Inbox.
The following XML shows a sample <unarchive-order> request:
<?xml version="1.0" encoding="UTF-8"?>
<unarchive-order xmlns="http://checkout.google.com/schema/2" google-order-number="841171949013218" />
The <add-merchant-order-number> command instructs Google Checkout to associate an order number or other unique value that you have assigned to identify a contribution.
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 contributor in addition to displaying the message in the contributor'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>Thank you for your generous contribution!</message> <send-email>true</send-email> </send-buyer-message>
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"> | ||||||
| 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 | Decimal | ||||||
| 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>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> |
| 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"/> | ||||||
|
