diff --git a/14/umbraco-commerce/SUMMARY.md b/14/umbraco-commerce/SUMMARY.md index d8f71cf1bc7..85d4ebbae90 100644 --- a/14/umbraco-commerce/SUMMARY.md +++ b/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) diff --git a/14/umbraco-commerce/key-concepts/sales-taxt-providers.md b/14/umbraco-commerce/key-concepts/sales-taxt-providers.md new file mode 100644 index 00000000000..14e557324eb --- /dev/null +++ b/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 +{ + 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` 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. diff --git a/14/umbraco-commerce/media/v14/taxes/country-tax-calculation-method.png b/14/umbraco-commerce/media/v14/taxes/country-tax-calculation-method.png new file mode 100644 index 00000000000..6a3a7c28a96 Binary files /dev/null and b/14/umbraco-commerce/media/v14/taxes/country-tax-calculation-method.png differ diff --git a/14/umbraco-commerce/media/v14/taxes/no-sales-tax-providers.png b/14/umbraco-commerce/media/v14/taxes/no-sales-tax-providers.png new file mode 100644 index 00000000000..46c3e7849a8 Binary files /dev/null and b/14/umbraco-commerce/media/v14/taxes/no-sales-tax-providers.png differ diff --git a/14/umbraco-commerce/media/v14/taxes/pick-sales-tax-provider.png b/14/umbraco-commerce/media/v14/taxes/pick-sales-tax-provider.png new file mode 100644 index 00000000000..a33567d91ae Binary files /dev/null and b/14/umbraco-commerce/media/v14/taxes/pick-sales-tax-provider.png differ diff --git a/14/umbraco-commerce/media/v14/taxes/product-tax-class.png b/14/umbraco-commerce/media/v14/taxes/product-tax-class.png new file mode 100644 index 00000000000..2b178019dc2 Binary files /dev/null and b/14/umbraco-commerce/media/v14/taxes/product-tax-class.png differ diff --git a/14/umbraco-commerce/media/v14/taxes/store-default-tax-class.png b/14/umbraco-commerce/media/v14/taxes/store-default-tax-class.png new file mode 100644 index 00000000000..ce8dc281171 Binary files /dev/null and b/14/umbraco-commerce/media/v14/taxes/store-default-tax-class.png differ diff --git a/14/umbraco-commerce/media/v14/taxes/store-prices-include-tax-warning.png b/14/umbraco-commerce/media/v14/taxes/store-prices-include-tax-warning.png new file mode 100644 index 00000000000..989568b180a Binary files /dev/null and b/14/umbraco-commerce/media/v14/taxes/store-prices-include-tax-warning.png differ diff --git a/14/umbraco-commerce/media/v14/taxes/store-prices-include-tax.png b/14/umbraco-commerce/media/v14/taxes/store-prices-include-tax.png new file mode 100644 index 00000000000..495b52cd551 Binary files /dev/null and b/14/umbraco-commerce/media/v14/taxes/store-prices-include-tax.png differ diff --git a/14/umbraco-commerce/media/v14/taxes/tax-calculation-method-settings.png b/14/umbraco-commerce/media/v14/taxes/tax-calculation-method-settings.png new file mode 100644 index 00000000000..4e991c6dab1 Binary files /dev/null and b/14/umbraco-commerce/media/v14/taxes/tax-calculation-method-settings.png differ diff --git a/14/umbraco-commerce/media/v14/taxes/tax-calculation-methods.png b/14/umbraco-commerce/media/v14/taxes/tax-calculation-methods.png new file mode 100644 index 00000000000..c5716f0df7f Binary files /dev/null and b/14/umbraco-commerce/media/v14/taxes/tax-calculation-methods.png differ diff --git a/14/umbraco-commerce/media/v14/taxes/tax-class-country-region-settings-modal.png b/14/umbraco-commerce/media/v14/taxes/tax-class-country-region-settings-modal.png new file mode 100644 index 00000000000..9b30300b6df Binary files /dev/null and b/14/umbraco-commerce/media/v14/taxes/tax-class-country-region-settings-modal.png differ diff --git a/14/umbraco-commerce/media/v14/taxes/tax-class-country-region-settings.png b/14/umbraco-commerce/media/v14/taxes/tax-class-country-region-settings.png new file mode 100644 index 00000000000..23313bcb480 Binary files /dev/null and b/14/umbraco-commerce/media/v14/taxes/tax-class-country-region-settings.png differ diff --git a/14/umbraco-commerce/media/v14/taxes/tax-class-general-settings.png b/14/umbraco-commerce/media/v14/taxes/tax-class-general-settings.png new file mode 100644 index 00000000000..1a018cd4c55 Binary files /dev/null and b/14/umbraco-commerce/media/v14/taxes/tax-class-general-settings.png differ diff --git a/14/umbraco-commerce/media/v14/taxes/tax-classes.png b/14/umbraco-commerce/media/v14/taxes/tax-classes.png new file mode 100644 index 00000000000..09b893c5d8a Binary files /dev/null and b/14/umbraco-commerce/media/v14/taxes/tax-classes.png differ diff --git a/14/umbraco-commerce/reference/taxes/README.md b/14/umbraco-commerce/reference/taxes/README.md new file mode 100644 index 00000000000..eca67862b71 --- /dev/null +++ b/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 order's tax amounts. + +### [Fixed Tax Rates](./fixed-tax-rates.md) + +This option allows you to define a single fixed tax rate to apply for all products of the same type shipped to the same country. This option is useful for countries that have a fixed tax rate (the norm in EU countries). + +### [Calculated Tax Rates](./calculated-tax-rates.md) + +This option allows you to dynamically calculate the tax obligations of an order by using third-party calculation platforms. This complex option is useful for countries with different tax rates for different product types or regions within the country (the norm in the US). diff --git a/14/umbraco-commerce/reference/taxes/calculated-tax-rates.md b/14/umbraco-commerce/reference/taxes/calculated-tax-rates.md new file mode 100644 index 00000000000..18411ce1202 --- /dev/null +++ b/14/umbraco-commerce/reference/taxes/calculated-tax-rates.md @@ -0,0 +1,55 @@ +--- +description: Calculated Rate Taxes in Umbraco Commerce. +--- + +# Calculated Tax Rates + +This option allows you to dynamically calculate the tax obligations of an order by using third-party calculation platforms. This complex option is useful for countries with different tax rates for different product types or regions within the country (the norm in the US). + +When using calculated rate taxes, taxes are calculated as a single price adjustment against the order total price and will not 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 to 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 order's 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 used by the calculation service to determine the correct tax rate. 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 + +It is possible to configure a store to accept prices including tax. When using tax calculation methods it is not possible to enable this feature. A warning will show if you try 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) diff --git a/14/umbraco-commerce/reference/taxes/fixed-tax-rates.md b/14/umbraco-commerce/reference/taxes/fixed-tax-rates.md new file mode 100644 index 00000000000..0e3e2261bb7 --- /dev/null +++ b/14/umbraco-commerce/reference/taxes/fixed-tax-rates.md @@ -0,0 +1,49 @@ +--- +description: Fixed Rate Taxes in Umbraco Commerce. +--- + +# Fixed Tax Rates + +Fixed-rate taxes allow you to dynamically calculate the tax obligations of an order by using third-party calculation platforms. This complex option is useful for countries with different tax rates for different product types or regions within the country (the norm in the US). + +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) + +3. Click on the **Create Tax Class** button. +4. 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) + +5. 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) + +6. 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) + +7. 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) diff --git a/14/umbraco-commerce/release-notes/README.md b/14/umbraco-commerce/release-notes/README.md index fd61352b09d..fa3f6a11004 100644 --- a/14/umbraco-commerce/release-notes/README.md +++ b/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. diff --git a/14/umbraco-commerce/upgrading/version-specific-upgrades.md b/14/umbraco-commerce/upgrading/version-specific-upgrades.md index 3bf928c7672..12d007c3430 100644 --- a/14/umbraco-commerce/upgrading/version-specific-upgrades.md +++ b/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