docs: tax provider updates for next release (#12431)

* docs: tax provider updates for next release * change images * fix vale error * fix vale errors * generate
2025-05-13 14:13:17 +03:00
1 parent 0c698194ea
commit 76bc21ff25
@@ -10,11 +10,11 @@ export const metadata = {

 # {metadata.title}

-In this document, you'll learn about the options of the Tax Module.
+In this guide, you'll learn about the options of the Tax Module.

 ## providers

-The `providers` option is an array of either tax module providers or path to a file that defines a tax provider.
+The `providers` option is an array of either [tax module providers](../tax-provider/page.mdx) or path to a file that defines a tax provider.

 When the Medusa application starts, these providers are registered and can be used to retrieve tax lines.

@@ -27,6 +27,7 @@ Learn more about why modules are isolated in [this documentation](!docs!/learn/f
 - [Tax Settings Per Region](./tax-region/page.mdx): Set different tax settings for each tax region.
 - [Tax Rates and Rules](./tax-rates-and-rules/page.mdx): Manage each region's default tax rates and override them with conditioned tax rates.
 - [Retrieve Tax Lines for carts and orders](./tax-calculation-with-provider/page.mdx): Calculate and retrieve the tax lines of a cart or order's line items and shipping methods with tax providers.
+- [Custom Tax Providers](./tax-provider/page.mdx): Create custom tax providers to calculate tax lines differently for each tax region.

 ---

@@ -4,7 +4,7 @@ export const metadata = {

 # {metadata.title}

-In this document, you’ll learn how tax lines are calculated and what a tax provider is.
+In this guide, you’ll learn how tax lines are calculated using the tax provider.

 ## Tax Lines Calculation

@@ -64,16 +64,8 @@ The method returns tax lines for the line item and shipping methods. For example

 ## Using the Tax Provider in the Calculation

-The tax lines retrieved by the `getTaxLines` method are actually retrieved from the tax region’s provider.
+The tax lines retrieved by the `getTaxLines` method are actually retrieved from the tax region’s [Tax Module Provider](../tax-provider/page.mdx).

-A tax module provider whose main service implements the logic to shape tax lines. Each tax region has a tax provider.
+A tax module implements the logic to shape tax lines. Each tax region uses a tax provider.

-The Tax Module provides a `system` tax provider that only transforms calculated item and shipping tax rates into the required return type.
-
-{/* ---
-
-TODO add once tax provider guide is updated + add module providers match other modules.
-
-## Create Tax Provider
-
-Refer to [this guide](/modules/tax/provider) to learn more about creating a tax provider. */}
+Learn more about tax providers, configuring, and creating them in the [Tax Module Provider](../tax-provider/page.mdx) guide.
@@ -0,0 +1,84 @@
+export const metadata = {
+  title: `Tax Module Provider`,
+}
+
+# {metadata.title}
+
+In this guide, you’ll learn about the Tax Module Provider and how it's used.
+
+<Note title="Looking for no-code docs?">
+
+Refer to this [Medusa Admin User Guide](!user-guide!/settings/tax-regions) to learn how to manage tax provider of a tax region using the dashboard.
+
+</Note>
+
+## What is a Tax Module Provider?
+
+The Tax Module Provider handles tax line calculations in the Medusa application. It integrates third-party tax services, such as TaxJar, or implements custom tax calculation logic.
+
+The Medusa application uses the Tax Module Provider whenever it needs to calculate tax lines for a cart or order, or when you [calculate the tax lines using the Tax Module's service](../tax-calculation-with-provider/page.mdx).
+
+![Diagram showcasing the communication between Medusa the Tax Module Provider, and the third-party tax provider.](https://res.cloudinary.com/dza7lstvk/image/upload/v1746790996/Medusa%20Resources/tax-provider-service_kcgpne.jpg)
+
+---
+
+## Default Tax Provider
+
+The Tax Module provides a `system` tax provider that acts as a placeholder tax provider. It performs basic tax calculation, as you can see in the [Create Tax Module Provider](/references/tax/provider#gettaxlines) guide.
+
+This provider is installed by default in your application and you can use it with tax regions.
+
+<Note title="Tip">
+
+The identifier of the system tax provider is `tp_system`.
+
+</Note>
+
+---
+
+## How to Create a Custom Tax Provider?
+
+A Tax Module Provider is a module whose service implements the `ITaxProvider` imported from `@medusajs/framework/types`.
+
+The module can have multiple tax provider services, where each are registered as separate tax providers.
+
+Refer to the [Create Tax Module Provider](/references/tax/provider) guide to learn how to create a Tax Module Provider.
+
+After you create a tax provider, you can choose it as the default Tax Module Provider for a region in the [Medusa Admin dashboard](!user-guide!/settings/tax-regions).
+
+---
+
+## How are Tax Providers Registered?
+
+### Configure Tax Module's Providers
+
+The Tax Module accepts a `providers` option that allows you to configure the providers registered in your application.
+
+Learn more about this option in the [Module Options](../module-options/page.mdx) guide.
+
+### Registration on Application Start
+
+When the Medusa application starts, it registers the Tax Module Providers defined in the `providers` option of the Tax Module.
+
+For each Tax Module Provider, the Medusa application finds all tax provider services defined in them to register.
+
+### TaxProvider Data Model
+
+A registered tax provider is represented by the [TaxProvider data model](/references/tax/models/TaxProvider) in the Medusa application.
+
+This data model is used to reference a service in the Tax Module Provider and determine whether it's installed in the application.
+
+![Diagram showcasing the TaxProvider data model](https://res.cloudinary.com/dza7lstvk/image/upload/v1746791254/Medusa%20Resources/tax-provider-model_r6ktjw.jpg)
+
+The `TaxProvider` data model has the following properties:
+
+- `id`: The unique identifier of the tax provider. The ID's format is `tp_{identifier}_{id}`, where:
+    - `identifier` is the value of the `identifier` property in the Tax Module Provider's service.
+    - `id` is the value of the `id` property of the Tax Module Provider in `medusa-config.ts`.
+- `is_enabled`: A boolean indicating whether the tax provider is enabled.
+
+### How to Remove a Tax Provider?
+
+You can remove a registered tax provider from the Medusa application by removing it from the `providers` option in the Tax Module's configuration.
+
+Then, the next time the Medusa application starts, it will set the `is_enabled` property of the `TaxProvider`'s record to `false`. This allows you to re-enable the tax provider later if needed by adding it back to the `providers` option.
@@ -18,4 +18,24 @@ A tax region, represented by the [TaxRegion data model](/references/tax/models/T

 Tax regions can inherit settings and rules from a parent tax region.

-Each tax region has tax rules and a tax provider.
+---
+
+## Tax Rules in a Tax Region
+
+Tax rules define the tax rates and behavior within a tax region. They specify:
+
+- The tax rate percentage.
+- Which products the tax applies to.
+- Other custom rules to determine tax applicability.
+
+Learn more about tax rules in the [Tax Rates and Rules](../tax-rates-and-rules/page.mdx) guide.
+
+---
+
+## Tax Provider
+
+Each tax region can have a default tax provider. The tax provider is responsible for calculating the tax lines for carts and orders in that region.
+
+You can use Medusa's default tax provider or create a custom one, allowing you to integrate with third-party tax services or implement your own tax calculation logic.
+
+Learn more about tax providers in the [Tax Provider](../tax-provider/page.mdx) guide.