docs: document tax-inclusive promotions concept (medusajs#12849)

Author: shahednasser

www/apps/book/public/llms-full.txt

@@ -27808,6 +27808,14 @@ A region’s price preference’s `is_tax_inclusive`'s value takes higher preced
 - the selected price belongs to the region;
 - and the region has a price preference
 
+***
+
+## Tax-Inclusive Pricing with Promotions
+
+When you enable tax-inclusive prices for regions or currencies, this can impact how promotions are applied to the cart. So, it's recommended to enable tax-inclusiveness for promotions as well.
+
+Learn more in the [Tax-Inclusive Promotions](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/promotion/promotion-taxes/index.html.md) guide.
+
 
 # Calculate Product Variant Price with Taxes
 
@@ -28973,6 +28981,7 @@ export interface AddItemAdjustmentAction {
   amount: number
   code: string
   description?: string
+  is_tax_inclusive?: boolean
 }
 ```
 
@@ -29613,6 +29622,142 @@ Learn more about workflows in [this documentation](https://docs.medusajs.com/doc
 ***
 
 
+# Tax-Inclusive Promotions
+
+In this guide, you’ll learn how taxes are applied to promotions in a cart.
+
+This feature is available from [Medusa v2.8.5](https://github.com/medusajs/medusa/releases/tag/v2.8.5).
+
+## What are Tax-Inclusive Promotions?
+
+By default, promotions are tax-exclusive, meaning that the discount amount is applied as-is to the cart before taxes are calculated and applied to the cart total.
+
+A tax-inclusive promotion is a promotion for which taxes are calculated from the discount amount entered by the merchant.
+
+When a promotion is tax-inclusive, the discount amount is reduced by the calculated tax amount based on the [tax region's rate](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/tax-region/index.html.md). The reduced discount amount is then applied to the cart total.
+
+Tax-inclusiveness doesn't apply to Buy X Get Y promotions.
+
+### When to Use Tax-Inclusive Promotions
+
+Tax-inclusive promotions are most useful when using [tax-inclusive prices](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/tax-inclusive-pricing/index.html.md) for items in the cart.
+
+In this scenario, Medusa applies taxes consistently across the cart, ensuring that the total price reflects the taxes and promotions correctly.
+
+You can see this in action in the [examples below](#tax-inclusiveness-examples).
+
+***
+
+## What Makes a Promotion Tax-Inclusive?
+
+The [Promotion data model](https://docs.medusajs.com/references/promotion/models/Promotion/index.html.md) has an `is_tax_inclusive` property that determines whether the promotion is tax-inclusive.
+
+If `is_tax_inclusive` is disabled (which is the default), the promotion's discount amount will be applied as-is to the cart, before taxes are calculated. See an example in the [Tax-Exclusive Promotion Example](#tax-exclusive-promotion-example) section.
+
+If `is_tax_inclusive` is enabled, the promotion's discount amount will first be reduced by the calculated tax amount (based on the [tax region's rate](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/tax/tax-region/index.html.md)). The reduced discount amount is then applied to the cart total. See an example in the [Tax-Inclusive Promotion Example](#tax-inclusive-promotion-example) section.
+
+***
+
+## How to Set a Promotion as Tax-Inclusive
+
+You can enable tax-inclusiveness for a promotion when [creating it in the Medusa Admin](https://docs.medusajs.com/user-guide/promotions/create/index.html.md).
+
+You can set the `is_tax_inclusive` property when creating a promotion by using either the [Promotion workflows](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/promotion/workflows/index.html.md) or the [Promotion Module's service](https://docs.medusajs.com/references/promotion/index.html.md).
+
+For most use cases, it's recommended to use [workflows](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md) instead of directly using the module's service, as they implement the necessary rollback mechanisms in case of errors.
+
+For example, if you're creating a promotion with the [createPromotionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createPromotionsWorkflow/index.html.md) in an API route:
+
+```ts highlights={[["17"]]}
+import type {
+  MedusaRequest,
+  MedusaResponse,
+} from "@medusajs/framework/http"
+import { createPromotionsWorkflow } from "@medusajs/medusa/core-flows"
+
+export async function POST(
+  req: MedusaRequest,
+  res: MedusaResponse
+) {
+  const { result } = await createPromotionsWorkflow(req.scope)
+    .run({
+      input: {
+        promotionsData: [{
+          code: "10OFF",
+          // ...
+          is_tax_inclusive: true,
+        }],
+      }
+    })
+
+  res.send(result)
+}
+```
+
+In the above example, you set the `is_tax_inclusive` property to `true` when creating the promotion, making it tax-inclusive.
+
+### Updating a Promotion's Tax-Inclusiveness
+
+A promotion's tax-inclusiveness cannot be updated after it has been created. If you need to change a promotion's tax-inclusiveness, you must delete the existing promotion and create a new one with the desired `is_tax_inclusive` value.
+
+***
+
+## Tax-Inclusiveness Examples
+
+The following sections provide examples of how tax-inclusive promotions work in different scenarios, including both tax-exclusive and tax-inclusive promotions.
+
+These examples will help you understand how tax-inclusive promotions affect the cart total, allowing you to decide when to use them effectively.
+
+### Tax-Exclusive Promotion Example
+
+Consider the following scenario:
+
+- A tax-exclusive promotion gives a `$10` discount on the cart's total.
+- The cart's tax region has a `25%` tax rate.
+- The cart total before applying the promotion is `$100`.
+- [The prices in the cart's tax region are tax-exclusive](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/tax-inclusive-pricing/index.html.md).
+
+The result:
+
+1. Apply `$10` discount to cart total: `$100` - `$10` = `$90`
+2. Calculate tax on discounted total: `$90` x `25%` = `$22.50`
+3. Final total: `$90` + `$22.50` = `$112.50`
+
+### Tax-Inclusive Promotion Example
+
+Consider the following scenario:
+
+- A tax-inclusive promotion gives a `$10` discount on the cart's total.
+- The cart's tax region has a `25%` tax rate.
+- The cart total before applying the promotion is `$100`.
+- [The prices in the cart's tax region are tax-exclusive](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/tax-inclusive-pricing/index.html.md).
+
+The result:
+
+1. Calculate actual discount (removing tax): `$10` ÷ `1.25` = `$8`
+2. Apply discount to cart total: `$100` - `$8` = `$92`
+3. Calculate tax on discounted total: `$92` x `25%` = `$23`
+4. Final total: `$92` + `$23` = `$115`
+
+### Tax-Inclusive Promotions with Tax-Inclusive Prices
+
+Consider the following scenario:
+
+- A tax-inclusive promotion gives a `$10` discount on the cart's total.
+- The cart's tax region has a `25%` tax rate.
+- The cart total before applying the promotion is `$100`.
+- [The prices in the cart's tax region are tax-inclusive](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/tax-inclusive-pricing/index.html.md).
+
+The result:
+
+1. Calculate actual discount (removing tax): `$10` ÷ `1.25` = `$8`
+2. Calculate cart total without tax: `$100` ÷ `1.25` = `$80`
+3. Apply discount to cart total without tax: `$80` - `$8` = `$72`
+4. Add tax back to total: `$72` x `1.25` = `$90`
+
+The final total is `$90`, which correctly applies both the tax-inclusive promotion and tax-inclusive pricing.
+
+
 # Links between Region Module and Other Modules
 
 This document showcases the module links defined between the Region Module and other Commerce Modules.

www/apps/resources/app/commerce-modules/pricing/tax-inclusive-pricing/page.mdx

@@ -76,3 +76,11 @@ A region’s price preference’s `is_tax_inclusive`'s value takes higher preced
 - both the `region_id` and `currency_code` are provided in the calculation context;
 - the selected price belongs to the region;
 - and the region has a price preference
+
+---
+
+## Tax-Inclusive Pricing with Promotions
+
+When you enable tax-inclusive prices for regions or currencies, this can impact how promotions are applied to the cart. So, it's recommended to enable tax-inclusiveness for promotions as well.
+
+Learn more in the [Tax-Inclusive Promotions](../../promotion/promotion-taxes/page.mdx) guide.

www/apps/resources/app/commerce-modules/promotion/actions/page.mdx

@@ -29,6 +29,7 @@ export interface AddItemAdjustmentAction {
   amount: number
   code: string
   description?: string
+  is_tax_inclusive?: boolean
 }
 ```
 

www/apps/resources/app/commerce-modules/promotion/promotion-taxes/page.mdx

@@ -0,0 +1,162 @@
+---
+tags:
+  - tax
+product:
+  - cart
+  - tax
+---
+
+export const metadata = {
+  title: `Tax-Inclusive Promotions`,
+}
+
+# {metadata.title}
+
+In this guide, you’ll learn how taxes are applied to promotions in a cart.
+
+<Note>
+
+This feature is available from [Medusa v2.8.5](https://github.com/medusajs/medusa/releases/tag/v2.8.5).
+
+</Note>
+
+## What are Tax-Inclusive Promotions?
+
+By default, promotions are tax-exclusive, meaning that the discount amount is applied as-is to the cart before taxes are calculated and applied to the cart total.
+
+A tax-inclusive promotion is a promotion for which taxes are calculated from the discount amount entered by the merchant.
+
+When a promotion is tax-inclusive, the discount amount is reduced by the calculated tax amount based on the [tax region's rate](../../tax/tax-region/page.mdx). The reduced discount amount is then applied to the cart total.
+
+<Note>
+
+Tax-inclusiveness doesn't apply to Buy X Get Y promotions.
+
+</Note>
+
+### When to Use Tax-Inclusive Promotions
+
+Tax-inclusive promotions are most useful when using [tax-inclusive prices](../../pricing/tax-inclusive-pricing/page.mdx) for items in the cart.
+
+In this scenario, Medusa applies taxes consistently across the cart, ensuring that the total price reflects the taxes and promotions correctly.
+
+You can see this in action in the [examples below](#tax-inclusiveness-examples).
+
+---
+
+## What Makes a Promotion Tax-Inclusive?
+
+The [Promotion data model](/references/promotion/models/Promotion) has an `is_tax_inclusive` property that determines whether the promotion is tax-inclusive.
+
+If `is_tax_inclusive` is disabled (which is the default), the promotion's discount amount will be applied as-is to the cart, before taxes are calculated. See an example in the [Tax-Exclusive Promotion Example](#tax-exclusive-promotion-example) section.
+
+If `is_tax_inclusive` is enabled, the promotion's discount amount will first be reduced by the calculated tax amount (based on the [tax region's rate](../../tax/tax-region/page.mdx)). The reduced discount amount is then applied to the cart total. See an example in the [Tax-Inclusive Promotion Example](#tax-inclusive-promotion-example) section.
+
+---
+
+## How to Set a Promotion as Tax-Inclusive
+
+<Note title="Looking for no-code approach?">
+
+You can enable tax-inclusiveness for a promotion when [creating it in the Medusa Admin](!user-guide!/promotions/create).
+
+</Note>
+
+You can set the `is_tax_inclusive` property when creating a promotion by using either the [Promotion workflows](../workflows/page.mdx) or the [Promotion Module's service](/references/promotion).
+
+<Note>
+
+For most use cases, it's recommended to use [workflows](!docs!/learn/fundamentals/workflows) instead of directly using the module's service, as they implement the necessary rollback mechanisms in case of errors.
+
+</Note>
+
+For example, if you're creating a promotion with the [createPromotionsWorkflow](/references/medusa-workflows/createPromotionsWorkflow) in an API route:
+
+```ts highlights={[["17"]]}
+import type {
+  MedusaRequest,
+  MedusaResponse,
+} from "@medusajs/framework/http"
+import { createPromotionsWorkflow } from "@medusajs/medusa/core-flows"
+
+export async function POST(
+  req: MedusaRequest,
+  res: MedusaResponse
+) {
+  const { result } = await createPromotionsWorkflow(req.scope)
+    .run({
+      input: {
+        promotionsData: [{
+          code: "10OFF",
+          // ...
+          is_tax_inclusive: true,
+        }],
+      }
+    })
+
+  res.send(result)
+}
+```
+
+In the above example, you set the `is_tax_inclusive` property to `true` when creating the promotion, making it tax-inclusive.
+
+### Updating a Promotion's Tax-Inclusiveness
+
+A promotion's tax-inclusiveness cannot be updated after it has been created. If you need to change a promotion's tax-inclusiveness, you must delete the existing promotion and create a new one with the desired `is_tax_inclusive` value.
+
+---
+
+## Tax-Inclusiveness Examples
+
+The following sections provide examples of how tax-inclusive promotions work in different scenarios, including both tax-exclusive and tax-inclusive promotions.
+
+These examples will help you understand how tax-inclusive promotions affect the cart total, allowing you to decide when to use them effectively.
+
+### Tax-Exclusive Promotion Example
+
+Consider the following scenario:
+
+- A tax-exclusive promotion gives a `$10` discount on the cart's total.
+- The cart's tax region has a `25%` tax rate.
+- The cart total before applying the promotion is `$100`.
+- [The prices in the cart's tax region are tax-exclusive](../../pricing/tax-inclusive-pricing/page.mdx).
+
+The result:
+
+1. Apply `$10` discount to cart total: `$100` - `$10` = `$90`
+2. Calculate tax on discounted total: `$90` x `25%` = `$22.50`
+3. Final total: `$90` + `$22.50` = `$112.50`
+
+### Tax-Inclusive Promotion Example
+
+Consider the following scenario:
+
+- A tax-inclusive promotion gives a `$10` discount on the cart's total.
+- The cart's tax region has a `25%` tax rate.
+- The cart total before applying the promotion is `$100`.
+- [The prices in the cart's tax region are tax-exclusive](../../pricing/tax-inclusive-pricing/page.mdx).
+
+The result:
+
+1. Calculate actual discount (removing tax): `$10` ÷ `1.25` = `$8`
+2. Apply discount to cart total: `$100` - `$8` = `$92`
+3. Calculate tax on discounted total: `$92` x `25%` = `$23`
+4. Final total: `$92` + `$23` = `$115`
+
+### Tax-Inclusive Promotions with Tax-Inclusive Prices
+
+Consider the following scenario:
+
+- A tax-inclusive promotion gives a `$10` discount on the cart's total.
+- The cart's tax region has a `25%` tax rate.
+- The cart total before applying the promotion is `$100`.
+- [The prices in the cart's tax region are tax-inclusive](../../pricing/tax-inclusive-pricing/page.mdx).
+
+The result:
+
+1. Calculate actual discount (removing tax): `$10` ÷ `1.25` = `$8`
+2. Calculate cart total without tax: `$100` ÷ `1.25` = `$80`
+3. Apply discount to cart total without tax: `$80` - `$8` = `$72`
+4. Add tax back to total: `$72` x `1.25` = `$90`
+
+The final total is `$90`, which correctly applies both the tax-inclusive promotion and tax-inclusive pricing.

www/apps/resources/generated/edit-dates.mjs

@@ -58,7 +58,7 @@ export const generatedEditDates = {
   "app/commerce-modules/pricing/concepts/page.mdx": "2024-10-09T13:37:25.678Z",
   "app/commerce-modules/pricing/price-calculation/page.mdx": "2025-05-20T07:51:40.710Z",
   "app/commerce-modules/pricing/price-rules/page.mdx": "2025-05-20T07:51:40.710Z",
-  "app/commerce-modules/pricing/tax-inclusive-pricing/page.mdx": "2024-10-09T13:48:23.261Z",
+  "app/commerce-modules/pricing/tax-inclusive-pricing/page.mdx": "2025-06-27T15:43:35.193Z",
   "app/commerce-modules/pricing/page.mdx": "2025-05-20T07:51:40.710Z",
   "app/commerce-modules/product/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00",
   "app/commerce-modules/product/_events/page.mdx": "2024-07-03T19:27:13+03:00",
@@ -67,7 +67,7 @@ export const generatedEditDates = {
   "app/commerce-modules/product/page.mdx": "2025-05-20T07:51:40.711Z",
   "app/commerce-modules/promotion/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00",
   "app/commerce-modules/promotion/_events/page.mdx": "2024-07-03T19:27:13+03:00",
-  "app/commerce-modules/promotion/actions/page.mdx": "2024-10-09T14:49:01.645Z",
+  "app/commerce-modules/promotion/actions/page.mdx": "2025-06-27T15:42:19.142Z",
   "app/commerce-modules/promotion/application-method/page.mdx": "2024-06-26T07:55:59+00:00",
   "app/commerce-modules/promotion/campaign/page.mdx": "2025-02-26T11:32:24.484Z",
   "app/commerce-modules/promotion/concepts/page.mdx": "2025-02-26T11:31:54.391Z",
@@ -6546,8 +6546,6 @@ export const generatedEditDates = {
   "references/utils/utils.Payment/page.mdx": "2025-06-05T19:05:53.489Z",
   "app/integrations/guides/slack/page.mdx": "2025-06-26T12:57:20.880Z",
   "app/integrations/guides/sentry/page.mdx": "2025-06-16T10:11:29.955Z",
-  "app/integrations/guides/mailchimp/page.mdx": "2025-06-24T08:08:35.034Z",
-  "app/how-to-tutorials/tutorials/first-purchase-discounts/page.mdx": "2025-06-26T09:13:19.296Z",
   "app/integrations/guides/mailchimp/page.mdx": "2025-06-26T11:59:15.303Z",
   "app/how-to-tutorials/tutorials/first-purchase-discounts/page.mdx": "2025-06-26T11:55:27.175Z",
   "references/types/CommonTypes/interfaces/types.CommonTypes.CookieOptions/page.mdx": "2025-06-25T10:11:37.088Z",
@@ -6557,5 +6555,6 @@ export const generatedEditDates = {
   "references/types/interfaces/types.InitiatePaymentOutput/page.mdx": "2025-06-25T10:11:39.942Z",
   "references/types/interfaces/types.UpdatePaymentOutput/page.mdx": "2025-06-25T10:11:39.945Z",
   "app/how-to-tutorials/tutorials/gift-message/page.mdx": "2025-06-26T09:13:19.296Z",
-  "app/how-to-tutorials/tutorials/re-order/page.mdx": "2025-06-26T12:38:24.308Z"
+  "app/how-to-tutorials/tutorials/re-order/page.mdx": "2025-06-26T12:38:24.308Z",
+  "app/commerce-modules/promotion/promotion-taxes/page.mdx": "2025-06-27T15:44:46.638Z"
 }