docs: improvements to tax related docs (#13845)

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,13 +95,34 @@ 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"
 
-    // you can also initialize a client that
-    // communicates with a third-party service.
+type InjectedDependencies = {
+  logger: Logger
+}
+
+type Options = {
+  apiKey: string
+}
+
+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)
   }
 }
@@ -109,6 +130,26 @@ export default class MyTaxProvider implements ITaxProvider {
 
 ---
 
+### 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,