docs: docs for next release (#13621)

* docs: docs for next release * changes to opentelemetry dependencies * document plugin env variables * document admin changes * fix vale error * add version notes * document campaign budget updates * document campaign changes in user guide * document chages in cluster mode cli * documented once promotion allocation * document multiple API keys support
2025-10-21 10:32:08 +03:00
parent f38f0f9aca
commit ed715813a5
54 changed files with 1621 additions and 252 deletions
@@ -75,12 +75,12 @@ The [ApplicationMethod data model](/references/promotion/models/ApplicationMetho
      </Table.Cell>
      <Table.Cell>

-      Is the discounted amount applied to each item or split between the applicable items?
+      Is the discounted amount applied to each item, split between the applicable items, or applied on specific number of items?

      </Table.Cell>
      <Table.Cell>

-      `each`, `across`
+      `each`, `across`, `once`

      </Table.Cell>
    </Table.Row>
@@ -113,7 +113,11 @@ In this example, the cart must have two product variants with the SKU `SHIRT` fo

 ## Maximum Quantity Restriction

-When the `allocation` property in the `ApplicationMethod` is set to `each`, you can set the `max_quantity` property of `ApplicationMethod` to limit how many item quantities the promotion is applied to.
+You can restrict how many items the promotion is applied to either at the item level or the cart level.
+
+### Item Level Restriction
+
+When the `allocation` property in the `ApplicationMethod` is set to `each`, you can set the `max_quantity` property of `ApplicationMethod` to limit how many quantities of each applicable item the promotion is applied to.

 For example, if the `max_quantity` property is set to `1` and the customer has a line item with quantity two in the cart, the promotion is only applied to one of them.

@@ -147,4 +151,112 @@ This condition is applied on the quantity of every applicable item in the cart.
    ]
  }
 }
-```
+```
+
+### Cart Level Restriction
+
+<Note>
+
+The `once` allocation type is available from [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0).
+
+</Note>
+
+When the `allocation` property in the `ApplicationMethod` is set to `once`, you must set the `max_quantity` property of `ApplicationMethod`. It limits how many items in total the promotion is applied to.
+
+In this scenario, the Promotion Module prioritizes which applicable items the promotion is applied to based on the following rules:
+
+1. Prioritize items with the lowest price.
+2. Distribute the promotion sequentially until the `max_quantity` is reached.
+
+#### Example 1
+
+Consider:
+
+- A promotion whose application method has its `allocation` property set to `once` and `max_quantity` set to `2`.
+- A cart with three items having different prices, each with a quantity of `1`.
+
+The Promotion Module will apply the promotion to the two items with the lowest price.
+
+```json title="Example Cart"
+{
+  "cart": {
+    "items": [
+      {
+        "id": "item_1",
+        "price": 10,
+        "quantity": 1 // The promotion is applied to this item
+      },
+      {
+        "id": "item_2",
+        "price": 20,
+        "quantity": 1 // The promotion is applied to this item
+      },
+      {
+        "id": "item_3",
+        "price": 30,
+        "quantity": 1 // The promotion is NOT applied to this item
+      }
+    ]
+  }
+}
+```
+
+#### Example 2
+
+Consider:
+
+- A promotion whose application method has its `allocation` property set to `once` and `max_quantity` set to `2`.
+- A cart with two items having different prices and quantities greater than `2`.
+
+The Promotion Module will try to apply the promotion to the item with the lowest price first:
+
+```json title="Example Cart"
+{
+  "cart": {
+    "items": [
+      {
+        "id": "item_1",
+        "price": 10,
+        "quantity": 3 // The promotion is applied to 2 of this item
+      },
+      {
+        "id": "item_2",
+        "price": 20,
+        "quantity": 4 // The promotion is NOT applied to this item
+      }
+    ]
+  }
+}
+```
+
+Since that item has a quantity of `3`, the promotion is applied to `2` of that item, reaching the `max_quantity` limit. The promotion is not applied to the other item.
+
+#### Example 3
+
+Consider:
+
+- A promotion whose application method has its `allocation` property set to `once` and `max_quantity` set to `5`.
+- A cart with two items having different prices and quantities less than `5`.
+
+The Promotion Module will try to apply the promotion to the item with the lowest price first:
+
+```json title="Example Cart"
+{
+  "cart": {
+    "items": [
+      {
+        "id": "item_1",
+        "price": 10,
+        "quantity": 3 // The promotion is applied to all 3 of this item
+      },
+      {
+        "id": "item_2",
+        "price": 20,
+        "quantity": 4 // The promotion is applied to 2 of this item
+      }
+    ]
+  }
+}
+```
+
+The promotion is applied to all `3` quantities of the item with the lowest price. Since the `max_quantity` is `5`, the promotion is applied to `2` quantities of the other item, reaching the `max_quantity` limit.
@@ -14,31 +14,76 @@ Refer to this [Medusa Admin User Guide](!user-guide!/promotions/campaigns) to le

 ## What is a Campaign?

-A [Campaign](/references/promotion/models/Campaign) combines [promotions](../concepts/page.mdx#what-is-a-promotion) under the same conditions, such as start and end dates.
+A [Campaign](/references/promotion/models/Campaign) groups [promotions](../concepts/page.mdx#what-is-a-promotion) under the same conditions, such as start and end dates.

-Campaigns are useful for grouping promotions that share the same time frame or target audience. They're also useful for limiting the usage of promotions.
+Use campaigns to group promotions that share the same time frame or target audience, and to limit promotion usage.

 ![A diagram showcasing the relation between the Campaign and Promotion data models](https://res.cloudinary.com/dza7lstvk/image/upload/v1709899225/Medusa%20Resources/campagin-promotion_hh3qsi.jpg)

 ---

-## Campaign Limits
+## Limit Promotion Usage with Campaign Budgets

-Each campaign can have a budget represented by the [CampaignBudget data model](/references/promotion/models/CampaignBudget). The budget limits how many times the promotion can be used.
+Each campaign can have a budget represented by the [CampaignBudget data model](/references/promotion/models/CampaignBudget). The budget limits how many times a promotion can be used.

-There are two types of budgets:
+There are three types of budgets: two that are global and one that is based on cart attributes.

- `spend`: An amount that, when crossed, the promotion becomes unusable.
-    - For example, if the amount limit is set to `$100`, and the total amount of usage of this promotion crosses that threshold, the promotion can no longer be applied.
- `usage`: The number of times that a promotion can be used.
-    - For example, if the usage limit is set to `10`, the promotion can be used only 10 times by customers. After that, it can no longer be applied.
+### Global Budgets
+
+A global budget limits promotion usage without considering any cart attributes.
+
+There are two types of global budgets:
+
+- `spend`: An amount that, when exceeded, makes the promotion unusable.
+    - For example, if the amount limit is `$100` and the total usage of this promotion exceeds that threshold, the promotion can no longer be applied.
+- `usage`: The number of times a promotion can be used.
+    - For example, if the usage limit is `10`, customers can use the promotion only 10 times. After that, it can no longer be applied.

 ![A diagram showcasing the relation between the Campaign and CampaignBudget data models](https://res.cloudinary.com/dza7lstvk/image/upload/v1709899463/Medusa%20Resources/campagin-budget_rvqlmi.jpg)

-### How Budgets Limit Promotion Usage
+Global budgets track usage and limits through the following properties of the `CampaignBudget` data model:

-When a customer tries to use a promotion, Medusa checks whether the campaign has a budget and if the budget limit has been reached. If so, the promotion cannot be applied.
+- `limit`: The maximum amount or number of uses allowed for the promotion.
+- `used`: The current amount spent or number of times the promotion has been used.

-For example, if a campaign has a budget of type `usage` with a limit of `10`, and the promotion has already been used 10 times, it cannot be applied anymore and is considered expired.
+### Attribute-based Budgets

-However, once a promotion is applied to a cart, it remains valid until the order is completed, even if the budget limit is reached in the meantime. This ensures that customers who have already applied the promotion can still benefit from it during checkout.
+<Note>
+
+Attribute-based budgets were introduced in [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0).
+
+</Note>
+
+An attribute-based budget limits promotion usage based on a cart attribute. Use these budget types to have granular control over how many times a promotion can be used based on specific attributes.
+
+There's one type of attribute-based budget, which is `use_by_attribute`. It allows you to limit the number of times a promotion can be used based on a specific cart attribute.
+
+#### Allowed Attributes
+
+There are two attributes that you can limit promotion usage by:
+
+- `customer_id`: Limits promotion usage based on the unique identifier of a customer.
+- `customer_email`: Limits promotion usage based on the email address of a customer.
+
+These attributes are compared against the cart's `customer_id` or `email` to determine how many times the promotion has been used for that specific attribute value, and whether the budget limit has been reached.
+
+#### Tracking Attribute-based Usage
+
+The `CampaignBudgetUsage` data model tracks the usage of attribute-based budgets. It tracks how many times a promotion has been used for each unique attribute value. It includes the following properties:
+
+1. `attribute_value`: The value of the attribute, such as a specific customer ID or email.
+2. `used`: The number of times the promotion has been used for that attribute value.
+
+For example, if the attribute is `customer_id`, a new `CampaignBudgetUsage` record is created for each customer that uses the promotion to track their individual usage. Once a customer exceeds the limit set in the `CampaignBudget`, they can no longer use the promotion.
+
+![A diagram showcasing the relation between the CampaignBudget and CampaignBudgetUsage data models](https://res.cloudinary.com/dza7lstvk/image/upload/v1760340527/Medusa%20Resources/campaign-budget-attr_fv0v2u.jpg)
+
+---
+
+## How Campaign Budgets Limit Promotion Usage
+
+When a customer tries to use a promotion, Medusa checks whether the campaign has a budget and if the budget limit has been reached. If the limit is reached, the promotion cannot be applied.
+
+For example, if a campaign has a `usage` budget with a limit of `10` and the promotion has already been used 10 times, it can no longer be applied and is considered expired.
+
+However, once a promotion is applied to a cart, it remains valid until the order is completed, even if the budget limit is reached in the meantime. This ensures that customers who already applied the promotion can still benefit from it during checkout.