Tax Lines in Order Module

In this document, you’ll learn about tax lines in an order.

What are Tax Lines?#

A tax line indicates the tax rate of a line item or a shipping method.

The OrderLineItemTaxLine data model represents a line item’s tax line, and the OrderShippingMethodTaxLine 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 it 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 is_tax_inclusive is enabled, the tax amount is 10% of 5000, which is 500. The item's unit price becomes 4500.

When Are Tax Lines Recalculated?#

Unlike cart tax lines, which Medusa recalculates automatically as the customer builds their cart, order tax lines are only recomputed in specific situations.

Regular Orders#

For regular orders, Medusa does not automatically recompute tax lines when you update an order. For example, updating the order's shipping or billing address using the updateOrderWorkflow does not trigger a tax recomputation. The existing tax lines are preserved as-is.

To recompute a regular order's tax lines, use the updateOrderTaxLinesWorkflow.

Draft Orders#

For draft orders, Medusa recomputes tax lines in two situations:

• When you update the draft order's shipping or billing address using the updateDraftOrderWorkflow, Medusa recomputes the tax lines to reflect the correct tax jurisdiction.
• When you convert a draft order to a regular order using the convertDraftOrderWorkflow, Medusa recomputes the tax lines before placing the order. This prevents stale tax lines from carrying over to the new order.

In both cases, whether Medusa recomputes the tax lines depends on the region's automatic_taxes setting:

• If automatic_taxes is enabled, Medusa recomputes the tax lines from the tax provider.
• If automatic_taxes is disabled, the tax lines are not recomputed.