CCH® SureTax® for SalesForce Commerce Cloud User Guide

Updated: August 13, 2024

Summary

The CCH SureTax Salesforce Commerce Cloud cartridge provides a quick integration for comprehensive, accurate real-time tax calculations. The cartridge can be configured in the Business Manager.

This guide is for SGJC (SiteGenesis) and Storefront Reference Architecture (SFRA). If installing for SFRA, skip the ‘Custom Code for SiteGenesis’ section in this document and follow directions in the ‘CCH SureTax SFRA Integration Guide’ documentation

Component Overview

Functional Overview

Wolters Kluwer helps you to accurately bill and collect transaction taxes with CCH SureTax. CCH SureTax combines industry leading tax rates and taxability content with precise jurisdiction information, supporting the most complex sourcing and tax calculation rules found in sales and use tax.

During checkout, shopping cart and customer information is sent via the CCH SureTax API web service. Tax information is sent back by the CCH SureTax API and applied to line items in the cart.

The CCH SureTax portal can be accessed for transaction details.

Use Cases

The CCH SureTax cartridge can be used to calculate taxes on the Salesforce Commerce Cloud storefront by using the CCH SureTax API. It includes support for the following use cases:

SiteGenesis/SFRA:

  • Tax calculation for single and multiple line item orders.
  • Tax calculation for multiple shipping addresses.
  • Tax calculation for in store pickup items.
  • Tax exemptions.
  • Multiple site support, including the ability to process taxes for each individual store separately.
  • Cancel tax transactions.
  • Post order finalizations.

Important:

  • This cartridge is limited to the following CCH SureTax API Usage:
    • PostRequest : Used for general sales tax calculation
    • CancelPostRequest : Used to cancel tax transactions
  • Tax calculations are based on the shipping address.
    • If the shipping address (specifically the postal code) is changed then the taxes will be recalculated.
    • After the shipping address is provided, if any items in the basket are updated or the shipping address is changed then the taxes will be recalculated.
  • Taxes are calculated and recorded in CCH SureTax then sent back to be stored directly on the basket and eventually on the order in Salesforce Commerce Cloud.
    • Data stored includes both the tax amount and tax rates per line item.
  • All orders will use the original creation date to calculate the amount of tax to record. This also applies to all post order transactions.
  • Transactions can be identified in CCH SureTax using the Client Tracking field, which uses the order number from Salesforce Commerce.

Note: The CCH SureTax request element InvoiceNumber for finalize transactions will be the order number while transactions that are quote will be indicated by "Q[order number]", no value will be set if no order number is available.

  • If the CCH SureTax cartridge is not enabled within the site, then the native Salesforce Commerce Cloud tax calculation will be used.
  • If the CCH SureTax cartridge cannot connect to CCH SureTax during a customer session, the customer experience will continue without taxes. No error messages will be displayed. Errors will be captured in the custom.Suretax logs.

Compatibility

This cartridge has been tested and is compatible with:

  • Salesforce Commerce Cloud Release 20.9.
  • SFCC SFRA 5.0.1
  • Locale EN

Privacy and Payment

No payment information is accessed when sending information to CCH SureTax. Customer addresses are the only customer data sent to CCH SureTax for tax calculations.

Setup and Implementation Guide

Setup

  1. Import the "int_suretax" cartridge into the Salesforce Commerce Cloud Studio Workspace.
    1. Open Salesforce Commerce Cloud Studio.
    2. Click File > Import > General > Existing Projects Into Workspace.
    3. Browse to the directory where you saved the "int_suretax" cartridge.
    4. Click Finish.
    5. Click OK when prompted to link the cartridge to the sandbox and upload.
  2. Import metadata, services, and jobs using Site import (SureTaxSiteImport.zip).
    1. Log in to the Salesforce Commerce Cloud Business Manager.
    2. Select Administration > Site Development > Site Import & Export.
    3. In the Import section, set Upload Archive = ‘Local’
    4. Click Choose File and select the zip file metadata/SureTaxSiteImport.zip.
    5. Click Upload and confirm that the file was uploaded.
    6. Select uploaded file and click Import.
    7. Notes for files in Site Import zip:
      1. jobs.xml - imports the job (can omit if CCH SureTax job is already setup on your instance).
      2. services.xml - imports the services (can omit if services are already setup on your instance).
      3. system-objecttype-extensions.xml - imports meta data including custom preferences and attributes.

Configuration

  1. Add “int_suretax” to the effective cartridge path:
    1. Log in to the Salesforce Commerce Cloud Business Manager.
    2. Select Administration > Sites > Manage Sites.
    3. Select the desired site.
    4. Select the Settings tab.
    5. Add int_suretax: to the beginning of the Cartridges field (can be on right as well if only installing SFRA, please note to separate cartridges with ':').

  1. Click Apply.
  2. Update suretax.http.PostRequest service with the correct credentials.
    1. Log in to the Salesforce Commerce Cloud Business Manager.
    2. Select Administration > Operations > Services.
    3. Click CCH SureTax API PostRequest.

  1. Remove the dummy values and update the Credentials. The URL should point to either the development or production tax API Endpoint provided by CCH SureTax. The user name is the Client Number provided by CCH SureTax, and the password is the Validation Key provided by CCH SureTax.
    1. API Endpoint Production: https://api.taxrating.net/Services/V07/SureTax.asmx/PostRequest
    2. API Endpoint Testing: https://testapi.taxrating.net/Services/V07/SureTax.asmx/PostRequest
  2. Click Apply when finished.
  3. Update suretax.http.CancelPostRequest service with the correct credentials:
    1. Log in to the Salesforce Commerce Cloud Business Manager.
    2. Select Administration > Operations > Services.
    3. Click CCH SureTax API CancelPostRequest.
    4. Remove the dummy values and update the Credentials. The URL should point to either the development or production tax API Endpoint for Cancellations provided by CCH SureTax. The user name is the Client Number provided by CCH SureTax. Password is the Validation Key provided by CCH SureTax.
      1. API Endpoint Production: https://api.taxrating.net/Services/V07/SureTax.asmx/CancelPostRequest
      2. API Endpoint Testing: https://testapi.taxrating.net/Services/V07/SureTax.asmx/CancelPostRequest
    5. Click Apply when finished.
  4. Configure CCH SureTax Configurations using the Salesforce Commerce Cloud Business Manager.
    1. Log in to the Salesforce Commerce Cloud Business Manager.
    2. Select the desired site from the tabs across the top of the page.
    3. Click Site Merchant Tools > Preferences > Custom Preferences.
    4. Click CCH SureTax Configurations.

  1. Update the configurations as directed by CCH SureTax.
  2. Configure CCH SureTax Job using the Salesforce Commerce Cloud Business Manager.
    1. Log in to the Salesforce Commerce Cloud Business Manager.
    2. Select Administration > Operations > Jobs.
    3. Select the CCHSureTax job.

  1. On the General tab, specify the priority. Normal and High are the options, with Normal being the default.
  2. On the Schedule and History tab, adjust the setting to match the desired schedule. The default setting is to run once per day at 3:00 AM.
  3. On the Resources tab, click Assign. Assign the following to the job:
    1. Resource Type: System Resource
    2. Value: order
  4. On the Step Configurator tab, select the desired scope. Every site on which CCH SureTax is enabled should be selected within the scope of this job.
  5. On the Notification tab, specify the desired settings for notification.

Custom Code for SiteGenesis

Please view the README for copy/paste friendly custom code snippets.

Note: It is the expectation that these custom code snippets will modify the references of actual storefront cartridges. CCH SureTax (int_suretax) was developed assuming storefront cartridge naming conventions are as followed:

  • app_storefront_core
  • app_storefront_controller
  1. Locate the file CartModel.js located in:

{{siteRoot}}/app_storefront_controllers/cartridge/scripts/models

  1. Replace the entire calculate function with the snippet below. Code update will use CCH SureTax to calculate taxes if enabled; otherwise it will default to native behavior.

**Start Code**

// CCH SURETAX UPDATE - REPLACE original calculate: function 

calculate: function (finalizeTaxRequest, order) {

var finalizeTaxRequest = finalizeTaxRequest ? finalizeTaxRequest: false,

      calculateArgs,

      basket = this.object;

   var customerNumber ="";

	   if ( basket && basket.customer && basket.customer.profile ) {

	      customerNumber = basket.customer.profile.customerNo;

	   }

	   if(order) {		

	      if (order.customer && order.customer.profile) {

	         customerNumber = order.customer.profile.customerNo;

      }

	      calculateArgs = {

	         Basket: basket,

         Order: order,

	         FinalizeTaxRequest: finalizeTaxRequest,

	         InvoiceNo: order.getOrderNo(),

	         CustomerNo: customerNumber,

	         customer: order.getCustomer()

	      };

	   } else {

      calculateArgs = {

         Basket: basket,

         FinalizeTaxRequest: false,

         CustomerNo: customerNumber

      };

   }

dw.system.HookMgr.callHook('dw.ocapi.shop.basket.calculate', 'calculate', calculateArgs);

   },

**End Code**

  1. Access the file calculate.js located in:

{{siteRoot}}/app_storefront_core/cartridge/scripts/cart/calculate.js

Note: A sample calculate.js with the proceeding updates can be found in: ** int_suretax/cartridge/scripts/cart/calculate.js

  1. On or around line 18 of calculate.js (below the line starting with 'var Status...'), include a line to require sureTax.js (see bolded line below) for tax calculation via CCH SureTax.

**Start Code**

var TaxMgr = require('dw/order/TaxMgr');

var Logger = require('dw/system/Logger');

var Status = require('dw/system/Status');

var SureTax = require("int_suretax/cartridge/scripts/suretax/sureTax");

**End Code**

  1. On or around line 28 of calculate.js, replace the line **exports.calculate = function (...** with the following lines:

**Start Code**

exports.calculate = function (args){

   var basket = args.Basket;

   var order = args.Order ? args.Order : null;

   var finalizeTaxRequest = args.FinalizeTaxRequest ? args.FinalizeTaxRequest: null;

   var customerNo = (args.CustomerNo && args.CustomerNo.length > 0) ? args.CustomerNo : null;

   var invoiceNo = (args.InvoiceNo && args.InvoiceNo.length > 0) ? args.CustomerNo : null;

**End Code**

  1. On or around line 80 of calculate.js, replace calculateTax(basket); with the following lines:

**Start Code**

   if(dw.system.Site.getCurrent().getCustomPreferenceValue('STEnable')){

      SureTax.calculateTax(basket, finalizeTaxRequest, customerNo, invoiceNo, order);

   } else {

      calculateTax(basket); }

**End Code**

  1. Update the "start" method of the COPlaceOrder.js controller with a call to CCH SureTax to finalize (if configured) the tax transaction if the order is successful. On or around line 178, copy the entire snippet below from line starting with '//CCH SURETAX UPDATES..' upto and including the line starting with '// END OF CCH ' and paste it in

    {{siteRoot}}/app_storefront_controllers/cartridge/controllers/COPlaceOrder.js above the function call to "clearForms".

**Start Code**

   var orderPlacementStatus = Order.submit(order);

   if (!orderPlacementStatus.error) {

      // CCH SURETAX UPDATES: Calls CCH SureTax calculation again to

      // associate transaction with order and possibly finalize the request

      var ConfigUtils = new ( require("int\_suretax/cartridge/scripts/suretax/util/configUtils") );

      if(ConfigUtils.settings.isEnabled) {

         Transaction.wrap(function () {

            cart.calculate(ConfigUtils.settings.Finalize, order);

         });

     } // END OF CCH SURETAX UPDATES
	 
     clearForms();

   }

   return orderPlacementStatus;

**End Code**

  1. Upload the updates.

External Interfaces

All requests are completed through the CCH SureTax API via REST. For the full reference guide, contact your CCH SureTax representative.

Testing

Go to the Storefront, add items to your cart, and complete a purchase. Verify the tax amount is calculated correctly during checkout and by viewing the order via the Business Manager.

Operations and Maintenance

Data Storage

All relevant CCH SureTax data in Salesforce Commerce Cloud is stored within attribute definitions of the following system objects:

  • Basket
  • Customer Group
  • Order
  • Profile
  • Site Preferences

See the Business Manager section for more information.

Log in to the CCH SureTax portal to access tax data stored within the CCH SureTax platform.

Availability

The functionality of this cartridge depends on the availability of CCH SureTax API service.

Support

Contact CCH SureTax support through the Contact Us link on http://www.salestax.com/.

User Guide

Business Manager

CCH SureTax Site Preferences

The following is an outline of all of the configuration options available in Merchant Tools > Preferences > Custom Preferences > CCH SureTax Configurations:

  • CCH SureTax Tax Integration Enabled? Activate the extension for the entire site by selecting Yes.
  • Global Business Unit. The business unit that will be sent to CCH SureTax for all transactions. The maximum length of business unit is 20 characters. Reporting within CCH SureTax allows filtering by business unit.
  • Provider Type. The type of business that will be sent to CCH SureTax for all transactions.
  • Finalize Tax Transaction on order placement? Finalize the Tax Transaction on successful order placement by selecting Yes. A Selection of No would require the finalization to occur within CCH.
  • Tax Calculation Option. Option to choose whether to send the product ID (SKU), the transaction type code, or tax class as the tax transaction item identifier for proper tax calculation. If Transaction Type Code is selected, then the configured Transaction type code from the site preferences will be used for tax calculation.
    • Type Code (TransTypeCode). If Transaction Type Code is selected, then the configured Transaction type code from the site preferences will be used for tax calculation. For this selection, the Shipping Transaction Type Code will be used for all shipping line items.
    • Product ID / SKU (ID). If Product ID / SKU selected, then the product ID will be used for tax calculation. For this selection, the Shipping Transaction Type Code will be used for all shipping line items. Product ID/SKUs must be mapped in CCH SureTax platform.
    • Tax Class (taxClassID). If Tax Class is selected, then configured tax class for each product and shipping method will be sent to CCH SureTax for tax calculation. Tax classes must be mapped in CCH SureTax platform.
  • Transaction Type Code. The code use to identify tax transactions within the CCH SureTax system
  • Shipping Transaction Type Code. The code use to identify tax transactions for shipping charges within the CCH SureTax system.
  • Sales Type Code. The type of customer that is shopping on the site. This is the global configuration for this value, and can be overridden by the customer and customer group if values for this attribute exists on those levels.
    • Residential customer (R)
    • Business customer (B)
    • Industrial customer (I)
    • Lifeline customer (L)
  • Exemption Code. Specify whether the customers of this site are tax-exempt. This is the global configuration for this value, and can be overridden by the customer and customer group if it values for this attribute exists on those levels.
    • No Exemptions (00)
    • Federal Excise Tax Exempt (01)
    • State Taxes Exempt (02)
    • Federal Excise Tax and State Taxes Exempt (03)
    • Local Taxes Exempt
    • Federal Excise Tax and Local Taxes Exempt
    • State and Local Taxes Exempt
    • All Taxes Exempt – Apply no tax or fees (99)
  • Tax Exempt Reason Code. Specify the reason that the customers of this site qualify as tax exempt. This is the global configuration for this value, and can be overridden by the customer and customer group if it values for this attribute exists on those levels.
    • Federal government (01)
    • State or local government (02)
    • Tribal government (03)
    • Foreign diplomat (04)
    • Charitable organization (05)
    • Religious or educational organization (06)
    • Resale (07)
    • Agricultural production (08)
    • Industrial production/manufacturing (09)
    • Direct pay permit (10)
    • Direct mail (11)
    • Other (12)
  • CCH SureTax ShipFrom Street Address. Specify up to two lines of the street address for the ship from address.
  • CCH SureTax ShipFrom Street Address 2. Specify up to two lines of the street address for the ship from address.
  • CCH SureTax ShipFrom City. Specify the city for the ship from address.
  • CCH SureTax ShipFrom Country Code. Specify the country for the ship from address.
  • CCH SureTax ShipFrom StateCode. Specify the state or province for the ship from address.
  • CCH SureTax ShipFrom ZipCode. Specify the zip code for the ship from address.

Configuring Customer Group Information

There are settings for the CCH SureTax extension that are customer specific. These settings can be specified for a group of customers or for individual customers. By default, an individual customer is configured the same as the group to which the customer belongs. In this case, the settings of the customer group will be sent to CCH SureTax.

Note: In Salesforce Commerce Cloud customers can belong to multiple customer groups. In the case where a customer belongs to multiple customer groups, the settings of the first customer group to differ from the global configurations will be sent to CCH SureTax.

To configure customer group information, do the following:

  1. Log in to the Salesforce Commerce Cloud Business Manager.
  2. Select Merchant Tools > Customers > Customer Groups.
  3. Select the customer group to configure.

4.

Select

the

CCH

SureTax

tab.

5.	Modify configurations as needed:
  • Sales Type Code. The type of customer that is shopping on the site. This is the global configuration for this value, and can be overridden by the customer and customer group if it values for this attribute exists on those levels.
    • Residential customer (R)
    • Business customer (B)
    • Industrial customer (I)
    • Lifeline customer (L)
  • Exemption Code. Specify whether the customers of this site are tax-exempt. This is the global configuration for this value, and can be overridden by the customer and customer group if it values for this attribute exists on those levels.
    • No Exemptions (00)
    • Federal Excise Tax Exempt (01)
    • State Taxes Exempt (02)
    • Federal Excise Tax and State Taxes Exempt (03)
    • Local Taxes Exempt
    • Federal Excise Tax and Local Taxes Exempt
    • State and Local Taxes Exempt
    • All Taxes Exempt – Apply no tax or fees (99)
  • Tax Exempt Reason Code. Specify the reason that the customers of this site qualify as tax exempt. This is the global configuration for this value, and can be overridden by the customer and customer group if it values for this attribute exists on those levels.
    • Federal government (01)
    • State or local government (02)
    • Tribal government (03)
    • Foreign diplomat (04)
    • Charitable organization (05)
    • Religious or educational organization (06)
    • Resale (07)
    • Agricultural production (08)
    • Industrial production/manufacturing (09)
    • Direct pay permit (10)
    • Direct mail (11)
    • Other (12)

Configuring Customer Information

Individual customers can be configured differently than the group to which the customer belongs. In this case, the settings of the customer will be sent to CCH SureTax.

To configure CCH SureTax for customers, do the following:

  1. Log in to the Salesforce Commerce Cloud Business Manager.

  2. Select Merchant Tools > Customers > Customers.

  3. Select the customer to configure.

  4. On the General tab, scroll to the CCH SureTax section.

  5. Modify configurations as needed:

  • Sales Type Code. The type of customer that is shopping on the site. This is the global configuration for this value, and can be overridden by the customer and customer group if it values for this attribute exists on those levels.
    • Residential customer (R)
    • Business customer (B)
    • Industrial customer (I)
    • Lifeline customer (L)
  • Exemption Code. Specify whether the customers of this site are tax-exempt. This is the global configuration for this value, and can be overridden by the customer and customer group if it values for this attribute exists on those levels.
    • No Exemptions (00)
    • Federal Excise Tax Exempt (01)
    • State Taxes Exempt (02)
    • Federal Excise Tax and State Taxes Exempt (03)
    • Local Taxes Exempt
    • Federal Excise Tax and Local Taxes Exempt
    • State and Local Taxes Exempt
    • All Taxes Exempt – Apply no tax or fees (99)
  • Tax Exempt Reason Code. Specify the reason that the customers of this site qualify as tax exempt. This is the global configuration for this value, and can be overridden by the customer and customer group if it values for this attribute exists on those levels.
    • Federal government (01)
    • State or local government (02)
    • Tribal government (03)
    • Foreign diplomat (04)
    • Charitable organization (05)
    • Religious or educational organization (06)
    • Resale (07)
    • Agricultural production (08)
    • Industrial production/manufacturing (09)
    • Direct pay permit (10)
    • Direct mail (11)
    • Other (12)

Exploring Order Data

When an order is placed, a quote or a finalization (depending on configuration) request is sent to CCH SureTax to calculate taxes on the order. The transaction can be identified in CCH SureTax by the client tracking field which will match the order number. The details of the tax calculation are stored on the order and can be access within the Salesforce Commerce Cloud Business Manager.

This access the tax related data stored within the order:

  1. Select Merchant Tools > Ordering > Orders.
  2. Select the desired order to view.
  3. The following are available on the General tab:
  • Tax Rate. This value is the Effective Tax Rate returned from CCH SureTax and is provided and stored per line item.
  • Total Tax. This value is the sum of the total tax applied to each line item, including the shipping line items.

  1. The following are available by navigating to the Attributes Tab and viewing the CCH SureTax section:
  • CCH SureTax Order Status. CCH SureTax transaction status for the current order.
    • QUOTE. This status indicates a successful tax transaction created via order placement. Although successful, this transaction is not yet finalized and therefore no detailed tax information is saved in the CCH SureTax tables for reporting.
    • FINALIZED. This status indicates a successful tax transaction created via order placement. This a completed transaction with accompanying line item tax information saved in CCH SureTax tables.
    • UPDATED-CANCELLED. This status indicates a canceled tax transaction executed via a scheduled job post order placement. This is a change in the original tax status initially applied when order was placed.
    • UPDATED-FINALIZED. This status indicates a successful tax transaction executed via a scheduled job post order placement. This is a change in the original tax status initially applied when order was placed. This a completed transaction with accompanying line item tax information saved in CCH SureTax tables.
    • FAILED: This status indicates an unsuccessful tax transaction.
    • Note: Only orders with status FINALIZED or UPDATED-FINALIZED can be canceled.
  • CCH SureTax Transaction ID. The transaction ID provided by CCH SureTax.
  • CCH SureTax Transaction Notes. Transaction details like the response code, transaction (success or error) message, and total taxes returned from CCH SureTax (if applicable).
  • Exemption Code. This indicates that exemption type applied to the order.
    • Note: This data will be used in any post order request to preserve the exemption status of the current order
  • Tax Exempt Reason Code. This indicates that exemption reason applied to the order.There is no exemption applied this field will indicate that there is no data available. This data will be used in any post order request
    • Note: This data will be used in any post order request to preserve the exemption status of the current order.

Job Functionality

The CCH SureTax job is used to facilitate post order placement tax transactions. The job is designed to process orders that meets any of the following conditions:

  • CCH Tax Update Flag is set to one of the following:
    • Note: Only orders with status FINALIZED or UPDATED-FINALIZED can be canceled.
    • CANCEL: This flag will trigger a cancellation request to CCH SureTax.
    • FINALIZE: This flag will trigger a finalization request to CCH SureTax.
  • Order has status Cancelled and the tax transaction for the order is finalized, which is indicated by a CCH SureTax Order Status of FINALIZED or UPDATED-FINALIZED
    • An order that meets this condition will have a cancellation request submitted to CCH SureTax.

Updating the tax transaction via the CCH Tax Update Flag:

  1. Select Merchant Tools > Ordering > Orders.

  2. Select the order to update.

  3. Select the Attributes tab.

  4. Select an option from the CCH SureTax Update Flag dropdown.

  5. Click Apply when finished. The a new tax transaction will be sent to CCH SureTax and the order will be updated once the job is executed via the normal scheduled or by a manual triggering.

    To Access the CCH SureTax Job, do the following:

  6. Log in to the Salesforce Commerce Cloud Business Manager

  7. Select Administration > Operations > Jobs

  8. Select the "CCHSureTax" job

Known Issues and Limitations

There are no known existing issues. Please report any issues to CCH SureTax support.

Release History

Version Date Changes
17.1.0 08/1/2017 Initial release
18.1.0 10/17/2018 Recertification
19.1.0 06/28/2019 Recertification SGJC(SiteGenesis), added SFRA support, minor updates
20.1.0 8/31/2020 Recertification SGJC(SiteGenesis) and SFRA. Added unit tests, removed use of imports() from modules, and updated to support calculation requests larger than 4k characters.