English | Site Directory

Google Checkout APIs

HTML API Parameter Reference

Understanding API Parameter Names
HTML Parameter Definitions

This document contains definitions for all of the HTML parameters discussed in the Google Checkout HTML API Developer's Guide. In addition to the parameter definitions, the Understanding HTML API Parameter Names section, which is reproduced from the main HTML API document, discusses some of the key characteristics of HTML API requests and field names.

Understanding API Parameter Names

The names for the input parameters used in the HTML API correlate very closely to the names of the elements in the Google Checkout XML schema. The list below specifies key characteristics of HTML API requests and field names:

  • Each API request contains the _type field, which specifies the type of API request being submitted. For example, in a Checkout (Shopping Cart) API request, the value of the type field is checkout-shopping-cart. In the XML API, the <checkout-shopping-cart> tag is the root tag in a Checkout API request.

    Similarly, for any other API request, the value of the _type field equals the name of the root XML tag used to execute the same request in the XML API. For example, the root XML tag for a risk information notification is <risk-information-notification>. As such, the value of the _type parameter would be risk-information-notification.

  • The HTML parameter name for an element in the XML schema reflects the path to that element in a tree representation of the XML schema. The name is constructed using the following conventions:

    • Combine the names of the elements in the path to create the parameter name for an element. The parameter name begins with the first element below the root tag, which is identified separately using the _type parameter, and element names are separated using periods (.). For example, the continue-shopping-url field appears in a Checkout API request. In an XML API request, this value appears in the following context:

      <checkout-shopping-cart>
        <checkout-flow-support>
          <merchant-checkout-flow-support>
            ...
            <request-buyer-phone-number>true</request-buyer-phone-number>
            ...
          </merchant-checkout-flow-support>
        </checkout-flow-support>
      </checkout-shopping-cart>
      

      In an HTML API request, the field uses the following format:

      checkout-flow-support.merchant-checkout-flow-support.request-buyer-phone-number=true
      
    • Some XML elements can recur in a normal request. For example, an order may contain more than one item, and you might charge tax in more than one state.

      To represent a recurring XML element in an HTML parameter name, you must associate an index number with that element in the HTML parameter name. For example, the following example shows HTML parameters for two items. The XML schema allows the <item> tag to recur in an API request. As such, in an HTML parameter name, you must append -# to the element name item, replacing the pound (#) symbol with the item's index number in the list. Please use the number 1 to identify the first item in a list. The following fields demonstrate how you would provide the name and description for two different items in an HTML API request:

      _type=checkout-shopping-cart
      &shopping-cart.items.item-1.item-name=Peanut%20Butter
      &shopping-cart.items.item-2.item-name=Strawberry%20Jelly
      &shopping-cart.items.item-1.item-description=Made%20from%20peanuts
      &shopping-cart.items.item-2.item-description=Made%20from%20strawberries
      

HTML Parameter Definitions

The tables below define the parameters that you can use in HTML API requests for Google Checkout. Parameters are listed in alphabetical order and link to more information about the API commands for which they are used. Please note the following information about the parameter definitions:

  • As discussed above, HTML parameter names represent a path to an element in the Google Checkout XML schema. In the definitions below, parameters are alphabetized by the last element in that path. For example, the adjustment-total parameter in the list actually has the parameter name order-adjustment.adjustment-total in an API request.

  • Some parameter definitions may apply to more than one API function. For example, tax rules may specify the state where a tax rule applies while shipping methods may specify a state where the shipping method is (or is not) available. In the XML schema, both functions use the <state> tag. In the HTML API, both functions also specify a state. Technically, the state parameter for tax rules has a different name than the state parameter for shipping methods. However, in this document, the state parameter is defined once, and the parameter definition identifies the different ways to identify a state in HTML API requests.

  • As noted above, some XML elements can recur in a normal API request and the HTML API relies on an index number to properly identify these elements. For example, if there are two items in an order, the names of those items can be identified using the shopping-cart.items.item-1.item-name and shopping-cart.items.item-2.item-name parameters. In this document, the definition for a parameter will explicitly identify any indexed elements in that parameter's name. For example, the item-name parameter definition states, "The item element, which must be numbered, associates this parameter with a specific item in an order."

  • The "Sample use(s)" section of each parameter definition shows how the given parameter is used in the context of an API request. In this document, examples for parameters that appear in Checkout API requests are shown using the following convention:

    <input type="hidden" name="PARAMETER_NAME" value="SAMPLE_VALUE"/>

    Sample uses of parameters that are used in any other type of API transaction are shown using the convention below. In fact, you may also submit server-to-server Checkout API requests, in which case you would not use the hidden input parameter syntax noted above.

    PARAMETER_NAME=PARAMETER_VALUE
  • In the "Sample use(s)" section of the parameter definitions, a portion of a parameter name may appear in brackets as shown in the following example:

    checkout-flow-support.merchant-checkout-flow-support.shipping-methods.
      flat-rate-shipping-#.[shipping-restrictions | address-filters].allow-us-po-box

    This syntax indicates that, when used in this context, the allow-us-po-box parameter name must contain the shipping-restrictions element or the address-filters element.

You can use the table below to jump to parameters starting with a particular letter.

ABCDEFGHIKLMNOPQRSTUVWZ

_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

additional-fixed-charge

The additional-fixed-charge parameter allows you to specify a fixed charge that will be added to the total cost of an order if the buyer selects the associated shipping option. If you also adjust the calculated shipping cost using the additional-variable-charge-percent parameter, the fixed charge will be added to the adjusted shipping rate.

Associated recurring elements


The parameter name contains the carrier-calculated-shipping element, which must be numbered with a value of 1. In addition, the parameter name also contains the carrier-calculated-shipping-option element, which associates the parameter value with a particular shipping option.

Content format for parameter value


Double

Sample use(s)


<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-#.additional-fixed-charge" value="5.00"/>

additional-variable-charge-percent

The additional-variable-charge-percent parameter specifies a percentage amount by which a carrier-calculated shipping rate will be adjusted. The parameter's value may be positive or negative. For example, if the parameter's value is 15, then the carrier's shipping rate will effectively be multiplied by 1.15 to determine the shipping cost presented to the buyer. So, if the carrier shipping rate were $10.00, the adjusted shipping rate would be $11.50 – i.e. $10.00 + ($10.00 X 15%). If the additional-variable-charge-percent parameter value is negative, the calculated shipping rate will be discounted by the specified percentage.

Associated recurring elements


The parameter name contains the carrier-calculated-shipping element, which must be numbered with a value of 1. In addition, the parameter name also contains the carrier-calculated-shipping-option element, which associates the parameter value with a particular shipping option.

Content format for parameter value


Double

Sample use(s)


<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-#.additional-variable-charge-percent" value="10"/>

address1

The address1 parameter identifies the first line of the address to which an order is being shipped.

API commands


Content format for parameter value


String

Sample use(s)


risk-information.billing-address.address1=10%20Main%20Street

address2

The address2 parameter identifies the second line of the address to which an order is being shipped.

API commands


Content format for parameter value


String

Sample use(s)


risk-information.billing-address.address2=Building%20A

adjustment-total

The adjustment-total parameter contains the total adjustment to an order total based on tax, shipping, gift certificates and coupon codes.

API commands


Content format for parameter value


Decimal

Sample use(s)


order-adjustment.adjustment-total=11.05

allow-us-po-box

The allow-us-po-box parameter indicates whether a particular shipping method can be used to ship an order to a U.S. post office (P.O.) box. To prevent a flat-rate shipping option from being offered to customers who are shipping orders to P.O. boxes in the United States, include this parameter with a value of false in the shipping-restrictions for the shipping option. The default value for this parameter is true.

Associated recurring elements


The flat-rate-shipping element needs to be numbered to associate the shipping restriction (or address filter) with the appropriate shipping method.

API commands


Content format for parameter value


Boolean

Sample use(s)


<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-#.shipping-restrictions.allow-us-po-box" value="false"/>

amount

The amount parameter identifies the amount of money to charge or refund for an order. The parameter's value may either be the full amount of the order or a partial amount. If this parameter 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 parameter is omitted as a part of a refund-order command, Google will refund the full order amount to the customer.

API commands


Content format for parameter value


Decimal

Sample use(s)


<input type="hidden" name="amount" value="19.99"/>

analytics-data

The analytics-data parameter enables merchants that submit server-to-server Checkout API requests to use Google Analytics to track Checkout orders. The Using Google Analytics to Track Google Checkout Orders document explains how to retrieve the appropriate value for this parameter.

Content format for parameter value


String

Sample use(s)


<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.analytics-data" value="SW5zZXJ0IDxhbmFseXRpY3MtZGF0YT4gdmFsdWUgaGVyZS4"/>

applied-amount

The applied-amount parameter contains the amount of a coupon or gift certificate that was applied to an order total.

Associated recurring elements


The applied-amount parameter must contain either the coupon-adjustment or the gift-certificate-adjustment element, and that element must be numbered.

API commands


Content format for parameter value


Decimal

Sample use(s)


order-adjustment.merchant-codes.[coupon-adjustment-# | gift-certificate-adjustment-#].applied-amount=10.00

authorization-amount

The authorization-amount parameter contains the amount that was reauthorized to be charged to the customer's credit card. Google guarantees that these funds will be available for seven days – 168 hours – from the time that the reauthorization takes place.

API commands


Content format for parameter value


Decimal

Sample use(s)


authorization-amount=50.00

authorization-expiration-date

The authorization-expiration-date parameter identifies the time that a credit card authorization for an order expires.

API commands


Content format for parameter value


Date/Time

Sample use(s)


authorization-expiration-date=2007-03-26T15%3A06%3A26.000Z

avs-response

The avs-response parameter contains an Address Verification System (AVS) response.

Possible values for this parameter are:

Y - Full AVS match (address and postal code)
P - Partial AVS match (postal code only)
A - Partial AVS match (address only)
N - no AVS match
U - AVS not supported by issuer

API commands


Content format for parameter value


String

Sample use(s)


risk-information.avs-response=Y

buyer-account-age

The buyer-account-age parameter identifies the age, in days, of the buyer's Google Checkout account.

API commands


Content format for parameter value


Integer

Sample use(s)


risk-information.buyer-account-age=6

buyer-id

The buyer-id parameter contains an ID that uniquely identifies the user to Google.

API commands


Content format for parameter value


Long

Sample use(s)


buyer-id=294873009217523

calculated-amount

The calculated-amount parameter contains the calculated amount of a coupon or gift certificate.

Associated recurring elements


The calculated-amount parameter will contain either the coupon-adjustment or the gift-certificate-adjustment element, and that element will be numbered.

API commands


Content format for parameter value


Decimal

Sample use(s)


order-adjustment.merchant-codes.[coupon-adjustment-# | gift-certificate-adjustment-#].calculated-amount=10.00

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


carrier-pickup

The carrier-pickup parameter specifies how the package will be transferred from the merchant to the shipper. Valid values for this parameter are REGULAR_PICKUP, SPECIAL_PICKUP and DROP_OFF. The default value for this parameter is DROP_OFF.

Associated recurring elements


The parameter name contains the carrier-calculated-shipping element, which must be numbered with a value of 1. In addition, the parameter name also contains the carrier-calculated-shipping-option element, which associates the parameter value with a particular shipping option.

Content format for parameter value


String

Sample use(s)


<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.carrier-calculated-shipping-options.carrier-calculated-shipping-option-#.carrier-pickup" value="REGULAR_PICKUP"/>

city

The city parameter identifies the city associated with an order's billing or shipping address.

API commands


Content format for parameter value


String

Sample use(s)


In a carrier-calculated-shipping option in a Checkout API request:
<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.shipping-packages.shipping-package-#.ship-from.city" value="Mountain View"/>

In a new order notification:
[buyer-billing-address | buyer-shipping-address].city=Mountain+View

In a risk information notification:
billing-address.city=Mountain+View


code

The code parameter contains the code for a coupon or gift certificate that a customer would like to apply to an order or that was applied to an order.

Associated recurring elements


In a new order notification, the code parameter will contain either the coupon-adjustment or the gift-certificate-adjustment element, and that element will be numbered.

API commands


Content format for parameter value


String

Sample use(s)


In a new order notification:
order-adjustment.merchant-codes.[coupon-adjustment-# | gift-certificate-adjustment-#].code=12345

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

company-name

The company-name parameter identifies the company to which an order is being shipped. Please note that Google does not currently request this information from customers but may do so in the future. However, until then, this parameter will contain an empty value.

API commands


Content format for parameter value


String

Sample use(s)


In a new order notification:
[buyer-billing-address | buyer-shipping-address].company-name=Vandalay+Industries

In a risk information notification:
billing-address.company-name=Vandalay+Industries


contact-name

The contact-name parameter identifies the person to whom an order is being shipped.

API commands


Content format for parameter value


String

Sample use(s)


In a new order notification:
[buyer-billing-address | buyer-shipping-address].contact-name=Art+Vandalay

In a risk information notification:
billing-address.contact-name=Art+Vandalay


continue_url

The continue-shopping-url parameter contains a URL that allows the buyer to continue shopping after confirming an order.

API commands


Content format for parameter value


String (URL)

Sample use(s)


<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.continue-shopping-url" value="http://www.example.com"/>

country-area
The country-area parameter identifies a region of the United States. Valid values for this parameter are:
CONTINENTAL_48 - All U.S. states except Alaska and Hawaii
FULL_50_STATES - All U.S. states
ALL - All U.S. postal service addresses, including military addresses, U.S. insular areas, etc.

Associated recurring elements


When the country-area parameter is associated with a shipping method, the us-country-area and flat-rate-shipping elements need to be numbered. When the country-area parameter is associated with a default tax table, the default-tax-rule and us-country-area elements must both be numbered. When the country-area parameter is associated with an alternate tax table, the alternate-tax-table, alternate-tax-rule and us-country-area elements must all be numbered.

API commands


Content format for parameter value


String

Sample use(s)


<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-#.shipping-restrictions.[allowed-areas | excluded-areas].us-country-area-#.country-area" value="CONTINENTAL_48"/>

<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.default-tax-rule-#.tax-areas.us-country-area-#.country-area" value="CONTINENTAL_48"/>

<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.alternate-tax-tables.alternate-tax-table-#.alternate-tax-rule-#.tax-areas.us-country-area-#.country-area" value="CONTINENTAL_48"/>


country-code

As a subtag of postal-area, the country-code parameter specifies a country associated with a tax areashipping restriction or address filter. In all other contexts, the country-code parameter identifies the country code associated with an order's billing address or shipping address. The value of this parameter must be a two-letter ISO 3166 country code.

Associated recurring elements


When the country-code parameter appears in a carrier-calculated shipping option in a Checkout API request, the shipping-package element must be numbered. In addition, the carrier-calculated-shipping element must be numbered with a value of 1.

API commands


Content format for parameter value


String

Sample use(s)


In a carrier-calculated-shipping option in a Checkout API request:
<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.shipping-packages.shipping-package-#.ship-from.country-code" value="US"/>

In a new order notification:
[buyer-billing-address | buyer-shipping-address].country-code=US

In a risk information notification:
billing-address.country-code=US


currency
The currency parameter identifies the unit of currency associated with a price, shipping cost or other monetary value. Every monetary value in a Google Checkout API request must specify the currency associated with that value. The value of the currency parameter must be a three-letter ISO 4217 currency code.

Associated recurring elements


The currency parameter includes recurring elements any time the monetary value associated with the currency also contains a recurring element. For example, in a Checkout API request, the unit-price parameter identifies the price of an item and contains the recurring item element. As such, the currency associated with the unit-price parameter value will also contain the repeating price parameter.

API commands


Content format for parameter value


String

Sample use(s)


In a Checkout API request:
item type="hidden" name="shopping-cart.items.item-1.unit-price" value="12.99"
item type="hidden" name="shopping-cart.items.item-1.unit-price.currency" value="USD"

In a new order notification:
order-adjustment.total-tax=1.38&order-adjustment.total-tax.currency=USD

In a refund order request:
amount=12.99&amount.currency=USD


cvn-response

The cvn-response parameter contains a credit verification value for the order.

Possible values for this parameter are:

M - CVN match
N - No CVN match
U - CVN not available
E - CVN error

API commands


Content format for parameter value


String

Sample use(s)


cvn-response=Mrisk-information.cvn-response=M

delivery-address-category

The delivery-address-category parameter indicates whether the shipping method should be applied to a residential or a commercial address. Valid values for this parameter are RESIDENTIAL and COMMERCIAL.

Associated recurring elements


The parameter name contains the carrier-calculated-shipping element, which must be numbered with a value of 1. In addition, the parameter name also contains the shipping-package element, which associates the parameter value with a particular package in an order.

Content format for parameter value


String

Sample use(s)


<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.shipping-packages.shipping-package-#.delivery-address-category" value="RESIDENTIAL"/>

description

As a subtag of digital-content, the description parameter contains instructions for downloading a digital content item. Please use the item-description parameter to provide the description of the item being purchased. Note: This field has a maximum length of 1024 characters and may contain HTML tags. (HTML tags must be XML-escaped as described in the Google Checkout Developer's Guide.)

As a subtag of promotion, the description parameter contains information about a promotion that Google applied to an order.

Associated recurring elements


The item element, which must be numbered, associates this parameter with a specific item in an order.

Content format for parameter value


String

Sample use(s)


<input type="hidden" name="shopping-cart.items.item-#.digital-content.description" value="Please go to &lt;a href="http://supersoft.example.com"&gt;our website&lt;/a&gt;, and enter your access key so that you can download our software."/>

display-disposition

The display-disposition parameter specifies when the buyer will be able to access purchased digital content. The only valid values for this parameter are OPTIMISTIC and PESSIMISTIC.

  • If the value of the display-disposition parameter is OPTIMISTIC, then Google will display instructions for accessing the digital content as soon as the buyer confirms the order. We recommend that you only use optimistic delivery if you can easily revoke access to the digital content if Google cannot authorize the customer's credit card.

  • If the value of the display-disposition parameter is PESSIMISTIC, the buyer cannot access purchased digital content until his credit card has been authorized to be charged for the amount of the order.

The default value for this parameter is PESSIMISTIC.

Associated recurring elements


The item element, which must be numbered, associates this parameter with a specific item in an order.

Content format for parameter value


String

Sample use(s)


<input type="hidden" name="shopping-cart.items.item-#.digital-content.display-disposition" value="OPTIMISTIC"/>
<input type="hidden" name="shopping-cart.items.item-#.digital-content.display-disposition" value="PESSIMISTIC"/>

edit_url

The edit-cart-url parameter contains a URL that allows the buyer to make changes to the shopping cart before confirming an order.

API commands


Content format for parameter value


String (URL)

Sample use(s)


<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.edit-cart-url" value="http://www.example.com/edit?id=123"/>

eligible-for-protection

The eligible-for-protection parameter indicates whether an order is eligible for Google Checkout's payment guarantee policy.

API commands


Content format for parameter value


Boolean

Sample use(s)


risk-information.eligible-for-protection=true

email

The email parameter identifies an email address that could be used to contact the person to be billed for an order or the order recipient.

API commands


Content format for parameter value


String

Sample use(s)


In a new order notification:
[buyer-billing-address | buyer-shipping-address].email=johnm%40example.com

In a risk information notification:
billing-address.email=johnm%40example.com


email-allowed

The email-allowed parameter indicates whether the customer is willing to receive marketing emails from the merchant.

API commands


Content format for parameter value


Boolean

Sample use(s)


buyer-marketing-preferences.email-allowed=true

email-delivery

The email-delivery parameter indicates that the merchant will send email to the buyer explaining how to access the digital content. Email delivery allows the merchant to charge the buyer for an order before allowing the buyer to access the digital content.

Associated recurring elements


The item element, which must be numbered, associates this parameter with a specific item in an order.

Content format for parameter value


Boolean

Sample use(s)


<input type="hidden" name="shopping-cart.items.item-#.digital-content.email-delivery" value="false"/>
<input type="hidden" name="shopping-cart.items.item-#.digital-content.email-delivery" value="true"/>

error-message

The error-message parameter contains a message that describes why an API request caused an error.

API commands


Content format for parameter value


Container

Sample use(s)


error-message=Bad+username+or+password+for+API+access.

fax

The fax parameter identifies a fax number that can be used to contact the person to be billed for an order or the order recipient. Please note that Google does not currently request this information from customers but may do so in the future. However, until then, this parameter will contain an empty value.

API commands


Content format for parameter value


String

Sample use(s)


In a new order notification:
[buyer-billing-address | buyer-shipping-address].fax=5552221212

In a risk information notification:
billing-address.fax=5552221111


financial-order-state

The financial-order-state parameter identifies the financial status of an order. Valid values for this parameter are:

REVIEWING - Google Checkout is reviewing the order.
CHARGEABLE - The order is ready to be charged.
CHARGING - The order is being charged; you may not refund or cancel an order until is the charge is completed.
CHARGED - The order has been successfully charged; if the order was only partially charged, the buyer's account page will reflect the partial charge.
PAYMENT_DECLINED - The charge attempt failed.
CANCELLED - Either the buyer or the seller canceled the order. An order's financial state cannot be changed after the order is canceled. Learn more about when an order may be canceled.
CANCELLED_BY_GOOGLE - Google canceled the order. Google may cancel orders due to a failed charge without a replacement credit card being provided within a set period of time or due to a failed risk check. If Google cancels an order, you will be notified of the reason the order was canceled in the reason parameter of an order-state-change-notification.

Please see the Financial Commands in the Order Processing API document for more information about these states.

API commands


Content format for parameter value


String

Sample use(s)


financial-order-state=REVIEWING

first-name

The first-name parameter contains the first name of the buyer or recipient of an order. Please see the Matching Names in Notifications to Names in Your Database section for details about Google Checkout's name-splitting algorithm.

Content format for parameter value


String

Sample use(s)


In a new order notification:
[buyer-billing-address | buyer-shipping-address].structured-name.first-name=Art

In a risk information notification:
billing-address.structured-name.first-name=Art


fulfillment-order-state

The fulfillment-order-state parameter indicates the status of an order in the order handling process. Valid values for this parameter are:

NEW - The order has been received but not prepared for shipping.
PROCESSING - The order is being prepared for shipping.
DELIVERED - The seller has shipped the order.
WILL_NOT_DELIVER - The seller will not ship the order; this status is used for canceled orders.

API commands


Content format for parameter value


String

Sample use(s)


fulfillment-order-state=NEW

good-until-date

The good-until-date parameter identifies the date that the order in a Checkout API request expires. The date must be specified using the ISO 8601 Date and Time Format. The time must include the time-zone designator for UTC (Coordinated Universal Time), which is "Z", or you may specify a local time along with a time-zone offset in hours and minutes. A time zone offset of "+hh:mm" indicates that the date/time uses a local time zone which is "hh" hours and "mm" minutes ahead of UTC. A time zone offset of "-hh:mm" indicates that the date/time uses a local time zone which is "hh" hours and "mm" minutes behind UTC. The examples show dates formatted using the UTC time-zone designator and using time-zone offsets.

Note: If you specify a value for this element, Google Checkout will reject the shopping cart if the user submits the cart after the specified date.

API commands


Content format for parameter value


Date/Time

Sample use(s)


<input type="hidden" name="shopping-cart.cart-expiration.good-until-date" value="2007-12-31T11:59:59-05:00"/>

Sample use(s)


In a Checkout API request:
<input type="hidden" name="shopping-cart.cart-expiration.good-until-date" value="2007-12-31T11:59:59-05:00"/>

In a new order notification:
shopping-cart.cart-expiration.good-until-date=2007-12-31T11%3A59%3A59-05%3A00


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

id

When the id parameter is used in a Checkout API request, it specifies a value that uniquely identifies the address from which a package will be shipped for carrier-calculated shipping. When it appears in a new order notification, the id parameter specifies a value that uniquely identifies a Google Checkout promotion.

Associated recurring elements


In a Checkout API request, the carrier-calculated-shipping element must be numbered with a value of 1 and the shipping-package element must also be numbered. In a new order notification, the promotion element will be numbered so that the promotion ID can be associated with a specific promotion.

API commands


Content format for parameter value


String

Sample use(s)


promotions.promotion-#.id=4910

ip-address

The ip-address parameter contains the buyer's IP address, which Google uses to assess the risk that the order is fraudulent.

API commands


Content format for parameter value


String

Sample use(s)


risk-information.ip-address=10.10.10.10

item-description

The item-description parameter contains a description of an item.

Associated recurring elements


The item element, which must be numbered, associates this parameter with a specific item in an order.

API commands


Content format for parameter value


String

Sample use(s)


<input type="hidden" name="shopping-cart.items.item-#.item-description" value="Easy to use MP3 Player"/>
<input type="hidden" name="item_description_#" value="Easy to use MP3 Player"/>

item-name

The item-name parameter identifies the name of an item.

Associated recurring elements


The item element, which must be numbered, associates this parameter with a specific item in an order.

API commands


Content format for parameter value


String

Sample use(s)


<input type="hidden" name="shopping-cart.items.item-#.item-name" value="HelloWorld 2GB MP3 Player"/>

key

The key parameter contains a key needed to download or unlock a digital content item.

Associated recurring elements


The item element, which must be numbered, associates this parameter with a specific item in an order.

Content format for parameter value


String

Sample use(s)


<input type="hidden" name="shopping-cart.items.item-#.digital-content.key" value="1456-1514-3657-2198"/>

last-name

The last-name parameter contains the last name of the buyer or recipient of an order. Please see the Matching Names in Notifications to Names in Your Database section for details about Google Checkout's name-splitting algorithm.

Content format for parameter value


String

Sample use(s)


In a new order notification:
[buyer-billing-address | buyer-shipping-address].structured-name.last-name=Vandalay

In a risk information notification:
billing-address.structured-name.last-name=Vandalay


latest-charge-amount

The latest-charge-amount parameter contains the amount most recently charged for a particular order.

API commands


Content format for parameter value


Decimal

Sample use(s)


latest-charge-amount=50.00

latest-chargeback-amount

The latest-chargeback-amount parameter contains the amount most recently charged back against a particular order.

API commands


Content format for parameter value


Decimal

Sample use(s)


latest-chargeback-amount=50.00

latest-promotion-charge-amount

The latest-promotion-charge-amount parameter indicates how much Google contributed to the latest charge amount as a part of an ongoing promotion. For example, suppose Google offered a promotion in which a buyer who completed an order through Google Checkout received $10 off any purchase of $100 or more. If a merchant charged the customer the full amount of a $100 order, then the latest-charge-amount value would be $100 and the latest-promotion-charge-amount would be $10.

Content format for parameter value


Decimal

Sample use(s)


latest-promotion-charge-amount=10.00

latest-promotion-chargeback-amount

The latest-promotion-chargeback-amount parameter indicates that a portion of the latest chargeback amount was originally paid by Google as a part of a promotion and is therefore being recouped by Google rather than by the customer. For example, suppose Google offered a promotion in which a buyer who completed an order through Google Checkout received $10 off any purchase of $100 or more. If a buyer had completed a $100 order, then the buyer would have paid $90 and Google would have paid $10 of the order total. If the buyer then disputed the charge, then the latest-chargeback-amount value would be $100 and the latest-promotion-chargeback-amount would be $10.

Content format for parameter value


Decimal

Sample use(s)


latest-promotion-chargeback-amount=10.00

latest-promotion-refund-amount

The latest-promotion-refund-amount parameter indicates that a portion of the latest refund amount was originally paid by Google as a part of a promotion and is therefore being refunded to Google rather than to the customer. For example, suppose Google offered a promotion in which a buyer who completed an order through Google Checkout received $10 off any purchase of $100 or more. If a merchant refunded the customer the full amount of a $100 order, then the latest-refund-amount value would be $100 and the latest-promotion-refund-amount would be $10. Accordingly, the buyer would receive a $90 refund ($100 - $10).

Content format for parameter value


Decimal

Sample use(s)


latest-promotion-refund-amount=10.00

latest-refund-amount

The latest-refund-amount parameter contains the most recent refund amount for a particular order.

API commands


Content format for parameter value


Decimal

Sample use(s)


latest-refund-amount=50.00

merchant-item-id

The merchant-item-id parameter 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 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.

Associated recurring elements


The item element, which must be numbered, associates this parameter with a specific item in an order.

API commands


Content format for parameter value


String

Sample use(s)


<input type="hidden" name="shopping-cart.items.item-#.merchant-item-id" value="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


mode

The mode parameter specifies the method that will be used to round monetary values to two decimal places. This parameter may contain any of the following values, each of which is defined in the Java 1.5 specification for the RoundingMode enumeration.RoundingMode enumeration.

  • UP - This mode rounds numbers away from zero. For example, the number 1.111 would be rounded to 1.12.

  • DOWN - This mode rounds numbers toward zero. For example, the number 1.666 would be rounded to 1.66.

  • CEILING - This mode rounds numbers toward positive infinity. For positive numbers, the CEILING mode functions identically to the UP rounding mode. For negative numbers, the CEILING mode functions identically to the DOWN rounding mode.

  • HALF_UP - This mode rounds numbers to the nearest digit. However, if the number being rounded is followed by a five and no additional nonzero digits, then then that number will be rounded up. For example, the number 1.165 would be rounded to 1.17. This method is the default rounding mode for U.K. merchants.

  • HALF_DOWN - This mode rounds numbers to the nearest digit. However, if the number being rounded is followed by a five and no additional nonzero digits, then then that number will be rounded down. For example, the number 1.165 would be rounded to 1.16.

  • HALF_EVEN - This mode, which is also known as banker's rounding, is the default rounding mode for U.S. merchants. Banker's rounding is the same as the traditional method of rounding numbers with one exception. In banker's rounding, if the number to be rounded is followed by a five and no additional nonzero digits, the number is rounded to the nearest even number.

API commands


Content format for parameter value


String

Sample use(s)


<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.rounding-policy.mode" value="HALF_UP"/>

name

In a Checkout API request, the name parameter value contains a string that can be used to identify a tax table or shipping method. The parameter value must be at least one non-space character and may not be longer than 255 characters. The name parameter can also be used in a Checkout API request to identify the name of a query string parameter that will be included in a web beacon URL for third-party conversion tracking. The parameter's value is the name that the third-party tracking provider uses in its web beacon URLs.

In a new order notification, the name parameter specifies the name that Google uses to identify a promotion in the Merchant Center.

Associated recurring elements


When the name parameter specifies the name of a query string parameter that will be included in a web beacon URL for third-party conversion tracking, the parameterized-url element must be numbered to associate the URL with a particular web beacon. In addition, the url-parameter element must be numbered so that the parameter name may be associated with the parameter value, which is expressed using the type parameter. When the name parameter is associated with an alternate tax table, the alternate-tax-table element must be numbered. When the name parameter is associated with a shipping method in a Checkout API request, either the flat-rate-shipping or pickup element needs to be numbered. Finally, when the name parameter is associated with a promotion, the promotion element must be numbered so that the promotion name can be associated with a specific promotion.

Content format for parameter value


String

Sample use(s)


Identifying a shipping method in a Checkout API request:
input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.[flat-rate-shipping-# | pickup-shipping-#].name" value="Standard shipping"/

Identifying a tax table in a Checkout API request:
input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.alternate-tax-tables.alternate-tax-table-#.name" value="reduced"/

Identifying a URL parameter in a Checkout API request:
input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.parameterized-urls.parameterized-url-#.parameters.url-parameter-#.name" value="taxes"/

Identifying a promotion in a new order notification:
promotions.promotion-#.name=Google+10+off+50


new-financial-order-state

The new-financial-order-state parameter identifies the financial-order-state for an order following a status change. The new-financial-order-state parameter is included in an order state change notification along with a previous-financial-order-state, which identifies the financial-order-state for the order prior to the status change.

Please see the Financial Commands in the Order Processing API document or the financial-order-state element definition for a complete list of valid values for this parameter.

API commands


Content format for parameter value


String

Sample use(s)


new-financial-order-state=CHARGED

new-fulfillment-order-state

The new-fulfillment-order-state parameter identifies the fulfillment-order-state for an order following a status change. The new-fulfillment-order-state parameter is included in an order-state-change-notification along with a previous-fulfillment-order-state, which identifies the fulfillment-order-state for the order prior to the status change.

Please see the fulfillment-order-state element definition for a complete list of valid values for this parameter.

API commands


Content format for parameter value


String

Sample use(s)


new-fulfillment-order-state=PROCESSING

order-total

The order-total parameter contains the total cost of an order, including taxes and shipping costs as well as discounts from coupons and gift certificates.

API commands


Content format for parameter value


Decimal

Sample use(s)


order-total=114.54

partial-cc-number

The partial-cc-number parameter contains the last four digits of the buyer's credit card number.

API commands


Content format for parameter value


String

Sample use(s)


risk-information.partial-cc-number=1234

phone

The phone parameter identifies a phone number that can be used to contact the person to be billed for an order or the order recipient. To receive either the phone number for the buyer or the order recipient, you must set a preference in your Google Checkout merchant account. To set this preference, log in to your merchant account and click the Settings tab. Then click the Integration link on the left side of the page. Expand the list of advanced settings and, depending on your preferences, check the box next to either or both of the following preferences:

  • Return the buyer's ship-to phone number in the new order notification
  • Return the buyer's billing phone number in the new order notification

Then click the Save button to update your settings.

API commands


Content format for parameter value


String

Sample use(s)


In a new order notification:
[buyer-billing-address | buyer-shipping-address].phone=5552221212

In a risk information notification:
billing-address.phone=5552221111


platform-id

The platform-id parameter should only be used by e-commerce providers who make API requests on behalf of a merchant. The parameter's value contains a Google Checkout merchant ID that identifies the e-commerce provider.

Note for e-commerce Providers: The Google Checkout Terms and Conditions require e-commerce providers that manage websites for merchants who are affiliated with Google Checkout to identify themselves. The value of the platform-id parameter should be a Google Checkout Merchant ID that uniquely identifies the e-commerce provider.

In keeping with this requirement, e-commerce providers should sign up for a Google Checkout merchant account. They should then use the merchant ID for that account as the platform-id parameter value in Checkout API requests for all merchants using the provider's platform. However, providers should still use the merchant IDs and merchant keys assigned to the individual merchants to encode API requests from those merchants.

API commands


Content format for parameter value


Long

Sample use(s)


<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.platform-id" value="1234567890"/>

postal-code

The postal-code parameter identifies the zip code or postal code associated with either a billing address or a shipping address.

Associated recurring elements


When the postal-code parameter appears in a carrier-calculated shipping option in a Checkout API request, the shipping-package element must be numbered. In addition, the carrier-calculated-shipping element must be numbered with a value of 1.

API commands


Content format for parameter value


String

Sample use(s)


In a carrier-calculated-shipping option in a Checkout API request:
<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.carrier-calculated-shipping-1.shipping-packages.shipping-package-#.ship-from.postal-code" value="94043"/>

In a new order notification:
[buyer-billing-address | buyer-shipping-address].postal-code=94043

In a risk information notification:
billing-address.postal-code=94043


postal-code-pattern

The postal-code-pattern parameter contains a postal code or a range of postal codes for a specific country. To specify a range of postal codes, use an asterisk as a wildcard operator. For example, you can provide a postal-code-pattern value of SW* to indicate that a shipping option is available or a tax rule applies in any postal code beginning with the characters SW.

Associated recurring elements


When the postal-code-pattern parameter is associated with a shipping method, the postal-area and flat-rate-shipping elements need to be numbered. When the postal-code-pattern parameter is associated with a default tax table, the default-tax-rule and postal-area elements must both be numbered. When the postal-code-pattern parameter is associated with an alternate tax table, the alternate-tax-table, alternate-tax-rule and postal-area elements must all be numbered.

API commands


Content format for parameter value


String

Sample use(s)


<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-#.shipping-restrictions.[allowed-areas | excluded-areas].postal-area.postal-code-pattern" value="SW*"/>

<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.default-tax-table.default-tax-rule-#.tax-areas.postal-area-#.postal-code-pattern" value="SW*"/>

<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.tax-tables.alternate-tax-tables.alternate-tax-table-#.alternate-tax-rule-#.tax-areas.postal-area-#.postal-code-pattern" value="SW*"/>


previous-financial-order-state

The previous-financial-order-state parameter identifies the financial-order-state for an order prior to a status change. The previous-financial-order-state parameter is included in an order-state-change-notification along with a new-financial-order-state, which identifies the financial-order-state for the order following the status change.

Please see the Financial Commands in the Order Processing API document or the financial-order-state element definition for a complete list of valid values for this parameter.

API commands


Content format for parameter value


String

Sample use(s)


previous-financial-order-state=CHARGING

previous-fulfillment-order-state

The previous-fulfillment-order-state parameter identifies the fulfillment-order-state for an order prior to a status change. The previous-fulfillment-order-state parameter is included in an order-state-change-notification along with a new-fulfillment-order-state, which identifies the fulfillment-order-state for the order following the status change.

Please see the fulfillment-order-state element definition for a complete list of valid values for this parameter.

API commands


Content format for parameter value


String

Sample use(s)


previous-fulfillment-order-state=NEW

price

The price parameter contains the cost to ship an order using a particular shipping method.

Associated recurring elements


The parameter name must contain either the flat-rate-shipping or pickup elements, and that element must be numbered to associate the price with a particular shipping method.

API commands


Content format for parameter value


Decimal

Sample use(s)