CCH® SureTax® for Adobe Commerce (Magento) User Guide

Updated: July 10, 2024

Installing and Configuring CCH SureTax Extension

Overview

CCH SureTax provides real-time tax calculations. When an order is placed in Magento, the taxes are calculated and stored in Magento. This ensures that the tax quoted at the time of the sale will be accurate. When an invoice is created in Magento, the taxes are finalized using the original date of sale and stored in CCH SureTax. When a credit memo is created in Magento, the taxes to be refunded are finalized and stored in CCH SureTax. This credit in CCH SureTax uses the date of the original sales order being refunded so that the tax obligations are the same as the time of sale.

Installation Instructions

Pre-Requisites

  • CCH® SureTax® account
  • CCH® SureAddress™ account (if using Address Validation features)
  • Magento 2 configured with the following:
    • PHP configured with the following extensions:
      • OpenSSL (for example, enable extension php_openssl.dll in php.ini)
        • SoapClient (for example, enable extension php_soap.dll in php.ini)
        • Curl (for example, enable extension php_curl.dll in php.ini)
        • In the Curl Section:
          • curl.cainfo must be set in php.ini
  • CCHSureTax for B2B extension
    • If Magento B2B module is installed with your Adobe Commerce Instance, then WoltersKluwer_CCHSureTaxB2B extension needs to be installed. Please See Installation section.

Installation

There are two ways to install the CCH SureTax for Magento 2 plugin. You can install using composer or manually install it.

Install using composer

  1. Buy the extension at Magento Marketplace.
  2. Go to magento root directory
  3. Enable magento maintenance mode
  4. Run following based on the Magento Edition
    1. Adobe Commerce Edition
      1. composer require wolterskluwer/cchsuretax:1.4.2
    2. If B2B module is installed then run the following command to get CCHSureTax B2B extension
      1. composer require wolterskluwer/cchsuretaxb2b:1.0.0
    3. Magento OpenSource Edition
      1. composer require wolterskluwer/cchsuretax-ce:1.4.2
    4. Note: Check the version numbers before running the commands. Above mentioned are examples.
  5. Follow prompts on the screen
  6. Disable maintenance mode
  1. In your Magento 2 installation, create a folder named
    1. app/code/WoltersKluwer/CCHSureTax.
  2. Extract the contents of the CCH SureTax extension ZIP file and copy the contents to the above directory.
  3. Open a terminal window and run the following commands from your Magento 2 installation directory:
    1. php bin/magento setup:upgrade
    2. php bin/magento setup:di:compile
    3. php bin/magento setup:static-content:deploy
    4. php magento cache:flush

Configuring the CCH SureTax Extension

There are five steps to configuring the CCH SureTax Extension for Magento:

  1. Configure the global settings.
  2. Configure the website and store information.
  3. Configure the customer group information.
  4. Configure the customer-specific information.
  5. Configure additional fields in Magento.

Configuring Global Settings

The global information of the CCH SureTax configuration contains information that is applicable across the Magento installation. To configure global settings, select Store > Configuration.

Select Default Config as the Store View.

Navigate to Sales tab > Tax. When you save the configuration, the connection to CCH SureTax is tested using the URL, client number, and validation key entered. All configuration values are saved, but if an error occurs, you are notified.

CCH SureTax Connection Settings

  • Enable SureTax Calculation. Activate the extension for the entire Magento installation by selecting 'Yes'.
  • Environment. Choose whether you want to configure settings for the Production or Development environment.
  • Client Number. Your CCH SureTax client number, which you get from your CCH SureTax representative. Validated when the configuration settings are saved.
  • Data API Client Number. Your CCH SureTax Data API client number.
  • URL. The URL for CCH SureTax calculation.
    • Note: The URL for CCH SureTax calculation will look similar to the following: https://<hostname>/Services/V07/SureTax.asmx
  • Data API URL. URL for CCH SureTax Data API webservice.
    • Note: The URL for Data API will look similar to the following: https://<hostname>/v01/
  • Data API Validation Key. Your CCH SureTax company validation key.
  • Select the Import CCH SureTax Data. CCH SureTax Web Services imports the data required to complete the setup.
  • Validation Key. Your CCH SureTax company validation key, which you get from your CCH SureTax representative. Validated when the configuration settings are saved.

CCH SureTax Settings

  • Business Unit. The business unit that will be sent to CCH SureTax for all transactions from the Magento installation unless a business unit is specified for a website or store. The maximum length of business unit is 20 characters. Reporting within CCH SureTax allows filtering by business unit.
  • SKU Option. Select an option to indicate which field will be sent as the SKU to CCH SureTax.
    • When 'SKU' is selected, it is important to create SKU mappings of the following in CCH SureTax portal:
      • 'Shipping' is sent as the CCH SureTax TransTypeCode in calculation requests for Shipping.
      • 'Gift Wrap' is sent as the CCH SureTax TransTypeCode in calculation requests for gift wrap lines.
      • 'Gift Wrap Printed Card' is sent as the CCH SureTax TransTypeCode in calculation requests for gift wrap printed card lines.
  • Finalize Option. Choose whether to finalize transactions. If 'No' is selected, then only queries will be sent to CCH SureTax.
  • Error Handling During Order Placement. Choose how to handle errors during order placement.
  • Enable Debug Logging. Select option to Enable Debug Logging.
    • Note: This should only be used for debugging. User should set up log rotation or clean up this log since it can grow to a large size.
  • Configure Decimal Places. Select option to set decimal places in the amounts returned from SureTax Response.
  • Default Shipping Transaction Type Code. Configure the default shipping transaction type code.
  • Default Gift Wrapping Transaction Type Code. Configure the default gift wrapping transaction type code.
  • Default Gift Wrapping Printed Card Transaction Type Code. Configure the default gift wrapping Printed Card transaction type code.
  • Default Transaction Type Code. Configure the default transaction type code.
  • Default Sales Type Code. Configure the default Sales type code.
  • Default Provider Type Code. Configure the default Provider type code.
  • Default Exemption Code. Configure the default Exemption code.
  • Default Exemption Reason Code. Configure the default Exemption Reason code.
  • Return Sales Tax Only. Configure whether to Return Sales Tax Only.

CCH SureAddress Connection Settings

  • Enable CCH SureAddress. Configure Enable CCH SureAddress.
  • Environment. Choose whether you want to configure settings for the Production or Test environment.
  • Client Number. Your CCH SureAddress Data API client number.
  • Validation Key. Your CCH SureAddress company validation key.
  • URL. URL for CCH SureAddress web service.
    • Note: The URL for CCH SureAddress will look similar to the following: https://<hostname>/sureaddress.asmx

CCH SureAddress Settings

  • Address Option. This option gives store admin ability to choose how the address validation behaves by selecting between Original Address vs Verified address or Automatic Address Update.
    • Options:
      • Select Address: Option to select the address between original address and validated address
      • Automatic Update: Updates the address to validated address.

CCH SureAddress Integration Points

Address validation (AV) using CCH SureAddress is integrated with Magento in the following sections:

  • Website > Place Order > Checkout process - AV is automatic for Address on Shipping Page
  • Magento Admin > Place Order form contains a 'Validate Address' button
  • Magento Admin > Customers > Edit > Addresses Section contains a 'Validate Address' button
  • Website > Registered user account management > Address Book contains a 'Validate Address' button
  • Magento Admin (Magento 2.3+) > Stores > Sources > New or Edit > Address Data Section contains a 'Validate Address' button Note: For the above items we assume CCH SureAddress is enabled. The user is given the option to select an "Original" or "Verified" address.

Configuring Website and Store Information

The Website and Store Information of the CCH SureTax configuration contains information that is applicable to an individual website or store. By default, an individual store is configured the same as the website to which the store belongs. In this case, the settings of the website will be sent to CCH SureTax. If a store is configured differently than the website to which the store belongs, then the settings of the store will be sent to CCH SureTax. If neither the store nor the website are configured, then the global settings will be sent to CCH SureTax.

To configure website and store information, select the desired Website/Store as the Store View option. Set the configurations for the website/store similar to the global settings above.

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.

To configure customer group information, navigate to the desiredcustomer group page. Select the Configure SureTax Details tab, and configure the CCH SureTax details for the customer group.

  • Sales Type Code. The type of customer that is purchasing each item.
  • Exemption Code. Specify whether the customers in the group qualify as tax-exempt.
  • Exemption Reason. Specify the reason that the customers in the group qualify as tax exempt.

Once the configuration is added, click Save.

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 set up customers, navigate to the desired customer page. Select the Configure SureTax Details tab, and configure the details for the user.

  • Wolters Kluwer Customer ID: Option to select what is sent to CCH SureTax calculation for customer ID.
    • If 'Customer ID Option' is set to 'Use Wolters Kluwer Customer ID' (Stores > Configuration - Sales > Tax), this will be the customer ID sent for CCH SureTax calculation requests. This is data saved in table customer_entity, column wolterskluwer_customer_id.
      • Allows ability to use import customer ID from external systems.
    • Otherwise, Magento customer ID is used, which is increment_id column in customer_entity table.
  • Sales Type Code. The type of customer that is purchasing each item.
  • Exemption Code. Specify whether the customer qualifies as tax-exempt.
  • Exemption Reason. The reason that the customer qualifies as tax-exempt.

Once the configuration is added for the customer, click Save.

Configuring Magento Fields

The Default 'Ship From Address' should be configured, and the Base Currency should be configured to "US Dollar." For more information on configuring these setting in Magento, see the Magento documentation. CCH SureTax Location Id has been added to Shipping Origin settings. This Location ID is sent in the SureTax Request at item level.

Discounts

The discount amount is deducted before the tax calculation, and these line item amounts are used for tax calculation. Magento Discount settings support details:

  • Apply Customer Tax After Discount. This is supported.
  • Apply Customer Tax Before Discount. This is not supported and options is ignored.
  • Apply Discount on Prices Excluding Tax. This is supported.
  • Apply Discount on prices including Tax. This is not supported and may have unpredictable behavior if enabled.

Catalog Price Rules setting for "Apply to Shipping Amount" as "Yes" are not supported for the following discount scenarios (known limitation):

  • Fixed amount discount
  • Fixed amount discount for whole cart
  • Buy X get Y free (discount amount is Y)

Fees Support with Magento Fixed Price Tax (FPT)

FPT is used to support fees (a type of fixed tax) that can be calculated by CCH SureTax for certain products. To set up FPT, do the following:

  1. In CCH SureTax portal, you must map to the appropriate SKU that may have a fee. Alternatively, if you use the TransTypeCode option, you can set the TransTypeCode to the product in Magento Admin.
  2. In Magento Admin, select "Yes" in Stores > Configuration > Sales > Tax > Fixed Product Taxes > Enable FPT.

Recommended settings in Magento Admin for FPT (see below screenshot):

FPT screenshot

Display Price in Sales Modules has to be set to including to show the Fee (see below screenshot). Note that Fee is saved as 'tax_fee':

Tax Fee screenshot

Setting Up Products

The product tax class in Magento is sent to CCH SureTax as the transaction type indicator. These values determine the taxability of products.

Verify that each product tax class in the list has been properly mapped in CCH SureTax.

Important Notes about the CCH SureTax Extension for Magento

  • Taxes are calculated in CCH SureTax when a sales order is created.
  • Tax calculations are based on the shipping address.
  • Taxes are recorded in CCH SureTax when an invoice is created.
  • All invoices will use the date of the original sales order to calculate the amount of tax to record.
  • All credit memos will use the date of the original sales order to calculate the amount of tax to refund.
  • Default tax reporting in Magento displays tax collected by each tax rule you created in the system. However, when using CCH SureTax, Magento tax rules are typically not used; instead, tax rules and calculations are configured within CCH SureTax. Because of this, Magento's tax report may show there are no Magento tax rules collecting tax. A full tax report is available within CCH SureTax.
  • Taxes are calculated in CCH SureTax for orders placed with a shipping address within the United States, United States Territories, or Canada.
  • Tax calculations are based on the shipping address. If the shipping address is changed on a sales order when viewing the order instead of editing the order, Magento does not recalculate the taxes. To ensure accurate tax calculations, the sales order should be edited to change the shipping address.
  • Magento system configuration settings to display taxes in the catalog are not supported by the CCH SureTax extension. Catalog prices cannot be configured to display real-time taxes. Magento system configuration settings to apply discounts after taxes are calculated are not supported by the CCH SureTax extension. Discounts are applied to reduce the tax base prior to the calculation of taxes by CCH SureTax.
  • In certain cases, there may be a one cent discrepancy in the amount of tax calculated at the line item level and the amount of tax returned at the invoice level. Further, if multiple invoices are created for the same customer in succession, Magento will distribute this penny between the various invoices. The discrepancy is due to a rounding issue within Magento and is not related to the tax calculations performed by CCH SureTax.
  • When there are multiple credit memos for an order, there may be a one cent discrepancy between the amount of tax calculated on the order and the amount of tax Magento can credit on the final credit memo. This discrepancy is due to the rounding of taxes on individual items and is not related to the tax calculations performed by CCH SureTax. If the credit memo cannot be saved because of this difference, a one cent adjustment fee should be added to the credit memo.

Sources Inventory Support (Magento 2.3 Only)

With Magento 2.3+, CCH SureTax setting can be configured for Default Ship-From Address for Tax Calculation to use Sources. If enabled, the default source will be used as Ship-From address for their respective line items.

Notes:

  • Order level line items (Shipping, Gift Card, and Gift Wrap Order) will use the Origin Address as the Ship-From address.
  • After order is placed and a different source is selected (e.g. during Shipping), the tax calculation will not reflect these changes.

Using the CCH SureTax Extension

Configuring Customers

To accurately calculate taxes on orders for different customers, customers need to be categorized by the type of sales. If customers are exempt from paying taxes, this information needs to be communicated to CCH SureTax. In order to communicate this to CCH SureTax, customers need to be configured in the CCH SureTax extension. See Configuring Customer Information on page 8 for instructions on configuring customers.

Configuring Sales

Tax calculations are sent to CCH SureTax based on the shipping address. Transactions can be identified in CCH SureTax using the sales order number. If the extension has an issue connecting to CCH SureTax, the Magento tax rules are used to calculate taxes thus continuing the shopping process like normal.

Shopping Cart

With the CCH SureTax extension enabled, quotes for taxes on items in the shopping cart are calculated by CCH SureTax. The use of CCH SureTax is transparent to the customer. The customer follows the same steps as taken during the Magento shopping experience. Once the customer specifies the shipping address, the tax estimate is calculated and displayed on the screen. Any changes in the shopping cart generate additional requests to CCH SureTax for new tax quotes.

Sales Orders

When the sales order is created, a quote request is sent to CCH SureTax to calculate taxes on the sales order. The quote transaction can be identified by the sales order number. The details of the tax calculation are stored in Magento for calculations on invoices and credit memos.

Order Grid

To view the CCH SureTax TransID, and look up orders in CCH SureTax portal do the following:

  1. Open Magento 2 Admin.
  2. Click the CCH SureTax icon
  3. Use the order grid

Checkout Process

The customer shopping experience during the checkout process does not change with the CCH SureTax extension. Requests for tax quotes are sent to CCH SureTax when changes are made in the checkout process. When the customer places the final order, a final request to calculate the taxes is sent to CCH SureTax with the order number specified in the request.

Invoices

Magento allows creation of invoices that total a portion of a sales order or the entire sales order amount. When the invoice is created, a request to formalize the taxes is sent to CCH SureTax. The transaction can be identified in CCH SureTax by the client tracking field which will match the invoice number. The date of the original sales order is used as the date on the finalization request to ensure that the taxes are calculated the same as on the sales order.

CCH SureTax calculates taxes for the items on an invoice when the request for the invoice is sent to CCH SureTax. If the taxes charged to the customer on the invoice differ from the taxes calculated by CCH SureTax, further action is required:

  • When the customer has been charged too much in taxes on the invoice, a tax adjustment is sent to CCH SureTax to adjust the tax obligation.
  • When the customer has not been charged enough in taxes on the invoice, the difference is stored in the CCH SureTax extension to be reported on the Transaction Report. See CCH SureTax Transactions on the next page.

Credit Memos

Magento allows creation of credit memos that total a portion of a sales order or the entire sales order amount. The CCH SureTax extension creates a credit transaction in CCH SureTax for each individual credit memo. The date of the original sales order is used as the date on the credit memo to ensure that the taxes are calculated the same as on the sales order. The transaction can be identified in CCH SureTax by the sales order number.

CCH SureTax calculates taxes for the items on a credit memo when the request for the credit is sent to CCH SureTax. If the taxes refunded to the customer on the credit memo differ from the taxes calculated by CCH SureTax, further action is required:

  • When the customer has not been refunded enough in taxes on the credit memo, a tax adjustment is sent to CCH SureTax to adjust the tax obligation.
  • When the customer has been refunded too much in taxes on the credit memo, the difference is stored in the CCH SureTax extension to be reported in the Transaction Report. See CCH SureTax Transactions on the next page.

Taxes

The CCH SureTax extension obtains all tax calculations from CCH SureTax. The only tax feature from Magento that is used by the extension is the Product Tax Classes. However, these must be properly configured to match the product mappings in CCH SureTax. See Setting up Products section for instructions on configuring product tax classes.

Note: Proper capitalization of the product tax class as defined in CCH SureTax is required.

If the CCH SureTax extension encounters errors during the processing of taxes or the CCH SureTax extension is disabled for any store, website, or the installation as a whole, the tax rates within Magento will be used to calculate taxes. Ensure that the tax rates are properly configured as described in the Magento User Guide.

Using Reports

The Order Taxes report within Magento groups the taxes charged by the tax rate used. Since the CCH SureTax extension does not typically use the Magento tax rates, this report will not display any of the taxes calculated by CCH SureTax. This report will show the subset of taxes collected that were not calculated by CCH SureTax. Detailed reports of taxes calculated by CCH SureTax should be obtained from CCH SureTax.

Processing with CCH SureTax

CCH SureTax Transactions Invoices

The report of CCH SureTax invoice transactions is available through the CCH SureTax > Transactions > Invoices menu from the Admin page. The report shows each invoice and, if applicable, information about the transaction sent to CCH SureTax. The transaction report includes the CCH SureTax identification, the status of the transaction in CCH SureTax, the tax recorded in Magento, the tax recorded in CCH SureTax, and any notes about the transaction. The report may be downloaded in either CSV or Excel XML format.

The report can be filtered by most fields:

  • ID. The line ID number
  • Invoice #. The Magento invoice number
  • Order #. The Magento sales order number
  • Date. The date of the Magento invoice
  • Magento Collected Tax. The amount of the tax stored in Magento
  • SureTax Calculated Tax. The amount of the tax calculated by CCH SureTax
  • Difference. A calculation of the difference between the taxes stored in Magento and the tax calculated by CCH SureTax
    • Note: You cannot filter reports by Difference.
  • SureTax Trans ID. An identification of the transaction in CCH SureTax
  • Client Tracking. The value that has been saved in the Client Tracking field in CCH SureTax
  • SureTax Status. An indication of whether the transaction was successfully created or adjusted in CCH SureTax
    • Finalized. Taxes were successfully calculated in CCH SureTax.
    • Finalize_Adjusted. Taxes were adjusted in CCH SureTax to reflect actual customer payments.
    • Finalize_Payment_Required. Taxes were successfully calculated in CCH SureTax, but additional taxes are due.
    • Finalize_Fail. Calculation request ran into issues and is not finalized in CCH SureTax.
    • Adjustment_Fail. Tax adjustment request ran into issues and is not finalized in CCH SureTax.
    • N/A. Taxes have not been processed in CCH SureTax.
      • Note. Additional information about the processing in CCH SureTax

Invoices Batch Processing

A group of invoices that have not been processed by CCH SureTax can be sent to CCH SureTax for processing from the transaction report. The purpose of reconciling transactions is to ensure invoices processed using stored taxes within Magento are posted to CCH SureTax. If there is a difference between the tax amount calculated by CCH SureTax and the amount calculated in Magento, tax only adjustments will be posted to CCH SureTax as appropriate. If the amount returned by CCH SureTax is greater, the under payment will be posted to the SureTax Invoice report. If the amount returned by CCH SureTax is less, then a tax only adjustment will be posted to CCH SureTax.

  1. Select SureTax > Transactions > Invoices on the Admin page.
  2. All invoices that have been successfully processed in CCH SureTax will display the CCH SureTax identifier and show a CCH SureTax status of "Finalized" or "Finalize_Adjusted".
  3. Check any transactions you want to send to CCH SureTax that do not display a CCH SureTax identifier.
    • Note: You may select a maximum of 20 transactions.
  4. Select Batch Finalize from the Actions drop-down menu.
  5. Click Submit.

Credit Memos

The report of CCH SureTax credit memo transactions is available through the SureTax > Transactions > Credit Memos menu from the Admin page. The report shows each credit memo and, if applicable, information about the transaction sent to CCH SureTax. The transaction report includes the CCH SureTax identification, the status of the transaction in CCH SureTax, the tax recorded in Magento, the tax recorded in CCH SureTax, and any notes about the transaction. The report may be downloaded in either CSV or Excel XML format.

The report can be filtered by most fields:

  • ID. The line ID number
  • Credit Memo #. The Magento invoice number
  • Order #. The Magento sales order number
  • Date. The date of the Magento invoice
  • Magento Tax Refunded. The amount of the tax stored in Magento
  • SureTax Tax Refunded. The amount of the tax calculated by CCH SureTax
  • Difference. A calculation of the difference between the taxes stored in Magento and the tax calculated by CCH SureTax
    • Note: You cannot filter reports by Difference.
  • SureTax Trans ID. An identification of the transaction in CCH SureTax
  • Client Tracking. The value that has been saved in the Client Tracking field in CCH SureTax
  • SureTax Status. An indication of whether the transaction was successfully created or adjusted in CCH SureTax
    • Finalized. Credit memo was successfully placed in CCH SureTax
    • Finalize_Adjusted. Taxes were adjusted in CCH SureTax to reflect actual customer payments.
    • Finalize_Payment_Required. Taxes were successfully calculated in CCH SureTax, but additional taxes are due.
    • Finalize_Fail. Credit memo ran into issues and is not finalized in CCH SureTax.
    • Adjustment_Fail. Tax adjustment request ran into issues and is not finalized in CCH SureTax.
    • N/A. Taxes have not been processed in CCH SureTax.
      • Note. Additional information about the processing in CCH SureTax

Credit Memo Batch Processing

A group of credit memos that have not been processed by CCH SureTax can be sent to CCH SureTax for processing from the transaction report. The purpose ofreconciling transactions is to ensure credit memos processed using stored taxes within Magento are posted to CCH SureTax. If there is a difference between the tax amount calculated by CCH SureTax and the amount calculated in Magento, tax only adjustments will be posted to CCH SureTax as appropriate. If the amount returned by CCH SureTax is greater, then a tax only adjustment will be posted to CCH SureTax. If the amount returned by CCH SureTax is less, the under payment will be posted to the SureTax Invoice report.

  1. Select SureTax > Transactions > Credit Memos on the Admin page.
  2. All credit memos that have been successfully processed in CCH SureTax will display the CCH SureTax identifier and show a CCH SureTax status of "Finalized" or "Finalize_Adjusted
  3. Select any transactions you want to send to CCH SureTax that do not display a CCH SureTax identifier.
    • Note: You may select a maximum of 20 transactions.
  4. Click the Actions drop-down menu, and then select Batch Finalize.
  5. Click Submit.

Technical Documents

Module Specifications

The CCH SureTax extension for Magento includes the following major functionality: sales tax quote lookup, gift options, and sales tax calculation and storage in CCH SureTax.

Sales Tax Quote Lookup

During the shopping cart, checkout, and administrator order processes, taxes are computed by CCH SureTax and returned to Magento for display on screen. No detailed tax information is saved in CCH SureTax for reporting or review, but taxes are saved to Magento data structures. See: WoltersKluwer_SureTax_Model_Tax_Sales_Total_Quote_Tax

Gift Options

Taxability of gift wrapping and printed gift cards can be configured in Enterprise Edition. Taxes are computed for gift options by CCH SureTax based on the product tax class specified in the extension configuration. Gift option taxes are saved to Magento data structures. See: WoltersKluwer_SureTax_Model_Tax_Sales_Total_Quote_Giftwrap

Sales Tax Calculation and Storage in CCH SureTax

When an invoice or credit memo is created, taxes are computed by CCH SureTax and returned to Magento for storage. All detailed tax information is saved in CCH SureTax for immediate reporting or review. If the taxes calculated in CCH SureTax do not match the taxes calculated in Magento on an invoice or credit memo, a tax adjustment is saved to CCH SureTax as needed. The status of each transaction is stored in Magento with additional warning messages stored for each transaction that did not get successfully finalized, adjusted, or credited. See: WoltersKluwer_SureTax_Helper_WebService

CCH SureTax API Mapping

Magento Field CCH SureTax API Field
SureTax > Global > Client Number ClientNumber
SureTax > Global > Validation Key ValidationKey
SureTax > Global > Global BusinessUnit BusinessUnit (If a configuration has not been saved for the particular website or store)
SureTax > Global > Provider Type Item > RegulatoryCode
SureTax > Global > Tax Class for Shipping Item > TransTypeCode (On the item sent for the shipping amount)
SureTax > Global > Tax Class for Gift Options Item > TransTypeCode (On the item sent for gift wrapping or printed gift card amount)
SureTax > Website/Store > BusinessUnit Business Unit (The store business unit if a configuration has been saved for the store; otherwise the website business unit if a configuration has been saved for the website)
System > Configuration > Shipping Settings > Origin > Country Item > OriginCountryCode ShipFromAddress > Country (If a configuration has not been saved for the particular website or store or the website/store uses the default ship from address)
System > Configuration > Shipping Settings > Origin > Region/State ShipFromAddress > State (If a configuration has not been saved for the particular website or store or the website/store uses the default ship from address)
System > Configuration > Shipping Settings > Origin > Region/State ShipFromAddress > State (If a configuration has not been saved for the particular website or store or the website/store uses the default ship from address)
System > Configuration > Shipping Settings > Origin > City ShipFromAddress > City (If a configuration has not been saved for the particular website or store or the website/store uses the default ship from address)
System > Configuration > Shipping Settings > Origin > Street Address ShipFromAddress > PrimaryAddressLine (If a configuration has not been saved for the particular website or store or the website/store uses the default ship from address)
System > Configuration > Shipping Settings > Origin > Street Address Line 2 ShipFromAddress > SecondaryAddressLine (If a configuration has not been saved for the particular website or store or the website/store uses the default ship from address)
SureTax > Website/Store > Ship From Address > Street Address Line 1 ShipFromAddress > PrimaryAddressLine (The address within the configuration for the store; otherwise the address within the configuration for the website)
SureTax > Website/Store > Ship From Address > Street Address Line 2 ShipFromAddress > SecondaryAddressLine (The address within the configuration for the store; otherwise the address within the configuration for the website)
SureTax > Website/Store > Ship From Address > City ShipFromAddress > City (The address within the configuration for the store; otherwise the address within the configuration for the website)
SureTax > Website/Store > Ship From Address > Country Item > OriginCountryCode; ShipFromAddress > Country (The address within the configuration for the store; otherwise the address within the configuration for the website)
SureTax > Website/Store > Ship From Address > State ShipFromAddress > State (The address within the configuration for the store; otherwise the address within the configuration for the website)
SureTax > Website/Store > Ship From Address > Zip/Postal ShipFromAddress > PostalCode (The address within the configuration for the store; otherwise the address within the configuration for the website)
Sales > Tax > Product Tax Classes > Name Item > TransTypeCode
SureTax > Customer Groups > Sales Type Code Item > SalesTypeCode (If a configuration has not been saved for the particular customer)
SureTax > Customer Groups > Exemption Code Item > TaxExemptionCodeList (If a configuration has not been saved for the particular customer)
SureTax > Customer Groups > Exemption Reason Code Item > ExemptReasonCode (If a configuration has not been saved for the particular customer)
SureTax > Customers > Sales Type Code Item > SalesTypeCode (If a configuration has been saved for the customer)
SureTax > Customers > Exemption Code Item > TaxExemptionCodeList (If a configuration has been saved for the customer)
SureTax > Customers > Exemption Reason Code Item > ExemptReasonCode (If a configuration has been saved for the customer)

Appendix

Uninstalling the CCH SureTax for Magento 2 Extension

Uninstalling using command line

  1. If the extension is installed using composer then it can be removed from the command line.
  2. Run "php bin/magento module:uninstall WoltersKluwer_CCHSureTax"
  3. For detailed instructions please visit Official Link

Uninstalling Manually

  1. Magento extensions installed manually can use following steps to remove
  2. Remove all files and folders from the Magento 2 installation app/code/WoltersKluwer/CCHSureTax (you can remove the WoltersKluwer folder).
  3. Remove module WoltersKluwer_CCHSureTax from app/etc/config.php with a text editor.
  4. Remove module WoltersKluwer_CCHSureTax from the table setup_module. You can do this by connecting to your Magento 2 database (using MySQL Workbench or Toad) and running the following SQL script: DELETE FROM setup_module WHERE module=\'WoltersKluwer_CCHSureTax\';
  5. Open a terminal window and run the following command from your Magento 2 installationdirectory: php bin/magento setup:upgrade

Uninstalling Data

Warning: Take special care with the below steps. They will delete all your CCH SureTax transaction and configuration data saved by this extension. The below should only be done by an expert developer or DBA.

  1. Connect to your Magento 2 database (e.g. using MySQL Workbench or Toad) and run the following SQL scripts:
    • DELETE FROM core_config_data WHERE path LIKE \'%cchsuretax%\';
    • DELETE FROM core_config_data WHERE path LIKE '%cchsureaddress%'; Drop columns starting with "wolterskluwer" from Magento 2 table customer_group
  2. Drop tables with names starting with wolterskluwer_

Database Tables

  • Tables added:
    • wolterskluwer_suretax_creditmemo
    • wolterskluwer_suretax_invoice
    • wolterskluwer_suretax_exemption_codes
    • wolterskluwer_suretax_exemption_reason_codes
    • wolterskluwer_suretax_regulatory_codes
    • wolterskluwer_suretax_sales_type_codes
    • wolterskluwer_suretax_transaction_type_codes
  • Added Columns to Magento 2 tables:
    • customer_group:
      • wolterskluwer_exempt_code
      • wolterskluwer_exempt_rsn_code
      • wolterskluwer_sales_type_code
    • customer_entity
      • wolterskluwer_exempt_code
      • wolterskluwer_exempt_rsn_code
      • wolterskluwer_sales_type_code
      • wolterskluwer_customer_id
    • quote
      • wolterskluwer_trans_id
      • sales_order
      • wolterskluwer_trans_id

Invoice and Credit Memo Statuses

  • Finalized
  • Finalize_Fail
  • Finalize_Adjusted
  • Finalize_Payment_Required
  • Adjustment_Fail
  • Quote (When Finalize Option is set to "No" and a user either creates invoices, credit memos, or batch finalizes, the status will be set to quote for those.)

Tax Adjustments

  • Tax Adjustments to CCH SureTax may occur during the following scenarios:

    • Invoice is finalized
    • Credit Memo is finalized

  • Tax Adjustments are made by comparing the order placement tax vs the finalized tax returned by CCH SureTax.

    • For Invoices:
      • If finalized tax is greater than order placement tax:
        • Invoice's status is set to FINALIZED_PAYMENT_REQUIRED
      • If finalized tax is less than order placement tax:
        • Tax Adjustment web service call (SoapTaxAdjustmentRequest method) is made to CCH SureTax
          • If successful, the invoice's status is set to FINALIZED_ADJUSTED
          • If there's an error, the invoice's status is set to ADJUSTMENT_FAILED
    • For Credit Memos:
      • If finalized tax is less than order placement tax:
        • Credit memo's status is set to FINALIZED_PAYMENT_REQUIRED
      • If finalized tax is greater than order placement tax:
        • Tax Adjustment web service call (SoapTaxAdjustmentRequest method) is made to CCH SureTax
          • If successful, the credit memo's status is set to FINALIZED_ADJUSTED
          • If there is an error, the credit memo's status is set to ADJUSTMENT_FAILED

CCH SureTax Error Handling During Posting of Transactions

If finalizing in CCH SureTax is enabled and the extension encounters errors that post to CCH SureTax and returns an error, the following logic is performed:

  • When creating invoice, if we see any issues with CCH SureTax response, such as a status of Line Item Errors, then we cancel the transaction in CCH SureTax. This is to avoid invoices being posted with errors.
  • Credit Memos, and Batch finalize from CCH SureTax Invoices/Credit Memos forms have similar behavior as above.

Known Issues

  • Address Validation is not supported for multi-address shipping orders.
  • Native Magento Credit Memo inaccurately shows more taxes than collected when Gift Wrapping is included with the order.
  • When an order has a Gift-Wrapping item and payment is done using Gift Card, then the Gift-Wrapping amount is inaccurately excluded from the Gift Card (seen in Magento 2.1.11, but not seen in Magento 2.2.22).
  • CCH SureTax batch invoice and credit memo pages do not filter correctly when "Yes" is selected for the row checkbox filter.
  • Catalog Price Rules setting for "Apply to Shipping Amount" as Yes is not supported by this extension for handling of discounts on shipping tax calculated by CCH SureTax.
  • For certain case for multi-shipping order, the actual error message is not displayed if a single item with multiple quantities being shipped to different addresses if 'Show Error and don't Place Order' option is selected for calculation.
  • Magento does not provide any way to save a Fee that is incurred on shipping. Because of this issue Invoice and Credit Memo will always show that difference. Quote and Order forms do not have the same issue.