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

docs: improvements to tax related docs (#13845)

Browse Source
This commit is contained in:
Shahed Nasser
2025-10-24 09:44:47 +03:00
committed by GitHub
parent 226984cf0f
commit 8d574d6f29
4 changed files with 64 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
www/apps/book/public/llms-full.txt
View File

@@ -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"

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

@@ -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`.

4
www/apps/resources/generated/edit-dates.mjs
View File

@@ -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",

63
www/apps/resources/references/tax_provider/interfaces/tax_provider.ITaxProvider/page.mdx
View File

@@ -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,