Transcription
Integration GuideVertex Tax Links for Magento 2 - 4.2.0For Vertex Cloud and Vertex Indirect Tax O Series February 2021
Copyright and legal noticesCopyright 2021 Vertex, Inc. All rights reserved.This documentation may not be reproduced, displayed, distributed, modified, posted,republished, or transmitted in any form or by any means, without the prior written consent ofVertex, Inc. or its affiliates (collectively, “Vertex”), except as otherwise specified in a valid,current Vertex license agreement or allowed by law.DisclaimersThe information contained in this documentation is designed to help users in regard to thesubject matter covered. Some of it may be based upon interpretations of federal, state, foreignand other tax laws and regulations. Each entity is responsible for making its own determinationof how such laws and regulations apply to its own circumstances and for evaluating thecapabilities of, and all data and results generated by, any product that is described in thisdocumentation. Vertex is not engaged in providing legal, tax or accounting advice or servicesand the information contained in this documentation or in any product cannot replace theadvice of competent legal counsel. Further, the information in this documentation is subject tochange without notice and is not warranted to be error-free. If you find any errors, pleasereport them to us in writing.Trademarks and Service MarksThe trademarks, logos and service marks ("marks") displayed in this documentation are theproperty of Vertex or other third parties. Users are not permitted to use these marks withoutthe prior written consent of Vertex or the third party that may own the mark.Third Party ProductsCopies of the licenses for some third-party products included with a Vertex product may befound in or with the installation materials for that product.
ContentsPreface . 4About Vertex and our services . 4Contacting Vertex. 4About Vertex Tax Links for Magento 2 . 4About this guide . 5Chapter 1. Release Notes . 6Compatibility . 6Enhancements and fixes. 7Known issues . 11Chapter 2. Installation . 12Before you install. 12Environments . 12Vertex account information . 13System and data backup . 13Accessing Vertex Tax Links . 13No installation required for Magento 2 releases 2.2.11 and after 2.3.4 . 13Standard installation for Magento 2 versions 2.3.1 through 2.3.4 . 14Using Composer with automated kickoff (recommended) . 14Using Composer with manual kickoff . 15Troubleshooting . 17Authentication Required (repo.magento.com) message . 17Could not find package vertex/module-tax at any version [ ] . 18After you install . 18Uninstalling Vertex Tax Links . 18Chapter 3. Configuration . 20Architecture and design . 21Magento tax request flow . 22Tax calculation. 22API overview. 22Vertex Tax Links for Magento 2 configuration for Magento version 2.4.x . 37Accessing the Vertex Tax Links for Magento 2 configuration (version 2.4.x) . 37Vertex cache . 39Configurable data for Magento 2 (version 2.4.x) . 40Managing the Vertex Tax Links for Magento 2, version 2.4.x configuration . 41Vertex Tax Links for Magento 2 configuration for Magento versions prior to 2.4.x . 56Accessing the Vertex Tax Links for Magento 2 configuration. 57Vertex cache . 59Configurable data . 60Managing the Vertex Tax Links for Magento 2 configuration . 61Additional Vertex tax solution functions . 81Monitoring . 81Logging . 82Address Cleansing . 82Vertex Tax Links for Magento 2 Integration Guide - 4.2.0Log on to myVertex
PrefaceThis preface contains information about Vertex services, Vertex Cloud, Vertex Indirect Tax OSeries , and available documentation.About Vertex and our servicesVertex, Inc. is a leading tax software and services provider that empowers global commerce.Vertex connects customers and partners across all industries to deliver the world’s most trustedtax solutions for businesses to grow with confidence.Vertex provides cloud-based and on-premise solutions that can be tailored to specific industriesfor every major line of indirect tax, including sales and consumer use, value added, and payroll.Headquartered in Pennsylvania with offices worldwide, Vertex employs over 1,000 professionalsand serves companies across the globe. For office addresses and telephone numbers, go tohttp://www.vertexinc.com/contact.Contacting VertexContact details depend on whether you are integrating with Vertex Cloud or Vertex O Series asfollows: If you are integrating with Vertex Cloud, contact Vertex via email or phone: To contact Vertex by email: CloudSupport@VertexInc.com. To contact Vertex by phone: 1.855.221.5885. If you are integrating with Vertex O Series: To contact Vertex about technical support, account services, or training, go towww.vertexinc.com/contact/. To access technical information about your Vertex tax solution, go tohttps://vertexinc.custhelp.com/. To contact Vertex by phone: 1.800.281.1900.About Vertex Tax Links for Magento 2Vertex Tax Links for Magento 2 is a connector that integrates Magento 2 with Vertex taxsolutions for sales tax calculation. This functionality is available for the United States andCanada.Vertex Tax Links for Magento 2 Integration Guide - 4.2.0Log on to myVertex
Preface 5About this guideThis guide contains information to install and configure Vertex Tax Links for Magento 2 (Vertexconnector) with Vertex tax solutions. Magento is a highly customizable application, and thisguide provides instructions to help you leverage that capability.Vertex Tax Links for Magento 2 Integration Guide - 4.2.0Log on to myVertex
Chapter 1. Release NotesThis chapter provides information about Vertex Tax Links for Magento 2, version 4.x.Vertex Tax Links for Magento 2 is a connector that integrates Magento 2 with Vertex taxsolutions for sales tax calculation. This functionality is available for the United States andCanada, including U.S. E-commerce merchants selling products to consumers in the EuropeanUnion, where the associated ERP (not Magento) writes to the Vertex tax journal.For detailed information about installing and using Vertex Tax Links for Magento 2, refer to thefollowing chapters: Installation (see page 12)Configuration (see page 20)In this chapterCompatibility .6Enhancements and fixes .7Known issues .11CompatibilityVertex Tax Links for Magento 2 is supported as follows:Vertex Tax SolutionMagento 2Vertex O Series for Indirect Tax 7.0 using the 7.0 schemaVertex O Series for Indirect Tax 8.0 using the 7.0 schemaVertex O Series for Indirect Tax 9.0 using the 7.0 schemaVersion 2.2.11 through 2.4.2Vertex CloudVertex Tax Links for Magento 2 Integration Guide - 4.2.0Log on to myVertex
Chapter 1. Release Notes 7Enhancements and fixesThis section provides a release history of enhancements and fixes to Vertex Tax Links forMagento 2.Version 4.2.0 enhancements and fixes Added Commodity Code and Commodity Type fields in the Catalog section as productattributes. Added a back-end administration destination mapping feature that assists with Value AddedTax (VAT) calculations. Updated MFTF (for testing) to best practices.Version 4.0.0 enhancements and fixes Redesigned administration configuration to be more user friendly. Enhanced the Vertex connector to use the Shipping Origin address as the Seller in Vertex taxcalls. Limited scope of an issue where fixed-price bundle products tax did not include the addedcost of any options. This issue now occurs only if you have tax configured in Magento toapply to the original price only. Resolved an issue that caused taxes to not be calculated on an order with both physical andvirtual products before setting a billing address. Resolved an issue where tax details occasionally were missing from the database for recordkeeping. Removed superfluous plugins that affected administration order creation. Updated MFTF (for testing) to best practices. Renamed Sections and ActionGroups and updated documentation for running these testsagainst your Vertex test environment. Updated Integration Tests for compatibility with PHP Unit 9. Removed deprecated code. Removed ApiClient and ClientInterface and replaced with service-specific interfaces. Replaced Install and Upgrade scripts with an XML schema file and patches.Version 3.3.0 enhancements and fixes Vertex Address Validation is now included in the installation. When enabled, this moduleprompts to correct address information during both the shipping and billing steps of thebuilt-in, one-page checkout.Vertex Tax Links for Magento 2 Integration Guide - 4.2.0Log on to myVertex
Chapter 1. Release Notes 8 Vertex Trusted ID is now encrypted when saved to the database. Vertex Trusted ID is now masked in the Vertex log tables. Fixed Product Taxes created through Magento are now submitted to Vertex.Note: If you are using Fixed Product Taxes, consult your Vertex representative to determinehow this may affect your tax calculation. Vertex now supports the Magento configuration to charge tax on the original price or thecustom price.Vertex logs now include the time (in milliseconds) it took the Vertex API to return a result.Resolved an issue where, after installation, Vertex cache was disabled.Resolved an issue where entirely discounted shipping costs caused totals to be improperlyrecorded when taxes were submitted to Vertex.Resolved an issue where invoices were not created for bundled products when taxes weresubmitted to Vertex.Ensured that SKUs are not treated as integers when querying the database.Resolved an issue where the tax configuration page did not load.Resolved an issue where discounts increased the subtotal when taxes were calculatedthrough Vertex.Resolved an issue where Magento compilation failed on certain systems.Resolved an issue where line items with custom SKUs were not invoiced properly.Resolved an issue where the tax configuration page hung in the browser.Version 3.2.0 enhancements and fixes Enhanced the connector to support Vertex Flexible Fields, which enable a merchant to sendadditional information to the Vertex Tax Engine. This information can then be used in TaxAssist Rules to refine a product’s applicable tax. Refer to Managing the Vertex Tax Links forMagento 2 configuration for more information. Resolved an issue where an incorrect Customer Code was sent when Vertex invoices wereset to send during Order Status Change. Resolved an issue where assisted parameters were not requested and logged during Invoicecalls made during Order Status Change. Resolved issues where calls to Vertex were not made due to string values that were toolong. These are now trimmed to the maximum allowed length in the Vertex SDK (includingSKUs). Resolved an issue where the tax code, Vertex tax code, and invoice text codes were notsaved for orders created during Guest Checkout. Resolved an issue where Guest Orders were invoiced twice if logging was enabled.Vertex Tax Links for Magento 2 Integration Guide - 4.2.0Log on to myVertex
Chapter 1. Release Notes 9Resolved an issue where shipping was not included on a Vertex invoice if that invoice wassent in the same request when its Order was created if that order was placed using guestcheckout.Resolved an issue where taxes for Magento Commerce Gift Wrap were not properly writtento the Vertex Tax Journal.Version 3.1.0 enhancements and fixes Enhanced the connector to support configurable Vertex Delivery Terms. Enhanced the connector to support configurable ship-to countries. Enhanced the connector to support Business to Consumer Value Added Tax (B2C VAT) in theEuropean Union (EU). Enhanced the connector to support multiple tax summarization displays. Enhanced the connector to support configurable Vertex Logging. Enhanced the connector to use Magento Tax Rates when the ship-to country is notdesignated for Vertex Tax Links. Redesigned Vertex Settings to enhance performance. Logged exceptions now include parent exceptions in the log. Resolved an issue where changes in Customer Group were ignored when ordering throughthe Admin Panel. Resolved an issue where Vertex invoice message did not display on the Admin Panel whenusing Authorize.net as the payment method with an order status of Suspected Fraud. Added an error message when a "99999" ZIP code is entered as part of the shipping address. Resolved an issue where tax did not display in checkout for digital products. Removed an invalid address error message after the address was corrected. Resolved an issue preventing a VALID Vertex API Status when a non-default website wasconfigured. Added a warning message when Invoice When Order Status is selected but status is notselected. A Vertex Negative Invoice (Credit Memo) will no longer be sent if an Invoice is not sent first. A "Vertex invoice has been sent" message no longer displays for Storefront customers. Resolved an issue where bundled product extended prices were not passed appropriatelywhen the connector is configured to write to the tax journal based on order status. Resolved issue where connector ignored Catalog Price Rule. Resolved issue where Vertex Customer Code value is not persisted when another customerattribute is edited.Vertex Tax Links for Magento 2 Integration Guide - 4.2.0Log on to myVertex
Chapter 1. Release Notes 10Resolved an issue where the MainDivision (state/region) was not being sent to Vertex.Resolved an issue where installing Magento with an already existing config.php file failed.Resolved an issue where the customer code was not sent to Vertex during calculation andinvoicing.Resolved an issue where requests were not logged in production mode.Resolved compatibility issues when submitting an Invoice or Credit Memo in MagentoCommerce 2.1.Resolved issues where invoicing may fail if an invoice is being created during the samerequest as an order placement.Resolved issue where an error was generated during Braintree/Authorize.Net credit cardpayments.Version 3.0.0 enhancements and fixes Enhanced the connector to support O Series 7.0. Improved messaging for location when managing tax classes. Resolved issues when discounts were applied to the cost of shipping. Resolved issues where bundled products were incorrectly invoiced. Resolved issues where certain order statuses did not trigger Vertex invoicing. Resolved issues where the shipping rate was passed to Vertex incorrectly. Resolved issues where the Vertex Status bar was incorrect for certain scopes. Resolved issues where invoices and credit memos submitted incorrect data to Vertex forinvoicing. Resolved issues with calculation when checking out using PayPal with virtual products.Vertex Tax Links for Magento 2 Integration Guide - 4.2.0Log on to myVertex
Chapter 1. Release Notes 11Known issuesThis section describes known issues with Vertex Tax Links for Magento 2: Line item tax is inconsistent during storefront order creation (due to invoice-level rounding).The total tax recorded in the debug log during Invoice calls is always 0.The Magento Shopping Cart does not display the tax amount separately when the system isconfigured to display the price including tax.Address cleansing does not re-validate addresses that were updated during checkout.When an Invoice is created, Vertex performs a larger than necessary database query, whichsometimes causes an out-of-memory error.Vertex Tax Links for Magento 2 Integration Guide - 4.2.0Log on to myVertex
Chapter 2. InstallationThis chapter describes how to install and uninstall Vertex Tax Links for Magento 2.In this chapterBefore you install.12No installation required for Magento 2 releases 2.2.11 andafter 2.3.4 .13Standard installation for Magento 2 versions 2.3.1 through2.3.4 .14Troubleshooting .17After you install .18Uninstalling Vertex Tax Links .18Before you installThis section describes prerequisites before you begin to install Vertex Tax Links for Magento 2.Note: If your Magento instance has an earlier version of Vertex Tax Links installed, and youwant to upgrade your Vertex Tax Links version, you must uninstall the earlier version ofVertex Tax Links before upgrading.EnvironmentsEnsure that your environment can support Vertex Tax Links, as described below:Magento 2 version 2.2.0 through 2.4.2 is installed.PHP’s Composer package manager must be installed. Before installation, ensure that youhave composer.phar in Magento’s base directory. See the Composer download site(https://getcomposer.org/download/) for instructions on installing Composer.Refer to the Release Notes (see page 6) for more information about version compatibility,release history of fixes and enhancements, and descriptions of any known issues. Vertex Tax Links for Magento 2 Integration Guide - 4.2.0Log on to myVertex
Chapter 2. Installation 13Vertex account informationConfirm that you have the following account information provided by Vertex or your ITdepartment: Login user name and password, or a Trusted IDEndpoints for tax calculation and address verificationCompany name that you registered with VertexSystem and data backupAlways back up your files and data before making any significant changes to your webstore.Complete the following steps to perform a full backup of your Magento software and databefore installation:1. On the command line, type:php bin/magento setup:backup --code --media –db2. Press Enter.3. Copy the contents of var/backups to a safe location.Accessing Vertex Tax LinksWhen Vertex Tax Links for Magento 2, version 4.2.0, is not delivered as part of Magento’s corebundled extension, you can access the connector from the Magento Composer Repository.No installation required for Magento 2 releases2.2.11 and after 2.3.4As part of Magento's core bundled extension process, Vertex Tax Links for Magento 2 - versionis already installed when using a Magento 2 release after 2.3.4 (and version 2.2.11).Downloading and installing Vertex Tax Links is not required. Configure the connector using theinstructions in Chapter 3. Configuration (see page 20).Vertex Tax Links for Magento 2 Integration Guide - 4.2.0Log on to myVertex
Chapter 2. Installation 14Standard installation for Magento 2 versions2.3.1 through 2.3.4There are two ways to install Vertex Tax Links for Magento 2 using Composer:Automated kickoff - Refer to Using Composer with automated kickoff (see page 14) fordetails Manual kickoff - Refer to Using Composer with manual kickoff (see page 15) for detailsNote: Vertex recommends that you use the automated kickoff to install Vertex Tax Links forMagento 2. Using Composer with automated kickoff (recommended)Because the Vertex connector is bundled with Magento 2, merchants no longer need topurchase the connector from the Marketplace. This is also true for non-bundled versions ofMagento.Installing Vertex Tax Links using Composer with automated kickoffComplete the following steps to install Vertex Tax Links using Composer with automated kickoff:1. Enter the following command to tell Composer to require Vertex Tax Links for Magento:VersionCommand2.3.0php composer.phar require vertex/module-tax:"3.4.1 as 3.0.0" -update-with-dependencies2.3.1-2.3.2php composer.phar require vertex/product-magento-module:"3.4.1 as3.1.0" -- update-with-dependencies2.3.3php composer.phar require vertex/product-magento-module:"3.4.1 as3.2.0" -- update-with-dependencies2.3.3-p1php composer.phar require vertex/product-magento-module:"3.4.1 as3.2.1" -- update-with-dependencies2.3.4php composer.phar require vertex/product-magento-module:"3.4.1 as3.3.0" -- update-with-dependencies2.3.4-p2php composer.phar require vertex/product-magento-module:"3.4.1 as3.3.1" -- update with dependencies2.3.5 and2.3.5-p1php composer.phar require vertex/product-magento-module:"3.4.1 as3.4.0" -- update-with-dependenciesA message similar to Installingvertex/module-tax (4.0)displays.Vertex Tax Links for Magento 2 Integration Guide - 4.2.0Log on to myVertex
Chapter 2. Installation 15Notes:If Authentication required displays, refer to Authentication Required (see page 17).If there are other errors during this process, contact Vertex Support for more information.Refer to Contacting Vertex (see page 4) for details.1. Enter the following command to place Magento into maintenance mode: php bin/magento maintenance:enable2. Enter the following command to enable Vertex Tax Links version 4.0:php bin/magento module:enable Vertex Tax3. Enter the following command to update your Magento database:php bin/magento setup:upgrade4. Enter the following command to regenerate static content:php bin/magento setup:static-content:deploy5. Enter the following command to regenerate dependency injections:php bin/magento setup:di:compile6. Enter the following command to disable maintenance mode in Magento:php bin/magento maintenance:disableUsing Composer with manual kickoffNote: Vertex recommends that you do use the automated kickoff procedure (see page 14), notthis manual kickoff procedure.Before you can install Vertex Tax Links for Magento 2, you must first upload Vertex Tax Links toyour Magento server by completing the following steps:1. Download Vertex Tax Links for Magento - version 3.4.0 from https://vertexinc.custhelp.com/or the Magento Marketplace.2. In your Magento installation’s base directory (magento), create a directory labeled artifacts.Note: The process you use to create a directory varies based on your environment. One methodyou can use is the mkdir command: mkdir [magento]/artifacts.3. Upload the ZIP file for Vertex Tax Links for Magento 2 - version 3.4.0 to the[magento]/artifacts directory that you created.Note: The process you use to upload the ZIP file varies based on your environment. One methodyou can use is the wget command:wget [link to vertex tax links] -o artifacts/vertex-module-tax-3.4.0.zipwget [link to vertex sdk] –o artifacts/vertex-sdk-1.2.0.zipwget [link to vertex address validation module] .zipVertex Tax Links for Magento 2 Integration Guide - 4.2.0Log on to myVertex
Chapter 2. Installation 16Installing Vertex Tax Links using Composer with manual kickoffComplete the following steps to install Vertex Tax Links for Magento:1. Enter the following command to inform Composer that the artifacts repository exists:php composer.phar config repositories.vertex artifact artifacts2. Enter the following command to specify that Composer must require Vertex Tax Links forMagento:VersionCommand2.3.0php composer.phar require vertex/module-tax:"3.4.1 as 3.0.0" -update-with-dependencies2.3.1-2.3.2php composer.phar require vertex/product-magento-module:"3.3.0 as3.1.0" -- update-with-dependencies2.3.3php composer.phar require vertex/product-magento-module:"3.3.0 as3.2.0" -- update with dependencies2.3.3-p1php composer.phar require vertex/product-magento-module:"3.3.0 as3.2.1" -- update with dependencies2.3.4php composer.phar require vertex/product-magento-module:"3.4.1 as3.3.0" -- update-with-dependencies2.3.4-p2php composer.phar require vertex/product-magento-module:"3.4.1 as3.3.1" -- update with dependencies2.3.5 and2.3.5-p1php composer.phar require vertex/product-magento-module:"3.4.1 as3.4.0" -- update-with-dependenciesA message similar to Installing vertex/module-tax (3.4.0) displays.Note: If there are errors during this process, contact Vertex Support for more information. Referto Contacting Vertex (see page 4) for details.3. Enter the following command to place Magento into maintenance mode:php bin/magento maintenance:enable4. Enter the following command to enable Vertex Tax Links version 3.4.0:php bin/magento module:enable Vertex Tax5. Enter the following command to update your Magento database:php bin/magento setup:upgrade6. Enter the following command t
This chapter provides information about Vertex Tax Links for Magento 2, version 4.x. Vertex Tax Links for Magento 2 is a connector that integrates Magento 2 with Vertex tax solutions for sales tax calculation. This functionality is available for the United States and
