7fe164bc1d
Generated the following references: - `inventory` - `js_client` - `medusa` - `medusa_config` - `medusa_react` - `modules` - `payment` - `pricing` - `product` - `services` - `stock_location` - `tax_calculation` - `types` - `workflows` Co-authored-by: Shahed Nasser <27354907+shahednasser@users.noreply.github.com>
101 lines
14 KiB
Plaintext
101 lines
14 KiB
Plaintext
---
|
|
displayed_sidebar: homepage
|
|
---
|
|
|
|
import TypeList from "@site/src/components/TypeList"
|
|
|
|
# ITaxCalculationStrategy
|
|
|
|
## Overview
|
|
|
|
A tax calculation strategy is used to calculate taxes when calculating a cart's totals. The Medusa
|
|
backend provides a tax calculation strategy that handles calculating the taxes, taking into account the
|
|
defined tax rates and settings such as whether tax-inclusive pricing is enabled.
|
|
|
|
You can override the tax calculation strategy to implement different calculation logic or to
|
|
integrate a third-party service that handles the tax calculation. You can override it either
|
|
in a Medusa backend setup or in a plugin.
|
|
|
|
A tax calculation strategy should be defined in a TypeScript or JavaScript file created under the `src/strategies` directory.
|
|
The class must also implement the `ITaxCalculationStrategy` interface imported from the `@medusajs/medusa` package.
|
|
|
|
For example, you can create the file `src/strategies/tax-calculation.ts` with the following content:
|
|
|
|
```ts title="src/strategies/tax-calculation.ts"
|
|
import {
|
|
ITaxCalculationStrategy,
|
|
LineItem,
|
|
LineItemTaxLine,
|
|
ShippingMethodTaxLine,
|
|
TaxCalculationContext,
|
|
} from "@medusajs/medusa"
|
|
|
|
class TaxCalculationStrategy
|
|
implements ITaxCalculationStrategy {
|
|
|
|
async calculate(
|
|
items: LineItem[],
|
|
taxLines: (ShippingMethodTaxLine | LineItemTaxLine)[],
|
|
calculationContext: TaxCalculationContext
|
|
): Promise<number> {
|
|
throw new Error("Method not implemented.")
|
|
}
|
|
|
|
}
|
|
|
|
export default TaxCalculationStrategy
|
|
```
|
|
|
|
---
|
|
|
|
## Methods
|
|
|
|
### calculate
|
|
|
|
This method calculates the tax amount for a given set of line items under applicable
|
|
tax conditions and calculation contexts.
|
|
|
|
This method is used whenever taxes are calculated. If automatic tax calculation is disabled in a region,
|
|
then it's only triggered when taxes are calculated manually as explained in
|
|
[this guide](https://docs.medusajs.com/modules/taxes/storefront/manual-calculation).
|
|
|
|
#### Example
|
|
|
|
An example of the general implementation of this method in the Medusa backend's tax calculation strategy:
|
|
|
|
```ts
|
|
async calculate(
|
|
items: LineItem[],
|
|
taxLines: (ShippingMethodTaxLine | LineItemTaxLine)[],
|
|
calculationContext: TaxCalculationContext
|
|
): Promise<number> {
|
|
const lineItemsTaxLines = taxLines.filter(
|
|
(tl) => "item_id" in tl
|
|
) as LineItemTaxLine[]
|
|
const shippingMethodsTaxLines = taxLines.filter(
|
|
(tl) => "shipping_method_id" in tl
|
|
) as ShippingMethodTaxLine[]
|
|
|
|
const lineItemsTax = this.calculateLineItemsTax(
|
|
items,
|
|
lineItemsTaxLines,
|
|
calculationContext
|
|
)
|
|
|
|
const shippingMethodsTax = this.calculateShippingMethodsTax(
|
|
calculationContext.shipping_methods,
|
|
shippingMethodsTaxLines
|
|
)
|
|
|
|
return Math.round(lineItemsTax + shippingMethodsTax)
|
|
}
|
|
```
|
|
|
|
#### Parameters
|
|
|
|
<TypeList types={[{"name":"items","type":"[LineItem](../../entities/classes/entities.LineItem.mdx)[]","description":"The line items to calculate the tax total for.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"`string`","description":"The line item's ID","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"created_at","type":"`Date`","description":"The date with timezone at which the resource was created.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"updated_at","type":"`Date`","description":"The date with timezone at which the resource was updated.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"cart_id","type":"`string`","description":"The ID of the cart that the line item may belongs to.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"cart","type":"[Cart](../../entities/classes/entities.Cart.mdx)","description":"The details of the cart that the line item may belongs to.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"order_id","type":"`null` \\| `string`","description":"The ID of the order that the line item may belongs to.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"order","type":"[Order](../../entities/classes/entities.Order.mdx)","description":"The details of the order that the line item may belongs to.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"swap_id","type":"`string`","description":"The ID of the swap that the line item may belong to.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"swap","type":"[Swap](../../entities/classes/entities.Swap.mdx)","description":"The details of the swap that the line item may belong to.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"claim_order_id","type":"`string`","description":"The ID of the claim that the line item may belong to.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"claim_order","type":"[ClaimOrder](../../entities/classes/entities.ClaimOrder.mdx)","description":"The details of the claim that the line item may belong to.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"tax_lines","type":"[LineItemTaxLine](../../entities/classes/entities.LineItemTaxLine.mdx)[]","description":"The details of the item's tax lines.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"adjustments","type":"[LineItemAdjustment](../../entities/classes/entities.LineItemAdjustment.mdx)[]","description":"The details of the item's adjustments, which are available when a discount is applied on the item.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"title","type":"`string`","description":"The title of the Line Item.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"description","type":"`null` \\| `string`","description":"A more detailed description of the contents of the Line Item.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"thumbnail","type":"`null` \\| `string`","description":"A URL string to a small image of the contents of the Line Item.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"is_return","type":"`boolean`","description":"Is the item being returned","optional":false,"defaultValue":"false","expandable":false,"children":[]},{"name":"is_giftcard","type":"`boolean`","description":"Flag to indicate if the Line Item is a Gift Card.","optional":false,"defaultValue":"false","expandable":false,"children":[]},{"name":"should_merge","type":"`boolean`","description":"Flag to indicate if new Line Items with the same variant should be merged or added as an additional Line Item.","optional":false,"defaultValue":"true","expandable":false,"children":[]},{"name":"allow_discounts","type":"`boolean`","description":"Flag to indicate if the Line Item should be included when doing discount calculations.","optional":false,"defaultValue":"true","expandable":false,"children":[]},{"name":"has_shipping","type":"`null` \\| `boolean`","description":"Flag to indicate if the Line Item has fulfillment associated with it.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"unit_price","type":"`number`","description":"The price of one unit of the content in the Line Item. This should be in the currency defined by the Cart/Order/Swap/Claim that the Line Item belongs to.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"variant_id","type":"`null` \\| `string`","description":"The id of the Product Variant contained in the Line Item.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"variant","type":"[ProductVariant](../../entities/classes/entities.ProductVariant.mdx)","description":"The details of the product variant that this item was created from.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"product_id","type":"`null` \\| `string`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"quantity","type":"`number`","description":"The quantity of the content in the Line Item.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"fulfilled_quantity","type":"`null` \\| `number`","description":"The quantity of the Line Item that has been fulfilled.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"returned_quantity","type":"`null` \\| `number`","description":"The quantity of the Line Item that has been returned.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"shipped_quantity","type":"`null` \\| `number`","description":"The quantity of the Line Item that has been shipped.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"metadata","type":"`Record<string, unknown>`","description":"An optional key-value map with additional details","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"includes_tax","type":"`boolean`","description":"Indicates if the line item unit\\_price include tax","optional":false,"defaultValue":"false","expandable":false,"featureFlag":"tax_inclusive_pricing","children":[]},{"name":"original_item_id","type":"`null` \\| `string`","description":"The ID of the original line item. This is useful if the line item belongs to a resource that references an order, such as a return or an order edit.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"order_edit_id","type":"`null` \\| `string`","description":"The ID of the order edit that the item may belong to.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"order_edit","type":"`null` \\| [OrderEdit](../../entities/classes/entities.OrderEdit.mdx)","description":"The details of the order edit.","optional":true,"defaultValue":"","expandable":true,"children":[]},{"name":"refundable","type":"`null` \\| `number`","description":"The amount that can be refunded from the given Line Item. Takes taxes and discounts into consideration.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"subtotal","type":"`null` \\| `number`","description":"The subtotal of the line item","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"tax_total","type":"`null` \\| `number`","description":"The total of tax of the line item","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"total","type":"`null` \\| `number`","description":"The total amount of the line item","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"original_total","type":"`null` \\| `number`","description":"The original total amount of the line item","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"original_tax_total","type":"`null` \\| `number`","description":"The original tax total amount of the line item","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"discount_total","type":"`null` \\| `number`","description":"The total of discount of the line item rounded","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"raw_discount_total","type":"`null` \\| `number`","description":"The total of discount of the line item","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"gift_card_total","type":"`null` \\| `number`","description":"The total of the gift card of the line item","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"taxLines","type":"([LineItemTaxLine](../../entities/classes/entities.LineItemTaxLine.mdx) \\| [ShippingMethodTaxLine](../../entities/classes/entities.ShippingMethodTaxLine.mdx))[]","description":"The tax lines used for the calculation","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"calculationContext","type":"[TaxCalculationContext](../types/medusa.TaxCalculationContext.mdx)","description":"Other details relevant for the calculation","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"shipping_address","type":"[Address](../../entities/classes/entities.Address.mdx) \\| `null`","description":"The shipping address used in the cart.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"customer","type":"[Customer](../../entities/classes/entities.Customer.mdx)","description":"The customer that the cart belongs to.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"region","type":"[Region](../../entities/classes/entities.Region.mdx)","description":"The cart's region.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"is_return","type":"`boolean`","description":"Whether the cart is used in a return flow.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"shipping_methods","type":"[ShippingMethod](../../entities/classes/entities.ShippingMethod.mdx)[]","description":"The shipping methods used in the cart.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"allocation_map","type":"[LineAllocationsMap](../types/medusa.LineAllocationsMap.mdx)","description":"The gift cards and discounts applied on line items.\nEach object key or property is an ID of a line item","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/development/entities/repositories#retrieving-a-list-of-records" sectionTitle="calculate"/>
|
|
|
|
#### Returns
|
|
|
|
<TypeList types={[{"name":"Promise","type":"Promise<number>","optional":false,"defaultValue":"","description":"The calculated tax total","expandable":false,"children":[{"name":"number","type":"`number`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/development/entities/repositories#retrieving-a-list-of-records" sectionTitle="calculate"/>
|