chore: reorganize docs apps (#7228)
* reorganize docs apps * add README * fix directory * add condition for old docs
This commit is contained in:
Shahed Nasser authored and 
GitHub committed
1 parent
224ebb2154
commit
4fe28f5a95
6187 files changed
+601447
-598226
No files matched your search
+136
@@ -0,0 +1,136 @@
|
||||
---
|
||||
slug: /references/tax/provider
|
||||
---
|
||||
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# How to Create a Tax Provider
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## How to Create a Tax Provider
|
||||
|
||||
A tax provider class is defined in a TypeScript or JavaScript file. The class must implement the
|
||||
`ITaxProvider` interface imported from `@medusajs/types`.
|
||||
|
||||
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:
|
||||
|
||||
```ts title="src/services/my-tax.ts"
|
||||
import { ITaxProvider } from "@medusajs/types"
|
||||
|
||||
export default class MyTaxProvider implements ITaxProvider {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
For example:
|
||||
|
||||
```ts title="src/services/my-tax.ts"
|
||||
export default class MyTaxProvider implements ITaxProvider {
|
||||
static identifier = "my-tax"
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Constructor
|
||||
|
||||
You can use the `constructor` of your tax provider to access the resources registered in the dependency container.
|
||||
|
||||
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.
|
||||
|
||||
For example:
|
||||
|
||||
```ts
|
||||
export default class MyTaxProvider implements ITaxProvider {
|
||||
// ...
|
||||
constructor(container, options) {
|
||||
// you can access options here
|
||||
|
||||
// you can also initialize a client that
|
||||
// communicates with a third-party service.
|
||||
this.client = new Client(options)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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 useful during checkout or when calculating the totals of orders or exchanges.
|
||||
|
||||
### Example
|
||||
|
||||
An example of how this method is implemented in the `system` provider:
|
||||
|
||||
```ts
|
||||
// ...
|
||||
|
||||
export default class SystemTaxService implements ITaxProvider {
|
||||
// ...
|
||||
|
||||
async getTaxLines(
|
||||
itemLines: TaxTypes.ItemTaxCalculationLine[],
|
||||
shippingLines: TaxTypes.ShippingTaxCalculationLine[],
|
||||
_: TaxTypes.TaxCalculationContext
|
||||
): Promise<(TaxTypes.ItemTaxLineDTO | TaxTypes.ShippingTaxLineDTO)[]> {
|
||||
let taxLines: (TaxTypes.ItemTaxLineDTO | TaxTypes.ShippingTaxLineDTO)[] =
|
||||
itemLines.flatMap((l) => {
|
||||
return l.rates.map((r) => ({
|
||||
rate_id: r.id,
|
||||
rate: r.rate || 0,
|
||||
name: r.name,
|
||||
code: r.code,
|
||||
line_item_id: l.line_item.id,
|
||||
provider_id: this.getIdentifier(),
|
||||
}))
|
||||
})
|
||||
|
||||
taxLines = taxLines.concat(
|
||||
shippingLines.flatMap((l) => {
|
||||
return l.rates.map((r) => ({
|
||||
rate_id: r.id,
|
||||
rate: r.rate || 0,
|
||||
name: r.name,
|
||||
code: r.code,
|
||||
shipping_line_id: l.shipping_line.id,
|
||||
provider_id: this.getIdentifier(),
|
||||
}))
|
||||
})
|
||||
)
|
||||
|
||||
return taxLines
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 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_name","type":"`string`","description":"The name of the item's product.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"product_category_id","type":"`string`","description":"The ID of the category of the item's product.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"product_categories","type":"`string`[]","description":"The categories of the item's product.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"product_sku","type":"`string`","description":"The SKU of the item's product.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"product_type","type":"`string`","description":"The type of the item's product.","optional":true,"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/experimental/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":[{"naLine truncated
|
||||
|
||||
### Returns
|
||||
|
||||
<TypeList types={[{"name":"Promise","type":"Promise<([ItemTaxLineDTO](../../../tax/interfaces/tax.ItemTaxLineDTO/page.mdx) \\| [ShippingTaxLineDTO](../../../tax/interfaces/tax.ShippingTaxLineDTO/page.mdx))[]>","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":[]}]}]}]} sectionTitle="getTaxLines"/>
|
||||
+16
@@ -0,0 +1,16 @@
|
||||
---
|
||||
displayed_sidebar: taxReference
|
||||
---
|
||||
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# ItemTaxCalculationLine
|
||||
|
||||
**ItemTaxCalculationLine**: `Object`
|
||||
|
||||
A line item and the tax rates configured to apply to the
|
||||
product contained in the line item.
|
||||
|
||||
## Properties
|
||||
|
||||
<TypeList types={[{"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_name","type":"`string`","description":"The name of the item's product.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"product_category_id","type":"`string`","description":"The ID of the category of the item's product.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"product_categories","type":"`string`[]","description":"The categories of the item's product.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"product_sku","type":"`string`","description":"The SKU of the item's product.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"product_type","type":"`string`","description":"The type of the item's product.","optional":true,"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/experimental/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":[]}]}]} sectionTitle="ItemTaxCalculationLine"/>
|
||||
+16
@@ -0,0 +1,16 @@
|
||||
---
|
||||
displayed_sidebar: taxReference
|
||||
---
|
||||
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
# ShippingTaxCalculationLine
|
||||
|
||||
**ShippingTaxCalculationLine**: `Object`
|
||||
|
||||
A shipping method and the tax rates configured to apply to the
|
||||
shipping method.
|
||||
|
||||
## Properties
|
||||
|
||||
<TypeList types={[{"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":"`string`","description":"The ISO 3 character currency code of the taxable shipping.","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"rates","type":"[TaxRateDTO](../../../tax/interfaces/tax.TaxRateDTO/page.mdx)[]","description":"The rates applicable on the shipping method.","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/experimental/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":[]}]}]} sectionTitle="ShippingTaxCalculationLine"/>
|
||||
Reference in new issue
Block a user