Configuring the Adobe Commerce Extension

An Adobe Commerce extension for Taxamo Assure by Vertex is available here on the Adobe Commerce Marketplace.

This extension is only for Adobe Commerce users and is not required for other types of deployments.

The extension is intended for Adobe Commerce store owners who are based in Great Britain and Northern Ireland and meet the following criteria:

• You sell low value physical goods to consumers based in the EU.
• You do not want to register for VAT using an intermediary for Import One-Stop Shop (IOSS).
• You want to want to transfer VAT remittance liability to Taxamo.
• You want to use Taxamo’s IOSS number with your parcel carrier.

Taxamo will be responsible for collecting and remitting the VAT for IOSS-eligible sales and for filing the IOSS return each month.

You will need to send Taxamo's IOSS number to your parcel carrier for the relevant IOSS sales.

This service does not apply to digital goods. You cannot use it for Business-to-Business (B2B) transactions.

Supported Software

We recommend that you use Adobe Commerce Version 2.4.4 to ensure the best experience.

This version of the extension has been tested with Adobe Commerce Versions 2.3.7 and 2.4.4.

For more information about the different versions of the extension, see Adobe Commerce Release Notes.

❗️

Warning

If you are upgrading to a more recent version of the extension, you need to remove the older version before you install it.

Restrictions

The following restrictions apply:

• Refunds: You cannot use the extension with the advanced returns module (RMA) in Adobe Commerce 2.x.x. Instead, you can use the Credit Memo function to issue a refund.
• Credit Memo Refunds: Adjustment fees and adjustment refunds are not sent for orders where Taxamo is liable. This does not apply to orders where Taxamo is not liable.
• Shipping: Adobe Commerce Multi-Shipping is not supported by the extension. You must ship from a single location in Great Britain and Northern Ireland.
• Gift Cards: Gift cards are not supported. This includes partial payments where a gift card is used.
• Currency Rates: You cannot set currency rates for display purposes.
• Payment Options: Cash on Delivery is not supported.
• Product Type Restrictions: Physical goods are the only product type that is supported. The service does not return any tax information for other goods like virtual goods. For more information, see the Product Type Restrictions section of this document.

Configuration Overview

To configure the extension, complete the following steps:

1. Configure Taxamo Assure by Vertex.
2. Install and configure the extension. You can install it using Composer.

Taxamo Assure by Vertex Configuration

The Taxamo Assure by Vertex service is offered in two environments:

• Sandbox: Use this environment to do test setup and configuration. You can create and confirm transactions here without entering a credit card or incurring any charges.
• Production: Use this environment to create actual transactions. For IOSS qualifying transactions, the service charges 2 EUR per parcel sent. You need to enter your actual credit card information.

Sandbox Configuration

1. Sign up for the sandbox environment.
   You use the sandbox environment to test your integration. After you complete the testing there, you must move to the production environment.
   To sign up for the sandbox, go to https://manage.sandbox.marketplace.taxamo.com/auth.html#self-signup/Taxamo.

2. Configure billing (mandatory) and other settings (optional) in the Sandbox.
   You need to add the test credit card information in the Sandbox environment. This is a requirement. For more information, see Configuring Billing Information.
   You can also configure other settings such as invoicing. For more information, see Settings Overview.

❗️

Warning

Do not enter your VAT number in the VAT Number field on the dashboard in the Sandbox system.

3. Retrieve your access token.
   You need an access token to authenticate the requests that you send to the API. You need to retrieve and note this.
   To retrieve the access token:
   a. Open the dashboard at https://manage.sandbox.marketplace.taxamo.com.
   b. Enter the email that you registered in the User field and enter the password that you were sent when you activated the registration.
   d. Go to Settings > View API Access Tokens.
   e. To view the token, click Reveal.

❗️

Warning

The API access token is intended to be known only by you. Do not save it to source code repositories such as GitHub or Mercurial. If you must share it, for example with the person doing your configuration, do so in a secure manner. If it is compromised, you can reset it in the Taxamo Assure by Vertex dashboard.

Production Configuration

1. Sign up for the Production environment.
   To sign up for it, go to https://manage.marketplace.taxamo.com/auth.html#self-signup/Taxamo.

2. Configure billing (mandatory) and other settings (optional) in the Production environment.
   You need to add your actual credit card information in the Production environment. This is a requirement. For more information, see Configuring Billing Information.
   You can also configure other settings such as invoicing. For more information, see Settings Overview.

3. Retrieve your access token from the Production environment.
   You need an access token to authenticate the requests that you send to the API. You need to retrieve and note this.
   To retrieve the access token:
   a. Open the dashboard at https://manage.marketplace.taxamo.com.
   b. Enter the email that you registered in the User field and enter the password that you were sent when you activated the registration.
   d. Go to Settings > View API Access Tokens.
   e. To view the token, click Reveal.
   Add the production access token to your API configuration.

Installing the Extension

You must use the command-line interface called Composer to install the extension. For detailed instructions, see General CLI installation

1. Order the extension on the Adobe Commerce Marketplace. Go to the Adobe Commerce Marketplace here.
2. Retrieve your access keys from here on the Adobe Commerce Marketplace.
3. Add the access keys to your project's auth.json file.
4. To install the extension in Composer in Adobe Commerce 2.4.4, enter the following command:

composer require vertexinc/taxamo-tax

To install the extension in versions before Adobe Commerce 2.4.4, enter the following command:

composer require vertexinc/taxamo-tax:1.0.0

5. To install the extension in Magento, run the following commands:

php bin/magento setup:upgrade
php bin/magento cache:flush
php bin/magento cache:clean

6. If you are using Production mode, run the following commands:

php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy

Adobe Commerce Configuration

1. Open the Adobe Commerce Admin panel and go to Stores > Configuration > Sales > Tax. The settings are under the Taxamo panel.
2. Enter the API token for the sandbox or production system in the API Token field. This is the token that you retrieved when you configured Taxamo Assure by Vertex.

❗️

Warning

Remember that you need to change this token when you want to connect to another system.

3. To enable the extension, choose Yes in the Enable field.

❗️

Warning

If you disable the extension using the General Configuration, the extension files are not removed from app>code. To delete these files, you need to use the module:disable command in the Command-Line Interface (CLI).
If you need to enable the extension again, you will need to reinstall the extension.

4. To switch between sandbox and production, select it from the Mode field. You need to ensure that you are using the correct API to connect to Taxamo Assure by Vertex.

❗️

Warning

Do not use the Sandbox environment to process real transactions from your production system. You must use Production for these transactions.

5. You need to ensure that your Ship From details are UK-based. To ensure this is the case, select Great Britain and Northern Ireland from the Ship From Address - Country Code field.

6. To enable the ship-to countries that you want Taxamo Assure by Vertex to calculate tax for, select them from the Enabled Countries list.

7. You can choose to display a tax liability message to your customers. This message is displayed in the Checkout Payment & Review step when Taxamo is not liable for a transaction in one of the enabled countries from the previous step. You can enter a message in the Tax Liability Message field.

8. Configure your CRON settings. CRON expressions define how often data is sent between Adobe Commerce and Taxamo Assure by Vertex. Three fields control the timing for these expressions. They are set to run every 5 minutes by default:

• Store Tax CRON Expression: Defines how often Store Transaction requests are sent.
• Confirm Tax CRON Expression: Defines how often the Confirm Transaction requests are sent.
• Refund Tax CRON Expression: Defines how often the Refund Transaction requests are sent.

📘

Note

It can take some minutes for any changes to take effect as this depends on the Cron scheduler settings in Adobe Commerce.

9. Configure Log Settings. To enable logging, choose Yes from the Enable Debug Log field. This ensures that logs are stored. When enabled, the following settings are available:

• Enable Log Cleansing: When set to Yes, enabled logs are cleaned by a cron job.
• Log Clean Cron Expression: Expression that defines the cron job's schedule for log cleaning.
• Log Retention Days: Number of days that logs are retained for while cleaning is enabled.

Using the Extension

When the extension is installed and configured, tax information is retrieved for qualifying transactions and returned in the customer's basket (if the shipping address is known) and at the checkout.

A qualifying transaction is one up to 150 EUR where Taxamo bears the liability under IOSS. These are called IOSS transactions. These must be shipped from Great Britain and Northern Ireland to the European Union (EU).

All other transactions are non-IOSS transactions. In these cases, no tax information is returned by Taxamo Assure by Vertex.

Taxamo Assure by Vertex calculates the tax rate when the following conditions are met:

• The extension is enabled.
• The transaction is an IOSS-qualifying transaction.
• The shipping address of the customer is known.
• The page the customer is using is enabled for Taxamo.
• The customer's basket does not contain any virtual products.

Product Type Restrictions

The extension only works with physical goods. It does not process transactions for virtual goods. If virtual goods are added to a basket, no tax information is returned by Taxamo Assure by Vertex.

Some virtual product types are:

• Virtual product type, including the Bundle product type where a virtual product is part of the bundle.
• Downloadable product type
• Gift card Virtual type for commerce only. This does not include the Combined type.

Viewing Tax Details

You can view the details for your transactions in the Adobe Commerce Admin panel under Sales > Order > Views.

For orders processed by Taxamo Assure by Vertex, the details are displayed in the Taxamo panel under Payment & Shipping. This displays the following values:

Credit Memos (Refunds)

When you issue a Credit Memo for an order in Adobe Commerce, an request is sent to Taxamo Assure by Vertex to
create a refund. Refunds in Taxamo are associated with specific line item/s on the order. This means that
Adjustment Refunds and Adjustment Fee changes in Adobe Commerce are not supported.

Alternatively, you can manually process refunds in the Taxamo Assure by Vertex dashboard. For more information, see Issuing Refunds from the Dashboard.

Email Configuration

For emails for orders, Adobe Commerce is responsible for sending the order emails to customers after the purchase. The Tax Line Item is displayed in the Total Orders section of the email. This will be populated with information from Taxamo where applicable.

For orders where Taxamo is liable, invoices are sent from Taxamo Assure by Vertex to the buyer. For more information about how to configure these invoices, see Configuring Invoices.

For orders where Taxamo is not liable, invoice emails are sent from Adobe Commerce.

For credit memos where Taxamo is liable, credit notes are sent from Taxamo Assure by Vertex to the buyer. For more information about how to configure these credit notes, see Configuring Invoices.

For credit memos where Taxamo is not liable, credit notes are sent from Adobe Commerce.

Viewing Orders in Taxamo Assure by Vertex

You can access the Taxamo Assure by Vertex dashboard using the URL that you received when you registered.

To view the transactions, go to the Taxamo Assure by Vertex dashboard and go to Transactions > List .

Error Logging

When enabled, the extension creates error and debug logs.

Errors are written to the log in the following situations:

• If Taxamo Assure by Vertex returns a response code other than 2xx, or it returns an error message.
• In the event of any sort of failure connecting to Taxamo Assure by Vertex.
• If any error occurs relating to the extension.

To view error logs, go to Stores > Taxamo: Logs. The file is var/log/taxamo-error.log.

When an error occurs, an admin notification message is displayed. This is indicated by a bell icon.

Debug Logging

The debug log is only updated if it is enabled in the General Configuration. When enabled, the
debug log will contain every request sent to Taxamo Assure by Vertex and every response sent back by it. The file is var/log/taxamo-debug.log.

Post-Configuration Tasks

1. Test the integration.
   After you have completed testing on your test store, ensure that all the relevant settings are applied to your production account. Verify that you can use the Production mode in the Adobe Commerce Admin UI with your production API token.
   For more information about testing the API, see Testing the API Integration.

2. Send Taxamo's IOSS number to your parcel carrier for the relevant IOSS sales.

❗️

Warning

Do not share this information with anyone else other than your parcel carrier.

Non-IOSS Transaction Handling

For transactions that do not qualify for IOSS (for example, for virtual goods or physical goods valued at more than 150 EUR) the extension does not return any tax information.

Mixed Baskets

If a buyer's basket contains both physical and virtual goods, and the physical goods are valued up to 150 EUR and qualify for IOSS, the service will process the physical goods. The service will not return any tax information for the virtual goods.

Shipping Charges

Shipping charges are taxed at the highest applicable standard rate, even for goods with reduced rates. For example if a transaction contains books that are taxed at a reduced rate of 10% to France, the standard rate of 20% is applied to the shipping charges.

Troubleshooting