| Note: This is the latest documentation. The previous version of this page is identical—only the left nav differs. |
This document describes a Google Checkout feature that enables buyers to add delivery instructions or gift messages to orders. This feature also allows buyers to request gift receipts for orders.
This document contains the following sections:
The Messaging Options section explains the different messaging options that you can offer through Google Checkout.
The Messaging Guidelines subsection provides guidelines for adding gift messages, delivery instructions and gift receipt options to your Google Checkout integration.
The Sample API Requests section provides XML examples for several different gift messaging scenarios.
The XML Tag Definitions section defines the XML tags used for advanced buyer messaging.
The XML Schema Changes section identifies the changes made for this feature in the publicly available Google Checkout XML schema.
If you have feedback or questions about this feature, please visit the Google Checkout Beta APIs section of the Google Checkout Merchants Forum
The advanced buyer messaging feature offers buyers three types of messaging options:
Gift messaging allows the buyer to write a personal note to the order recipient. You have the option of including separate "To" and "From" fields in gift messages. You can also set the maximum length of the note as well as the maximum number of lines in the note and the maximum number of characters per line. Google Checkout offers four types of gift messages, and the only difference between those types is the text that the Google Checkout UI displays.
The following XML tags enable you to provide gift messaging:
Gift receipts demonstrate proof of a transaction for the purpose of returning or exchanging items in an order. However, gift receipts omit certain information that is typically printed on a standard receipt, including the price paid for each item in the order and the order total. Google Checkout lets you offer customers the option of including a gift receipt with a shipped order. If you do offer the option, you can also specify whether the customer needs to explicitly add the gift receipt to the order or that the gift receipt will be included with the order unless the customer explicitly removes it.
Instructions allow the buyer to provide special instructions or information that is intended for either the merchant or the shipping carrier. Google Checkout offers four types of instructional messages, and the only difference between those types is the text that the Google Checkout UI displays.
The following XML tags enable you to provide instructional messaging:
The following guidelines will help you to implement these features on your site:
Gift receipt guidelines
If your API request includes the <include-gift-receipt> tag and the tag's value is true, then Google Checkout will indicate that a gift receipt will be included with the order. The buyer will have the option of removing the gift receipt from the order before completing the purchase.
If your API request includes the <include-gift-receipt> tag with any value other than true or the tag is specified without a value, then Google Checkout will offer the buyer the option of adding a gift receipt to the order.
Messaging guidelines - Note that these guidelines apply to gift messages and instructional messages.
If your API request includes a messaging tag that contains a value, then Google Checkout will add the message to the order. The buyer will then have the option of editing or removing the provided text. This use case occurs when a buyer is able to enter a message on your site before clicking a Google Checkout button.
On the other hand, if your API request includes a messaging tag that does not contain a value, then Google Checkout will offer the buyer the option of adding the corresponding type of message to the order. This use case occurs when a buyer has not entered a message on your site before clicking a Google Checkout button.
For example, the following XML excerpt indicates that the buyer entered a gift message before proceeding to Google Checkout and that the buyer can also add delivery instructions to the order through the Checkout UI:
<gift-message>Dear Mom, Enjoy this gift. Love, Dave</gift-message>
<delivery-instructions/>
For gift messages only, you can explicitly specify "To" and "From" fields using the to and from attributes of the gift messaging tag.
By default, messages have a maximum length of 1000 characters divided into 20 lines of up to 50 characters each.
Note: If you provide values for all three of these attributes, then Google will multiply the max-line-length and max-lines attribute values to determine the maximum number of characters for the message, even if that number differs from the max-chars attribute value. For example, the following XML would enable the user to create a message of no more than 75 characters:
<special-instructions max-chars="100" max-line-length="25" max-lines="3"/>
The XML examples below explain several use cases for this feature:
This example demonstrates how to provide gift messaging when the buyer has not entered (or is unable to enter) any message text on your site. This XML instructs Google to display a text box for the buyer to enter a gift message. Since the <gift-message> tag does not include the to or from attributes, Google Checkout would not display separate fields for the buyer to specify that information. In addition, since the , this XML instructs Google to display a field for the buyer to enter a <gift-message> tag does not include the max-chars, max-line-length or max-lines attributes, Google would use allow the message to contain up to 1000 characters.
<shopping-cart>
...
<buyer-messages>
<gift-message/>
</buyer-messages>
</shopping-cart>
The screenshot below highlights the link to add a gift message in the Checkout UI.
This example demonstrates how to define a maximum message length for a gift message. The XML below instructs Google to display a text box allowing a message of up to 200 characters. The XML also specifies that Google should display "To" and "From" fields for the message.
<shopping-cart>
...
<buyer-messages>
<gift-message to="" from="" max-chars="200"/>
</buyer-messages>
</shopping-cart>
The screenshot below shows the box that will display when the user clicks the link to add a gift message for this example.
This example specifies a gift message already entered by the buyer. In addition, the XML specifies values for the to and from attributes, so Google will populate the "To" and "From" fields in the gift message display with those values. Like the previous example, this example specifies a maximum length of 200 characters. In addition, the example includes a <delivery-instructions> tag that specifies a maximum length of 100 characters for that field.
<shopping-cart>
...
<>buyer-messages>
<gift-message to="Road Runner" from="Wile E. Coyote" max-chars="200">
Enjoy these Acme corporation gifts.
Sincerely yours,
W.E.C.
</gift-message>
<delivery-instructions max-chars="100"/>
</buyer-messages>
</shopping-cart>
The screenshot below highlights the gift message as it would appear in the order details. The image also highlights the Additional options section of the page, which displays links to edit the gift message or to add delivery instructions to the order.
This example demonstrates how to offer gift receipt. Specifically, this example instructs Google to offer the option to the buyer of having a gift receipt included with the order. However, in this example, the gift receipt option will not be selected by default. (For the gift receipt option to be selected by default, the <include-gift-receipt> tag would need to have a value of true.)
<shopping-cart>
...
<buyer-messages>
<include-gift-receipt>offer option</include-gift-receipt>
</buyer-messages>
</shopping-cart>
The screenshot below highlights the Additional options section of the page, which displays a link to add a gift receipt to an order.
This example demonstrates how to provide gift messaging when the buyer has not entered (or is unable to enter) any message text on your site. This HTML instructs Google to display a text box for the buyer to enter a gift message. Since the <gift-message> tag does not include the to or from attributes, Google Checkout would not display separate fields for the buyer to specify that information. In addition, since this HTML instructs Google to display a field for the buyer to enter a <gift-message> tag does not include the max-chars, max-line-length or max-lines attributes, Google would use allow the message to contain up to 1000 characters.
<input type="hidden" name="shopping-cart.buyer-messages.gift-message-1" value="" />
The screenshot below highlights the link to add a gift message in the Checkout UI.
This example demonstrates how to define a maximum message length for a gift message. The HTML below instructs Google to display a text box allowing a message of up to 200 characters. The HTML also specifies that Google should display "To" and "From" fields for the message.
<input type="hidden" name="shopping-cart.buyer-messages.gift-message-1" value="" />
<input type="hidden" name="shopping-cart.buyer-messages.gift-message-1.to" value="" />
<input type="hidden" name="shopping-cart.buyer-messages.gift-message-1.from" value="" />
<input type="hidden" name="shopping-cart.buyer-messages.gift-message-1.max-chars" value="200" />
The screenshot below shows the box that will display when the user clicks the link to add a gift message for this example.
This example specifies a gift message already entered by the buyer. In addition, the HTML specifies values for the to and from attributes, so Google will populate the "To" and "From" fields in the gift message display with those values. Like the previous example, this example specifies a maximum length of 200 characters. In addition, the example includes a <delivery-instructions> tag that specifies a maximum length of 100 characters for that field.
To:
<input type="text" name="shopping-cart.buyer-messages.gift-message-1.to" value="Road Runner" /><br/>
From:
<input type="text" name="shopping-cart.buyer-messages.gift-message-1.from" value="Wile E. Coyote" /><br/>
<input type="hidden" name="shopping-cart.buyer-messages.gift-message-1.max-chars" value="200" />
Message:
<textarea name="shopping-cart.buyer-messages.gift-message-1" rows="9" cols="40">
Enjoy these Acme corporation gifts.
Sincerely yours,
W.E.C
</textarea><br/>
<input type="hidden" name="shopping-cart.buyer-messages.delivery-instructions-1" value="" />
<input type="hidden" name="shopping-cart.buyer-messages.delivery-instructions-1.max-chars" value="100" />
The screenshot below highlights the gift message as it would appear in the order details. The image also highlights the Additional options section of the page, which displays links to edit the gift message or to add delivery instructions to the order.
This example demonstrates how to offer gift receipt. Specifically, this example instructs Google to offer the option to the buyer of having a gift receipt included with the order. However, in this example, the gift receipt option will not be selected by default. (For the gift receipt option to be selected by default, the <include-gift-receipt> tag would need to have a value of true.)
<input type="hidden" name="shopping-cart.buyer-messages.include-gift-receipt-1" value="offer option" />
The screenshot below highlights the Additional options section of the page, which displays a link to add a gift receipt to an order.
This
example demonstrates the code from Example 1 above included in a Buy Now button form. Be sure to replace MERCHANT_ID with your merchant ID. Also, if you are a U.K. merchant, replace USD with GBP.
<form action="https://checkout.google.com/api/checkout/v2/checkoutForm/Merchant/MERCHANT_ID" id="BB_BuyButtonForm" method="post" name="BB_BuyButtonForm">
<input name="item_name_1" type="hidden" value="Google T-Shirt"/>
<input name="item_description_1" type="hidden" value="Short-sleeved Google T-Shirt"/>
<input name="item_quantity_1" type="hidden" value="1"/>
<input name="item_price_1" type="hidden" value="14.99"/>
<input name="item_currency_1" type="hidden" value="USD"/>
<input name="_charset_" type="hidden" value="utf-8"/>
<input type="hidden" name="shopping-cart.buyer-messages.gift-message-1" value="" />
<input alt="" src="https://checkout.google.com/buttons/buy.gif?merchant_id=MERCHANT_ID&w=117&h=48&style=white&variant=text&loc=en_US" type="image"/>
</form>
This
example demonstrates the code from Example 1 above included in a Google Checkout HTML API form. Be sure to replace MERCHANT_ID with your merchant ID.
Also, if you are a U.K. merchant, replace USD with GBP.
<form action="https://checkout.google.com/api/checkout/v2/checkoutForm/Merchant/MERCHANT_ID" method="post" accept-charset="utf-8">
<input name="item_name_1" type="hidden" value="Google T-Shirt"/>
<input name="item_description_1" type="hidden" value="Short-sleeved Google T-Shirt"/>
<input name="item_quantity_1" type="hidden" value="1"/>
<input name="item_price_1" type="hidden" value="14.99"/>
<input name="item_currency_1" type="hidden" value="USD"/>
<input name="ship_method_name_1" type="hidden" value="USPS"/>
<input name="ship_method_price_1" type="hidden" value="2.99"/>
<input name="ship_method_currency_1" type="hidden" value="USD"/>
<input name="_charset_" type="hidden" value="utf-8"/>
<input type="hidden" name="shopping-cart.buyer-messages.gift-message-1" value="" />
<input type="image" name="Google Checkout" alt="Fast checkout through Google" src="http://checkout.google.com/buttons/checkout.gif?merchant_id=MERCHANT_ID&w=180&h=46&style=white&variant=text&loc=en_US" height="46" width="180"/>
</form>
This
example demonstrates the code from Example 1 above included for the Google Checkout shopping cart. Be sure to replace MERCHANT_ID with your merchant ID.
Also, if you are a U.K. merchant, replace USD with GBP.
Add this code just before the </body> tag in your webpage:
<script type="text/javascript" id="googlecart-script" src="https://checkout.google.com/seller/gsc/v2/cart.js?mid=MERCHANT_ID" currency="USD"></script>
Add the code for the product on your webpage:
<div class="product">
<input value="Google T-Shirt" class="product-title" type="hidden">
<input value="14.99" class="product-price" type="hidden">
<div title="Add to cart" role="button" tabindex="0" class="googlecart-add-button"></div>
</div>
Add the code in this form tag to your webpage. The code in this form tag is added to take advantage of Google Checkout shopping cart's support for the Google Checkout HTML API:
<form id="googlecart-checkout-config">
<input type="hidden" name="shopping-cart.buyer-messages.gift-message-1" value="" />
</form>
The following tables define the XML tags used for the advanced buyer messaging feature.
Certain symbols may be displayed next to some subtags in the definitions below. These symbols, and their meanings, are:
| buyer-messages | |
| Definition |
The <buyer-messages> tag encapsulates information about delivery instructions, gift messaging and gift receipts. |
| Subtag of | shopping-cart |
| Subtags | buyer-note?, delivery-instructions?, gift-message?, include-gift-receipt?, in-honor-of-message?, in-memory-of-message?, in-tribute-of-message?, special-instructions?, special-requests? |
| Content Format | Container |
| Example | <buyer-messages> |
| buyer-note | |||||||||||||
| Definition |
In a Checkout API request, the <buyer-note> tag indicates that the buyer will have the option of including a note to the merchant for the order. In a new order notification, the <buyer-note> tag, if present, contains the note that the buyer provided for the order. |
||||||||||||
| Attributes |
|
||||||||||||
| Subtag of | buyer-messages | ||||||||||||
| Content Format | Complex | ||||||||||||
| delivery-instructions | |||||||||||||
| Definition |
In a Checkout API request, the <delivery-instructions> tag indicates that the buyer will have the option of providing special delivery instructions for the shipped order. Presumably, these instructions are intended to be conveyed to the shipping carrier that delivers the order. In a new order notification, the <delivery-instructions> tag, if present, contains the delivery instructions that the buyer provided for the order. |
||||||||||||
| Attributes |
|
||||||||||||
| Subtag of | buyer-messages | ||||||||||||
| Content Format | Complex | ||||||||||||
| gift-message | |||||||||||||||||||
| Definition |
In a Checkout API request, the <gift-message> tag indicates that the buyer will have the ability to provide a gift message that the merchant will send with the shipped order. In a new order notification, the <gift-message> tag encapsulates information about the message that the buyer wants to send to the gift recipient. |
||||||||||||||||||
| Attributes |
|
||||||||||||||||||
| Subtag of | buyer-messages |
||||||||||||||||||
| Content Format | Complex | ||||||||||||||||||
| Example | <gift-message> | ||||||||||||||||||
| in-honor-of-message | |||||||||||||||||||
| Definition |
In a Checkout API request, the <in-honor-of-message> tag indicates that the buyer will have the option of including an "In honor of" message with the shipped order. In a new order notification, the <in-honor-of-message> tag, if present, contains the message that the buyer provided for the order. |
||||||||||||||||||
| Attributes |
|
||||||||||||||||||
| Subtag of | buyer-messages | ||||||||||||||||||
| Content Format | Complex | ||||||||||||||||||
| in-memory-of-message | |||||||||||||||||||
| Definition |
In a Checkout API request, the <in-memory-of-message> tag indicates that the buyer will have the option of including an "In memory of" message with the shipped order. In a new order notification, the <in-memory-of-message> tag, if present, contains the message that the buyer provided for the order. |
||||||||||||||||||
| Attributes |
|
||||||||||||||||||
| Subtag of | buyer-messages | ||||||||||||||||||
| Content Format | Complex | ||||||||||||||||||
| in-tribute-of-message | |||||||||||||||||||
| Definition |
In a Checkout API request, the <in-tribute-of-message> tag indicates that the buyer will have the option of including an "In tribute of" message with the shipped order. In a new order notification, the <in-tribute-of-message> tag, if present, contains the message that the buyer provided for the order. |
||||||||||||||||||
| Attributes |
|
||||||||||||||||||
| Subtag of | buyer-messages | ||||||||||||||||||
| Content Format | Complex | ||||||||||||||||||
| include-gift-receipt | |
| Definition |
In a Checkout API request, the <include-gift-receipt> tag indicates that the buyer will have the option of including a gift receipt with the shipped order. If the tag's value is true, then Google Checkout will automatically select the option of including a gift receipt with the order, and the buyer will be able to decide not to include a gift receipt. Otherwise, if the tag is present, regardless of its value, Google Checkout will offer the option of including a gift receipt with the order. In a new order notification, the <include-gift-receipt> tag indicates whether the buyer elected to include a gift receipt with the shipped order. |
| Subtag of | buyer-messages |
| Content Format | Boolean |
| shopping-cart | |
| Definition |
The <shopping-cart> tag contains the list of items in a customer order and some other basic order information. |
| Subtag of | checkout-shopping-cart, new-order-notification, merchant-calculation-callback |
| Subtags | buyer-messages?, cart-expiration?, items, merchant-private-data? |
| API Commands | Checkout, Merchant Calculation Callback, New Order Notification |
| Content Format | Container |
| Example | <shopping-cart> |
| special-instructions | |||||||||||||
| Definition |
In a Checkout API request, the <special-instructions> tag indicates that the buyer will have the option of providing special instructions for the shipped order. Presumably, these instructions are intended to be conveyed to the merchant preparing the order for delivery. In a new order notification, the <special-instructions> tag, if present, contains the special instructions that the buyer provided for the order. |
||||||||||||
| Attributes |
|
||||||||||||
| Subtag of | buyer-messages | ||||||||||||
| Content Format | Complex | ||||||||||||
| special-requests | |||||||||||||
| Definition |
In a Checkout API request, the <special-requests> tag indicates that the buyer will have the option of specifying special requests for the order. Presumably, these requests are intended to be conveyed to the merchant preparing the order for delivery. In a new order notification, the <special-requests> tag, if present, contains the special requests that the buyer provided for the order. |
||||||||||||
| Attributes |
|
||||||||||||
| Subtag of | buyer-messages | ||||||||||||
| Content Format | Complex | ||||||||||||
This section identifies the changes to the publicly available Google Checkout XML schema for this feature.
The definition of the <shopping-cart> tag has been updated to enable support for advanced buyer messages. This tag now contains an optional <buyer-messages> subtag. This tag, in turn, contains information about messages for the order recipient, gift receipt information or special delivery instructions.
<xs:complexType name="ShoppingCart">
<xs:all>
<xs:element name="merchant-private-data" type="tns:anyMultiple" minOccurs="0" />
<xs:element name="cart-expiration" type="tns:CartExpiration" minOccurs="0" />
<xs:element name="items">
<xs:complexType>
<xs:sequence>
<xs:element name="item" type="tns:Item" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="buyer-messages" minOccurs="0">
<xs:complexType>
<xs:sequence>
<xs:choice minOccurs="0" maxOccurs="unbounded">
<xs:element name="gift-message" type="tns:BuyerMessageWithToFrom" />
<xs:element name="include-gift-receipt" type="xs:string" />
<xs:element name="delivery-instructions" type="tns:BuyerMessageWithoutToFrom" />
<xs:element name="special-instructions" type="tns:BuyerMessageWithoutToFrom" />
<xs:element name="special-requests" type="tns:BuyerMessageWithoutToFrom" />
<xs:element name="in-honor-of-message" type="tns:BuyerMessageWithToFrom" />
<xs:element name="in-tribute-of-message" type="tns:BuyerMessageWithToFrom" />
<xs:element name="in-memory-of-message" type="tns:BuyerMessageWithToFrom" />
<xs:element name="buyer-note" type="tns:BuyerMessageWithToFrom" />
</xs:choice>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:all>
</xs:complexType>
The following elements have been added to the Checkout schema for the advanced buyer messaging feature:
<xs:complexType name="BuyerMessageWithToFrom">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="from" type="tns:MessageFrom" use="optional"/>
<xs:attribute name="to" type="tns:MessageTo" use="optional"/>
<xs:attribute name="max-chars" type="tns:MaxChars" use="optional"/>
<xs:attribute name="max-line-length" type="tns:MaxLineLength" use="optional"/>
<xs:attribute name="max-lines" type="tns:MaxLines" use="optional"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="BuyerMessageWithoutToFrom">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="max-chars" type="tns:MaxChars" use="optional"/>
<xs:attribute name="max-line-length" type="tns:MaxLineLength" use="optional"/>
<xs:attribute name="max-lines" type="tns:MaxLines" use="optional"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:simpleType name="MessageFrom">
<xs:restriction base="xs:string">
<xs:minLength value="0" />
<xs:maxLength value="100" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="MessageTo">
<xs:restriction base="xs:string">
<xs:minLength value="0" />
<xs:maxLength value="100" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="MaxChars">
<xs:restriction base="xs:int">
<xs:minInclusive value="1" />
<xs:maxInclusive value="1000" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="MaxLineLength">
<xs:restriction base="xs:int">
<xs:minInclusive value="1" />
<xs:maxInclusive value="50" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="MaxLines">
<xs:restriction base="xs:int">
<xs:minInclusive value="1" />
<xs:maxInclusive value="20" />
</xs:restriction>
</xs:simpleType>
|
