The MerchantCalculationsAPIFunctions.asp library contains a set of functions that are used to create Merchant Calculations API XML responses.
This document includes an explanation of each function in the MerchantCalculationsAPIFunctions.asp 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.asp library.
Please refer to the ResponseHandler.asp implementation to see sample usages of these functions.
createMerchantCalculationResults
createMerchantCodeResults
getMerchantCodeInfo
createMerchantCodeResult
verifyShippable
getShippingRate
getTaxRate
Definition:
The processMerchantCalculationCallback function handles a <merchant-calculation-callback> request and returns a <merchant-calculation-results> XML response. This function calls the createMerchantCalculationResults function, which constructs the <merchant-calculation-results> response. This function then prints the <merchant-calculation-results> response to return the <merchant-calculation-results> information to Google Checkout and logs the response as well.
Parameters:
| Parameter Name | Definition |
|---|---|
| domMcCallbackObj | Required. This parameter contains a DOM object representation of an XML document. |
Functions that call processMerchantCalculationCallback:
Code:
Dim xmlMcResults
' Process <merchant-calculation-callback> and create
' <merchant-calculation-results>
xmlMcResults = createMerchantCalculationResults(domMcCallbackObj)
' Respond with <merchant-calculation-results> XML
Response.write xmlMcResults
' Log <merchant-calculation-results>
logMessage logFilename, xmlMcResults
End Function
Definition:
The createMerchantCalculationResults function creates the XML DOM for a <merchant-calculation-results> XML response. This function receives the <merchant-calculation-callback> from the processMerchantCalculationCallback function.
This function calls the createMerchantCodeResults, getShippingRate and getTaxRate functions to calculate shipping costs, taxes and discounts that should be applied to the order total.
Parameters:
| Parameter Name | Definition |
|---|---|
| domMcCallbackObj | Required. This parameter contains a DOM object representation of an XML document. |
Functions that call createMerchantCalculationResults:
Code:
' Define the objects used to create the <merchant-calculation-callback>
Dim domMcResultsObj
Dim domMcResults
Dim domMerchantCodeResults
Dim domMerchantCodeResultsRoot
Dim domResults
Dim domResult
Dim domResponse
Dim domMcCallbackObjRoot
Dim domTaxList
Dim calcTax
Dim domMethodList
Dim domMethod
Dim attrShippingName
Dim domAnonymousAddressList
Dim domAnonymousAddress
Dim attrAddressId
Dim domMerchantCodeList
Dim totalTax
Dim domTotalTax
Dim domShippingRate
Dim shippingRate
Dim domShippable
Dim shippable
Set domMcResultsObj = Server.CreateObject(strMsxmlDomDocument)
domMcResultsObj.async = False
domMcResultsObj.appendChild( _
domMcResultsObj.createProcessingInstruction("xml", _
strXmlVersionEncoding))
' Create root tag for <merchant-calculation-results> response
' and set xmlns attribute
Set domMcResults = domMcResultsObj.appendChild( _
domMcResultsObj.createElement("merchant-calculation-results"))
domMcResults.setAttribute "xmlns", strXmlns
' Create child element <results>
Set domResults = domMcResults.appendChild( _
domMcResultsObj.createElement("results"))
Set domMcCallbackObjRoot = domMcCallbackObj.documentElement
' Retrieve Boolean value indicating whether merchant calculates
' tax for the order.
' e.g. <tax>true</tax>
' If you do not use custom calculations to calculate tax, you
' may ignore the next two lines of code.
Set domTaxList = domMcCallbackObjRoot.getElementsByTagname("tax")
calcTax = domTaxList(0).text
' Retrieve the names of the shipping methods available for the order
' These shipping methods will have been communicated to Google Checkout
' in a CheckoutAPIRequest. Note: The <merchant-calculated-callback>
' will only contain <merchant-calculated-shipping> options from
' the Checkout API request.
Set domMethodList = _
domMcCallbackObjRoot.getElementsByTagname("method")
' Retrieve shipping addresses from the <merchant-calculated-callback>
' response. These shipping addresses are anonymous, meaning they
' only include the city, region (state), postal code and country
' code for the address
Set domAnonymousAddressList = _
domMcCallbackObjRoot.getElementsByTagname( _
"anonymous-address")
' Retrieve a list of coupon and gift certificate codes that
' should be applied to the order total. Note: The
' <merchant-calculated-callback> can only contain these codes if
' the <accept-merchant-coupons> or <accept-gift-certificates> tag
' in the corresponding Checkout API request has a value of "true".
Set domMerchantCodeList = _
domMcCallbackObjRoot.getElementsByTagname( _
"merchant-code-string")
' Loop through address IDs to build <result> elements
For Each domAnonymousAddress In domAnonymousAddressList
' Retrieve the address ID
attrAddressId = domAnonymousAddress.getAttribute("id")
If domMethodList.length > 0 Then
' Loop for each merchant-calulated shipping method
For Each domMethod In domMethodList
' Retrieve the name of the shipping method
attrShippingName = domMethod.getAttribute("name")
' Create a <result> element in the response with
' shipping-name and address-id attributes
Set domResult = _
domResults.appendChild( _
domMcResultsObj.createElement("result"))
domResult.setAttribute "shipping-name", attrShippingName
domResult.setAttribute "address-id", attrAddressId
' If the <tax> tag in the <merchant-calculation-callback>
' has a value of "true", call the getTaxRate function
' to calculate taxes for the order.
If calcTax = "true" Then
Set domTotalTax = _
domResult.appendChild( _
domMcResultsObj.createElement("total-tax"))
domTotalTax.setAttribute "currency", attrCurrency
totalTax = getTaxRate(domMcCallbackObj, _
attrAddressId, attrShippingName)
domTotalTax.appendChild( _
domMcResultsObj.createTextNode(totalTax))
End If
' If there are coupon or gift certificate codes, call
' the createMerchantCodeResults function to verify those
' codes and to create <coupon-result> or
' <gift-certificate-result> elements to be included in
' the <merchant-calculation-response>.
If domMerchantCodeList.length > 0 Then
Set domMerchantCodeResults = _
createMerchantCodeResults(domMcCallbackObj, _
domMerchantCodeList, attrAddressId)
Set domMerchantCodeResultsRoot = _
domMerchantCodeResults.documentElement
domResult.appendChild( _
domMerchantCodeResultsRoot.cloneNode(true))
End If
' Call the getShippingRate function to calculate the
' shipping cost for the shipping method-address ID
' combination.
Set domShippingRate = _
domResult.appendChild( _
domMcResultsObj.createElement("shipping-rate"))
domShippingRate.setAttribute "currency", attrCurrency
shippingRate = getShippingRate(domMcCallbackObj, _
attrAddressId, attrShippingName)
domShippingRate.appendChild( _
domMcResultsObj.createTextNode(shippingRate))
' Verify that the order can be shipped to the address
shippable = verifyShippable(domMcCallbackObj, _
attrAddressId, attrShippingName)
Set domShippable = _
domResult.appendChild( _
domMcResultsObj.createElement("shippable"))
domShippable.text = shippable
Next
' This block executes if no shipping methods are specified
Else
' Create a <result> element in the response with
' shipping-name and address-id attributes
Set domResult = domResults.appendChild( _
domMcResultsObj.createElement("result"))
domResult.setAttribute "address-id", attrAddressId
' If the <tax> tag in the <merchant-calculation-callback>
' has a value of "true", call the getTaxRate function
' to calculate taxes for the order.
If calcTax = "true" Then
Set domTotalTax = _
domResult.appendChild( _
domMcResultsObj.createElement("total-tax"))
domTotalTax.setAttribute "currency", attrCurrency
totalTax = getTaxRate(domMcCallbackObj, _
attrAddressId, attrShippingName)
domTotalTax.appendChild( _
domMcResultsObj.createTextNode(totalTax))
End If
' If there are coupon or gift certificate codes, call
' the createMerchantCodeResults function to verify those
' codes and to create <coupon-result> or
' <gift-certificate-result> elements to be included in
' the <merchant-calculation-response>.
If domMerchantCodeList.length > 0 Then
Set domMerchantCodeResults = _
createMerchantCodeResults(domMcCallbackObj, _
domMerchantCodeList, attrAddressId)
Set domMerchantCodeResultsRoot = _
domMerchantCodeResults.documentElement
domResult.appendChild( _
domMerchantCodeResultsRoot.cloneNode(true))
End If
End If
Next
' Return <merchant-calculation-results> XMLDOM
createMerchantCalculationResults = domMcResults.xml
Set domMcResultsObj = Nothing
Set domMcResults = Nothing
Set domMerchantCodeResults = Nothing
Set domMerchantCodeResultsRoot = Nothing
Set domResults = Nothing
Set domResult = Nothing
Set domResponse = Nothing
Set domMcCallbackObjRoot = Nothing
Set domTotalTax = Nothing
Set domShippingRate = Nothing
Set domShippable = Nothing
Set domTaxList = Nothing
Set domMethodList = Nothing
Set domMethod = Nothing
Set domAnonymousAddressList = Nothing
Set domAnonymousAddress = Nothing
Set domMerchantCodeList = Nothing
End Function
Definition:
The createMerchantCodeResults function creates the <merchant-code-results> tag, which encapsulates the calculated amounts for a list of coupon or gift certificate codes. It then calls the getMerchantCodeInfo function, which you will need to modify, to retrieve information about each coupon or gift certificate code.
Parameters:
| Parameter Name | Definition |
|---|---|
| domMcCallbackObj | Required. This parameter contains a DOM object representation of an XML document. |
| domMerchantCodeList | Required. This parameter contains the list of coupon and gift certificate codes that a customer wants to apply to an order. |
| addressId | Required. This parameter contains the value of the id parameter for an address in a <merchant-calculation-callback>. |
Functions that call createMerchantCodeResults:
Code:
domMerchantCodeList, addressId)
' Define the objects used to create the <coupon-result> or
' <gift-certificate-result>
Dim code
Dim domMcResultsObj
Dim merchantCode
Dim codeType
Dim calculatedAmount
Dim message
Dim domMerchantCodeResults
Dim domMerchantCodeResultObj
Dim domMerchantCodeResultRoot
' Create an empty XMLDOM
Set domMcResultsObj = Server.CreateObject(strMsxmlDomDocument)
domMcResultsObj.async = False
Set domMerchantCodeResults = _
domMcResultsObj.appendChild( _
domMcResultsObj.createElement("merchant-code-results"))
For Each merchantCode In domMerchantCodeList
code = merchantCode.getAttribute("code")
Set domMerchantCodeResultObj = _
getMerchantCodeInfo(domMcCallbackObj, code, addressId)
Set domMerchantCodeResultRoot = _
domMerchantCodeResultObj.documentElement
domMerchantCodeResults.appendChild( _
domMerchantCodeResultRoot.cloneNode(true))
Next
Set createMerchantCodeResults = domMcResultsObj
' Release the objects used to create the <coupon-result> or
' <gift-certificate-result>
Set domMcResultsObj = Nothing
Set domMerchantCodeResultObj = Nothing
Set domMerchantCodeResultRoot = Nothing
End Function
Definition:
The getMerchantCodeInfo function retrieves information about a coupon or gift certificate code provided by the customer. You will need to modify this function to retrieve information about the code. The changes you will need to make are discussed in the comments in the function. After retrieving this information, this function calls and returns the value of the createMerchantCodeResult function.
Parameters:
| Parameter Name | Definition |
|---|---|
| domMcCallbackObj | Required. This parameter contains a DOM object representation of an XML document. |
Functions that call getMerchantCodeInfo:
Code:
' Define objects that contain information about the merchant code
Dim elemCodeType
Dim elemCodeValid
Dim elemCalculatedAmount
Dim elemMessage
' +++ CHANGE ME +++
' You need to modify this function to retrieve information about
' a coupon or gift certificate code provided by the customer. This
' function needs to retrieve the following information about the code:
' 1. The code's type. The code type may be either "coupon" or
' "gift-certificate".
' 2. A flag that indicates whether the code is valid. The value
' of this flag must be either "true" or "false".
' 3. The calculated amount of the code. If the code is valid,
' you need to quantify the amount of the code discount.
' This data is optional.
' 4. A message that should be displayed with the code. This
' data is optional.
' This function returns the result from the createMerchantCodeResult
' function, which is a <coupon-result> or a <gift-certificate-result>,
' to the createMerchantCodeResults function, which adds the XML
' block to the response.
elemCodeType = "coupon"
elemCodeValid = "true"
elemCalculatedAmount = "10.00"
elemMessage = "You saved $" & elemCalculatedAmount
Set getMerchantCodeInfo = _
createMerchantCodeResult(elemCodeType, elemCodeValid, elemCode, _
elemCalculatedAmount, elemMessage)
End Function
Definition:
The createMerchantCodeResult function creates the XML DOM for a <coupon-result> or a <gift-certificate-result> for a Merchant Calculations API response.
Parameters:
| Parameter Name | Definition |
|---|---|
| elemCodeType | Required. This parameter indicates whether a <merchant-code-string> in a Merchant Calculations API request contains a coupon code or a gift certificate code. Valid values are coupon and gift-certificate. |
| elemCodeValid | Required. This parameter indicates whether a coupon or gift certificate code is valid. This parameter should have a Boolean (true/false) value. |
| elemCode | Required. This parameter contains a coupon or gift certificate code. |
| elemCalculatedAmount | Optional. This parameter contains the amount that should be deducted from an order total for a particular coupon or gift certificate code. |
| elemMessage | Required. This parameter contains the message to be logged. |
Functions that call createMerchantCodeResult:
Code:
elemCalculatedAmount, elemMessage)
' Define objects used to create the <coupon-result> or
' <gift-certificate-result>
Dim domCodeResultObj
Dim domMerchantCodeResult
Dim domValid
Dim domCode
Dim domMessage
Dim domCalculatedAmount
' create an empty XMLDOM
Set domCodeResultObj = Server.CreateObject(strMsxmlDomDocument)
domCodeResultObj.async = False
' Create root tag for <coupon-result> or <gift-certificate-result>
Set domMerchantCodeResult = _
domCodeResultObj.appendChild( _
domCodeResultObj.createElement(elemCodeType & "-result"))
' Create <valid> tag, which will indicate whether the code is valid
Set domValid = _
domMerchantCodeResult.appendChild( _
domCodeResultObj.createElement("valid"))
domValid.text = elemCodeValid
' Add the coupon or gift certificate code in a <code> tag
Set domCode = _
domMerchantCodeResult.appendChild( _
domCodeResultObj.createElement("code"))
domCode.text = elemCode
' Add the <calculated-amount> tag if there is a value for the
' elemCalculatedAmount parameter. You could omit this tag if the
' code is invalid.
If elemCalculatedAmount <> "" Then
Set domCalculatedAmount = domMerchantCodeResult.appendChild( _
domCodeResultObj.createElement("calculated-amount"))
domCalculatedAmount.setAttribute "currency", attrCurrency
domCalculatedAmount.text = elemCalculatedAmount
End If
' Add a <message> tag if the elemMessage parameter has a value
If elemMessage <> "" Then
Set domMessage = _
domMerchantCodeResult.appendChild( _
domCodeResultObj.createElement("message"))
domMessage.text = elemMessage
End If
Set createMerchantCodeResult = domCodeResultObj
' Release objects used to create the <coupon-result> or
' <gift-certificate-result>
Set domCodeResultObj = Nothing
Set domMerchantCodeResult = Nothing
Set domValid = Nothing
Set domCode = Nothing
Set domCalculatedAmount = Nothing
Set domMessage = Nothing
End Function
Definition:
The verifyShippable function determines whether an order can be shipped to the specified address using the specified shipping method. You will need to modify this function to return a Boolean value indicating whether the order is shippable using the given shipping method.
Parameters:
| Parameter Name | Definition |
|---|---|
| domMcCallbackObj | Required. This parameter contains a DOM object representation of an XML document. |
| addressId | Required. This parameter contains the value of the id parameter for an address in a <merchant-calculation-callback>. |
| shippingMethod | Required. This parameter identifies the name of the shipping method for which you must calculate shipping costs. |
Functions that call verifyShippable:
Code:
' +++ CHANGE ME +++
' You need to modify this function to return a Boolean (true/false)
' value that indicates whether the order can be shipped to the
' specified address (addressId) using the specified shipping
' method (shippingMethod).
verifyShippable = "true"
End Function
Definition:
The getShippingRate function determines the cost of shipping the order to the specified address using the specified shipping method. You will need to modify this function to calculate and return this cost.
Parameters:
| Parameter Name | Definition |
|---|---|
| domMcCallbackObj | Required. This parameter contains a DOM object representation of an XML document. |
| addressId | Required. This parameter contains the value of the id parameter for an address in a <merchant-calculation-callback>. |
| shippingMethod | Required. This parameter identifies the name of the shipping method for which you must calculate shipping costs. |
Functions that call getShippingRate:
Code:
' +++ CHANGE ME +++
' You need to modify this function to return the cost of
' shipping an order to the specified address using the specified
' shipping method.
getShippingRate = "8.76"
End Function
Definition:
The getTaxRate function returns the total tax that should be applied to the order if it is shipped to the specified address. You will need to modify this function to return the calculated tax amount.
Parameters:
| Parameter Name | Definition |
|---|---|
| domMcCallbackObj | Required. This parameter contains a DOM object representation of an XML document. |
| addressId | Required. This parameter contains the value of the id parameter for an address in a <merchant-calculation-callback>. |
| shippingMethod | Required. This parameter identifies the name of the shipping method for which you must calculate shipping costs. |
Functions that call getTaxRate:
Code:
' +++ CHANGE ME +++
' You need to modify this function to return the total tax for
' an order based on the specified address.
getTaxRate = "17.55"
End Function
