CCH® SureTax® for Dynamics 365 Sales User Guide

Updated: Sept 30, 2024

Introduction and Pre-Requisites

Welcome to CCH SureTax for Microsoft Dynamics 365 Sales

CCH SureTax for Dynamics 365 Sales helps you accurately calculate sales tax.

  • CCH SureTax package is composed of the following:
    • CCH SureTax Sales solution
      • This contains the CCH SureTax Power App
        • CCH SureTax Configurations are performed here
      • Contains all Dynamics 365 CE Entities required for Tax Calculation
  • Supported industries: General Sales
  • Supported Modules:
    • Microsoft Dynamics 365 Sales
    • Microsoft Dynamics 365 Field Service
    • Microsoft Dynamics 365 Project Operations
  • Supported countries: United States and Canada
  • Supported Dynamics 365 Sales forms and workflows for Sales Tax Calculation:
    • Opportunities
    • Quotes
    • Orders
    • Invoices

CCH SureTax Pre-requisites and Configuration

For this add-on to function correctly, you must have the following:

  • Valid client number and validation key for CCH SureTax V07 (Calculation) and CCH SureTax Data API enabled for your account.
    • Endpoint URLs for CCH SureTax V07 and Data API.
      • The URL for CCH SureTax will typically look like the following:
        • https://<hostname>/Services/V07/SureTax.asmx
        • The URL for CCH SureTax Data API will typically look like the following:
          • https://<hostname>/v01/
      • Your CCH SureTax Client Number and Validation key are typically identical for both above.
      • Please contact your CCH SureTax representative for any questions.
  • From the CCH SureTax portal (you can get your login and URL from your CCH SureTax representative), you must do the following:
    • Nexus Configuration
    • SKU/Product mapping setup
    • SKU named 'Freight' must be setup.
      • At a minimum, we recommend that you create a SKU mapping to act as your default SKU mapping, which allows you to use unmapped SKUs:
        • E.g.
          • SKU / Product Value = -1
          • Customer Type = 99 -- Default
          • Regulatory Code = 99 -- Default
          • Transaction Type Code can be set to the default product you want to use (for example, 990101 - General Sales)

Installation and Configuration

Installing CCH SureTax for Dynamics 365 Sales

The following section includes instructions for installing the following CCH SureTax for Microsoft Dynamics 365 Sales.

  1. Unzip the package file CCH_SureTax_for_Dynamics_365_Sales_Package_AppSource.zip

  2. Unzip package.zip

  3. It contains a solution zip file

    1. package/PkgAssets/CCHSureTaxSales.zip

  4. CCH SureTax solutions can be installed directly through Microsoft Power Apps

    1. Navigate to https://make.powerapps.com
    2. Select the desired environment at the top right corner.
    3. Select Solutions at the bottom left corner.
    4. Import each solution in the order shown below
      1. Import CCH® SureTax® Sales Solution zip file with the name CCHSureTaxSales.zip
      2. Click on Publish all Customizations.

  5. CCH SureTax solutions can be installed directly through the environment

    1. Navigate to your D365 environment (ex https://sample.crm.dynamics.com/)
    2. Select Settings at top right corner => Advanced Settings => Customization => Solutions
    3. Follow Step 3d from above.

  6. CCH SureTax Package can be installed using the Microsoft CRM tool PackageDeployment.

    1. Unzip the package.zip from CCH_SureTax_for_Dynamics_365_Sales_Package_AppSource
    2. Copy over the following files from package.zip to the root of your PackageDeployment folder
      1. PkgAssets
      2. CCH.SureTax.CE.Sales.PackagingDeployment.dll
    3. Run the PackageDeployer.exe
    4. Select the environment to be deployed.
    5. Follow all steps until successfully deployed.

User Security Tasks & Security Roles

Security roles allow you to assign user permissions for various parts of this add-on. Assign roles to your users to ensure they have access.

  • SureTax Power User
    1. Have permissions to edit and view all CCH SureTax fields on supported forms
  • SureTax Basic User
    1. Have permissions to view CCH SureTax fields on supported forms.
    2. Edit permissions are allowed for header/line-item CCH SureTax settings for Opportunities, Quotes, Orders, and Invoices.
  • NOTE: CCH SureTax settings for Products, Accounts, and Contacts can be edited if user has access to these Entities.

CCH SureTax Basic Config

This section configures the connection settings required for tax calculation and data setup. This data is stored at the Dynamics 365 Business Unit (Team/User) level.

To configure settings, do the following:

  • Open CCH SureTax Power App -> Click on Basic Config under Setup
  • Basic Configuration - General Settings:
    • All fields are required, except for CCH SureTax Business Unit (note that this is different from Dynamics 365 business unit).
    • Basic Setup
    • Enable SureTax:
      • If 'No', then this integration will be disabled for most part except Basic Config (above screen).
    • Disable Auto Calc:
      • If set to 'Yes', the calculation on all supported forms will be triggered only when 'Calculate Tax' button on each of the Transaction forms is used.
      • If set to 'No' the integration will calculate tax on all Transaction forms' tax relevant field updates.
    • Calc for Open Transactions:
      • Ensures transactions not initialized with SureTax settings are initialized to enable tax calculation for them.
      • This flag is useful when a customer could have existing open transactions before SureTax is installed and these transactions need to have tax calculated.
      • If set to 'Yes', allows tax calculation on transactions that are not initialized with SureTax settings.
      • Steps to follow:
        1. Set Disable Auto Calc to 'No'
        2. Choose an Open Transaction with no Suretax settings.
        3. Use 'CCH SureTax' -> 'Calculate Tax' button on the transaction form.
      • If set to 'No' plugin will not calculate the tax for open transactions.
      • Note: May impact performance. Recommended to set the flag to 'No' once calculate tax operation is performed on all required open transactions.
    • After values are filled in continue to SureTax Data API tab.
  • SureTax API:
    • All fields in this section are required to establish connection with SureTax and Calculate Tax on relevant transaction forms.
  • SureTax Data API:
    • All values in this section are needed to connect to CCH SureTax Data API. All fields are required.
    • After all fields are entered, click Save
    • Click on the button 'Import SureTax Data' to setup CCH SureTax data on your system.
      • This uses connection data stored for SureTax Data API to import tax data into relevant CCH SureTax entities.
      • Imported data from here is stored at the Organization level.
      • Note that feature checks to see if used SureTax Entities used to import data into have any failed Keys during creation (see Known issues). If any Failed keys are found, jobs will be made to activate keys for Entities used for SureTax Data. User will have to wait for the jobs to complete before attempting to Import SureTax Data again.
    • 'Validate' button - Can be used to verify that your values are valid.
    • 'Copy Settings' button - If you have more than 1 Dynamics 365 business unit, you can use 'Copy Settings' button to copy CCH SureTax settings
      • Basic Config
      • Sales Config
      • Field Service Sales Config
      • Field Service Purchasing Config
      • Project Operations Sales Config

from another business unit. It is recommended to use this after 1 Dynamics 365 business unit has been setup completely with CCH SureTax settings as all settings will be copied.

  • 'Update Plugin Steps' - Can be used to update plugin steps if more than one of our solutions is installed
    • If 'CCH SureTax Sales' solution is installed and 'CCH SureTaxField Service' solution is installed after it, then use this button to make sure all the required filtering and image attributes are in the respective plugin.
    • Even if the order is reversed for installation of our solutions, use the button to make sure all the required filtering and image attributes are in the respective plugin.

Configuring CCH SureTax Sales Setup

The CCH SureTax Sales Config form contains settings that can be configured at the Dynamics 365 business unit level. To configure settings, do the following:

  1. Open CCH SureTax Power App -> Click on Sales Config under Sales
    1. Sales Setup
  2. Enable SureTax - You can select specific forms to enable tax calculation for.
  3. Update Order Lines selection, select Yes/No. This determines when to update transaction lines for an order/invoice when a header level setting is updated.
  4. Tax Rule Override - Default Tax Logic is recommended, but you can select other options based on your business needs (This sets 'RuleOverride' value sent to CCH SureTax during calculation).
  5. Finalize Option -- This option controls if the CE Invoice Transaction is posted(finalized) in CCH SureTax, when posted in CE.
  6. Line-Item Defaults section contains all defaults used for tax calculation:
    1. Tax Exemption Code. Example: 00 -- No Exceptions.
    2. Regulatory Code. Example: 99 (DEFAULT).
    3. Sales Type Code. Example: T (Retail).
    4. Transaction Type Code. Select the most frequently usedTransaction Type Code for your business. Example: "990101 - General Sales."
    5. Unit type Code. Example: Select 99 for General Sales.
    6. Tax Situs Rule. Example: Select 22 for General Sales.
    7. Tax Exempt Reason Code.
  7. Freight Defaults:
    1. Tax Situs Rule -- Only used for freight. Example: Select 22 for General Sales.
    2. Transaction Type Code -- Only used for freight if Stocking Unit preference is set to Transaction Type Code.
  8. Click Save to save the options on the CCH SureTax Sales Config form.
  9. Ship-From Address tab:
    1. Enter the default Ship-From Address used for tax calculation.
    2. ShipFrom Setup
      1. Please enter all values, only Address Street 2 is not needed.
        1. Country is expected to be 2-digit abbreviation (e.g. US, CA, etc)
    3. Click Save
  10. SKU Preference:
    1. Sku Pref
    2. The SKU Preference feature is a way for user to set the SKU for each Product line item of Opportunities, Quotes, Sales Orders, and Invoices. The SKU can be assigned a value from a specific set of columns from relevant database Tables.
    3. To use this feature, Select the one record with Transaction Type as "Product Lines" will open up the SKU Preference form for user to edit.
    4. If the Stocking Unit Preference is "Transaction Type Code", the SureTax Transaction Type code associated with the product for a line item will be sent as the SKU. (For example, the common TransTypeCode 990101-General Sales will be assigned as the SKU)
    5. Keep in mind, Transaction Type Code is the default selection.
    6. However, if user change the Stocking Unit Preference to "SKU", the SKU Preference Table is now selectable.
    7. User can then select the Database Table. Only relevant tables are shown to the specific Transaction Form. (For example: Quote, Quote Detail, and Product tables are shown for the Transaction Form: Quote)
    8. On select of a table, its corresponding column names are populated in the SKU Preference Column dropdown list. User can now set the column field.
      1. The value of that column will be sent as the SKU to SureTax for a line item. (For example: setting the column "name" for the table "Quote" means that the quote's name will be sent as the SKU for all line items of that quote.)
  11. Data Exchange
    1. Data exchange
    2. The Data Exchange feature is a way for user to set the value of each of the 15 Data Exchange parameters. Each parameter can be assigned a value from a specific set of columns from relevant Tables. Or it can be assigned a static text with the "Manual Text Entry" option.
    3. These 15 parameters are optional fields that are sent with each line items to SureTax. They can be set for each Product line item of Opportunities, Quotes, Sales Orders, and Invoices.
    4. To use this feature, first select the Transaction Form you want to edit. The corresponding subgrid will be shown.
    5. When user click on a record of the parameter they want to edit, the Data Exchange form will open.
    6. User can then select the Database Table. Only relevant tables are shown to the specific Transaction Form. (For example: Quote, Quote Detail, and Product tables are shown for the Transaction Form: Quote)
    7. The option of "Manual Text Entry" is also there that will allow you to set a static text for this parameter. Once selected in the Table dropdown, the Manual Text Entry field will be editable for user to enter.
    8. However, on select of a table, its corresponding column names are populated in the Column dropdown list. User can now set the column field.
      1. The value of that column will be sent as the parameter to SureTax for a line item. (For example: setting the column "name" for the table "Quote" for the Parameter "Cost Center" means that the quote's name will be sent as the CostCenter field for all line items of that quote.)

Configuring CCH SureTax Settings for Products

Optional settings that override default values used for tax calculation can be configured for Products.

To configure settings, do the following:

  • Sales 🡪 navigate to Products 🡪 Select an Existing product
  • Click on CCH SureTax Dropdown 🡪 Settings Button
    • Product Settings
  • It will open a new form (shown above), where you can set:
    • Tax Situs Rule
    • Transaction Type Code

Configuring CCH SureTax Settings for Customers (Accounts and Contacts)

Optional settings that override default values used for tax calculation can be configured for Customers (Accounts and Contacts).

To configure settings, do the following:

  • Sales 🡪 navigate to Accounts or Contacts 🡪 Open existing Account/Contact
  • Click on CCH SureTax Dropdown 🡪 Settings Button
    • Account Settings
    • It will open a new form (shown above), where you can set:
      • Enable SureTax
      • Tax Exemption Code
      • Sales Type Code
      • Tax Exempt Reason Code

Using CCH SureTax for Dyanmics 365 Sales

Tax Calculation

  • Tax is calculated on supported forms if CCH SureTax is enabled. Tax calculation with CCH SureTax is triggered during the following:
    • Changes to tax relevant fields on Transaction form.
    • Product (Line Item) is added/edited, Quantity is updated.
    • Header Settings and/or Line Settings are updated.
      • Note: In all above Tax Calculation is triggered if 'Disable Auto Calc' is set to 'No' in Basic Configuration
  • Features specific to Invoices:
    • Invoice Paid - is supported by posting to CCH SureTax
      • Note: CCH SureTax will post the whole invoice regardless of Status Reason being Complete or Partial, as partial posting not supported correctly by Dynamics 365 Sales.
      • Note: Invoice is posted to SureTax only is 'Finalize Option' is set to 'Yes' in Basic Configuration
        • Complete Invoice
        • Partial Invoice
    • Cancel Invoice - will cancel the posted invoice in CCH SureTax
      • Note: Invoice is Cancelled in SureTax if the same Invoice is in Posted state in SureTax

Configuring CCH SureTax Header Settings

The CCH SureTax Settings form is available at the header level for all supported forms, is used to modify settings used for CCH SureTax calculation. Initial values are set based on default configured in CCH SureTax Sales Config, but CCH SureTax Settings set on Products and Customers take precedence (used if they are set).

  • Open supported form -> Fill in tax relevant details -> Save
  • Click on the CCH SureTax Dropdown 🡪 Header Settings button to view/edit CCH SureTax Settings.
    • Header Settings button
    • Header Settings Screen
  • You can modify the following fields:

    1. General Settings:

      1. Enable SureTax

    2. Date Settings:

      1. Transaction Date -- Date used for tax calculation date and initialized to when associated entity (e.g. Opportunity, Quote, Order, Invoice) is created.
      2. Compliance Date -- Available only for Invoices. Date used for Compliance Year/Month for tax calculation. If blank, the posting date of invoice used, otherwise, the entered date is used.
        1. Date Settings

    3. Header Settings:

      1. Tax Exemption Code
      2. Tax Exempt Reason Code
      3. Regulatory Code
      4. Sales Type Code
      5. Tax Situs Rule. Select the default Tax Situs Rule (e.g., 22 for General Sales).
      6. Transaction Type Code.
      7. Unit Type Code. Select the default code (e.g., 99 for General Sales).

    4. Freight Settings:

      1. Transaction Type Code.
      2. Tax Situs Rule. Select the default Tax Situs Rule (e.g., 22 for General Sales).
      3. Any form that supports Freight and Shipping, and would want to support CO Retail Delivery Fee, the Freight Amount needs to be entered into field even if its $0.

Configuring CCH SureTax Line Settings

Line settings are like the above for header settings but can be set for line items (Products).

  • Open supported form -> Fill in tax relevant details -> Save
  • Add Product (line item) and fill in details (or open existing).
  • While viewing the line item, CCH SureTax Dropdown 🡪 Line Settings button to view/edit CCH SureTax Settings.
    • Line Settings button
    • Line Settings Screen
  • You can modify the following fields:
    • Line Settings:
      • Enable SureTax
      • Tax Exemption Code
      • Regulatory Code
      • Sales Type Code
      • Transaction Type Code.
      • Unit Type Code. Select the default code (e.g., 99 for General Sales).
      • Tax Situs Rule. Select the default Tax Situs Rule (e.g., 22 for General Sales).
      • Tax Exempt Reason Code

Ship-To and Ship-From addresses used for CCH SureTax Calculation

Sales tax calculation requires a ship-to and ship-from addresses to accurately calculate sales/use tax. The CCH SureTax add-on uses the following on supported forms:

  • Ship-From Address:
    • 'Default Ship From Address' set in CCH SureTax Sales Config.
  • Ship-To Address:
    • Address entered in the supported form is used.

Viewing CCH SureTax Tax Details

Once tax is calculated, you can view details on supported forms (at header level), by view CCH SureTax Tax Details tab.

  • Open any supported form at header level.
  • Ensure you have calculated tax.
  • Click on CCH SureTax Dropdown 🡪 Tax Details Button.
  • Here you can view detailed tax data.
  • Tax Details Screen
  • Note that you can expand the Line item to quickly see more information (see below screenshot)
  • Jurisdiction Screen
  • To view more details for line items, click on the line item and the '->' icon on the right.
    • Line Detail
  • While viewing the line-item tax details, you can click on CCH SureTax Tax Details tab to view tax jurisdiction level tax data.
    • Line Detail Tax

Uninstalling and Updating

Uninstalling the CCH SureTax Add-on

To uninstall the CCH SureTax add-on, you can delete the CCH SureTax solutions:

  • Go to Power Apps site (e.g. https://make.powerapps.com/)
  • Select your environment
  • Select Solutions from the left navigation
  • Delete solutions in the order mentioned below.
    1. Delete CCH SureTax Sales solution
  • Note: This will delete all data, so backup CCH SureTax data (if needed) before proceeding.

Updating a CCH SureTax Add-on

To update to a newer version of the CCH SureTax add-on, do the following:

  • Go to Powe Apps site (https://make.powerapps.com/)
  • Select your environment
  • Click on Import Solution
  • Select the Sales Solution you want to update and click next
  • Use Update option under Advanced Settings
  • This will update the existing solution to latest version

Appendix

How CCH SureTax API is used

  • All calculation requests are sent as Quotes to CCH SureTax, except for Finalized requests, which are made when an Invoice is paid.
    • If CCH SureTax returns an error during tax calculation, the add-on stops the system from posting the document within Dynamics 365 Sales.
  • Freight is sent as a separate line item to CCH SureTax.
    • If Stocking Unit preference > Transaction Type Option is set to SKU, "Freight" must be mapped in CCH SureTax.
  • Country field used in all Address fields expect a 2-digit ISO code. If no country is set, CCH SureTax will send a blank string for country code.
  • Currency is expected to be for the country of the Ship-To address (CCH SureTax API does not perform currency conversion).
  • Discounts:
    • Discounts are subtracted from line-item amounts before they are sent to CCH SureTax for tax calculation.
    • Header Discounts are applied proportionally to all line items before they are sent to CCH SureTax for tax calculation.

CCH SureTax API Mapping for Tax Calculation

For the below, left is CCH SureTax data, and the right describes what is used from Dynamics 365.

Each CCH SureTax transaction is created with the following data at the header level:

  • <ClientNumber> - From CCH SureTax Basic Config
  • <ValidationKey> - From CCH SureTax Basic Config
  • <DataYear>, <DataMonth> - Transaction Date from CCH SureTax Settings
  • <CpmlDataMonth>, <CpmlDataYear> - Compliance Date from CCH Settings
  • <ResponseType> - "12C<CURRENCY_PRECISION>", e.g., if currency precision is 2 in Dynamics 365, then 12C2 would be used, the number 2 (on the right) sets the tax calculation response's decimal precision.
  • <ResponseGroup> - "00"
  • <STAN> - blank
  • <TotalRevenue> - Sum of all line amounts including Freight with discounts subtracted.
  • <ReturnFileCode> - "Q" used all times except "0" for when invoice is posted.

Each CCH SureTax line item is created with the following data (Freight is considered as a line item):

  • <InvoiceNumber> - The ID of the respective entity, which can be Opportunity ID, Order ID, Quote ID, or Invoice ID.
  • <LineNumber> -- In order and increments starting with 0, but 'freight' is the value used for the Freight line item.
  • <CustomerNumber> - Account Number. In case of Contact Account Number of the Account attached on the contact or Contact Name
  • <RegulatoryCode> - The Regulatory Code (Provider) from CCH SureTax Sales Config
  • <SalesTypeCode> - The Sales Type Code (Customer) from CCH SureTax Sales Config or Accounts/Contacts CCH SureTax Settings
  • <LocationCode> - blank
  • <TransDate> - Transaction Date from CCH SureTax Settings
  • <Revenue> - Amount for the line item. Any discount will be subtracted before in the price sent.
  • <TaxIncludedCode> - "0"
  • <Units> - Line item's Quanity
  • <FreightOnBoard> - "blank" (default). Can be configured in CCH SureTax Shipping Method Settings
  • <AuxRevenueType> - "01" (default)
  • <AuxRevenue> - "0" (default)
  • <TaxSitusRule> - Use "22" for General sales. This is configuredat CCH SureTax Sales Config and Products CCH SureTax Settings.
  • <RuleOverride> - "0" (Default). This can be configured in CCH SureTax Sales Config.
  • <UnitType> - Use "99" for General sales. This is configured at CCH SureTax Sales Config and Products CCH SureTax Settings.
  • <CommonCarrier> - "blank" (default). Can be configured in CCH SureTax Shipping Method Settings
  • <CurrencyCode> - Dynamics 365 Currency Code
  • <TaxExemptionCodeList> - From CCH SureTax Sales Config or Account/Contacts CCH SureTax Settings.
  • <ExemptReasonCode> - From CCH SureTax Sales Config or Account/Contacts CCH SureTax Settings.
  • <TransTypeCode>
    • Can be configured using the SKU Preference feature as part of CCH SureTax Sales Config. Please refer to Chapter 2 => Part D => Number 11.
      • For each line if the Stocking Unit Preference is "Transaction Type Code" then the Transaction Type Code will be used for the Line Item.
        • This is configured at CCH SureTax Sales Config and Products CCH SureTax Settings.
      • For each line if the Stocking Unit Preference is "SKU" then the value from the selected Column from the selected Table will be used.
  • <ShipToAddress> - Ship To address entered on the form.
    • Note that Will Call toggle on supported forms do not affect tax calculation, the correct Ship To address is expected to be filled on the form.
  • <ShipFromAddress>
    • Default Ship From address entered in CCH SureTax Sales Config.
  • <BillToAddress> - Bill To address entered on the form.

Customized Entities and Plugins

This CCH SureTax add-on uses customized entities and plugins to integrate seamlessly with Dynamics 365 Sales.

Please view the CCH SureTax for Dynamics 365 Sales Detailed Technical Documentation (DTD) for more information.

Known Issues

  • Entity Key creation may fail after installation of the Package. This can affect Entities used for 'Import SureTax Data'. If there are any failed keys, 'Import SureTax Data' will check for and attempt to fixed failed keys. If this happens, you must wait for system jobs to finish before attempting to 'Import SureTax Data'.