Sales Tax API Specification

Screen: ShopSite > Commerce Setup > Tax > Tax API Add-on

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:

Cart Update – Tax is calculated on the Shopping Cart Screen each time the shopping cart contents are modified, such as adding a product to the cart or updating product quantities in the cart. This is also done if the customer enters or changes the shipping ZIP or postal code or clicks on a button to recalculate the cart totals. This request may be made several times for a single cart.
Shipping Update – Tax is again calculated when the customer has provided a complete shipping address on the Checkout screen and clicks the button to complete the order. If the tax total changes, or if there is an error, the customer will be returned to the Checkout to confirm the totals before completing the order.
Final Check – Tax is calculated one last time on the Confirmation Screen (if it is being used). For the final check, the order will complete even if the Add-on responds with an error.
Add-on Test – ShopSite will also call the Add-on to test connectivity when the merchant first configures the Add-on. The test call passes a dummy ZIP code, country, and product 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:

Parameter	Description	Allowed Values	Notes
Cart Info The following information is included once per call:
api_tax_type	The call type ShopSite is making. There are four types of calls ShopSite may make: `calculate` – Cart updates. The only address information available is the ZIP/postal code and country. `pre_final` – Shipping update. The complete shipping address is available for use in tax calculation. `final` – Final check. The calculation made when the order is finalized. `test` – Add-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:

Parameter	Description	Allowed Values	Notes
Cart Info The following information is included once per response:
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