Google Checkout PHP Sample Code - CheckoutAPIFunctions.php

The CheckoutAPIFunctions.php library contains a set of functions that are used to create Checkout API XML requests. These XML requests include the items in the customer's shopping cart as well as tax tables, shipping options and other information that is used during the customer checkout process.

This document includes an explanation of each function in the CheckoutAPIFunctions.php file. Each explanation includes a list of the parameters that are passed to the function, links to other functions that call the function, and links to the sample API implementations that call the function.

Note: To use these functions in your web application, you will need to update the return values of the GetMerchantID and GetMerchantKey functions in the GlobalAPIFunctions.php library.

Please refer to the CheckoutShoppingCartDemo.php implementation to see sample usages of these functions.

Checkout API Functions

CreateItem

CreateShoppingCart

CreateUsCountryArea

CreateUsStateArea

CreateUsZipArea

CreateUsPlaceArea

CreateTaxArea

CreateDefaultTaxRule

CreateAlternateTaxRule

CreateAlternateTaxTable

CreateTaxTables

AddAllowedAreas

AddExcludedAreas

AddAreas

CreateFlatRateShipping

CreateMerchantCalculatedShipping

CreatePickup

CreateShipping

CreateMerchantCalculations

CreateMerchantCheckoutFlowSupport

CreateCheckoutShoppingCart

CreateItem

Definition:

The CreateItem function constructs the XML for a single <item> in a shopping cart.

Parameters:

Parameter Name	Definition
$item_name	Required. The $item_name parameter contains the name of the item.
$item_desc	Required. The $item_desc parameter contains a description of the item.
$quantity	Required. The $quantity parameter indicates how many units of the item are included in the order.
$unit_price	Required. The $unit_price parameter identifies the numeric cost of the item.
$tt_selector	Optional. The $tt_selector parameter identifies an alternate tax table that should be used to calculate taxes for the item. The $tt_selector parameter's value must correspond to the name parameter of an alternate tax table.
$private_item_data	Optional. The $private_item_data parameter contains proprietary information about the item. Google Checkout will return this information in the new order notification that includes the item. The parameter value must be well formed XML.

See Sample Usage:

CheckoutShoppingCartDemo
CheckoutShoppingCartDemoAlternativeMethod

Code:

function CreateItem($item_name, $item_desc, $quantity, $unit_price,
    $tt_selector="", $private_item_data="") {

    global $dom_items_obj;

    /*
     * Each of these parameters must have a value to create an <item>
     */
    $error_function_name = "CreateItem()";
    CheckForError($GLOBALS["mp_type"], $error_function_name,
        "item_name", $item_name);
    CheckForError($GLOBALS["mp_type"], $error_function_name,
        "item_description", $item_desc);
    CheckForError($GLOBALS["mp_type"], $error_function_name,
        "quantity", $quantity);
    CheckForError($GLOBALS["mp_type"], $error_function_name,
        "unit_price", $unit_price);
    CheckForError($GLOBALS["mp_type"], $error_function_name,
        "GLOBALS[\"currency\"]", $GLOBALS["currency"]);

    // HTML entities need to be escaped properly
    $item_name = htmlentities($item_name);
    $item_desc = htmlentities($item_desc);

    // Create the <items> tag if this is the first item to be created
    if ($dom_items_obj == "") {
        $dom_items_obj = domxml_new_doc("1.0");
        $dom_items_obj->append_child(
            $dom_items_obj->create_element("items"));
    }

    $dom_item_obj = domxml_new_doc("1.0");

    // Create the <item> tag for the item to be created
    $dom_item =
        $dom_item_obj->append_child(
            $dom_item_obj->create_element("item"));

    // Add the item name to the XML
    $dom_item_name =
        $dom_item->append_child(
            $dom_item_obj->create_element("item-name"));

    $dom_item_name->append_child(
        $dom_item_obj->create_text_node($item_name));

    // Add the item description to the XML
    $dom_item_desc = $dom_item->append_child(
        $dom_item_obj->create_element("item-description"));

    $dom_item_desc->append_child(
        $dom_item_obj->create_text_node($item_desc));

    // Add the quantity to the XML
    $dom_quantity = $dom_item->append_child(
        $dom_item_obj->create_element("quantity"));

    $dom_quantity->append_child(
        $dom_item_obj->create_text_node($quantity));

    // Add the unit price for the item to the XML
    $dom_price = $dom_item->append_child(
        $dom_item_obj->create_element("unit-price"));

    $dom_price->set_attribute("currency", $GLOBALS["currency"]);
    $dom_price->append_child(
        $dom_item_obj->create_text_node($unit_price));

    /*
     * If there is an alternate-tax-table associated with this item,
     * specify the table's name using the <tax-table-selector> tag.
     */
    if ($tt_selector != "") {
        $dom_tt_selector =
            $dom_item->append_child(
                 $dom_item_obj->create_element("tax-table-selector"));

        $dom_tt_selector->append_child(
            $dom_item_obj->create_text_node($tt_selector));
    }

    /*
     * If you have provided a value for the $private_item_data
     * variable, that value will be printed inside the
     * <merchant-private-item-data> tag.
     */

    if ($private_item_data != "") {
        $dom_private_item_data = domxml_open_mem($private_item_data);

        $dom_new_private_item_data =
            $dom_item->append_child(
                $dom_item_obj->create_element("merchant-private-item-data"));

        $dom_private_item_data_root =
            $dom_private_item_data->document_element();

        $dom_new_private_item_data->append_child(
            $dom_private_item_data_root->clone_node(true));
    }

    /*
     * The newly created item is added as a child of the <items> tag.
     */
    $dom_items_root = $dom_items_obj->document_element();
    $dom_item_root = $dom_item_obj->document_element();
    $dom_items_root->append_child($dom_item_root->clone_node(true));

    return $dom_item_obj;
}

CreateShoppingCart

Definition:

The CreateShoppingCart function constructs the XML for the <shopping-cart> element in a Checkout API request. Since the <shopping-cart> element contains all of the items in the cart, this function must be called after you have already called the CreateItem function for each item in the order.

Parameters:

Parameter Name	Definition
$cart_expiration	Optional. The $cart_expiration parameter identifies the date that the shopping cart expires. If you specify a value for this parameter, Google Checkout will reject the shopping cart if the user submits the cart after the specified date. If you do not specify a value for this element, the cart will not expire.
$merchant_private_data	Optional. The $merchant_private_data parameter contains proprietary information about the order. Google Checkout will return this information in the new order notification for the order. The parameter value must be well formed XML.

See Sample Usage:

CheckoutShoppingCartDemo
CheckoutShoppingCartDemoAlternativeMethod

Code:

CreateUsCountryArea

Definition:

The CreateUsCountryArea function is a wrapper function that calls the CreateUsPlaceArea function. The CreateUsPlaceArea function, in turn, creates and returns a <us-country-area> XML block.

Parameters:

Parameter Name	Definition
$area_place	The $area_place parameter identifies the U.S. region that should be included in the XML block. The valid values for the $area_place parameter are CONTINENTAL_48, FULL_50_STATES and ALL.

Parameter Name

Definition

$area_place

The $area_place parameter identifies the U.S. region that should be included in the XML block.

The valid values for the $area_place parameter are CONTINENTAL_48, FULL_50_STATES and ALL.

Functions that call CreateUsCountryArea:

AddAreas
CreateUsZipArea

Code:

function CreateUsCountryArea($area_place) {
return CreateUsPlaceArea("country", $area_place);
}

CreateUsStateArea

Definition:

The CreateUsStateArea function is a wrapper function that calls the CreateUsPlaceArea function. The CreateUsPlaceArea function, in turn, creates and returns a <us-state-area> XML block.

Parameters:

Parameter Name	Definition
$area_place	The $area_place parameter identifies the U.S. state that should be included in the XML block. The $area_place parameter value should be a two-letter U.S. state abbreviation.

Parameter Name

Definition

$area_place

The $area_place parameter identifies the U.S. state that should be included in the XML block.

The $area_place parameter value should be a two-letter U.S. state abbreviation.

Functions that call CreateUsStateArea:

AddAreas
CreateUsZipArea

Code:

function CreateUsStateArea($area_place) {
return CreateUsPlaceArea("state", $area_place);
}

CreateUsZipArea

Definition:

The CreateUsZipArea function is a wrapper function that calls the CreateUsPlaceArea function. The CreateUsPlaceArea function, in turn, creates and returns a <us-zip-area> XML block.

Parameters:

Parameter Name	Definition
$area_place	The $area_place parameter identifies the U.S. zip code}} that should be included in the XML block. The $area_place parameter value should be a five-digit U.S. zip code or a zip code pattern.

Parameter Name

Definition

$area_place

The $area_place parameter identifies the U.S. zip code}} that should be included in the XML block.

The $area_place parameter value should be a five-digit U.S. zip code or a zip code pattern.

Functions that call CreateUsZipArea:

AddAreas

Code:

function CreateUsZipArea($area_place) {
return CreateUsPlaceArea("zip", $area_place);
}

CreateUsPlaceArea

Definition:

The CreateUsPlaceArea function creates <us-country-area>, <us-state-area> and <us-zip-area> XML blocks. This function is called by the CreateTaxArea and AddAreas functions.

Parameters:

Parameter Name

Definition

$area_type

Required. The $area_type parameter indicates whether the function should construct a <us-country-area>, <us-state-area> or <us-zip-area> XML block. Valid values for this parameter are country, state and zip.

$area_place

The $area_place parameter identifies the U.S. region, state or zip code that should be included in the XML block.

If the value of the $area_type parameter is country, then the valid values for the $area_place parameter are CONTINENTAL_48, FULL_50_STATES and ALL.

If the value of the $area_type parameter is state, then the $area_place parameter value should be a two-letter U.S. state abbreviation.

If the value of the $area_type parameter is zip, then the $area_place parameter value should be a five-digit U.S. zip code or a zip code pattern.

Functions that call CreateUsPlaceArea:

CreateTaxArea
CreateUsCountryArea
CreateUsStateArea
CreateUsZipArea

Code:

function CreateUsPlaceArea($area_type, $area_place) {

    $error_function_name = "CreateUsPlaceArea(" . $area_type . ":" .
        $area_place . ")";

    // The area_type must be specified for the function call to execute.
    CheckForError($GLOBALS["mp_type"], $error_function_name, $area_type,
        $area_place);

    $dom_area_obj = domxml_new_doc("1.0");

    // Create the parent XML element for the $area_type
    $dom_area = $dom_area_obj->append_child(
        $dom_area_obj->create_element("us-" . $area_type . "-area"));

    /*
     * Create the elements that contain the $area_place data
     */
    if ($area_type == "state") {

        $dom_area_place = $dom_area->append_child(
            $dom_area_obj->create_element("state"));
        $dom_area_place->append_child(
            $dom_area_obj->create_text_node($area_place));

    } elseif ($area_type == "zip") {

        $dom_area_place =
            $dom_area->append_child(
                $dom_area_obj->create_element("zip-pattern"));
        $dom_area_place->append_child(
            $dom_area_obj->create_text_node($area_place));

    } elseif ($area_type == "country") {
        $dom_area_place =
            $dom_area->set_attribute("country-area", $area_place);
    }

    return $dom_area_obj;
}

CreateTaxArea

Definition:

The CreateTaxArea function creates a <tax-area> XML block, which identifies a geographic region where a tax rate applies.

Parameters:

Parameter Name	Definition
$area_type	Required. The $area_type parameter indicates whether the function should construct a <us-country-area>, <us-state-area> or <us-zip-area> XML block. Valid values for this parameter are country, state and zip.
$area_place	The $area_place parameter identifies the U.S. that should be included in the XML block.

See Sample Usage:

CheckoutShoppingCartDemo
CheckoutShoppingCartDemoAlternativeMethod

Code:

function CreateTaxArea($area_type, $area_place) {

    $error_function_name = "CreateTaxArea(" . $area_type . ")";

    // You must provide an $area_type value or the function will not execute.
    CheckForError($GLOBALS["mp_type"], $error_function_name,
        $area_type, $area_type);

    // Create the <tax-area> element
    $dom_tax_area_obj = domxml_new_doc("1.0");
    $dom_tax_area =
        $dom_tax_area_obj->append_child(
            $dom_tax_area_obj->create_element("tax-area"));

    /*
     * Call the CreateUsPlaceArea function to create the child
     * elements of the <tax-area> element
     */
    $dom_area = CreateUsPlaceArea($area_type, $area_place);
    $dom_area_root = $dom_area->document_element();
    $dom_tax_area->append_child($dom_area_root->clone_node(true));

    return $dom_tax_area_obj;
}

CreateDefaultTaxRule

Definition:

The CreateDefaultTaxRule function creates and returns a <default-tax-rule> XML block.

Parameters:

Parameter Name	Definition
$rate	Required. This parameter identifies the tax rate that should be assessed for a given tax rule. The value should be a positive decimal value. Any items that fall under this tax rate will be multiplied by this amount to calculate the tax for the item.
$dom_tax_area	Required. This parameter identifies the area where the tax rate should be applied. The value should be a <tax-area> XML block such as that returned by the CreateTaxArea function.
$shipping_taxed	Required. This parameter contains a Boolean value that indicates whether shipping costs should be taxed.

See Sample Usage:

CheckoutShoppingCartDemo
CheckoutShoppingCartDemoAlternativeMethod

Code:

function CreateDefaultTaxRule($rate, $dom_tax_area, $shipping_taxed="") {

    global $dom_default_tax_rules_obj;

    $error_function_name = "CreateDefaultTaxRule()";

    /*
     * You must specify a $rate and provide a $dom_tax_area object
     * for each tax rule
     */
    CheckForError($GLOBALS["mp_type"], $error_function_name,
        "rate", $rate);
    CheckForError($GLOBALS["mp_type"], $error_function_name,
        "dom_tax_area", $dom_tax_area);

    $dom_default_tax_rule_obj = domxml_new_doc("1.0");

    // Create the <default-tax-rule> element
    $dom_default_tax_rule =
        $dom_default_tax_rule_obj->append_child(
            $dom_default_tax_rule_obj->create_element("default-tax-rule"));

    // Add a <shipping-taxed> element if a $shipping_taxed value is provided
    if ($shipping_taxed != "") {

        $dom_shipping_taxed =
            $dom_default_tax_rule->append_child(
        $dom_default_tax_rule_obj->create_element("shipping-taxed"));

        $dom_shipping_taxed->append_child(
            $dom_default_tax_rule_obj->create_text_node($shipping_taxed));
    }

    // Add the tax rate for the tax rule
    $dom_rate = $dom_default_tax_rule->append_child(
        $dom_default_tax_rule_obj->create_element("rate"));
    $dom_rate->append_child($dom_default_tax_rule_obj->create_text_node($rate));

    // Add the tax area to the tax rule
    $dom_tax_area_root = $dom_tax_area->document_element();
    $dom_default_tax_rule->append_child($dom_tax_area_root->clone_node(true));

    /*
     * Create a <tax-rules> element if no other <default-tax-rule>
     * elements have been created. Append the rule to a list that
     * will appear under the <tax-rules> element within the
     * <default-tax-table> element
     */
    if ($dom_default_tax_rules_obj == "") {
        $dom_default_tax_rules_obj = domxml_new_doc("1.0");

        $dom_default_tax_rules_obj->append_child(
            $dom_default_tax_rules_obj->create_element("tax-rules"));
    }

    $dom_default_tax_rules_root =
        $dom_default_tax_rules_obj->document_element();
    $dom_default_tax_rule_root = $dom_default_tax_rule_obj->document_element();
    $dom_default_tax_rules_root->append_child(
        $dom_default_tax_rule_root->clone_node(true));

return $dom_default_tax_rule_obj;
}

CreateAlternateTaxRule

Definition:

The CreateAlternateTaxRule function creates and returns a <alternate-tax-rule> XML block.

Parameters:

Parameter Name	Definition
$rate	Required. This parameter identifies the tax rate that should be assessed for a given tax rule. The value should be a positive decimal value. Any items that fall under this tax rate will be multiplied by this amount to calculate the tax for the item.
$dom_tax_area	Required. This parameter identifies the area where the tax rate should be applied. The value should be a <tax-area> XML block such as that returned by the CreateTaxArea function.

See Sample Usage:

CheckoutShoppingCartDemo
CheckoutShoppingCartDemoAlternativeMethod

Code:

function CreateAlternateTaxRule($rate, $dom_tax_area) {

    global $dom_alt_tax_rules_obj;

    // Check for errors
    $error_function_name = "CreateAlternateTaxRule()";

    /*
     * You must specify a $rate and provide a $dom_tax_area object
     * for each tax rule
     */
    CheckForError($GLOBALS["mp_type"], $error_function_name,
        "rate", $rate);
    CheckForError($GLOBALS["mp_type"], $error_function_name,
        "dom_tax_area", $dom_tax_area);

    $dom_alt_tax_rule_obj = domxml_new_doc("1.0");

    // Create the <alternate-tax-rule> element
    $dom_alt_tax_rule = $dom_alt_tax_rule_obj->append_child(
        $dom_alt_tax_rule_obj->create_element("alternate-tax-rule"));

    // Add the tax rate for the tax rule
    $dom_rate = $dom_alt_tax_rule->append_child(
        $dom_alt_tax_rule_obj->create_element("rate"));
    $dom_rate->append_child($dom_alt_tax_rule_obj->create_text_node($rate));

    // Add the tax area to the tax rule
    $dom_tax_area_root = $dom_tax_area->document_element();
    $dom_alt_tax_rule->append_child($dom_tax_area_root->clone_node(true));

    /*
     * Create an <alternate-tax-rules> element if this is the first
     * <alternate-tax-rule> to be created. Append the rule to a list
     * that will appear under the <alternate-tax-rules> element within
     * an <alternate-tax-table> element
     */
    if ($dom_alt_tax_rules_obj == "") {
        $dom_alt_tax_rules_obj = domxml_new_doc("1.0");

        $dom_alt_tax_rules_obj->append_child(
            $dom_alt_tax_rules_obj->create_element("alternate-tax-rules"));
    }

    $dom_alt_tax_rules_root = $dom_alt_tax_rules_obj->document_element();
    $dom_alt_tax_rule_root = $dom_alt_tax_rule_obj->document_element();
    $dom_alt_tax_rules_root->append_child(
        $dom_alt_tax_rule_root->clone_node(true));

return $dom_alt_tax_rule_obj;
}

CreateAlternateTaxTable

Definition:

The CreateAlternateTaxTable function creates and returns a <alternate-tax-table> XML block. The XML will contain any <alternate-tax-rule> elements that have not already been included in an <alternate-tax-table>.

For example, suppose you want to create two alternate tax tables that each contain two alternate tax rules. One table will contain tax rates for food items and the other would contain tax rates for services. To create the alternate tax tables, you would need to call the CreateAlternateTaxRule function twice, once for each alternate tax rule in the food tax table. Then you would call the CreateAlternateTaxTable function. Then you would repeat this process, calling the CreateAlternateTaxRule function twice, once for each alternate tax rule in the services tax table, and then calling the CreateAlternateTaxTable function again.

Parameters:

Parameter Name	Definition
$standalone	The $standalone parameter contains a Boolean value that indicates how taxes should be calculated if there is no matching <alternate-tax-rule> in the <alternate-tax-table> for the customer's zip code, state or region. Please see the definition of the Checkout API's <alternate-tax-table> tag for more information.
$name	The $name parameter contains a string, such as "food", that can be used to identify the tax table.

See Sample Usage:

CheckoutShoppingCartDemo
CheckoutShoppingCartDemoAlternativeMethod

Code:

function CreateAlternateTaxTable($standalone, $name) {

    global $dom_alt_tax_rules_obj, $dom_alt_tax_tables_obj;

    /*
     * There must be at least one alternate tax rule to include
     * in the <alternate-tax-table>. This tax table will include
     * any <alternate-tax-rule> elements that were created since
     * after the last call to the CreateAlternateTaxTable function.
     */
    if ($dom_alt_tax_rules_obj == "") {
        trigger_error("You must have at least one alternate tax rule.",
            E_USER_ERROR);
    }

    // Check for errors
    $error_function_name = "CreateAlternateTaxTable()";

    /*
     * You must specify values for the $standalone and $name parameters
     */
    CheckForError($GLOBALS["mp_type"], $error_function_name,
        "standalone", $standalone);
    CheckForError($GLOBALS["mp_type"], $error_function_name,
        "name", $name);

    // Create the <alternate-tax-rules> object
    $dom_alt_tax_rules_obj->append_child(
        $dom_alt_tax_rules_obj->create_element("alternate-tax-rules"));

    // Create the <alternate-tax-table> element
    $dom_alt_tax_table_obj = domxml_new_doc("1.0");
    $dom_alt_tax_table = $dom_alt_tax_table_obj->append_child(
        $dom_alt_tax_table_obj->create_element("alternate-tax-table"));

    // Add attributes for the $standalone and $name values
    $dom_alt_tax_table->set_attribute("standalone", $standalone);
    $dom_alt_tax_table->set_attribute("name", $name);

    /*
     * Add the <alternate-tax-rules> element as
     * a child element of <alternate-tax-table>
     */
    $dom_alt_tax_rules_root = $dom_alt_tax_rules_obj->document_element();
    $dom_alt_tax_table->append_child($dom_alt_tax_rules_root->clone_node(true));

    /*
     * Create an <alternate-tax-tables> element, if one has not yet
     * been created, to contain all <alternate-tax-table> elements
     */
    if ($dom_alt_tax_tables_obj == "") {
        $dom_alt_tax_tables_obj = domxml_new_doc("1.0");
        $dom_alt_tax_tables_obj->append_child(
            $dom_alt_tax_tables_obj->create_element("alternate-tax-tables"));
    }

    /*
     * Add the <alternate-tax-table> element as a child of
     * the <alternate-tax-tables> element
     */
    $dom_alt_tax_tables_root = $dom_alt_tax_tables_obj->document_element();
    $dom_alt_tax_table_root = $dom_alt_tax_table_obj->document_element();
    $dom_alt_tax_tables_root->append_child(
        $dom_alt_tax_table_root->clone_node(true));

    $dom_alt_tax_rules_obj = domxml_new_doc("1.0");
    $dom_alt_tax_rules_obj->append_child(
        $dom_alt_tax_rules_obj->create_element("alternate-tax-rules"));

return $dom_alt_tax_tables_obj;
}

CreateTaxTables

Definition:

The CreateTaxTables function constructs the <tax-tables> XML for an order.

Parameters:

Parameter Name	Definition
$merchant_calculated	Required. The $merchant_calculated parameter contains a Boolean value that indicates whether tax for the order is calculated using a special process.

See Sample Usage:

CheckoutShoppingCartDemo
CheckoutShoppingCartDemoAlternativeMethod

Code:

function CreateTaxTables($merchant_calculated) {

    global $dom_default_tax_rules_obj, $dom_alt_tax_tables_obj,
        $dom_tax_tables_obj;

    // Check for errors
    $error_function_name = "CreateTaxTables()";

    /*
     * You must have already created the <default-tax-table> XML DOM
     * before calling this function. You must also provide a value
     * for the $merchant_calculated parameter.
     */
    if ($dom_default_tax_rules_obj == "") {
        trigger_error("You must have have at least one default tax rule.",
            E_USER_ERROR);
    }
    CheckForError($GLOBALS["mp_type"], $error_function_name,
        "merchant_calculated", $merchant_calculated);

    // Create a <default-tax-table> element
    $dom_default_tax_table_obj = domxml_new_doc("1.0");
    $dom_default_tax_table =
        $dom_default_tax_table_obj->append_child(
            $dom_default_tax_table_obj->create_element("default-tax-table"));

    /*
     * Add <default-tax-rule> elements as children of
     * the <default-tax-table> element
     */
    $dom_default_tax_rules_root =
        $dom_default_tax_rules_obj->document_element();
    $dom_default_tax_table->append_child(
        $dom_default_tax_rules_root->clone_node(true));

    // Create the <tax-tables> element
    $dom_tax_tables_obj = domxml_new_doc("1.0");
    $dom_tax_tables = $dom_tax_tables_obj->append_child(
        $dom_tax_tables_obj->create_element("tax-tables"));

    // Set the $merchant-calculated attribute on the <tax-tables> element
    if ($merchant_calculated != "") {
        $dom_tax_tables->set_attribute(
            "merchant-calculated", $merchant_calculated);
    }

    // Make the <default-tax-table> element a child of <tax-tables> element
    $dom_default_tax_table_root =
        $dom_default_tax_table_obj->document_element();
    $dom_tax_tables->append_child(
        $dom_default_tax_table_root->clone_node(true));

    // Add the <alternate-tax-tables> as children of <tax-tables>
    if ($dom_alt_tax_tables_obj != "") {
        $dom_alt_tax_tables_root =
            $dom_alt_tax_tables_obj->document_element();
        $dom_tax_tables->append_child(
            $dom_alt_tax_tables_root->clone_node(true));
    }

return $dom_tax_tables_obj;
}

AddAllowedAreas

Definition:

The AddAllowedAreas function is a wrapper function that calls the AddAreas function. The AddAreas function, in turn, creates and returns an <allowed-areas> XML DOM.

Parameters:

Parameter Name	Definition
$country_area	This parameter specifies a region of the country where a shipping option is available or unavailable. Valid values for this parameter are CONTINENTAL_48, FULL_50_STATES and ALL.
$state_areas	This parameter specifies an array of one or more states where a shipping option is available or unavailable. Each item in the array should be a two-letter U.S. state abbreviation.
$zip_areas	This parameter specifies an array of one or more zip codes where a shipping option is available or unavailable. Each item in the array should specify either a five-digit U.S. zip code or a range of zip codes. To specify a range of zip codes, use an asterisk as a wildcard operator. For example, you can specify zip codes 94040 through 94049 by including the value 9404\* in the zip_areas array.

See Sample Usage:

CheckoutShoppingCartDemo
CheckoutShoppingCartDemoAlternativeMethod

Code:

function AddAllowedAreas($country_area="", $state_areas=array(),
$zip_areas=array()) {
return AddAreas($country_area, $state_areas, $zip_areas, "allowed");
}

AddExcludedAreas

Definition:

The AddExcludedAreas function is a wrapper function that calls the AddAreas function. The AddAreas function, in turn, creates and returns an <excluded-areas> XML DOM.

Parameters:

Parameter Name	Definition
$country_area	This parameter specifies a region of the country where a shipping option is available or unavailable. Valid values for this parameter are CONTINENTAL_48, FULL_50_STATES and ALL.
$state_areas	This parameter specifies an array of one or more states where a shipping option is available or unavailable. Each item in the array should be a two-letter U.S. state abbreviation.
$zip_areas	This parameter specifies an array of one or more zip codes where a shipping option is available or unavailable. Each item in the array should specify either a five-digit U.S. zip code or a range of zip codes. To specify a range of zip codes, use an asterisk as a wildcard operator. For example, you can specify zip codes 94040 through 94049 by including the value 9404\* in the zip_areas array.

See Sample Usage:

CheckoutShoppingCartDemo
CheckoutShoppingCartDemoAlternativeMethod

Code:

function AddExcludedAreas($country_area="", $state_areas=array(),
$zip_areas=array()) {
return AddAreas($country_area, $state_areas, $zip_areas, "excluded");
}

AddAreas

Definition:

The AddAreas function creates a list of regions where shipping options are either available or unavailable. The first parameter to this function indicates whether a particular shipping option is available in the specified geographic regions. The remaining parameters specify the regions where that shipping option is available or unavailable.

Parameters:

Parameter Name	Definition
$country_area	This parameter specifies a region of the country where a shipping option is available or unavailable. Valid values for this parameter are CONTINENTAL_48, FULL_50_STATES and ALL.
$state_areas	This parameter specifies an array of one or more states where a shipping option is available or unavailable. Each item in the array should be a two-letter U.S. state abbreviation.
$zip_areas	This parameter specifies an array of one or more zip codes where a shipping option is available or unavailable. Each item in the array should specify either a five-digit U.S. zip code or a range of zip codes. To specify a range of zip codes, use an asterisk as a wildcard operator. For example, you can specify zip codes 94040 through 94049 by including the value 9404\* in the zip_areas array.
$allow_or_exclude	This parameter indicates whether a shipping option is available or unavailable in the specified regions. Valid values for this parameter are allowed and excluded.

Functions that call AddAreas:

AddAllowedAreas
AddExcludedAreas
error_msg

Code:

function AddAreas($country_area="", $state_areas=array(), $zip_areas=array(),
    $allow_or_exclude) {

    global $dom_areas_obj, $dom_shipping_restrictions_obj;

    // Check for errors
    $error_function_name = "CreateAllowedAreas()";

    // Verify that at least one region has been specified.
    if (($country_area == "") && ($state_areas == "") && ($zip_areas == "")) {
        trigger_error("You must provide at least one area.", E_USER_ERROR);
    }

    // Verify that the $allow_or_exclude parameter contains a valid value.
    $error_type = "INVALID_ALLOW_OR_EXCLUDE_VALUE";
    if (($allow_or_exclude != "allowed") && ($allow_or_exclude != "excluded")) {
        trigger_error("Areas must either be 'allowed' or 'excluded'.",
            E_USER_ERROR);
    }

    // Verify that $state_areas and $zip_areas parameters are arrays.
    $error_type = "INVALID_INPUT_ARRAY";
    if (($state_areas != "") && !is_array($state_areas)) {
        trigger_error(error_msg($error_type, $error_function_name,
            $allow_or_exclude . "_state"), E_USER_ERROR);
    }

    if (($zip_areas != "") && !is_array($zip_areas)) {
        trigger_error(error_msg($error_type, $error_function_name,
            $allow_or_exclude . "_zip"), E_USER_ERROR);
    }

    // Create the <allowed-areas> or <excluded-areas> element
    $dom_areas_obj = domxml_new_doc("1.0");
    $dom_areas = $dom_areas_obj->append_child(
        $dom_areas_obj->create_element($allow_or_exclude . "-areas"));

    // Add the <us-country-area> element if a $country_area is provided
    if ($country_area != "") {
        $dom_us_country_area = CreateUsCountryArea($country_area);
$dom_country_root = $dom_us_country_area->document_element();
$dom_areas->append_child($dom_country_root->clone_node(true));
    }

    // Add a <us-state-area> element for each item in the $state_areas array
    if ($state_areas != "") {
        foreach ($state_areas as $state) {
            $dom_us_state_area = CreateUsStateArea($state);
            $dom_state_root = $dom_us_state_area->document_element();
            $dom_areas->append_child($dom_state_root->clone_node(true));
        }
    }

    // Add a <us-zip-area> element for each item in the $zip_areas array
    if ($zip_areas != "") {
        foreach ($zip_areas as $zip) {
            $dom_us_zip_area = CreateUsZipArea($zip);
            $dom_zip_root = $dom_us_zip_area->document_element();
            $dom_areas->append_child($dom_zip_root->clone_node(true));
        }
    }

    /*
     * Create a <shipping-restrictions> parent element if one has
     * not already been created.
     */
    if ($dom_shipping_restrictions_obj == "") {
        $dom_shipping_restrictions_obj = domxml_new_doc("1.0");

        $dom_shipping_restrictions =
            $dom_shipping_restrictions_obj->append_child(
                $dom_shipping_restrictions_obj->create_element(
                    "shipping-restrictions"));
    }

    $dom_areas_root = $dom_areas_obj->document_element();
    $dom_shipping_restrictions_root =
        $dom_shipping_restrictions_obj->document_element();
    $dom_shipping_restrictions_root->append_child(
        $dom_areas_root->clone_node(true));

    return $dom_shipping_restrictions_obj;
}

CreateFlatRateShipping

Definition:

The CreateFlatRateShipping function is a wrapper function that calls the CreateShipping function. The CreateShipping function, in turn, creates and returns a <flat-rate-shipping> XML DOM.

Parameters:

Parameter Name	Definition
$name	The $name parameter contains a string that can be used to identify a particular shipping option.
$price	The $price parameter specifies the numeric cost of the shipping option.
$dom_shipping_restrictions_obj	The $dom_shipping_restrictions_obj parameter contains well-formed XML that identifies areas where the shipping option is either available or unavailable. This XML can be obtained by calling the AddAreas function.

See Sample Usage:

CheckoutShoppingCartDemo
CheckoutShoppingCartDemoAlternativeMethod

Code:

function CreateFlatRateShipping($name, $price,
    $dom_shipping_restrictions_obj="") {
    return CreateShipping("flat-rate-shipping", $name, $price,
        $dom_shipping_restrictions_obj);
}

CreateMerchantCalculatedShipping

Definition:

The CreateMerchantCalculatedShipping function is a wrapper function that calls the CreateShipping function. The CreateShipping function, in turn, creates and returns a <merchant-calculated-shipping> XML DOM.

Parameters:

Parameter Name	Definition
$name	The $name parameter contains a string that can be used to identify a particular shipping option.
$price	The $price parameter specifies the numeric cost of the shipping option.
$dom_shipping_restrictions_obj	The $dom_shipping_restrictions_obj parameter contains well-formed XML that identifies areas where the shipping option is either available or unavailable. This XML can be obtained by calling the AddAreas function.

See Sample Usage:

CheckoutShoppingCartDemo
CheckoutShoppingCartDemoAlternativeMethod

Code:

function CreateMerchantCalculatedShipping($name, $price,
    $dom_shipping_restrictions_obj="") {
    return CreateShipping("merchant-calculated-shipping", $name, $price,
        $dom_shipping_restrictions_obj);
}

CreatePickup

Definition:

The CreatePickup function is a wrapper function that calls the CreateShipping function. The CreateShipping function, in turn, creates and returns a <pickup> XML DOM.

Parameters:

Parameter Name	Definition
$name	The $name parameter contains a string that can be used to identify a particular shipping option.
$price	The $price parameter specifies the numeric cost of the shipping option.

See Sample Usage:

CheckoutShoppingCartDemo
CheckoutShoppingCartDemoAlternativeMethod

Code:

function CreatePickup($name, $price) {
return CreateShipping("pickup", $name, $price);
}

CreateShipping

Definition:

The CreateShipping function creates and returns <flat-rate-shipping>, <merchant-calculated-shipping> or <pickup> XML DOM objects. Each call to this function identifies the type of shipping option, the cost of the shipping option as well as a name that can be used to identify the shipping option. The function also accepts shipping restrictions for <flat-rate-shipping> and <merchant-calculated-shipping>.

Parameters:

Parameter Name	Definition
$shipping_type	The $shipping_type parameter indicates the type of shipping option for which XML is being created. Valid values for this parameter are flat-rate-shipping, merchant-calculated-shipping and pickup.
$name	The $name parameter contains a string that can be used to identify a particular shipping option.
$price	The $price parameter specifies the numeric cost of the shipping option.
$dom_shipping_restrictions_obj	The $dom_shipping_restrictions_obj parameter contains well-formed XML that identifies areas where the shipping option is either available or unavailable. This XML can be obtained by calling the AddAreas function.

Functions that call CreateShipping:

CreateFlatRateShipping
CreateMerchantCalculatedShipping
CreatePickup

Code:

function CreateShipping($shipping_type, $name, $price,
    $dom_shipping_restrictions_obj="") {

    global $dom_shipping_methods_obj;

    // Verify that there are values for all required parameters
    $error_function_name = "CreateShipping(" . $shipping_type . ")";
    CheckForError($GLOBALS["mp_type"], $error_function_name,
        "name", $name);
    CheckForError($GLOBALS["mp_type"], $error_function_name,
        "price", $price);
    CheckForError($GLOBALS["mp_type"], $error_function_name,
        "GLOBALS[\"currency\"]", $GLOBALS["currency"]);

    /*
     * Create a new parent element using the $shipping_type
     * as the element name
     */
    $dom_shipping_obj = domxml_new_doc("1.0");
    $dom_shipping = $dom_shipping_obj->append_child(
        $dom_shipping_obj->create_element($shipping_type));

    // Set the name and price for the shipping option
    $dom_shipping->set_attribute("name", $name);
    $dom_price = $dom_shipping->append_child(
        $dom_shipping_obj->create_element("price"));
    $dom_price->set_attribute("currency", $GLOBALS["currency"]);
    $dom_price->append_child($dom_shipping_obj->create_text_node($price));

    /*
     * Add shipping-restrictions for <flat-rate-shipping>
     * and <merchant-calculated-shipping>
     */
    if (($shipping_type == "flat-rate-shipping" ||
     $shipping_type == "merchant-calculated-shipping") &&
     $dom_shipping_restrictions_obj != "")
    {
        $dom_shipping_restrictions_root =
            $dom_shipping_restrictions_obj->document_element();
        $dom_shipping->append_child(
            $dom_shipping_restrictions_root->clone_node(true));
    }

    if ($dom_shipping_methods_obj == "") {
        $dom_shipping_methods_obj = domxml_new_doc("1.0");
        $dom_shipping_methods_obj->append_child(
            $dom_shipping_methods_obj->create_element("shipping-methods"));
    }

    // Add the shipping method to the XML request
    $dom_shipping_methods_root = $dom_shipping_methods_obj->document_element();
    $dom_shipping_root = $dom_shipping_obj->document_element();
    $dom_shipping_methods_root->append_child(
        $dom_shipping_root->clone_node(true));

return $dom_shipping_obj;
}

CreateMerchantCalculations

Definition:

The CreateMerchantCalculations function creates and returns a <merchant-calculations> XML block.

Parameters:

Parameter Name	Definition
$merchant_calc_url	The $merchant_calc_url parameter identifies a URL on your site to which Google Checkout should send Merchant Calculations API requests.
$accepts_coupons	The $accepts_coupons function contains a Boolean value that indicates whether Google Checkout should display an option for customers to enter coupon codes for an order.
$accepts_gift_certificates	The $accepts_gift_certificates function contains a Boolean value that indicates whether Google Checkout should display an option for customers to enter gift certificate codes for an order.

See Sample Usage:

CheckoutShoppingCartDemo
CheckoutShoppingCartDemoAlternativeMethod

Code:

function CreateMerchantCalculations($merchant_calc_url, $accepts_coupons="",
    $accept_gift_certificates="") {

    global $dom_merchant_calc_obj;

    // Verify that there is a value for the $merchant_calc_url parameter
    $error_function_name = "CreateMerchantCalculations()";
    CheckForError($GLOBALS["mp_type"], $error_function_name,
        "merchant_calc_url", $merchant_calc_url);

    // Create the <merchant-calculations> element
    if ($dom_merchant_calc_obj == "") {
        $dom_merchant_calc_obj = domxml_new_doc("1.0");

        $dom_merchant_calc = $dom_merchant_calc_obj->append_child(
            $dom_merchant_calc_obj->create_element("merchant-calculations"));
    }

    // Create the <merchant-calculations-url> element
    $dom_merchant_calc_url = $dom_merchant_calc->append_child(
        $dom_merchant_calc_obj->create_element("merchant-calculations-url"));
    $dom_merchant_calc_url->append_child(
        $dom_merchant_calc_obj->create_text_node($merchant_calc_url));

    // Create the <accepts-merchant-coupons> element
    if ($accepts_coupons != "") {

        $dom_accepts_coupons = $dom_merchant_calc->append_child(
            $dom_merchant_calc_obj->create_element("accept-merchant-coupons"));

        $dom_accepts_coupons->append_child(
            $dom_merchant_calc_obj->create_text_node($accepts_coupons));
    }

    // Create the <accepts-gift-certificates> element
    if ($accept_gift_certificates != "") {

        $dom_accept_gift_certificates = $dom_merchant_calc->append_child(
            $dom_merchant_calc_obj->create_element("accept-gift-certificates"));

        $dom_accept_gift_certificates->append_child(
            $dom_merchant_calc_obj->create_text_node(
                $accept_gift_certificates));
    }

return $dom_merchant_calc_obj;
}

CreateMerchantCheckoutFlowSupport

Definition:

The CreateMerchantCheckoutFlowSupport function builds a <merchant-checkout-flow-support> XML block. This XML contains information about taxes, shipping and other custom calculations to be used in the checkout process. The XML also contains URLs used during the checkout process, such as URLs for the customer to edit her shopping cart or to continue shopping.

Parameters:

Parameter Name	Definition
$edit_cart_url	The $edit_cart_url parameter contains a URL that the customer could click to edit her shopping cart.
$continue_shopping_url	The $continue_shopping_url parameter contains a URL that the customer could click to postpone the checkout process and continue shopping.

See Sample Usage:

CheckoutShoppingCartDemo
CheckoutShoppingCartDemoAlternativeMethod

Code:

CreateCheckoutShoppingCart

Definition:

The CreateCheckoutShoppingCart function returns the <checkout-shopping-cart> XML structure, which contains all of the items and checkout-related information for an order.

See Sample Usage:

CheckoutShoppingCartDemo
CheckoutShoppingCartDemoAlternativeMethod

Code: