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.