Tax Lines in Cart Module

In this document, you’ll learn about tax lines in a cart and how to retrieve tax lines with the Tax Module.

What are Tax Lines?#

A tax line indicates the tax rate of a line item or a shipping method. The LineItemTaxLine data model represents a line item’s tax line, and the ShippingMethodTaxLine data model represents a shipping method’s tax line.

Tax Inclusivity#

By default, the tax amount is calculated by taking the tax rate from the line item or shipping method’s amount, and then adding them to the item/method’s subtotal.

However, line items and shipping methods have an is_tax_inclusive property that, when enabled, indicates that the item or method’s price already includes taxes.

So, instead of calculating the tax rate and adding it to the item/method’s subtotal, it’s calculated as part of the subtotal.

For example, if a line item's amount is 5000, the tax rate is 10, and tax inclusivity is enabled, the tax amount is 10% of 5000, which is 500, making the unit price of the line item 4500.

Retrieve Tax Lines#

When using the Cart and Tax modules together, you can use the getTaxLines method of the Tax Module’s main service. It retrieves the tax lines for a cart’s line items and shipping methods.

Code
1// retrieve the cart2const cart = await cartModuleService.retrieveCart("cart_123", {3  relations: [4    "items.tax_lines",5    "shipping_methods.tax_lines",6    "shipping_address",7  ],8})9
10// retrieve the tax lines11const taxLines = await taxModuleService.getTaxLines(12  [13    ...(cart.items as TaxableItemDTO[]),14    ...(cart.shipping_methods as TaxableShippingDTO[]),15  ],16  {17    address: {18      ...cart.shipping_address,19      country_code:20        cart.shipping_address.country_code || "us",21    },22  }23)

Then, use the returned tax lines to set the line items and shipping methods’ tax lines:

Code
1// set line item tax lines2await cartModuleService.setLineItemTaxLines(3  cart.id,4  taxLines.filter((line) => "line_item_id" in line)5)6
7// set shipping method tax lines8await cartModuleService.setLineItemTaxLines(9  cart.id,10  taxLines.filter((line) => "shipping_line_id" in line)11)