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

2025-06-27 19:05:24 +03:00
parent 0bcde275bc
commit 1e16fa6f57
10 changed files with 353 additions and 25 deletions
@@ -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.
@@ -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.
@@ -29,6 +29,7 @@ export interface AddItemAdjustmentAction {
  amount: number
  code: string
  description?: string
+  is_tax_inclusive?: boolean
 }
 ```

@@ -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.
@@ -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"
 }
@@ -507,6 +507,10 @@ export const filesMap = [
    "filePath": "/www/apps/resources/app/commerce-modules/promotion/page.mdx",
    "pathname": "/commerce-modules/promotion"
  },
+  {
+    "filePath": "/www/apps/resources/app/commerce-modules/promotion/promotion-taxes/page.mdx",
+    "pathname": "/commerce-modules/promotion/promotion-taxes"
+  },
  {
    "filePath": "/www/apps/resources/app/commerce-modules/promotion/workflows/page.mdx",
    "pathname": "/commerce-modules/promotion/workflows"
@@ -1127,10 +1131,6 @@ export const filesMap = [
    "filePath": "/www/apps/resources/app/storefront-development/cart/manage-items/page.mdx",
    "pathname": "/storefront-development/cart/manage-items"
  },
-  {
-    "filePath": "/www/apps/resources/app/storefront-development/cart/page.mdx",
-    "pathname": "/storefront-development/cart"
-  },
  {
    "filePath": "/www/apps/resources/app/storefront-development/cart/retrieve/page.mdx",
    "pathname": "/storefront-development/cart/retrieve"
@@ -1191,10 +1191,6 @@ export const filesMap = [
    "filePath": "/www/apps/resources/app/storefront-development/customers/login/page.mdx",
    "pathname": "/storefront-development/customers/login"
  },
-  {
-    "filePath": "/www/apps/resources/app/storefront-development/customers/page.mdx",
-    "pathname": "/storefront-development/customers"
-  },
  {
    "filePath": "/www/apps/resources/app/storefront-development/customers/profile/page.mdx",
    "pathname": "/storefront-development/customers/profile"
@@ -1231,10 +1227,6 @@ export const filesMap = [
    "filePath": "/www/apps/resources/app/storefront-development/products/categories/nested-categories/page.mdx",
    "pathname": "/storefront-development/products/categories/nested-categories"
  },
-  {
-    "filePath": "/www/apps/resources/app/storefront-development/products/categories/page.mdx",
-    "pathname": "/storefront-development/products/categories"
-  },
  {
    "filePath": "/www/apps/resources/app/storefront-development/products/categories/products/page.mdx",
    "pathname": "/storefront-development/products/categories/products"
@@ -1247,10 +1239,6 @@ export const filesMap = [
    "filePath": "/www/apps/resources/app/storefront-development/products/collections/list/page.mdx",
    "pathname": "/storefront-development/products/collections/list"
  },
-  {
-    "filePath": "/www/apps/resources/app/storefront-development/products/collections/page.mdx",
-    "pathname": "/storefront-development/products/collections"
-  },
  {
    "filePath": "/www/apps/resources/app/storefront-development/products/collections/products/page.mdx",
    "pathname": "/storefront-development/products/collections/products"
@@ -1267,10 +1255,6 @@ export const filesMap = [
    "filePath": "/www/apps/resources/app/storefront-development/products/list/page.mdx",
    "pathname": "/storefront-development/products/list"
  },
-  {
-    "filePath": "/www/apps/resources/app/storefront-development/products/page.mdx",
-    "pathname": "/storefront-development/products"
-  },
  {
    "filePath": "/www/apps/resources/app/storefront-development/products/price/examples/sale-price/page.mdx",
    "pathname": "/storefront-development/products/price/examples/sale-price"
@@ -6086,6 +6086,14 @@ const generatedgeneratedCommerceModulesSidebarSidebar = {
          "sort_sidebar": "alphabetize",
          "description": "Learn how to use the Order Module in your customizations on the Medusa application server.",
          "children": [
+            {
+              "loaded": true,
+              "isPathHref": true,
+              "type": "ref",
+              "title": "Add Gift Message",
+              "path": "https://docs.medusajs.com/resources/how-to-tutorials/tutorials/gift-message",
+              "children": []
+            },
            {
              "loaded": true,
              "isPathHref": true,
@@ -13088,6 +13096,14 @@ const generatedgeneratedCommerceModulesSidebarSidebar = {
              "title": "Promotion",
              "children": []
            },
+            {
+              "loaded": true,
+              "isPathHref": true,
+              "type": "link",
+              "path": "/commerce-modules/promotion/promotion-taxes",
+              "title": "Tax-Inclusive Promotions",
+              "children": []
+            },
            {
              "loaded": true,
              "isPathHref": true,
@@ -22,6 +22,11 @@ export const promotionSidebar = [
            path: "/commerce-modules/promotion/concepts",
            title: "Promotion",
          },
+          {
+            type: "link",
+            path: "/commerce-modules/promotion/promotion-taxes",
+            title: "Tax-Inclusive Promotions",
+          },
          {
            type: "link",
            path: "/commerce-modules/promotion/application-method",
@@ -39,6 +39,10 @@ export const order = [
    "title": "Implement Quote Management",
    "path": "https://docs.medusajs.com/resources/examples/guides/quote-management"
  },
+  {
+    "title": "Add Gift Message",
+    "path": "https://docs.medusajs.com/resources/how-to-tutorials/tutorials/gift-message"
+  },
  {
    "title": "Implement Loyalty Points",
    "path": "https://docs.medusajs.com/resources/how-to-tutorials/tutorials/loyalty-points"
@@ -7,6 +7,10 @@ export const tax = [
    "title": "Get Variant Price with Taxes",
    "path": "https://docs.medusajs.com/resources/commerce-modules/product/guides/price-with-taxes"
  },
+  {
+    "title": "Tax-Inclusive Promotions",
+    "path": "https://docs.medusajs.com/resources/commerce-modules/promotion/promotion-taxes"
+  },
  {
    "title": "Example: Show Price with Taxes",
    "path": "https://docs.medusajs.com/resources/storefront-development/products/price/examples/tax-price"