docs: improvements to tax related docs (medusajs#13845)

Author: shahednasser

www/apps/book/public/llms-full.txt

@@ -12171,7 +12171,7 @@ Some examples of service events:
 
 ## Emit Event in a Workflow
 
-To emit a workflow event, use the `emitEventStep` helper step provided in the `@medusajs/medusa/core-flows` package.
+To emit a workflow event, use the `emitEventStep` helper step provided in the `@medusajs/medusa/core-flows` package. It allows you to emit an event from within a workflow, and it only emits the event after the workflow has finished successfully.
 
 For example:
 
@@ -40057,10 +40057,12 @@ Refer to this [Medusa Admin User Guide](https://docs.medusajs.com/user-guide/set
 
 ## What are Tax Rates?
 
-A tax rate is a percentage amount used to calculate the tax amount for each taxable item’s price, such as line items or shipping methods, in a cart. The sum of all calculated tax amounts are then added to the cart’s total as a tax total.
+A tax rate, represented by the [TaxRate data model](https://docs.medusajs.com/references/tax/models/TaxRate/index.html.md), is a percentage amount used to calculate the tax amount for each taxable item’s price, such as line items or shipping methods, in a cart. The sum of all calculated tax amounts are then added to the cart’s total as a tax total.
 
 Each tax region has a default tax rate. This tax rate is applied to all taxable items of a cart in that region.
 
+The `TaxRate` data model has a `rate` property that represents the percentage amount. For example, a `rate` of `10` means a tax rate of 10%.
+
 ### Combinable Tax Rates
 
 Tax regions can have parent tax regions. To inherit the tax rates of the parent tax region, set the `is_combinable` of the child’s tax rates to `true`.
@@ -83007,7 +83009,7 @@ A module is created under the `src/modules` directory of your Medusa application
 
 ### c. Define Module Options
 
-Next, define a TypeScript type for the Avalara module options. These options configure the module when it's registered in the Medusa application.
+Next, define a TypeScript type for the Avalara Module options. These options configure the module when it's registered in the Medusa application.
 
 Create the file `src/modules/avalara/types.ts` with the following content:
 
@@ -83094,7 +83096,7 @@ The constructor of a module's service receives the following parameters:
 1. An object with the dependencies to resolve from the [Module's container](https://docs.medusajs.com/docs/learn/fundamentals/modules/container/index.html.md).
 2. An object with the module options passed to the provider when it's registered.
 
-In the constructor, you validate that the required module options are provided. Then, you create an instance of the `Avatax` client using the provided options.
+In the constructor, you validate that the required options are provided. Then, you create an instance of the `Avatax` client using the provided options.
 
 You also define the `getIdentifier` method required by the `ITaxProvider` interface, which returns the provider's identifier.
 
@@ -84138,7 +84140,7 @@ In the compensation function, you revert the updates by restoring the original v
 
 You can now create the workflow. Create the file `src/workflows/update-product-item.ts` with the following content:
 
-```ts title="src/workflows/update-variant-item.ts" highlights={updateVariantItemWorkflowHighlights}
+```ts title="src/workflows/update-variant-item.ts" highlights={updateProductItemWorkflowHighlights}
 import { createWorkflow, WorkflowResponse, transform, when } from "@medusajs/framework/workflows-sdk"
 import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
 import { updateItemStep } from "./steps/update-item"

www/apps/resources/app/commerce-modules/tax/tax-rates-and-rules/page.mdx

@@ -14,10 +14,12 @@ Refer to this [Medusa Admin User Guide](!user-guide!/settings/tax-regions#manage
 
 ## What are Tax Rates?
 
-A tax rate is a percentage amount used to calculate the tax amount for each taxable item’s price, such as line items or shipping methods, in a cart. The sum of all calculated tax amounts are then added to the cart’s total as a tax total.
+A tax rate, represented by the [TaxRate data model](/references/tax/models/TaxRate), is a percentage amount used to calculate the tax amount for each taxable item’s price, such as line items or shipping methods, in a cart. The sum of all calculated tax amounts are then added to the cart’s total as a tax total.
 
 Each tax region has a default tax rate. This tax rate is applied to all taxable items of a cart in that region.
 
+The `TaxRate` data model has a `rate` property that represents the percentage amount. For example, a `rate` of `10` means a tax rate of 10%.
+
 ### Combinable Tax Rates
 
 Tax regions can have parent tax regions. To inherit the tax rates of the parent tax region, set the `is_combinable` of the child’s tax rates to `true`.

www/apps/resources/generated/edit-dates.mjs

@@ -90,7 +90,7 @@ export const generatedEditDates = {
   "app/commerce-modules/tax/_events/page.mdx": "2024-07-03T19:27:13+03:00",
   "app/commerce-modules/tax/module-options/page.mdx": "2025-05-20T07:51:40.711Z",
   "app/commerce-modules/tax/tax-calculation-with-provider/page.mdx": "2025-05-20T07:51:40.711Z",
-  "app/commerce-modules/tax/tax-rates-and-rules/page.mdx": "2025-02-26T11:35:15.214Z",
+  "app/commerce-modules/tax/tax-rates-and-rules/page.mdx": "2025-10-24T06:02:42.062Z",
   "app/commerce-modules/tax/tax-region/page.mdx": "2025-05-20T07:51:40.711Z",
   "app/commerce-modules/tax/page.mdx": "2025-05-20T07:51:40.711Z",
   "app/commerce-modules/user/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00",
@@ -1583,7 +1583,7 @@ export const generatedEditDates = {
   "references/tax/interfaces/tax.TaxRateRuleDTO/page.mdx": "2024-12-10T14:55:13.509Z",
   "references/tax/interfaces/tax.UpdateTaxRateDTO/page.mdx": "2024-12-10T14:55:13.523Z",
   "references/tax/types/tax.JoinerRelationship/page.mdx": "2024-12-09T13:22:04.496Z",
-  "references/tax_provider/interfaces/tax_provider.ITaxProvider/page.mdx": "2025-05-20T07:51:41.054Z",
+  "references/tax_provider/interfaces/tax_provider.ITaxProvider/page.mdx": "2025-10-24T06:00:50.804Z",
   "references/tax_provider/types/tax_provider.ItemTaxCalculationLine/page.mdx": "2024-12-09T13:22:04.464Z",
   "references/tax_provider/types/tax_provider.ShippingTaxCalculationLine/page.mdx": "2024-12-09T13:22:04.460Z",
   "references/types/DAL/interfaces/types.DAL.RepositoryService/page.mdx": "2025-10-21T08:10:45.266Z",

www/apps/resources/references/tax_provider/interfaces/tax_provider.ITaxProvider/page.mdx

@@ -86,7 +86,7 @@ export default class MyTaxProvider implements ITaxProvider {
 
 ### constructor
 
-You can use the `constructor` of your tax provider to access the resources registered in the [Module Container](https://docs.medusajs.com/resources/medusa-container-resources#module-container-resources).
+You can use the `constructor` of your Tax Module Provider's service to access the resources registered in the [Module Container](https://docs.medusajs.com/resources/medusa-container-resources#module-container-resources).
 
 You can also use the constructor to initialize your integration with the third-party provider. For example, if you use a client to connect to the third-party provider’s APIs, you can initialize it in the constructor and use it in other methods in the service.
 
@@ -95,20 +95,61 @@ Additionally, if you’re creating your tax provider as a plugin or a module pro
 For example:
 
 ```ts
-export default class MyTaxProvider implements ITaxProvider {
-  // ...
-  constructor(container, options) {
-    // you can access options here
+import {
+  ITaxProvider,
+  Logger
+} from "@medusajs/framework/types"
+
+type InjectedDependencies = {
+  logger: Logger
+}
+
+type Options = {
+  apiKey: string
+}
 
-    // you can also initialize a client that
-    // communicates with a third-party service.
+export default class MyTaxProvider implements ITaxProvider {
+  static identifier = "my-tax"
+  protected logger_: Logger
+  protected options_: Options
+  // assuming you're initializing a client
+  protected client
+
+  constructor (
+    { logger }: InjectedDependencies,
+    options: Options
+  ) {
+    this.logger_ = logger
+    this.options_ = options
+
+    // assuming you're initializing a client
     this.client = new Client(options)
   }
 }
 ```
 
 ---
 
+### getIdentifier
+
+This method is used to retrieve the unique identifier of the tax provider.
+
+#### Example
+
+```ts
+export default class MyTaxProvider implements ITaxProvider {
+  static identifier = "my-tax"
+  
+  getIdentifier(): string {
+    return MyTaxProvider.identifier
+  }
+}
+```
+
+#### Returns
+
+<TypeList types={[{"name":"string","type":"`string`","optional":false,"defaultValue":"","description":"The unique identifier of the tax provider.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getIdentifier"/>
+
 ### getTaxLines
 
 This method is used to retrieve the tax lines of items and shipping methods. It's used during checkout 
@@ -133,8 +174,8 @@ export default class SystemTaxService implements ITaxProvider {
     let taxLines: (TaxTypes.ItemTaxLineDTO | TaxTypes.ShippingTaxLineDTO)[] =
       itemLines.flatMap((l) => {
         return l.rates.map((r) => ({
-          rate_id: r.id,
-          rate: r.rate || 0,
+          rate_id: r.id, // this is optional. When integrating with a third-party, you don't need to provide it
+          rate: r.rate || 0, // For example, 10 for 10%
           name: r.name,
           code: r.code,
           line_item_id: l.line_item.id,
@@ -145,8 +186,8 @@ export default class SystemTaxService implements ITaxProvider {
     taxLines = taxLines.concat(
       shippingLines.flatMap((l) => {
         return l.rates.map((r) => ({
-          rate_id: r.id,
-          rate: r.rate || 0,
+          rate_id: r.id, // this is optional. When integrating with a third-party, you don't need to provide it
+          rate: r.rate || 0, // For example, 10 for 10%
           name: r.name,
           code: r.code,
           shipping_line_id: l.shipping_line.id,