From e9ca647a1dbe52a29ff0b4e269a034e8908e5814 Mon Sep 17 00:00:00 2001
From: Shahed Nasser <shahednasser@gmail.com>
Date: Mon, 8 May 2023 13:41:59 +0300
Subject: [PATCH] docs: added taxes conceptual guide (#3975)

* docs: added taxes conceptual guide

* fixed metadata

* added an example for the tax provider
---
 docs/content/modules/taxes/overview.mdx |  3 +-
 docs/content/modules/taxes/taxes.md     | 90 +++++++++++++++++++++++++
 www/docs/sidebars.js                    |  7 +-
 3 files changed, 93 insertions(+), 7 deletions(-)
 create mode 100644 docs/content/modules/taxes/taxes.md

diff --git a/docs/content/modules/taxes/overview.mdx b/docs/content/modules/taxes/overview.mdx
index aaa273cd91..dc9ff1a5ad 100644
--- a/docs/content/modules/taxes/overview.mdx
+++ b/docs/content/modules/taxes/overview.mdx
@@ -146,12 +146,11 @@ Learn how tax-related entities and concepts are built, their relation to other m
 <DocCardList colSize={6} items={[
   {
     type: 'link',
-    href: '#',
+    href: '/modules/taxes',
     label: 'Architecture: Tax',
     customProps: {
       icon: Icons['circle-stack-solid'],
       description: 'Learn about the Tax Architecture.',
-      isSoon: true,
     }
   },
   {
diff --git a/docs/content/modules/taxes/taxes.md b/docs/content/modules/taxes/taxes.md
new file mode 100644
index 0000000000..680e1df120
--- /dev/null
+++ b/docs/content/modules/taxes/taxes.md
@@ -0,0 +1,90 @@
+---
+description: 'Learn about taxes in Medusa. This includes learning about the usage of taxes in regions, tax rates, tax providers, and more.'
+---
+
+# Taxes Architecture Overview
+
+In this document, you’ll learn about taxes in Medusa.
+
+## Overview
+
+Taxes are fees applied on items and shipping options when making a purchase. Taxes are typically different for each region around the world, both in amount and calculation logic.
+
+In Medusa, there are different ways you can customize taxes, allowing you to implement what works for your setup or the regions your commerce store operates in. You can:
+
+- Create a tax provider that defines the tax lines applied to line items and shipping methods.
+- Customize the tax calculation strategy to change how taxes are calculated.
+- Override tax rates for specific products, product types, or shipping options in a region using endpoints or services.
+
+---
+
+## Taxes in Regions
+
+Since taxes are different for each country or region, taxes are configured per region.
+
+In the `Region` entity, the following attributes are related to taxes:
+
+- `tax_rate`: a number indicating the default tax rate to be applied in the region.
+- `tax_code`: a string indicating the tax code of the region. This can be useful to external systems for accounting purposes.
+- `gift_card_taxable`: a boolean value indicating whether gift cards in this region are taxable or not. By default, it’s `true`.
+- `automatic_taxes`: a boolean value indicating if taxes should be calculated automatically during checkout in that region. By default, it’s `true`.
+- `tax_provider_id`: the ID of the tax provider used in the region. By default, the `system` tax provider is used. The tax provider can also be accessed by expanding the `tax_provider` relation and accessing `region.tax_provider`.
+- `includes_tax`: a boolean value indicating if tax-inclusive pricing is enabled in the region. You can learn about tax-inclusive pricing [here](./inclusive-pricing.md).
+
+### Tax Rates
+
+A region has a default tax rate, defined in the `tax_rate` attribute. However, you can override this tax rate for specific products, product types, or shipping options in that region.
+
+This is represented by the `TaxRate` entity. A region can have many tax rates, and the taxes rates can be accessed by expanding the `tax_rates` relation and accessing `region.tax_rates`.
+
+Since a tax rate can be used to override taxes for specific conditions, the `TaxRate` entity has the following relations:
+
+- `products`: an array of products that this tax rate applies to. You can access them by expanding the `products` relation and accessing `tax_rate.products`.
+- `product_types`: an array of product types that this tax rate applies to. You can access them by expanding the `product_types` relation and accessing `tax_rate.product_types`.
+- `shipping_options`: an array of shipping options that this tax rate applies to. You can access them by expanding the `shipping_options` relation and accessing `tax_rate.shipping_options`.
+
+The `TaxRate` entity’s attributes include:
+
+- `rate`: a number indicating the tax rate to apply for the specified conditions.
+- `code`: a string indicating the tax code of this rate.
+- `name`: a string indicating the name of the tax rate.
+- `region_id`: a string indicating the ID of the region this tax rate applies to. You can also access the region by expanding the `region` relation and accessing `tax_rate.region`.
+
+### Tax Provider
+
+Tax providers are used to return the tax line items for a set of line items and shipping methods during checkout. The Medusa backend has a `system` tax provider. It returns the line items as-is, without making any changes. You can also create your own tax provider that matches your use case.
+
+Each region can use a different tax provider. By default, regions use the `system` tax provider.
+
+For example, the tax provider allows you to use the shipping address of the cart to create tax lines.
+
+---
+
+## Tax Lines
+
+During checkout, taxes are applied to line items and shipping methods as tax lines. The taxes applied to line items are represented by the `LineItemTaxLine` entity, and those applied to shipping methods are represented by the `ShippingMethodTaxLine` entity. Both entities extend the `TaxLine` class, which defines the following attributes:
+
+- `rate`: a number indicating the applied tax rate.
+- `name`: a string indicating the name of the tax rate.
+- `code`: a string indicating the tax code.
+
+In addition to these attributes, the `LineItemTaxLine` entity has an `item_id` attribute, which is a string indicating the ID of the line item this tax line is applied to. You can also access the line item by expanding the `item` relation and accessing `line_item_tax_line.item`.
+
+On the other hand, the `ShippingMethodTaxLine` has the attributes of `TaxLine` along with the `shipping_method_id` attribute, which is a string indicating the ID of the shipping method this tax line is applied to. You can also access the shipping method by expanding the `shipping_method` relation and accessing `shipping_method_tax_line.shipping_method`.
+
+---
+
+## Tax Calculation Strategy
+
+The tax calculation strategy is used to calculate taxes based on a set of line items, tax lines, and a context during checkout. The strategy is used throughout the Medusa backend, such as when calculating the totals of a cart.
+
+Medusa defines a default tax calculation strategy. It calculates the taxes of line items and shipping methods, and returns the total of the two.
+
+You can override the tax calculation strategy to define a calculation strategy that works for your use case.
+
+---
+
+## See Also
+
+- [Tax Inclusive Pricing](./inclusive-pricing.md)
+- [How to calculate taxes manually during checkout](./storefront/manual-calculation.md)
diff --git a/www/docs/sidebars.js b/www/docs/sidebars.js
index e083b71c07..fe6bd9c95a 100644
--- a/www/docs/sidebars.js
+++ b/www/docs/sidebars.js
@@ -915,12 +915,9 @@ module.exports = {
           },
         },
         {
-          type: "link",
-          href: "#",
+          type: "doc",
+          id: "modules/taxes/taxes",
           label: "Taxes",
-          customProps: {
-            sidebar_is_soon: true,
-          },
         },
         {
           type: "doc",