Umbraco Commerce Taxes Documentation

14/umbraco-commerce/SUMMARY.md

@@ -58,6 +58,7 @@
   * [Complex Variants](key-concepts/product-variants/complex-variants.md)
 * [Properties](key-concepts/properties.md)
 * [ReadOnly and Writable Entities](key-concepts/readonly-and-writable-entities.md)
+* [Sales Tax Providers](./key-concepts/sales-tax-providers.md)
 * [Search Specifications](key-concepts/search-specifications.md)
 * [Settings Objects](key-concepts/settings-objects.md)
 * [Shipping Package Factories](key-concepts/shipping-package-factories.md)
@@ -83,6 +84,9 @@
   * [Fixed Rate Shipping](reference/shipping/fixed-rate-shipping.md)
   * [Dynamic Rate Shipping](reference/shipping/dynamic-rate-shipping.md)
   * [Realtime Rate Shipping](reference/shipping/realtime-rate-shipping.md)
+* [Taxes](reference/taxes/README.md)
+    * [Fixed Tax Rates](reference/taxes/fixed-tax-rates.md)
+    * [Calculated Tax Rates](reference/taxes/calculated-tax-rates.md)
 * [Storefront API](reference/storefront-api/README.md)
   * [Endpoints](reference/storefront-api/endpoints/README.md)
     * [Order](reference/storefront-api/endpoints/order.md)

14/umbraco-commerce/key-concepts/sales-taxt-providers.md

@@ -0,0 +1,75 @@
+---
+description: Realtime sales tax features via Sales Tax Providers in Umbraco Commerce.
+---
+
+# Sales Tax Providers
+
+Sales Tax Providers are how Umbraco Commerce can perform real-time sales tax operations. Their job is to provide a standard interface between third-party sales tax operators and Umbraco Commerce. This is done to allow the passing of information between the two platforms.
+
+How the integrations work is often different for each sales tax operator. The Umbraco Commerce Sales Tax Providers add a flexible interface that should work with most sales tax operators.
+
+## Example Sales Tax Provider
+
+An example of a bare-bones Sales Tax Provider would look something like this:
+
+```csharp
+[SalesTaxProvider("my-sales-tax-provider-alias")]
+public class MySalesTaxProvider :  SalesTaxProviderBase<MySalesTaxProviderSettings>
+{
+    public MySalesTaxProvider(UmbracoCommerceContext umbracoCommerce)
+        : base(umbracoCommerce)
+    { }
+
+    ...
+}
+
+public class MySalesTaxProviderSettings
+{
+    [SalesTaxProviderSetting]
+    public string ApiKey { get; set; }
+
+    ...
+}
+
+```
+
+All Sales Tax Providers inherit from a base class `SalesTaxProviderBase<TSettings>`. `TSettings` is the type of a Plain Old Class Object (POCO) model class representing the Sales Tax Providers settings. The class must be decorated with `SalesTaxProviderAttribute` which defines the Sales Tax Providers `alias`.
+
+The settings class consists of a series of properties, each decorated with a `SalesTaxProviderSettingAttribute`. These will all be used to dynamically build an editor interface for the given settings in the backoffice.
+
+Labels and descriptions for providers and their settings are controlled through [Localization](#localization) entries.
+
+## Sales Tax Provider Responsibilities
+
+The responsibilities of a Sales Tax Provider are:
+
+* **Realtime Rates** - Calculating sales tax rate options for a given Order.
+
+### Realtime Rates
+
+Real-time rates are returned by implementing the `CalculateSalesTaxAsync` method. To facilitate rate calculation, a `SalesTaxProviderContext` object is passed to this method providing useful, contextual information, including:
+
+* **Order** - The Order and its items to be shipped.
+* **OrderCalculation** - The current order calculation state.
+* **FromAddress** - The address from which shipments will be shipped from.
+* **ToAddress** - The address to which shipments will be shipped to.
+* **Settings** - The sales tax provider settings are captured via the backoffice UI.
+* **AdditionalData** - A general dictionary store for any data that may need passing between methods.
+* **HttpContext** - A reference to the current HTTP context.
+
+Implementors should use these details to pass to the 3rd party sales tax operators API and retrieve the sales tax costs. These should then be returned to Umbraco Commerce as a `SalesTaxCalculationResult` which contains an `Amount` property for the total sales tax amount.
+
+## Localization
+
+When displaying your provider in the backoffice UI, it is neceserray to provide localizable labels. This is controlled by Umbraco's [UI Localization](https://docs.umbraco.com/umbraco-cms/extending/language-files/ui-localization) feature.
+
+Umbraco Commerce will automatically look for the following entries:
+
+| Key                                                                            |  Description |
+|--------------------------------------------------------------------------------| --- |
+| `ucSalesTaxProviders_{providerAlias}Label`                             | A main label for the provider |
+| `ucSalesTaxProviders_{providerAlias}Description`                       | A description for the provider |
+| `ucSalesTaxProviders_{providerAlias}Settings{settingAlias}Label`       | A label for a provider setting |
+| `ucSalesTaxProviders_{providerAlias}Settings{settingAlias}Description` | A description for a provider setting |
+
+Here `{providerAlias}` is the alias of the provider and `{settingAlias}` is the alias of a setting.

14/umbraco-commerce/reference/taxes/README.md

@@ -0,0 +1,15 @@
+---
+description: Tax calculation options in Umbraco Commerce.
+---
+
+# Taxes
+
+Umbraco Commerce offers two different tax calculation method configurations for calculating an orders tax amounts, which are:
+
+### [Fixed Tax Rates](./fixed-tax-rates.md)
+
+The fixed rate tax calculation option allows you to define a single fixed tax rate that will be applied for all products of the same type shipped to the same country. This is a simple option that is useful for countries that have a fixed tax rate (the norm in EU countries).
+
+### [Calculated Tax Rates](./calculated-tax-rates.md)
+
+The calculated tax rate option allows you to dynamically calculate the tax obligations of an order by using third party calculation platforms. This is a more complex option that is useful for countries that have different tax rates for different types of products or for different regions within the country (the norm in the US).

14/umbraco-commerce/reference/taxes/calculated-tax-rates.md

@@ -0,0 +1,52 @@
+---
+description: Calculated Rate Taxes in Umbraco Commerce.
+---
+
+# Calculated Tax Rates
+
+Fixed rate taxes allows you to dynamically calculate the tax obligations of an order by using third party calculation platforms. This is a more complex option that is useful for countries that have different tax rates for different types of products or for different regions within the country (the norm in the US).
+
+When using calculated rate taxes, taxes will be calculated as a single price adjustment against the order total price and so won't offer any breakdown.
+
+Calculated tax rates are configured using **Tax Calculation Methods**. A tax calculation method provides a connection to a third party calculation service via a [Sales Tax Provider](../../key-concepts/sales-taxt-providers.md). The sales tax provider passes the order details to the calculation service and returns the tax amount to be applied to the order.
+
+{% hint style="info" %}
+Before you can configure a tax calculation method, you will need install at least one [sales tax provider](../../key-concepts/sales-taxt-providers.md).
+
+A TaxJar example is provided on GitHub at [https://github.com/umbraco/Umbraco.Commerce.SalesTaxProviders.TaxJar](https://github.com/umbraco/Umbraco.Commerce.SalesTaxProviders.TaxJar)
+{% endhint %}
+
+## Tax Calculation Method Configuration
+
+1. Go to **Settings > Stores > {Your Store} > Taxes > Tax Calculation Methods**.
+
+    ![Tax Calculation Methods](../../media/v14/taxes/tax-calculation-methods.png)
+2. Click on the **Create Tax Calculation Method** button.
+3. Choose a **Sales Tax Provider** from the list.
+
+   ![Create Tax Calculation Method](../../media/v14/taxes/pick-sales-tax-provider.png)
+4. Enter the **Tax Calculation Method Name** and **Alias**.
+5. Configure the **Tax Calculation Method** settings.
+
+   ![Edit Tax Calculation Method](../../media/v14/taxes/tax-calculation-method-settings.png)
+6. Click **Save**.
+
+## Assigning a Tax Calculation Method
+
+Tax calculation methods are assigned to a **Country** entity. This allows you to define different tax calculation methods for different countries. The tax calculation method assigned to an orders shipping country will be used to calculate the tax amount for the order.
+
+![Country Tax Calculation Methods](../../media/v14/taxes/country-tax-calculation-method.png)
+
+## Providing Tax Codes
+
+When calculating taxes, you may need to provide product tax codes to the calculation service. Tax codes are used to identify the type of product being sold and are used by the calculation service to determine the correct tax rate to apply. To assign a tax code to a product, you can use a **Tax Class** with a code defined for the given country.
+
+![Tax Class Tax Codes](../../media/v14/taxes/tax-class-country-region-settings-modal.png)
+
+See [Tax Classes Configuration](./fixed-tax-rates.md#tax-class-configuration) for more information on how to configure tax classes.
+
+## Prices Inclusive of Tax
+
+Within Umbraco Commerce it is possible to configure a store to accept prices inclusive of tax. When using tax calculation methods it is not possible to enable this feature and so Umbraco Commerce will throw a warning if you tru to do so and a tax calculation method is already defined on a stores country.
+
+![Prices Inclusive of Tax Warning](../../media/v14/taxes/store-prices-include-tax-warning.png)

14/umbraco-commerce/reference/taxes/fixed-tax-rates.md

@@ -0,0 +1,38 @@
+---
+description: Fixed Rate Taxes in Umbraco Commerce.
+---
+
+# Fixed Tax Rates
+
+Fixed rate taxes allows you to define a single fixed tax rate that will be applied for all products of the same type shipped to the same country. This is a simple option that is useful for countries that have a fixed tax rate (the norm in EU countries).
+
+When using fixed rate taxes, taxes will be calculated for each price object in the order.
+
+Fixed rate taxes are defined using **Tax Classes**. A tax class is a classification for a specific type of product and can be configured to have different tax rates for different countries.
+
+## Tax Class Configuration
+
+1. Go to **Settings > Stores > {Your Store} > Taxes > Tax Classes**.
+   ![Tax Classes Methods](../../media/v14/taxes/tax-classes.png)
+2. Click on the **Create Tax Class** button.
+3. Enter the **Tax Class Name**, **Alias**, **Default Tax Rate** and optional **Default Tax Code**.
+   ![Edit Tax Class](../../media/v14/taxes/tax-class-general-settings.png)
+4. Optionally, define any country specific tax rates by toggling the checkbox in the **Country Tax Classes** for the country.
+   ![Country Region Tax Classes](../../media/v14/taxes/tax-class-country-region-settings.png)
+
+   Click the **Edit Tax Class** button to define the country specific tax rate / tax code.
+   ![Country Region Tax Classes Modal](../../media/v14/taxes/tax-class-country-region-settings-modal.png)
+5. Click **Save**.
+
+## Assigning a Tax Class
+
+There are two ways to assign a tax class to a product:
+
+### Store Default Tax Class
+In the store settings editor, set the **Default Tax Class** for the store. This will be the default tax class for all products in the store.
+![Store Default Tax Class](../../media/v14/taxes/store-default-tax-class.png)
+
+### Product Tax Class
+In the product document type, define a **Store Entity Picker** property configured for the **Tax Class** entity type, with the property alias **taxClass**.
+In the products content editor, set the **Tax Class** for the product. This will override the store default tax class for the product.
+![Product Tax Class](../../media/v14/taxes/product-tax-class.png)

14/umbraco-commerce/release-notes/README.md

@@ -17,6 +17,13 @@ If you are upgrading to a new major version, check the breaking changes in the [
 
 This section contains the release notes for Umbraco Commerce 14 including all changes for this version.
 
+#### 14.1.0 (25th September 2024)
+
+* Added [Sales Tax Provider](../../key-concepts/sales-taxt-providers.md) support.
+* Added Tax Calculation Method to allow for calculated tax rates.
+* Updated Countries to accept a tax calculation method.
+* Updated Tax Classes to support tax codes.
+
 #### 14.0.1 (24th September 2024)
 
 * Fixed broken migration causing exception on upgrade.

14/umbraco-commerce/upgrading/version-specific-upgrades.md

@@ -13,7 +13,11 @@ If you are upgrading to a new minor or patch version, you can find information a
 
 ## Version Specific Upgrade Notes History
 
-#### 14.0.0 
+#### 14.1.0
+
+* Tax Classes now have Country Region Tax Classes rather than Country Region Tax Rates so that tax codes can be assigned to products. Developers should update any references for Country Region Tax Rates to Country Region Tax Classes.
+
+#### 14.0.0
 
 * UI Config file configurations will need to use the new UI Extensions API