Google Checkout APIs

Documentation

Developer Tools

Support Resources

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.

_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)

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

Content format for parameter value

Double

Sample use(s)

address1

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

API commands

New Order Notification, Risk Information Notification

Content format for parameter value


e.g. "ajax apis" or "open source"

Google Checkout APIs

Documentation

Developer Tools

Support Resources

HTML API Parameter Reference

Understanding API Parameter Names

HTML Parameter Definitions