asyavee/medusa-store
1
0 Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

docs: updates to tax provider and other provider guides (#11626)

Browse Source
This commit is contained in:
Shahed Nasser authored and GitHub committed 2025-02-26 16:13:05 +02:00
1 parent 65eb3aa6c8
commit 0eadcdd555
13 files changed
+246 -138
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

www/apps/resources/references/auth_provider/classes/auth_provider.AbstractAuthModuleProvider/page.mdx
+1
View File
@@ -15,6 +15,7 @@ In this document, you’ll learn how to create an auth provider module and the m
Start by creating a new directory for your module provider.
If you're creating the module provider in a Medusa application, create it under the `src/modules` directory. For example, `src/modules/my-auth`.
If you're creating the module provider in a plugin, create it under the `src/providers` directory. For example, `src/providers/my-auth`.
<Note>
www/apps/resources/references/file/classes/file.AbstractFileProviderService/page.mdx
+1
View File
@@ -15,6 +15,7 @@ In this document, you’ll learn how to create a file provider module and the me
Start by creating a new directory for your module provider.
If you're creating the module provider in a Medusa application, create it under the `src/modules` directory. For example, `src/modules/my-file`.
If you're creating the module provider in a plugin, create it under the `src/providers` directory. For example, `src/providers/my-file`.
<Note>
www/apps/resources/references/fulfillment_provider/classes/fulfillment_provider.AbstractFulfillmentProviderService/page.mdx
+1
View File
@@ -23,6 +23,7 @@ For example, when the merchant creates a fulfillment for an order, the Fulfillme
Start by creating a new directory for your module provider.
If you're creating the module provider in a Medusa application, create it under the `src/modules` directory. For example, `src/modules/my-fulfillment`.
If you're creating the module provider in a plugin, create it under the `src/providers` directory. For example, `src/providers/my-fulfillment`.
<Note>
www/apps/resources/references/notification/classes/notification.AbstractNotificationProviderService/page.mdx
+1
View File
@@ -15,6 +15,7 @@ In this document, you’ll learn how to create a notification provider module an
Start by creating a new directory for your module provider.
If you're creating the module provider in a Medusa application, create it under the `src/modules` directory. For example, `src/modules/my-notification`.
If you're creating the module provider in a plugin, create it under the `src/providers` directory. For example, `src/providers/my-notification`.
<Note>
www/apps/resources/references/payment_provider/classes/payment_provider.AbstractPaymentProvider/page.mdx
+1
View File
@@ -23,6 +23,7 @@ For example, when the merchant captures an order's payment, the Payment Module u
Start by creating a new directory for your module provider.
If you're creating the module provider in a Medusa application, create it under the `src/modules` directory. For example, `src/modules/my-payment`.
If you're creating the module provider in a plugin, create it under the `src/providers` directory. For example, `src/providers/my-payment`.
<Note>
www/apps/resources/references/tax_provider/interfaces/tax_provider.ITaxProvider/page.mdx
+91 -28
View File
@@ -8,55 +8,70 @@ import { TypeList } from "docs-ui"
In this document, you’ll learn how to create a tax provider to use with the Tax Module, and the methods to implement.
---
## Overview
A tax provider is used to retrieve the tax lines in a provided context. The Tax Module provides a default `system` provider. You can create your own tax provider,
either in a plugin, in a provider module, or directly in your Medusa application's codebase, then use it in any tax region.
A tax provider is used to retrieve the tax lines in a provided context. The Tax Module provides a default `system` provider. You can create your own tax provider, either in a plugin, in a module provider, or directly in your Medusa application's codebase, then use it in any tax region.
---
## How to Create a Tax Provider
## Understanding Tax Provider Implementation
A tax provider class is defined in a TypeScript or JavaScript file. The class must implement the
`ITaxProvider` interface imported from `@medusajs/framework/types`.
The Tax Module Provider handles calculating taxes with a third-party provirder. However, it's not responsible for managing tax concepts within Medusa, such as creating a tax region. The Tax Module uses your tax provider within core operations.
The file can be defined in a plugin, a provider module, or under the `src/services` directory of your Medusa application. You can later pass the package's name or the
path to the file in the `providers` option of the Tax Module.
For example, during checkout, the tax provider of the tax region that the customer is in is used to calculate the tax for the cart and order. So, you only have to implement the third-party tax calculation logic in your tax provider.
For example:
---
```ts title="src/services/my-tax.ts"
## 1. Create Module Provider Directory
Start by creating a new directory for your module provider.
If you're creating the module provider in a Medusa application, create it under the `src/modules` directory. For example, `src/modules/my-tax`.
If you're creating the module provider in a plugin, create it under the `src/providers` directory. For example, `src/providers/my-tax`.
<Note>
The rest of this guide always uses the `src/modules/my-tax` directory as an example.
</Note>
---
## 2. Create the Tax Provider Service
Create the file `src/modules/my-tax/service.ts` that holds the module's main service. It must extend the `ITaxProvider` class imported from `@medusajs/framework/types`:
```ts title="src/modules/my-tax/service.ts"
import { ITaxProvider } from "@medusajs/framework/types"
export default class MyTaxProvider implements ITaxProvider {
// ...
// TODO implement methods
}
```
---
### Identifier Property
## Identifier Property
The `identifier` property in a tax provider is used when the tax provider is registered in the dependency container or added to the database. A tax provider is represented in the database by the `TaxProvider` data model.
The `identifier` property in a tax provider is used when the tax provider is loaded by the Tax Module and added to the database. A tax provider is represented in the database by the `TaxProvider` data model.
For example:
```ts title="src/services/my-tax.ts"
```ts title="src/modules/my-tax/service.ts"
export default class MyTaxProvider implements ITaxProvider {
static identifier = "my-tax"
// ...
}
```
---
### constructor
## Constructor
You can use the `constructor` of your tax provider to access the resources registered in the dependency container.
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 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.
Additionally, if you’re creating your tax provider as a plugin or a provider module to be installed in any Medusa application and you want to access its options, you can access them in the constructor.
Additionally, if you’re creating your tax provider as a plugin or a module provider to be installed in any Medusa application and you want to access its options, you can access them in the second parameter of the constructor.
For example:
@@ -75,14 +90,13 @@ export default class MyTaxProvider implements ITaxProvider {
---
## getTaxLines
### getTaxLines
This method is used to retrieve the tax lines of items and shipping methods. It's used
when the `getTaxLines` method of the Tax Module's main service is called.
This method is used to retrieve the tax lines of items and shipping methods. It's used during checkout
when the `getTaxLines` method of the Tax Module's main service is called for a tax
region that uses this tax provider.
This method is useful during checkout or when calculating the totals of orders or exchanges.
### Example
#### Example
An example of how this method is implemented in the `system` provider:
@@ -127,10 +141,59 @@ export default class SystemTaxService implements ITaxProvider {
}
```
### Parameters
#### Parameters
<TypeList types={[{"name":"itemLines","type":"[ItemTaxCalculationLine](../../types/tax_provider.ItemTaxCalculationLine/page.mdx)[]","description":"The line item lines to calculate taxes for.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"line_item","type":"[TaxableItemDTO](../../../tax/interfaces/tax.TaxableItemDTO/page.mdx)","description":"The line item to calculate taxes for.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"`string`","description":"The ID of the taxable item.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"product_id","type":"`string`","description":"The associated product's ID.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"product_type_id","type":"`string`","description":"The ID of the type of the item's product.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"quantity","type":"[BigNumberInput](../../../tax/types/tax.BigNumberInput/page.mdx)","description":"The quantity of the taxable item.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"unit_price","type":"[BigNumberInput](../../../tax/types/tax.BigNumberInput/page.mdx)","description":"The unit price of the taxable item.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"currency_code","type":"`string`","description":"The ISO 3 character currency code of the taxable item.","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"rates","type":"[TaxRateDTO](../../../tax/interfaces/tax.TaxRateDTO/page.mdx)[]","description":"The rates applicable on the item.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"`string`","description":"The ID of the tax rate.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"rate","type":"`null` \\| `number`","description":"The rate to charge.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"code","type":"`null` \\| `string`","description":"The code the tax rate is identified by.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"name","type":"`string`","description":"The name of the Tax Rate.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"metadata","type":"`null` \\| `Record<string, unknown>`","description":"Holds custom data in key-value pairs.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"tax_region_id","type":"`string`","description":"The ID of the associated tax region.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"is_combinable","type":"`boolean`","description":"Whether the tax rate should be combined with parent rates.\n\nLearn more [here](https://docs.medusajs.com/resources/commerce-modules/tax/tax-rates-and-rules#combinable-tax-rates).","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"is_default","type":"`boolean`","description":"Whether the tax rate is the default rate for the region.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"created_at","type":"`string` \\| `Date`","description":"The creation date of the tax rate.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"updated_at","type":"`string` \\| `Date`","description":"The update date of the tax rate.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"deleted_at","type":"`null` \\| `Date`","description":"The deletion date of the tax rate.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"created_by","type":"`null` \\| `string`","description":"Who created the tax rate. For example, the ID of the user that created the tax rate.","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]},{"name":"shippingLines","type":"[ShippingTaxCalculationLine](../../types/tax_provider.ShippingTaxCalculationLine/page.mdx)[]","description":"The shipping method lines to calculate taxes for.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"shipping_line","type":"[TaxableShippingDTO](../../../tax/interfaces/tax.TaxableShippingDTO/page.mdx)","description":"The shipping method to calculate taxes for.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"`string`","description":"The ID of the taxable shipping.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"shipping_option_id","type":"`string`","description":"The associated shipping option's ID.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"unit_price","type":"[BigNumberInput](../../../tax/types/tax.BigNumberInput/page.mdx)","description":"The unit price of the taxable shipping.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"currency_code","type":"`strLine truncated
### Returns
#### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;([ItemTaxLineDTO](../../../tax/interfaces/tax.ItemTaxLineDTO/page.mdx) \\| [ShippingTaxLineDTO](../../../tax/interfaces/tax.ShippingTaxLineDTO/page.mdx))[]&#62;","optional":false,"defaultValue":"","description":"The list of calculated line item and shipping tax lines.\nIf an item in the array has the `shipping_line_id` property, then it's a shipping tax line. Otherwise, if it has\nthe `line_item_id` property, then it's a line item tax line.","expandable":false,"children":[{"name":"(ItemTaxLineDTO \\| ShippingTaxLineDTO)[]","type":"([ItemTaxLineDTO](../../../tax/interfaces/tax.ItemTaxLineDTO/page.mdx) \\| [ShippingTaxLineDTO](../../../tax/interfaces/tax.ShippingTaxLineDTO/page.mdx))[]","optional":false,"defaultValue":"","description":"","expandable":false,"children":[{"name":"ItemTaxLineDTO \\| ShippingTaxLineDTO","type":"[ItemTaxLineDTO](../../../tax/interfaces/tax.ItemTaxLineDTO/page.mdx) \\| [ShippingTaxLineDTO](../../../tax/interfaces/tax.ShippingTaxLineDTO/page.mdx)","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getTaxLines"/>
---
## 3. Create Module Definition File
Create the file `src/modules/my-tax/index.ts` with the following content:
```ts title="src/modules/my-tax/index.ts"
import MyTaxProvider from "./service"
import {
ModuleProvider,
Modules
} from "@medusajs/framework/utils"
export default ModuleProvider(Modules.TAX, {
services: [MyTaxProvider],
})
```
This exports the module's definition, indicating that the `MyTaxProvider` is the module's service.
---
## 4. Use Module
To use your Tax Module Provider, add it to the `providers` array of the Tax Module in `medusa-config.ts`:
```ts title="medusa-config.ts"
module.exports = defineConfig({
// ...
modules: [
{
resolve: "@medusajs/medusa/tax",
options: {
providers: [
{
// if module provider is in a plugin, use `plugin-name/providers/my-tax`
resolve: "./src/modules/my-tax",
id: "my-tax",
options: {
// provider options...
},
},
],
},
},
]
})
```
www/utils/generated/typedoc-json-output/tax-provider.json
+62 -110
View File
@@ -1,12 +1,12 @@
{
"id": 41934,
"id": 0,
"name": "tax-provider",
"variant": "project",
"kind": 1,
"flags": {},
"children": [
{
"id": 41935,
"id": 1,
"name": "ShippingTaxCalculationLine",
"variant": "declaration",
"kind": 2097152,
@@ -24,20 +24,20 @@
"fileName": "provider.ts",
"line": 14,
"character": 12,
"url": "https://github.com/medusajs/medusa/blob/f00e6bf660ab96b9d41bc3d424c8d78c54eaa8e7/packages/core/types/src/tax/provider.ts#L14"
"url": "https://github.com/medusajs/medusa/blob/95eef899f72b72aa138e9db0dffe2a3eeb40f241/packages/core/types/src/tax/provider.ts#L14"
}
],
"type": {
"type": "reflection",
"declaration": {
"id": 41936,
"id": 2,
"name": "__type",
"variant": "declaration",
"kind": 65536,
"flags": {},
"children": [
{
"id": 41937,
"id": 3,
"name": "shipping_line",
"variant": "declaration",
"kind": 1024,
@@ -55,7 +55,7 @@
"fileName": "provider.ts",
"line": 18,
"character": 2,
"url": "https://github.com/medusajs/medusa/blob/f00e6bf660ab96b9d41bc3d424c8d78c54eaa8e7/packages/core/types/src/tax/provider.ts#L18"
"url": "https://github.com/medusajs/medusa/blob/95eef899f72b72aa138e9db0dffe2a3eeb40f241/packages/core/types/src/tax/provider.ts#L18"
}
],
"type": {
@@ -69,7 +69,7 @@
}
},
{
"id": 41938,
"id": 4,
"name": "rates",
"variant": "declaration",
"kind": 1024,
@@ -87,7 +87,7 @@
"fileName": "provider.ts",
"line": 22,
"character": 2,
"url": "https://github.com/medusajs/medusa/blob/f00e6bf660ab96b9d41bc3d424c8d78c54eaa8e7/packages/core/types/src/tax/provider.ts#L22"
"url": "https://github.com/medusajs/medusa/blob/95eef899f72b72aa138e9db0dffe2a3eeb40f241/packages/core/types/src/tax/provider.ts#L22"
}
],
"type": {
@@ -108,8 +108,8 @@
{
"title": "Properties",
"children": [
41937,
41938
3,
4
]
}
],
@@ -118,14 +118,14 @@
"fileName": "provider.ts",
"line": 14,
"character": 41,
"url": "https://github.com/medusajs/medusa/blob/f00e6bf660ab96b9d41bc3d424c8d78c54eaa8e7/packages/core/types/src/tax/provider.ts#L14"
"url": "https://github.com/medusajs/medusa/blob/95eef899f72b72aa138e9db0dffe2a3eeb40f241/packages/core/types/src/tax/provider.ts#L14"
}
]
}
}
},
{
"id": 41939,
"id": 5,
"name": "ItemTaxCalculationLine",
"variant": "declaration",
"kind": 2097152,
@@ -143,20 +143,20 @@
"fileName": "provider.ts",
"line": 29,
"character": 12,
"url": "https://github.com/medusajs/medusa/blob/f00e6bf660ab96b9d41bc3d424c8d78c54eaa8e7/packages/core/types/src/tax/provider.ts#L29"
"url": "https://github.com/medusajs/medusa/blob/95eef899f72b72aa138e9db0dffe2a3eeb40f241/packages/core/types/src/tax/provider.ts#L29"
}
],
"type": {
"type": "reflection",
"declaration": {
"id": 41940,
"id": 6,
"name": "__type",
"variant": "declaration",
"kind": 65536,
"flags": {},
"children": [
{
"id": 41941,
"id": 7,
"name": "line_item",
"variant": "declaration",
"kind": 1024,
@@ -174,7 +174,7 @@
"fileName": "provider.ts",
"line": 33,
"character": 2,
"url": "https://github.com/medusajs/medusa/blob/f00e6bf660ab96b9d41bc3d424c8d78c54eaa8e7/packages/core/types/src/tax/provider.ts#L33"
"url": "https://github.com/medusajs/medusa/blob/95eef899f72b72aa138e9db0dffe2a3eeb40f241/packages/core/types/src/tax/provider.ts#L33"
}
],
"type": {
@@ -188,7 +188,7 @@
}
},
{
"id": 41942,
"id": 8,
"name": "rates",
"variant": "declaration",
"kind": 1024,
@@ -206,7 +206,7 @@
"fileName": "provider.ts",
"line": 37,
"character": 2,
"url": "https://github.com/medusajs/medusa/blob/f00e6bf660ab96b9d41bc3d424c8d78c54eaa8e7/packages/core/types/src/tax/provider.ts#L37"
"url": "https://github.com/medusajs/medusa/blob/95eef899f72b72aa138e9db0dffe2a3eeb40f241/packages/core/types/src/tax/provider.ts#L37"
}
],
"type": {
@@ -227,8 +227,8 @@
{
"title": "Properties",
"children": [
41941,
41942
7,
8
]
}
],
@@ -237,14 +237,14 @@
"fileName": "provider.ts",
"line": 29,
"character": 37,
"url": "https://github.com/medusajs/medusa/blob/f00e6bf660ab96b9d41bc3d424c8d78c54eaa8e7/packages/core/types/src/tax/provider.ts#L29"
"url": "https://github.com/medusajs/medusa/blob/95eef899f72b72aa138e9db0dffe2a3eeb40f241/packages/core/types/src/tax/provider.ts#L29"
}
]
}
}
},
{
"id": 41943,
"id": 9,
"name": "ITaxProvider",
"variant": "declaration",
"kind": 256,
@@ -253,55 +253,7 @@
"summary": [
{
"kind": "text",
"text": "## Overview\n\nA tax provider is used to retrieve the tax lines in a provided context. The Tax Module provides a default "
},
{
"kind": "code",
"text": "`system`"
},
{
"kind": "text",
"text": " provider. You can create your own tax provider,\neither in a plugin, in a provider module, or directly in your Medusa application's codebase, then use it in any tax region.\n\n---\n\n## How to Create a Tax Provider\n\nA tax provider class is defined in a TypeScript or JavaScript file. The class must implement the\n"
},
{
"kind": "code",
"text": "`ITaxProvider`"
},
{
"kind": "text",
"text": " interface imported from "
},
{
"kind": "code",
"text": "`@medusajs/framework/types`"
},
{
"kind": "text",
"text": ".\n\nThe file can be defined in a plugin, a provider module, or under the "
},
{
"kind": "code",
"text": "`src/services`"
},
{
"kind": "text",
"text": " directory of your Medusa application. You can later pass the package's name or the\npath to the file in the "
},
{
"kind": "code",
"text": "`providers`"
},
{
"kind": "text",
"text": " option of the Tax Module.\n\nFor example:\n\n"
},
{
"kind": "code",
"text": "```ts title=\"src/services/my-tax.ts\"\nimport { ITaxProvider } from \"@medusajs/framework/types\"\n\nexport default class MyTaxProvider implements ITaxProvider {\n // ...\n}\n```"
},
{
"kind": "text",
"text": "\n\n---\n\n## Identifier Property\n\nThe "
"text": "### Identifier Property\n\nThe "
},
{
"kind": "code",
@@ -309,7 +261,7 @@
},
{
"kind": "text",
"text": " property in a tax provider is used when the tax provider is registered in the dependency container or added to the database. A tax provider is represented in the database by the "
"text": " property in a tax provider is used when the tax provider is loaded by the Tax Module and added to the database. A tax provider is represented in the database by the "
},
{
"kind": "code",
@@ -321,11 +273,11 @@
},
{
"kind": "code",
"text": "```ts title=\"src/services/my-tax.ts\"\nexport default class MyTaxProvider implements ITaxProvider {\n static identifier = \"my-tax\"\n // ...\n}\n```"
"text": "```ts title=\"src/modules/my-tax/service.ts\"\nexport default class MyTaxProvider implements ITaxProvider {\n static identifier = \"my-tax\"\n // ...\n}\n```"
},
{
"kind": "text",
"text": "\n\n---\n\n## Constructor\n\nYou can use the "
"text": "\n\n### constructor\n\nYou can use the "
},
{
"kind": "code",
@@ -333,7 +285,7 @@
},
{
"kind": "text",
"text": " of your tax provider to access the resources registered in the dependency container.\n\nYou 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.\n\nAdditionally, if you’re creating your tax provider as a plugin or a provider module to be installed in any Medusa application and you want to access its options, you can access them in the constructor.\n\nFor example:\n\n"
"text": " of your tax provider to access the resources registered in the [Module Container](https://docs.medusajs.com/resources/medusa-container-resources#module-container-resources).\n\nYou 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.\n\nAdditionally, if you’re creating your tax provider as a plugin or a module provider to be installed in any Medusa application and you want to access its options, you can access them in the second parameter of the constructor.\n\nFor example:\n\n"
},
{
"kind": "code",
@@ -347,7 +299,7 @@
},
"children": [
{
"id": 41946,
"id": 12,
"name": "getTaxLines",
"variant": "declaration",
"kind": 2048,
@@ -355,14 +307,14 @@
"sources": [
{
"fileName": "provider.ts",
"line": 171,
"line": 143,
"character": 2,
"url": "https://github.com/medusajs/medusa/blob/f00e6bf660ab96b9d41bc3d424c8d78c54eaa8e7/packages/core/types/src/tax/provider.ts#L171"
"url": "https://github.com/medusajs/medusa/blob/95eef899f72b72aa138e9db0dffe2a3eeb40f241/packages/core/types/src/tax/provider.ts#L143"
}
],
"signatures": [
{
"id": 41947,
"id": 13,
"name": "getTaxLines",
"variant": "signature",
"kind": 4096,
@@ -371,7 +323,7 @@
"summary": [
{
"kind": "text",
"text": "This method is used to retrieve the tax lines of items and shipping methods. It's used\nwhen the "
"text": "This method is used to retrieve the tax lines of items and shipping methods. It's used during checkout \nwhen the "
},
{
"kind": "code",
@@ -379,7 +331,7 @@
},
{
"kind": "text",
"text": " method of the Tax Module's main service is called.\n\nThis method is useful during checkout or when calculating the totals of orders or exchanges."
"text": " method of the Tax Module's main service is called for a tax\nregion that uses this tax provider."
}
],
"blockTags": [
@@ -434,14 +386,14 @@
"sources": [
{
"fileName": "provider.ts",
"line": 171,
"line": 143,
"character": 2,
"url": "https://github.com/medusajs/medusa/blob/f00e6bf660ab96b9d41bc3d424c8d78c54eaa8e7/packages/core/types/src/tax/provider.ts#L171"
"url": "https://github.com/medusajs/medusa/blob/95eef899f72b72aa138e9db0dffe2a3eeb40f241/packages/core/types/src/tax/provider.ts#L143"
}
],
"parameters": [
{
"id": 41948,
"id": 14,
"name": "itemLines",
"variant": "param",
"kind": 32768,
@@ -458,14 +410,14 @@
"type": "array",
"elementType": {
"type": "reference",
"target": 41939,
"target": 5,
"name": "ItemTaxCalculationLine",
"package": "@medusajs/types"
}
}
},
{
"id": 41949,
"id": 15,
"name": "shippingLines",
"variant": "param",
"kind": 32768,
@@ -482,14 +434,14 @@
"type": "array",
"elementType": {
"type": "reference",
"target": 41935,
"target": 1,
"name": "ShippingTaxCalculationLine",
"package": "@medusajs/types"
}
}
},
{
"id": 41950,
"id": 16,
"name": "context",
"variant": "param",
"kind": 32768,
@@ -558,16 +510,16 @@
{
"title": "Methods",
"children": [
41946
12
]
}
],
"sources": [
{
"fileName": "provider.ts",
"line": 108,
"line": 81,
"character": 17,
"url": "https://github.com/medusajs/medusa/blob/f00e6bf660ab96b9d41bc3d424c8d78c54eaa8e7/packages/core/types/src/tax/provider.ts#L108"
"url": "https://github.com/medusajs/medusa/blob/95eef899f72b72aa138e9db0dffe2a3eeb40f241/packages/core/types/src/tax/provider.ts#L81"
}
]
}
@@ -576,76 +528,76 @@
{
"title": "Interfaces",
"children": [
41943
9
]
},
{
"title": "Type Aliases",
"children": [
41935,
41939
1,
5
]
}
],
"packageName": "@medusajs/types",
"symbolIdMap": {
"41934": {
"0": {
"sourceFileName": "../../../../packages/core/types/src/tax/provider.ts",
"qualifiedName": ""
},
"41935": {
"1": {
"sourceFileName": "../../../../packages/core/types/src/tax/provider.ts",
"qualifiedName": "ShippingTaxCalculationLine"
},
"41936": {
"2": {
"sourceFileName": "../../../../packages/core/types/src/tax/provider.ts",
"qualifiedName": "__type"
},
"41937": {
"3": {
"sourceFileName": "../../../../packages/core/types/src/tax/provider.ts",
"qualifiedName": "__type.shipping_line"
},
"41938": {
"4": {
"sourceFileName": "../../../../packages/core/types/src/tax/provider.ts",
"qualifiedName": "__type.rates"
},
"41939": {
"5": {
"sourceFileName": "../../../../packages/core/types/src/tax/provider.ts",
"qualifiedName": "ItemTaxCalculationLine"
},
"41940": {
"6": {
"sourceFileName": "../../../../packages/core/types/src/tax/provider.ts",
"qualifiedName": "__type"
},
"41941": {
"7": {
"sourceFileName": "../../../../packages/core/types/src/tax/provider.ts",
"qualifiedName": "__type.line_item"
},
"41942": {
"8": {
"sourceFileName": "../../../../packages/core/types/src/tax/provider.ts",
"qualifiedName": "__type.rates"
},
"41943": {
"9": {
"sourceFileName": "../../../../packages/core/types/src/tax/provider.ts",
"qualifiedName": "ITaxProvider"
},
"41946": {
"12": {
"sourceFileName": "../../../../packages/core/types/src/tax/provider.ts",
"qualifiedName": "ITaxProvider.getTaxLines"
},
"41947": {
"13": {
"sourceFileName": "../../../../packages/core/types/src/tax/provider.ts",
"qualifiedName": "ITaxProvider.getTaxLines"
},
"41948": {
"14": {
"sourceFileName": "../../../../packages/core/types/src/tax/provider.ts",
"qualifiedName": "itemLines"
},
"41949": {
"15": {
"sourceFileName": "../../../../packages/core/types/src/tax/provider.ts",
"qualifiedName": "shippingLines"
},
"41950": {
"16": {
"sourceFileName": "../../../../packages/core/types/src/tax/provider.ts",
"qualifiedName": "context"
}
@@ -655,7 +607,7 @@
"1": "../../../../packages/core/types/src/tax/provider.ts"
},
"reflections": {
"1": 41934
"1": 0
}
}
}
www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/auth-provider.ts
+1
View File
@@ -27,6 +27,7 @@ const authProviderOptions: FormattingOptionsType = {
Start by creating a new directory for your module provider.
If you're creating the module provider in a Medusa application, create it under the \`src/modules\` directory. For example, \`src/modules/my-auth\`.
If you're creating the module provider in a plugin, create it under the \`src/providers\` directory. For example, \`src/providers/my-auth\`.
<Note>
www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/file.ts
+1
View File
@@ -27,6 +27,7 @@ const fileOptions: FormattingOptionsType = {
Start by creating a new directory for your module provider.
If you're creating the module provider in a Medusa application, create it under the \`src/modules\` directory. For example, \`src/modules/my-file\`.
If you're creating the module provider in a plugin, create it under the \`src/providers\` directory. For example, \`src/providers/my-file\`.
<Note>
www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/fulfillment-provider.ts
+1
View File
@@ -33,6 +33,7 @@ For example, when the merchant creates a fulfillment for an order, the Fulfillme
Start by creating a new directory for your module provider.
If you're creating the module provider in a Medusa application, create it under the \`src/modules\` directory. For example, \`src/modules/my-fulfillment\`.
If you're creating the module provider in a plugin, create it under the \`src/providers\` directory. For example, \`src/providers/my-fulfillment\`.
<Note>
www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/notification.ts
+1
View File
@@ -27,6 +27,7 @@ const notificationOptions: FormattingOptionsType = {
Start by creating a new directory for your module provider.
If you're creating the module provider in a Medusa application, create it under the \`src/modules\` directory. For example, \`src/modules/my-notification\`.
If you're creating the module provider in a plugin, create it under the \`src/providers\` directory. For example, \`src/providers/my-notification\`.
<Note>
www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/payment-provider.ts
+1
View File
@@ -33,6 +33,7 @@ For example, when the merchant captures an order's payment, the Payment Module u
Start by creating a new directory for your module provider.
If you're creating the module provider in a Medusa application, create it under the \`src/modules\` directory. For example, \`src/modules/my-payment\`.
If you're creating the module provider in a plugin, create it under the \`src/providers\` directory. For example, \`src/providers/my-payment\`.
<Note>
www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/tax-provider.ts
+83
View File
@@ -12,6 +12,89 @@ const taxProviderOptions: FormattingOptionsType = {
reflectionTitle: {
fullReplacement: "How to Create a Tax Provider",
},
shouldIncrementAfterStartSections: true,
expandMembers: true,
expandProperties: true,
startSections: [
`## Overview
A tax provider is used to retrieve the tax lines in a provided context. The Tax Module provides a default \`system\` provider. You can create your own tax provider, either in a plugin, in a module provider, or directly in your Medusa application's codebase, then use it in any tax region.`,
`## Understanding Tax Provider Implementation
The Tax Module Provider handles calculating taxes with a third-party provirder. However, it's not responsible for managing tax concepts within Medusa, such as creating a tax region. The Tax Module uses your tax provider within core operations.
For example, during checkout, the tax provider of the tax region that the customer is in is used to calculate the tax for the cart and order. So, you only have to implement the third-party tax calculation logic in your tax provider.`,
`## 1. Create Module Provider Directory
Start by creating a new directory for your module provider.
If you're creating the module provider in a Medusa application, create it under the \`src/modules\` directory. For example, \`src/modules/my-tax\`.
If you're creating the module provider in a plugin, create it under the \`src/providers\` directory. For example, \`src/providers/my-tax\`.
<Note>
The rest of this guide always uses the \`src/modules/my-tax\` directory as an example.
</Note>`,
`## 2. Create the Tax Provider Service
Create the file \`src/modules/my-tax/service.ts\` that holds the module's main service. It must extend the \`ITaxProvider\` class imported from \`@medusajs/framework/types\`:
\`\`\`ts title="src/modules/my-tax/service.ts"
import { ITaxProvider } from "@medusajs/framework/types"
export default class MyTaxProvider implements ITaxProvider {
// TODO implement methods
}
\`\`\``,
],
endSections: [
`## 3. Create Module Definition File
Create the file \`src/modules/my-tax/index.ts\` with the following content:
\`\`\`ts title="src/modules/my-tax/index.ts"
import MyTaxProvider from "./service"
import {
ModuleProvider,
Modules
} from "@medusajs/framework/utils"
export default ModuleProvider(Modules.TAX, {
services: [MyTaxProvider],
})
\`\`\`
This exports the module's definition, indicating that the \`MyTaxProvider\` is the module's service.`,
`## 4. Use Module
To use your Tax Module Provider, add it to the \`providers\` array of the Tax Module in \`medusa-config.ts\`:
\`\`\`ts title="medusa-config.ts"
module.exports = defineConfig({
// ...
modules: [
{
resolve: "@medusajs/medusa/tax",
options: {
providers: [
{
// if module provider is in a plugin, use \`plugin-name/providers/my-tax\`
resolve: "./src/modules/my-tax",
id: "my-tax",
options: {
// provider options...
},
},
],
},
},
]
})
\`\`\`
`,
],
},
}