CCH® SureTax® for D365 Commerce User Guide

Updated: June 18, 2024

Installation and Configuration

Integrating the CCH SureTax Plug-in into Commerce SDK

CCH SureTax for Microsoft Dynamics 365 Commerce SDK is a plug-in that integrates the CCH SureTax solution with Commerce SDK. With CCH SureTax for Commerce SDK installed, you can accurately calculate sales tax for the United States and Canada and manage your sales tax compliance without the need to maintain sales tax rates inside Commerce SDK.

Pre requisite for setting up new VM for commerce SDK

Installing Commerce POS

  • Install Microsoft Commerce scale unit and Store Commerce following the link below https://learn.microsoft.com/en-us/dynamics365/commerce/dev-itpro/install-csu-dev-env
  • Go to Retail and Commerce > Headquarters setup > Commerce scheduler > Initialize Commerce scheduler. Select Delete existing configuration. Click OK.
  • Go to Retail and Commerce > Headquarters setup > Commerce scheduler > Channel Database and execute jon 9999 from Full Data Sync menu.
  • Once the jobs are applied, go to Windows Services and execute Microsoft Dynamics 365 Commerce - Async Client.
  • Install the CCH Suretax plugins.
    • CCH.Suretax.Commerce.exe
    • CCH.Commerce.StoreCommerce.exe.

Retail Store Settings

There are various settings that are added to the retail store card by the plug-in. They affect the SureTax tax calculation in Store Commerce, and Cloud Point of Sale. All of the settings are store specific, so you can have different settings for each store if you want to. The settings are as follows:

Setting Purpose
SureTax URL The URL used to calculate taxes for the retail store.
SureTax client number Client number for the SureTax API
SureTax validation key Validation key for the SureTax API
Tax calculation mode Calculation mode that is used to determine which engine is used for tax calculation. Options are Use SureTax, Use Stock Calculation, and Disable Calculation. If the option is "Use SureTax", then SureTax is used to calculate tax for the store. If the option is "Use Stock Calculation" then the plug-in will use the standard POS tax calculation. If the option is "Disable Calculation", no taxes will be calculated at all.
Tax trigger mode Determines when tax is calculated in Store Commerce/CPOS. If it is set to "Automatic", tax will be calculated every time Store Commerce/CPOS calculates tax. I.e. when adding a line, shipping, etc. If it is set to "On Demand" it will only be calculated when the "Calculate Total" operation is triggered in Store Commerce/CPOS.
Tax exemption code Default tax exemption code to send to SureTax for the store.
Tax Exemption Reason Default tax exemption reason code to send to SureTax for the store.
Regulatory code Default regulatory code to send to SureTax for the store.
Transaction type code Default transaction type code to send to SureTax for the store.
Sales type code Default sales type code to send to SureTax for the store.
Transaction type option Determines what is sent to SureTax for the SKU. If it is "Stocking Unit", then the SKU/product id/charges code will be sent. If it is "Transaction Type Code", then the transaction type code of the item/charge/store will be sent.
Tax setup option Determines how the tax is recorded in AX. If it is "Breakdown by state and country", then the tax will recorded to a separate tax group for each state and country combination. If it is "Single sales tax group", then all the tax will be recorded in the same tax group.
Enable SureTax Call Logging If this is checked, the SureTax Store Commerce/CPOS plug-in will log its information in the Retail Server or offline database instead of in Event Viewer.
Retail store SKU Selection determines whether the Item ID or Retail Category or Item Group is sent as SKU to SureTax.
Store Decimal Precision Sets Number of decimal places to display on receipt for the store. Number of decimal places allowed are 2,3, and 4

SureTax Retail Store Setup Form

To make configuring the SureTax for Retail plug-in easier, we provide a form where you can set/see the SureTax settings for all stores at once. To access that form, either click the "SureTax Retail Store Setup" link on the "SureTax Global Workspace", or from Tax > CCH SureTax > Retail > CCH SureTax Retail Store Setup.

Configure SureTax Settings for Stores

You can set the SureTax settings for the stores in the grid manually, or under the Action tab, you can click "Default selected" or "Default all" to default the values from the "CCH SureTax Sales Setup" form, and the "CCH SureTax Basic Setup" form. "Default selected" only updates the currently selected records. "Default all" updates all records with the values from the setup forms.

For copying settings from a store to other store, Select a store and click "Set Copy From Store" to set a store as source. This can be also set under retail tab on SureTax Sales Setup Form. Next, select stores to which settings needs to be copied and click "Copy Settings to Selected" to complete the copy setting process.

Generating Offline Rates

If you are planning on using Store Commerce/suretax_commerce/CPOS in offline mode, please read this section. If you aren't you can ignore this section.

For the plug-in to calculate tax in offline mode, some tax rates will need to be imported from SureTax. To generate those rates, select the stores you want the rates to be generated for and click "Get for selected" (if for all, click "Get for all"). This brings up the standard D365 batch job dialog box. Set whatever settings you want for the job to execute. CCH recommends that you set a reoccurrence for the batch job at once a month, as sales tax rates can change that often and you don't want to have outdated rates.

To generate the offline rates, the plug-in makes a call to SureTax for each product, markup code, or retail category assigned to the store. Based on the Transaction Type Option, we will send either the SKU or the transaction type code associated to the item, markup code, or retail category. All calls are sent with the store's warehouse address, that way the rates reflect the physical location of each store.

You can view the rates generated for each store by clicking on the store you want to view, and then click "View offline rates". This will bring up a form that looks this:

If the store is located in Canada, the "PST Rate" and "GST Rate" will be filled in and the plug-in will use those two rates when calculating tax offline. If it is located in the United States, the "Tax rate", and "Fee rate" will be used instead.

Setting up the Distribution Schedule

The plug-in data that is configured in D365 headquarters has to pushed down to the Retail Server and offline databases before the Store Commerce/CPOS plug-ins can be used.

To initialize the SureTax distribution schedule:

  1. Go to Retail and Commerce > Headquarters setup > Commerce scheduler > Initialize Commerce scheduler.
  2. Go to Retail and Commerce > Retail and Commerce IT > Distribution schedule.
  3. Go to the STX-0001 job and set a channel database group.

Now to push the data down to the Retail Server and offline databases:

  1. Go to Retail and Commerce > Retail and Commerce IT > Distribution schedule.
  2. Run job STX-0001, or run 9999.

Now to pull the SureTax data from the Retail Server:

  1. Go to Retail and Commerce > Retail and Commerce IT > Distribution schedule.
  2. Run job P-0001.
  3. It is a good idea to create a batch job for this, and set a reoccurrence for every day at the end of the day.

Setting Up Custom Fields for Fee Display

Custom fields are needed to show the fee amounts sepaate from the tax amount in MPOS/CPOS. To create the custom fields:

  1. Go to Tax > CCH® SureTax > Retail > CCH® SureTax Retail Store Setup.
  2. Click Actions > Custom fields > Create custom fields.

To add the custom fields to your layout, reference this Microsoft link: https://docs.microsoft.com/en-us/dynamics365/retail/dev-itpro/custom-field-pos-totals. You only need to follow steps 8 through 21 as steps 1 through 7 were taken care of by the plug-in. The following fields need to be added to the Totals panel:

  • FeeAmount1
  • FeeAmount2
  • OtherFeeAmount

Repeat the previous steps for all other layouts you want the fees to be shown on.

Reconciliation

The SureTax for Retail plug-in contains a reconciliation process that will update SureTax for transactions that were finalized while the point of sale was in offline mode. If the tax amount SureTax calculates differs from the amount that was calculated in offline mode, it will adjust either SureTax or the D365 ledger.

Setting up SureTax Sales Setup

To get the correct amount into the D365 ledger, a journal name will need to be specified. You need to specify it on the SureTax Sales Setup form.

  1. Go to Tax > SureTax > Sales > SureTax Sales Setup.
  2. On the Retail tab, set the general journal name in the "Adjustment Journal Name" field.

Pulling Data from the Retail Server

The data needed to do the reconciliation needs to be pulled from the offline database. To accomplish this, follow these steps:

  1. On each register that is in offline mode, at least once a day, reconnect it to the Retail Server and wait for the "Pending transactions in offline database" field to be 0. After it is 0, you can move the register back into offline mode.
  2. In Dynamics 365, go to Retail and Commerce > Retail and Commerce IT > Distribution schedule.
  3. Select P-0001 and click Run now. If there are a lot of transactions, you may want to click Create batch job to execute the pull on the batch server.
  4. We recommend setting a Recurrence for the P-0001 batch job, to nightly.

Running SureTax Reconciliation Process

After the journal name is set, and the data is pulled from the Retail Server, it is time to run the reconciliation job. To do that follow these steps:

  1. Go to Tax > CCH SureTax > Retail > CCH SureTax Reconciliation.
  2. Set if you want to execute the job right now, or execute as a batch job. We recommend that you set the reconciliation job to run as often as the distribution schedule P-0001 is executed.
  3. Click OK.

Running the SureTax Reconciliation Report

To view the results of the reconciliation batch job, go to Tax > SureTax > Retail > SureTax Reonciliation Report. This executes an SSRS report. The report popup will give you a start and end date to filter the data. Here is a sample report:

Report Column Purpose
Date Reconciled Date the transaction was ran through the reconciliation process.
Original Invoice Id Invoice ID of the transaction in the POS.
Original Tax Amount Tax amount that was calculated while the POS was in offline mode.
Actual Tax Amount Tax amount that was calculated for the transaction by SureTax. This is the amount that should have been charged to the customer.
Amount Over Collected If the amount that was originally collected from the customer was more than what should have been collected, then this is the amount that SureTax is adjusted by.
Amount Under Collected If the amount that was originally collected from the customer was less than what should have been collected, then this is the amount that the D365 ledger is adjusted by.
SureTax Transaction Id SureTax transaction ID of the call that was made to get the actual tax amount that should have been collected.
SureTax Tax Adjustment Transaction Id SureTax transaction ID of the tax adjustment call. This will be zero unless more tax was collected then should have been.
Journal Num This is the D365 journal number that contains the adjusted tax amount if not enough tax was collected from the customer.

Store Commerce/Cloud Point of Sale, Tax Calculation

Once all of the data is set up in HQ, and successfully pushed to the Retail Server, tax will now calculate with the plugin in Store Commerce/CPOS. If you want to calculate tax in offline mode, you also need to make sure all of the data is pushed to the retail offline database at each offline enabled register.

Depending on the value set for "Tax trigger mode" on the retail store, will determine when tax will get calculated. If it is set to "Automatic" tax will calculate whenever Store Commerce/CPOS calculates tax (e.g. new line is added, quantity changed, etc.). If it is set to "On Demand", tax will only be calculated when the "Calculate total" operation is executed. This operation may not have a button on your POS. If it isn't you will have to add a button to your POS visual profile with the operation set to "310 Calculate Total", and then push the changes down to the retail server.

The tax amount in the totals grid on the POS will update after tax is calculated. See the following screenshot:

If the register is in offline mode, then the taxes are calculated based off of the offline rates in the retail offline database. The plug-in looks up the rate for either the SKU or transaction type code (depending on the "Transaction type option" on the store) and use that rate to calculate the tax amount for the line.

If you want to view the tax details that SureTax returned you can. If "Enable SureTax Call Logging" setting is set to Yes, the details will be logged in the RetailServer database, in the [ext].[SURETAXPLUGINLOG] table. If you are in offline mode, these will be logged in the retail offline database instead. If the setting is set to No then the calls will be logged in Event Viewer, under the Windows Logs > Application. The following screenshot is an example of a call:

When the transaction is paid for, then the plug-in will make a final call to SureTax for the transaction. If the transaction is of type "Customer Order", then only lines that are have been selected to be carried out will be finalized in SureTax, not the lines that were shipped, or scheduled to be picked up in a different store. The reason is that those lines will get finalized in HQ, or in a different Store Commerce/CPOS transaction, when they are picked up or shipped.

Discounts

When a discount is applied to a line/transaction, POS calculates the total for the line with the discount. That is the amount that is shown in the Lines grid. That amount is always the amount that we send as the revenue to SureTax for tax calculation.

Exemptions

CCH SureTax provides two types of exemption for POS customer order/quote: one at the customer exemption and another is the line/transaction level exemption.

Customer Exemption

Customer exemption is effective on entire transaction in POS. The customer can be configured with two types of exemptions:

  • SureTax exemption code. A SureTax exemption code can be selected from the drop-down and assigned directly to the customer in POS by editing the customer.
  • SureTax exemption reason code. A SureTax exemption reason code can be selected from the drop-down and assigned directly to the customer in MPOs by editing the customer.
  • AX Exemption Number. An AX exemption number can be selected from the drop-down and assigned to the customer. The AX exemption number has the SureTax exemption code assigned to them in AX headquarters.

The SureTax exemption code, exemption reason code, and AX exemption number for a customer can be changed by editing and saving the customer in POS. The corresponding change is reflected in AX headquarters for that customer. Also, the SureTax Exemption code attached to the AX exemption number will have higher priority than the exemption code set on the customer.

Line/Transaction Exemption

CCH SureTax uses the native MPOS functionality to override tax at line level or the entire transaction level. You can navigate to it by clicking the Actions button and then the Tax overrides button.

In AX Headquarters, go to Sales taxes under Retail and Commerce > Channel setup > Sales taxes > Sales tax override. Create a sales tax override and assign a SureTax exemption code to it.

This sales tax override can be added to sales tax override groups which will be in turn specified as sales tax override group in retail store setting.

This feature can be used to remove exemption also from specified line or transaction by assigning Tax exemption code 00 for the sales tax override.

When MPOS is in offline mode, then any exemption is taken as all exempt for a customer exemption and line/transaction exemption.

Retail Statement

To make sure the correct tax amount is posted to the ledger when posting a retail statement, make sure Voucher transactions is set to No under Aggregation (Retail and Commerce >Headquarters setup > Parameters > Commerce Parameters, Posting tab).

e-Commerce

Online Store Settings

There are various settings that are added to the Online store card by the plug-in. They affect the SureTax calculation in the Commerce Online Store website. The settings are as follows:

Setting Purpose
SureTax URL The URL used to calculate taxes for the retail store
SureTax client number Client number for the SureTax API
SureTax validation key Validation key for the SureTax API
Tax exemption code Default tax exemption code to send to SureTax for the store.
Regulatory code Default regulatory code to send to SureTax from the store
Transaction type code Default transaction type code to send to SureTax for the store.
Sales type code Default sales type code to send to SureTax from the store
Transaction Determines what is sent to SureTax for the SKU. If it is "Stocking Unit", then the SKU/product id/charges code will be sent. If it is "Transaction Type Code", then the transaction type code of the item/charge/store will be sent.
Tax setup option type option Determines how the tax is recorded in AX. If it is "Breakdown by state and country", then the tax will be recorded to a separate tax group for each state and country combination. If it is "Single sales tax group", then all the tax will be recorded in the same tax group.
Enable SureTax call logging If this is checked, the SureTax Store Commerce/CPOS plug-in will log its information in the Retail Server or offline database instead of in Event Viewer.

Pulling Data from the e-Commerce Online Store website

When the Commerce parameter under customer Order tab “Use real-time service for e- Commerce order creation” is OFF, follow these steps after order is placed in e-Commerce website to pull into D365 F & O Headquarters:

  1. In Dynamics 365, go to Retail and Commerce > Retail and Commerce IT > Distribution schedule. Select P-0001 and click Run now.
  2. Go to Retail and Commerce > Inquiries and Reports > Online Transactions. Click synchronize order to see the Sales Orders in D365 F&O Headquarters.

When the Commerce parameter under customer Order tab “Use real-time service for e- Commerce order creation” is ON, an open Sales Order is created in Headquarters for an order paid in the e-Commerce website.

e-Commerce Online Store Website, Tax Calculation

How it Works

SureTax will calculate tax each time the website triggers a tax calculation. The tax amount will be returned to e-Commerce. Furthermore, all orders created on the website will be sent to SureTax as queries so they will not impact the tax liability until they are transferred as a Sales Order in Dynamics 365 F&O. SureTax plugin supports both guest and registered users in the Online Store.

Things to Note

For sales orders created on the Commerce website, SureTax can exempt customers based on exemptions configured in the SureTax Console as well as in DynamicsAX365 D365 F & O. The SureTax integration will recognize customer specific and item specific SureTax Settings in configured Dynamics 365 F&O.

If you want to view the tax details that SureTax returned you can. If "Enable SureTax Call Logging" setting is set to “Yes”, the details will be logged in the RetailServer database, in the [ext].[SURETAXPLUGINLOG] table. If the setting is set to “No” then the calls will be logged in Event Viewer, under the Windows Logs > Application. The following screenshot is an example of a call:

The order placed in e-Commerce will be a Sales Order in Dynamics Headquarters. When the Sales Order is invoiced in Headquarters a final call will be made to SureTax.

Promo Codes

A discount is associated with a promo code in D365 F&O Headquarters. The promo code is added to the order created in the e-Commerce website. The revenue amount is sent to SureTax after the discount is subtracted from the revenue.

Fees and other charges

In order to display fees separate from taxes, the following changes must be made. Under the ECommerce.Sdk.Controls project, replace the content of these files with the content displayed below.

Code

private getExtensionPropertyValue(commerceProperties: CommerceProxy.Entities.CommerceProperty[], keyName: string, propertyName: string): any {
    if (!commerceProperties || !keyName)
        return null;
    var commerceProperty: CommerceProxy.Entities.CommerceProperty = null;
    var value: string = null;
    for (var i = 0; i < commerceProperties.length; i++) {
        if (commerceProperties[i].Key == keyName) {
            commerceProperty = commerceProperties[i];
            break;
        }
    }
    if (commerceProperty != null && commerceProperty.Value != null) {
        if (propertyName)
            value = commerceProperty.Value[propertyName];
        else
            value = commerceProperty.Value.StringValue;
        }
        return value;
    }

Verify the dll is updated with this change.

Note: The dll name may be different because of Assembly name configuration.

Correct Button

There is a SQL database issue which Microsoft is aware of which inserts a null value when a new record is inserted in the RetailChanneltable during deployment. When opening a Retail or Online store, and a null value error occurs, this can be easily corrected by going to the list of Online Stores ~ Setup tab. Under SureTax, click on the Correct button which will automatically replace the null values and correct the issue.

Gift Card Issuance

Microsoft does not support issuing Gift Cards in the Commerce website. Until Microsoft starts supporting this feature, you will want to ensure that Gift Cards cannot be selected for purchase. Go to “Assortments” in the Online Store to remove any gift card configuration if it exists.

Retail Call Center

The SureTax Plugin supports the calculation and posting of taxes for sales orders in Dynamics 365 F&O Call Center. Orders created in the Retail Store and e-Commerce (Online Store) can be successfully completed and invoiced in Dynamics 365 F&O Call Center. The SureTax plug-in settings are defaulted from the Sales Setup in Headquarters in Dynamics 365 F&O along with other entities such as Items and Customers. Therefore, the Sales Setup should match the Retail Store Setup and Online Store Setup resulting in matching taxes for all channels of D365 Commerce.

We can select the Call Center and add the user to Channel Users of Call Center. This action initiates the appearance of the Complete button in the tab of the Sales Order. The user can use the SureTax plug-in to calculate taxes and complete the Sales Order. Only completed Sales Orders can be invoiced in the Call Center.