This repository has been archived by the owner on Apr 22, 2019. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 15
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
31 changed files
with
855 additions
and
18 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,100 @@ | ||
| <!-- This list is in each of the documentation files. Ensure any updates are applied to the list in each file. --> | ||
| # Documentation | ||
|
|
||
| - [Home](../README.md) | ||
| - [Getting Started](./getting-started.md) | ||
| - Extension Features | ||
| - [Sales Tax](./sales-tax.md) | ||
| - [Address Validation](./address-validation.md) | ||
| - [Customs, Duty & Import Tax (CDIT)](./customs-duty-import-tax.md) | ||
| - [Document Management (Tax Exemptions)](./document-management.md) | ||
|
|
||
| # Address Validation | ||
|
|
||
| ## Table Of Contents | ||
|
|
||
| - [Overview](#overview) | ||
| - [Configuration](#configuration) | ||
| - [Frontend Checkout](#frontend-checkout) | ||
| * [Caveats](#caveats) | ||
| - [Frontend Add/Edit Customer Address](#frontend-add-edit-customer-address) | ||
| - [Backend Add/Edit Customer Address](#backend-add-edit-customer-address) | ||
| - [Backend Order Creation](#backend-order-creation) | ||
| * [Caveats](#caveats-1) | ||
|
|
||
| ## Overview | ||
|
|
||
| This extension implements address validation in nearly every area where an address can be entered: | ||
|
|
||
| - Frontend Checkout | ||
| - Frontend add/edit customer address | ||
| - Backend order creation | ||
| - Backend add/edit customer address | ||
|
|
||
| The following sections explain how address validation works in the four areas listed above. Note: Address validation is not enabled for virtual orders (orders where only a billing address is required). | ||
|
|
||
| ## Configuration | ||
|
|
||
| 1. In the Magento admin, go to `Stores > Settings > Configuration > Sales > Tax`. Click on the **AvaTax - Address Validation** section. | ||
| 2. Review each of the options in this section and input the appropriate value. This is [a screenshot of the configuration options.](images/configuration_screenshot_2.0.0-rc1.png?raw=true) | ||
|
|
||
| ## Frontend Checkout | ||
|
|
||
| When a guest or a signed in customer proceeds from the **Shipping** step to the **Review & Payment** step, the address they submitted will be sent to AvaTax to be validated. | ||
|
|
||
| If the configuration setting **Allow User To Choose Original (Invalid) Address** has been set to **Yes**, both the Suggested Address and Original Address will be displayed: | ||
|
|
||
|  | ||
|
|
||
| If the configuration setting **Allow User To Choose Original (Invalid) Address** has been set to **No**, only the valid address will be displayed to the user: | ||
|
|
||
|  | ||
|
|
||
| If a signed in customer is checking out and their address gets validated, the address the customer selected will automatically be set to the suggested address once the customer proceeds to the **Review & Payment** step. If the customer selects the original address, their customer address will be updated to that address. This will happen every time the user selects a different address. | ||
|
|
||
| If the user submits an address that AvaTax cannot validate, an [error message](https://help.avalara.com/kb/001/Common_Error_Messages_returned_with_GetTax_and_Validate_Requests#Common_Error_Messages) will be displayed to give some indication to the user that their address may be incorrect. This does not disrupt the checkout process: | ||
|
|
||
|  | ||
|
|
||
| If the address is already valid or if the address is from a country that is not on the list of **Enabled Countries** for address validation, nothing will be displayed to the user. | ||
|
|
||
| If the user clicks the **edit your address** or **click here** links in the instructions, they will be navigated back to the **Shipping** step. | ||
|
|
||
| ### Caveats | ||
|
|
||
| - If a customer selects the suggested address and goes back to the shipping step, the customer address in the database will be validated but the address displayed to the customer will not appear to be validated. If they leave that address selected and proceed to the **Review & Payment** step, they will see no option to **Verify Your Address** and the valid address will already be assigned to the quote. | ||
| - Refreshing the page on the **Review & Payment** step removes the **Verify Your Address** section. The address that was selected before the refresh will be the shipping address on the quote. This also has the effect of negating the first caveat. The user still has the ability to progress to the first step and submit a different address for validation but the address the initially submitted will already be valid so they will not see the **Verify Your Address** section after progressing to the **Review & Payment** step. | ||
| - New addresses created by a signed in customer will not be validated until they progress from the **Shipping** step to the **Review & Payment** step. | ||
| - Address validation for multi-address checkout is not available. | ||
|
|
||
| ## Frontend Add/Edit Customer Address | ||
|
|
||
| When a customer is adding or editing an address tries to save that address, they will be presented with a modal displaying this **Verify Your Address** form: | ||
|
|
||
|  | ||
|
|
||
| If the customer clicks the **x** icon, the **edit your address** link, or the **Edit Address** button, the modal will close and the form will not be submitted. If the customer clicks **Save Address** with the suggested address selected, the fields which are highlighted will be updated in the form and the form will be submitted. Otherwise, the original address will be submitted without any modifications to the form fields. If the config field **Allow User To Choose Original (Invalid) Address** is set to **No**, and the customer clicks save address, the valid address will be submitted. If the API response returns an error, that error will be displayed to the customer just as it is in the checkout. The customer will then have the option of either editing their address or saving it. If the address is not located inside one of the enabled countries or is already valid, nothing will be displayed to the user and the form will be submitted normally. | ||
|
|
||
| ## Backend Add/Edit Customer Address | ||
|
|
||
| Address validation in this area is triggered by clicking the **Validate Address** button at the bottom of an address form: | ||
|
|
||
|  | ||
|
|
||
| If the address is already valid, a success message will appear displaying the message *"This address is already valid"*. If the address is not from one of the enabled countries, an error message will appear displaying the message *"Address validation is not enabled for the country you selected"*. After the address has been validated, the suggested address will automatically be selected and the form will be updated. Selecting either address will update the form with that address. Clicking the **edit your address** link will scroll to the top of the page. | ||
|
|
||
| If the address is unable to be validated (see screenshot below), a message will be displayed indicating the reason why the validation failed (e.g. *"An exact street name match could not be found"* or *"The address number is out of range"*). The customer address can be revised by clicking the provided link; saving the customer record at this point will save the address as entered. | ||
|
|
||
|  | ||
|
|
||
| ## Backend Order Creation | ||
|
|
||
| Address validation in this area is also triggered by clicking the **Validate Address** button of the bottom of the Billing or Shipping Address forms. If **Same As Billing Address** is checked, the **Validate Address** button will not exist below the Shipping Address form. After the **Validate Address** button is clicked, a modal will appear displaying the same form that is displayed in the frontend add/edit customer address area: | ||
|
|
||
|  | ||
|
|
||
| If the address is already valid, a success message will appear displaying the message *"This address is already valid"*. If the address is not from one of the enabled countries, an error message will appear displaying the message *"Address validation is not enabled for the country you selected"*. | ||
|
|
||
| ### Caveats | ||
|
|
||
| - If an admin is editing an existing order and they edit the **Shipping Address** or **Billing Address**, form validation is not available. This use case is not supported by this extension. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,78 @@ | ||
| <!-- This list is in each of the documentation files. Ensure any updates are applied to the list in each file. --> | ||
| # Documentation | ||
|
|
||
| - [Home](../README.md) | ||
| - [Getting Started](./getting-started.md) | ||
| - Extension Features | ||
| - [Sales Tax](./sales-tax.md) | ||
| - [Address Validation](./address-validation.md) | ||
| - [Customs, Duty & Import Tax (CDIT)](./customs-duty-import-tax.md) | ||
| - [Document Management (Tax Exemptions)](./document-management.md) | ||
|
|
||
| # Customs, Duty & Import Tax (CDIT) | ||
|
|
||
| ## Table Of Contents | ||
|
|
||
| - [Overview](#overview) | ||
| - [Configuration](#configuration) | ||
| * [Shipping Method Mapping](#shipping-method-mapping) | ||
| - [Known Issues](#known-issues) | ||
| - [Cross Border Class Management](#cross-border-class-management) | ||
| * [Basic Steps to Setup Cross Border Classes](#basic-steps-to-setup-cross-border-classes) | ||
| * [Example Cross Border Class - HS Code](#example-cross-border-class---hs-code) | ||
| - [Seller is Importer of Record Override](#seller-is-importer-of-record-override) | ||
|
|
||
| ## Overview | ||
|
|
||
| > Important Note: This extension's support for this Avalara feature is currently in beta and requires that you [install version 2.x.x of of the extension](./getting-started.md#install-via-composer). | ||
| This AvaTax connector for Magento provides a set of features to support Customs Duty and Import Tax (hereafter referred to as CDIT). These features include: | ||
|
|
||
| - HS Code and Unit of Measure configuration for Products and their Destinations | ||
| - Map Native and Custom Shipping Methods with AvaTax’s shipping modes | ||
| - Display CDIT tax summaries in Emails, Checkout, and Admin Orders/Invoices/Credit Memos | ||
| - Configuring CDIT Passthrough and Non-Passthrough | ||
|
|
||
| ## Configuration | ||
|
|
||
| 1. In the Magento admin, go to `Stores > Settings > Configuration > Sales > Tax`. Click on the **AvaTax - Customs** section. | ||
| 2. Review each of the options in this section and input the appropriate value. This is [a screenshot of the configuration options](images/configuration_screenshot_2.0.0-rc1.png?raw=true). | ||
| 3. CDIT will only work for countries that have AvaTax enabled for them, which is found under `AvaTax - General > Taxable Countries` | ||
|
|
||
| ### Shipping Method Mapping | ||
|
|
||
| You can configure what Magento shipping methods map to AvaTax's shipping methods by selecting Magento Shipping methods in each of the AvaTax options of Air, Ocean, or Ground. The AvaTax connector only knows about the core shipping methods. If you use shipping methods from other extensions, you can utilize the `Custom Shipping Mode Mappings` table by specifying the AvaTax shipping mode and the custom shipping method code used by Magento. | ||
|
|
||
| For your convenience, you can also specify a default AvaTax shipping mode that will be used if no mapping was found in the aforementioned configuration properties. This can be useful if you typically only ship using one AvaTax mode. | ||
|
|
||
| ## Known Issues | ||
|
|
||
| * Due to lack of support from the Avalara API, any HS Codes that have required "Unit of Measure" parameters can not be used. | ||
|
|
||
| ## Cross Border Class Management | ||
|
|
||
| In order for Magento to properly send **HS Codes** and **Unit Amounts** to AvaTax for CDIT calculation, you must setup **Cross Border Classes**. A **Cross Border Class** defines a relation between **Cross Border Types** and destination countries, along with their relevant properties such as **HS Code**, **Unit Amount**, etc. | ||
|
|
||
| Magento utilizes **Cross Border Classes** by comparing the **Cross Border Type** defined on a product in the quote and the destination country specified in the ship to address of the quote. If there is a matching **Cross Border Class**, then that **Cross Border Class'** relevant properties are sent along to AvaTax when calculating tax. If a **Unit Name** and **Unit Amount Attribute** are specified on the **Cross Border Class**, then Magento retrieves the value of the **Unit Amount Attribute** on the product. | ||
|
|
||
| ### Basic Steps to Setup Cross Border Classes | ||
|
|
||
| 1. Create Cross Border Type | ||
| 2. (Optional) Create Product Unit Value attribute and assign to attribute set | ||
| 3. Create Cross Border Class | ||
| 4. Assign Created Cross Border Type to Products | ||
| 5. (Optional) Assign Unit Value to Products | ||
|
|
||
| ### Example Cross Border Class - HS Code | ||
|
|
||
| Let's assume a customer is purchasing a V-Neck sweater. This V-Neck sweater, when shipped to Canada, should have an HS Code of 6109900090. To achieve this, we must do the following: | ||
|
|
||
| 1. Create a Cross Border Type. For demonstration purposes, we created a Cross Border Type of **Vneck** | ||
| 2. Create a Cross Border Class. This class will specify a destination country of CA, a Cross Border Type of **Vneck**, and an HS code of 6109900090 | ||
| 3. Modify our Magento product, **V-Neck Sweater**, to have a Cross Border Type of **Vneck** | ||
|
|
||
| After performing those steps, if we add **V-Neck Sweater** to our cart, proceed to checkout, and select a shipping address in Canada, we should now see CDIT tax displayed in the tax summary display in the cart. | ||
|
|
||
| ## Seller is Importer of Record Override | ||
|
|
||
| By default, Magento does not send to AvaTax any value for `SellerIsImporterOfRecord`, but rather relies on your to configure your AvaTax account with the proper settings. However, should you need to modify this value on a per-customer basis, the AvaTax connector provides you the ability to specify on a customer record, whether to force the `SellerIsImporterOfRecord` value to be `Yes` or `No`. |
Oops, something went wrong.