From 150aa50397825ae800f3acf4bbc68fe28e397582 Mon Sep 17 00:00:00 2001
From: Shahed Nasser <shahednasser@gmail.com>
Date: Mon, 20 Oct 2025 19:18:48 +0300
Subject: [PATCH] feat(tax,types): Add method to retrieve a Tax Module
 Provider's service (#13784)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

**What** — What changes are introduced in this PR?

Add a method in the Tax Module's servie to retrieve a provider by its ID.

**Why** — Why are these changes relevant or necessary?

The Tax Module Provider could be used for use cases other than calculating tax lines. For example, Avalara supports importing products to manage product-specific taxes. However, it's not possible right now to listen to the `product.created` event and create the product in Avalara with its provider. Instead, you'll have to create a separate module that also connects to Avalara and resolve it in the subsriber.

This also matches the pattern in the Analytics Module, which allows retrieving the underlying provider.

**How** — How have these changes been implemented?

Add a `getProvider` method to the Tax Module's service and its interface.

**Testing** — How have these changes been tested, or how can the reviewer test the feature?

Added integration test for the method.

---

## Examples

Provide examples or code snippets that demonstrate how this feature works, or how it can be used in practice.
This helps with documentation and ensures maintainers can quickly understand and verify the change.

```ts
const avalaraProvider = taxModuleService.getProvider("tp_avalara_avalara")
```

---

## Checklist

Please ensure the following before requesting a review:

- [x] I have added a **changeset** for this PR
    - Every non-breaking change should be marked as a **patch**
    - To add a changeset, run `yarn changeset` and follow the prompts
- [x] The changes are covered by relevant **tests**
- [x] I have verified the code works as intended locally
- [ ] I have linked the related issue(s) if applicable

---

## Additional Context

Add any additional context, related issues, or references that might help the reviewer understand this PR.
---
 .changeset/khaki-berries-impress.md                |  6 ++++++
 packages/core/types/src/tax/service.ts             | 14 ++++++++++++++
 .../tax/integration-tests/__tests__/index.spec.ts  |  6 ++++++
 .../modules/tax/src/services/tax-module-service.ts |  4 ++++
 4 files changed, 30 insertions(+)
 create mode 100644 .changeset/khaki-berries-impress.md

diff --git a/.changeset/khaki-berries-impress.md b/.changeset/khaki-berries-impress.md
new file mode 100644
index 0000000000..b8f4c898f5
--- /dev/null
+++ b/.changeset/khaki-berries-impress.md
@@ -0,0 +1,6 @@
+---
+"@medusajs/tax": patch
+"@medusajs/types": patch
+---
+
+feat(tax,types): Add method to retrieve a Tax Module Provider's service
diff --git a/packages/core/types/src/tax/service.ts b/packages/core/types/src/tax/service.ts
index 16945076f6..4ef6e29f27 100644
--- a/packages/core/types/src/tax/service.ts
+++ b/packages/core/types/src/tax/service.ts
@@ -25,6 +25,7 @@ import {
   UpdateTaxRegionDTO,
   UpsertTaxRateDTO,
 } from "./mutations"
+import { ITaxProvider } from "./provider"
 
 /**
  * The main service interface for the Tax Module.
@@ -915,4 +916,17 @@ export interface ITaxModuleService extends IModuleService {
     config?: RestoreReturn<TReturnableLinkableKeys>,
     sharedContext?: Context
   ): Promise<Record<string, string[]> | void>
+
+  /**
+   * This method returns the service of a Tax Module Provider by its ID. A Tax Module Provider's ID is of the format
+   * `tp_{identifier}_{id}`, where `identifier` is the static `identifier` property defined in the provider's service,
+   * and `id` is the ID set in `medusa-config.ts` when registering the provider.
+   *
+   * @returns {ITaxProvider} An instance of the Tax Module Provider's service.
+   *
+   * @example
+   * const avalaraProvider = taxModuleService.getProvider("tp_avalara_avalara")
+   * // TODO: perform custom actions with the provider
+   */
+  getProvider(providerId: string): ITaxProvider
 }
diff --git a/packages/modules/tax/integration-tests/__tests__/index.spec.ts b/packages/modules/tax/integration-tests/__tests__/index.spec.ts
index 87eb559c5f..52ea965603 100644
--- a/packages/modules/tax/integration-tests/__tests__/index.spec.ts
+++ b/packages/modules/tax/integration-tests/__tests__/index.spec.ts
@@ -1177,6 +1177,12 @@ moduleIntegrationTestRunner<ITaxModuleService>({
           }),
         ])
       })
+
+      it("should retrieve a tax module provider's service", async () => {
+        const providerService = service.getProvider("tp_system")
+        expect(providerService).toBeDefined()
+        expect(providerService.getIdentifier()).toEqual("system")
+      })
     })
   },
 })
diff --git a/packages/modules/tax/src/services/tax-module-service.ts b/packages/modules/tax/src/services/tax-module-service.ts
index 597089e5dd..fc4173b931 100644
--- a/packages/modules/tax/src/services/tax-module-service.ts
+++ b/packages/modules/tax/src/services/tax-module-service.ts
@@ -508,6 +508,10 @@ export default class TaxModuleService
     return taxLines
   }
 
+  getProvider(providerId: string): ITaxProvider {
+    return this.taxProviderService_.retrieveProvider(providerId)
+  }
+
   private async getTaxLinesFromProvider(
     providerId: string,
     items: ItemWithRates[],