|
| 1 | +--- |
| 2 | +description: Realtime sales tax features via Sales Tax Providers in Umbraco Commerce. |
| 3 | +--- |
| 4 | + |
| 5 | +# Sales Tax Providers |
| 6 | + |
| 7 | +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. |
| 8 | + |
| 9 | +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. |
| 10 | + |
| 11 | +## Example Sales Tax Provider |
| 12 | + |
| 13 | +An example of a bare-bones Sales Tax Provider would look something like this: |
| 14 | + |
| 15 | +```csharp |
| 16 | +[SalesTaxProvider("my-sales-tax-provider-alias")] |
| 17 | +public class MySalesTaxProvider : SalesTaxProviderBase<MySalesTaxProviderSettings> |
| 18 | +{ |
| 19 | + public MySalesTaxProvider(UmbracoCommerceContext umbracoCommerce) |
| 20 | + : base(umbracoCommerce) |
| 21 | + { } |
| 22 | + |
| 23 | + ... |
| 24 | +} |
| 25 | + |
| 26 | +public class MySalesTaxProviderSettings |
| 27 | +{ |
| 28 | + [SalesTaxProviderSetting] |
| 29 | + public string ApiKey { get; set; } |
| 30 | + |
| 31 | + ... |
| 32 | +} |
| 33 | + |
| 34 | +``` |
| 35 | + |
| 36 | +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`. |
| 37 | + |
| 38 | +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. |
| 39 | + |
| 40 | +Labels and descriptions for providers and their settings are controlled through [Localization](#localization) entries. |
| 41 | + |
| 42 | +## Sales Tax Provider Responsibilities |
| 43 | + |
| 44 | +The responsibilities of a Sales Tax Provider are: |
| 45 | + |
| 46 | +* **Realtime Rates** - Calculating sales tax rate options for a given Order. |
| 47 | + |
| 48 | +### Realtime Rates |
| 49 | + |
| 50 | +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: |
| 51 | + |
| 52 | +* **Order** - The Order and its items to be shipped. |
| 53 | +* **OrderCalculation** - The current order calculation state. |
| 54 | +* **FromAddress** - The address from which shipments will be shipped from. |
| 55 | +* **ToAddress** - The address to which shipments will be shipped to. |
| 56 | +* **Settings** - The sales tax provider settings are captured via the backoffice UI. |
| 57 | +* **AdditionalData** - A general dictionary store for any data that may need passing between methods. |
| 58 | +* **HttpContext** - A reference to the current HTTP context. |
| 59 | + |
| 60 | +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. |
| 61 | + |
| 62 | +## Localization |
| 63 | + |
| 64 | +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. |
| 65 | + |
| 66 | +Umbraco Commerce will automatically look for the following entries: |
| 67 | + |
| 68 | +| Key | Description | |
| 69 | +|--------------------------------------------------------------------------------| --- | |
| 70 | +| `ucSalesTaxProviders_{providerAlias}Label` | A main label for the provider | |
| 71 | +| `ucSalesTaxProviders_{providerAlias}Description` | A description for the provider | |
| 72 | +| `ucSalesTaxProviders_{providerAlias}Settings{settingAlias}Label` | A label for a provider setting | |
| 73 | +| `ucSalesTaxProviders_{providerAlias}Settings{settingAlias}Description` | A description for a provider setting | |
| 74 | + |
| 75 | +Here `{providerAlias}` is the alias of the provider and `{settingAlias}` is the alias of a setting. |
0 commit comments