From 8d574d6f2968b252d79b6a02f9056e59421a4bb8 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Fri, 24 Oct 2025 09:44:47 +0300 Subject: [PATCH] docs: improvements to tax related docs (#13845) --- www/apps/book/public/llms-full.txt | 12 ++-- .../tax/tax-rates-and-rules/page.mdx | 4 +- www/apps/resources/generated/edit-dates.mjs | 4 +- .../tax_provider.ITaxProvider/page.mdx | 63 +++++++++++++++---- 4 files changed, 64 insertions(+), 19 deletions(-) diff --git a/www/apps/book/public/llms-full.txt b/www/apps/book/public/llms-full.txt index 084fe26d4d..f7a68c63a4 100644 --- a/www/apps/book/public/llms-full.txt +++ b/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" diff --git a/www/apps/resources/app/commerce-modules/tax/tax-rates-and-rules/page.mdx b/www/apps/resources/app/commerce-modules/tax/tax-rates-and-rules/page.mdx index 33263a5a16..bd75d74097 100644 --- a/www/apps/resources/app/commerce-modules/tax/tax-rates-and-rules/page.mdx +++ b/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`. diff --git a/www/apps/resources/generated/edit-dates.mjs b/www/apps/resources/generated/edit-dates.mjs index cd3802ae67..559342da2a 100644 --- a/www/apps/resources/generated/edit-dates.mjs +++ b/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", diff --git a/www/apps/resources/references/tax_provider/interfaces/tax_provider.ITaxProvider/page.mdx b/www/apps/resources/references/tax_provider/interfaces/tax_provider.ITaxProvider/page.mdx index b1c31dd651..2f6ab7a77e 100644 --- a/www/apps/resources/references/tax_provider/interfaces/tax_provider.ITaxProvider/page.mdx +++ b/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 + + + ### 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,