Sales Tax API Specification

ShopSite's Sales Tax API allows developers to create add-on applications that can be used to calculate tax rates using information from the shopping cart. In order to use an add-on, the merchant must first configure ShopSite to use the add-on. This document discusses what information is passed between ShopSite and the add-on, and how that information is passed.

How ShopSite Calculates Tax

ShopSite calculates tax several times during the checkout process. Each time this is done, ShopSite will call the Add-on and pass it information about the shopping cart contents.

There are several different times ShopSite will make a call to the Add-on:

Each time the Add-on is called, it will respond with a tax total, which is displayed to the customer in the Shopping Cart. The Add-on should also include other information in the response, which may be used by the shopping cart or a third-party service.

What ShopSite Sends to the Add-on

Each time ShopSite needs to calculate sales tax, it will create an HTTP POST request, and information about the shopping cart will be sent as parameters in the HTTP request. The following information is sent to the add-on for use in calculating sales tax:

Cart Info

The following information is included once per call:

Parameter Description Allowed Values Notes
api_tax_type The call type ShopSite is making. There are four types of calls ShopSite may make:
  • calculateCart updates. The only address information available is the ZIP/postal code and country.
  • pre_finalShipping update. The complete shipping address is available for use in tax calculation.
  • finalFinal check. The calculation made when the order is finalized.
  • testAdd-on Test. A test call with a dummy ZIP, country, and product.
  • calculate
  • pre_final
  • final
  • test
storeid The StoreID of the store calling the Add-on. This can be used with the store URL and serial number to uniquely identify the store. Unrestricted text
storeurl The URL of the store calling the Add-on. This can be used with the StoreID and serial number to uniquely identify the store. Any valid URL
serialnum The serial number of the store calling the Add-on. This can be used with the StoreID and store URL to uniquely identify the store. 10 digit numeral (e.g. 1234567890)
docid A unique cart ID number. This can be used by the Add-on to associate multiple requests for the same Shopping Cart. If the Add-on is tracking the tax collected by the merchant, this can ensure that the tax is only calculated once for each order. Unique Number (e.g. 4321)
locale The store locale. Any valid country/language locale code (e.g. en-US). Set by the merchant on the locale screen.
parmX Additional Parameters 1-10 (where X is the field number). These may be used for any additional information the developer requires. Unrestricted text Configured on the Sales Tax Add-on screen. Developers should provide merchants with expected values.
addr The first line of the customer shipping address. Not available for calculate calls. Unrestricted text Entered by the customer on the Checkout screen.
addr2 Optional. The second line of the customer shipping address. Not available for calculate calls. Unrestricted text Entered by the customer on the Checkout screen.
city The shipping address city. Not available for calculate calls. Unrestricted text Entered by the customer on the Checkout screen.
region The shipping address state or region. The merchant may configure ShopSite to use a pre-populated pull-down to ensure region codes match those expected by the Add-on and other third-party services. Not available for calculate calls. Unrestricted text Entered by the customer on the Checkout screen. The pull-down is configured by the merchant on the States and Countries screen.
postalcode The shipping address ZIP or postal code. This is usually the primary mechanism for determining the tax zone. Unrestricted text Entered by the customer on the Checkout screen.
country The shipping address country. The merchant may configure ShopSite to use a pre-populated pull-down to ensure country names match those expected by the Add-on and other third-party services. Unrestricted text Entered by the customer on the Checkout screen. The pull-down is configured by the merchant on the States and Countries screen.
shipping_amount The shipping rate total, if the merchant selected to calculate tax on shipping fees. Currency value (e.g. 1.95) Configured by the merchant on the Sales Tax screen.
shipping_taxcode The shipping tax code, if the merchant selected to calculate tax on shipping fees. The Add-on developer should inform the merchant what to use for this code. Unrestricted text The merchant configures the tax code to use for shipping on the Sales Tax Add-on screen.
surcharge_amount The order surcharge, if the merchant selected to add a surcharge and calculate tax on it. Currency value (e.g. 1.95) Configured by the merchant on the Sales Tax screen.
surcharge_taxcode The surcharge tax code, if the merchant selected to add a surcharge and calculate tax on it. The Add-on developer should inform the merchant what to use for this code. Unrestricted text The merchant configures the tax code to use for shipping on the Sales Tax Add-on screen.
item_total The total number of unique products in the order. This number tells the Add-on how many products to expect, and how many products to include in the response. Non-zero positive integer
coupon_total The total number of coupons applied to the order. This number tells the Add-on how many coupons to expect. Non-zero positive integer
cXamount The discounted amount in dollars, represented by a negative number. For example, -2.95 would be a total discount of two dollars and ninety-five cents. Negative number
cXname The name of the coupon (as it will appear in the shopping cart). Alphanumeric character string
cXapplied_type The type of coupon being applied, which dictates how the coupon is applied. For example, OneTimeApplied means that the coupon can only be used once, where as FreeShipApplied means that the coupon applies to all items in the cart.
  • Applied
  • OneTimeApplied
  • FreeShipApplied
  • OneTimeFreeShipApplied
cXitem_num The coupon database record number. Non-zero positive integer

Product Info

The following information is included once for each product. The X in the field name represents the item number from 1 through the value of item_total.

Parameter Description Allowed Values Notes
pXitem_num The product ID in the Shopping Cart. Any number
pXname The product name. HTML in the product name is stripped out. Unrestricted text The merchant sets the product name on the Add A Product screen.
pXsku The product SKU Unrestricted text The merchant sets the product SKU on the Add A Product screen.
pXquantity The quantity of the product being ordered. Non-zero positive integer Set by the customer on the Shopping Cart screen.
pXamount The total price for the product (product price multiplied by quantity). Currency value (e.g. 1.95) Calculated in the Shopping Cart.
pXtaxcode The tax code selected for the product. The Add-on developer may specify what tax codes are allowed. Unrestricted text The tax code list is configured by the merchant on the Sales Tax Add-on screen. The Add-on developer should provide a list of tax codes that are allowed.
pXtype The product type.
  • Tangible
  • Download
The product type is set by the merchant on the Add A Product screen.
pXdfieldN The product Extra Fields (where N is the field number from 1 through 25). If necessary, the developer may require the merchant to include required information in one or more extra fields. Unrestricted text The product Extra Fields are configured by the merchant on the Add A Product screen.
pXtaxable The product taxable field is included so that that the API can determine which products need tax calculated.
  • checked
  • unchecked
The product Taxable field is configured by the merchant on the Add A Product or Edit Product screen.

What the Add-on Returns to ShopSite

After being invoked by ShopSite, the Add-on is expected to return the following information to ShopSite:

Cart Info

The following information is included once per response:

Parameter Description Allowed Values Notes
taxapi_status* Indicates whether or not the Add-on was able to calculate tax for the order.
  • success
  • failed
*For ShopSite 10 SP1 merchants, this response field is named status instead of taxapi_status.
message If the tax calculation status returns a failed response, this should define the error message that is displayed to the customer. Unrestricted text
total_tax The total tax for the order. The Add-on should return a value, even if the tax total is zero (0.00). Currency value (e.g. 1.95)
tax_name Optional. The name of the tax line-item in the Shopping Cart totals. Unrestricted text
product_count The total number of products included in the response. This must be the same as the item_total sent in the call. Non-zero positive integer

Product Info

The following information is included once for each product. The X in the field name represents the item number from 1 to the value of product_count.

Parameter Description Allowed Values Notes
pXitem_num The product ID in the Shopping Cart. This must match the product ID passed from the Shopping Cart. Any number
pXtax_rate The tax rate for this product that was used to calculate the tax total. percent multiplier (e.g. 0.067) The tax rate is required for compatibility with some third-party payment services.

ShopSite Help and Resource Center
Last updated: March 01, 2010
Give Feedback


ShopSite Shopping Cart Software