You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -37367,7 +37367,7 @@ The [ApplicationMethod data model](https://docs.medusajs.com/references/promotio
37367
37367
|---|---|---|
37368
37368
|\`type\`|Does the promotion discount a fixed amount or a percentage?|\`fixed\`|
37369
37369
|\`target\_type\`|Is the promotion applied to a cart item, shipping method, or the entire order?|\`items\`|
37370
-
|\`allocation\`|Is the discounted amount applied to each item or split between the applicable items?|\`each\`|
37370
+
|\`allocation\`|Is the discounted amount applied to each item, split between the applicable items, or applied on specific number of items?|\`each\`|
37371
37371
37372
37372
## Target Promotion Rules
37373
37373
@@ -37395,7 +37395,11 @@ In this example, the cart must have two product variants with the SKU `SHIRT` fo
37395
37395
37396
37396
## Maximum Quantity Restriction
37397
37397
37398
-
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.
37398
+
You can restrict how many items the promotion is applied to either at the item level or the cart level.
37399
+
37400
+
### Item Level Restriction
37401
+
37402
+
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.
37399
37403
37400
37404
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.
37401
37405
@@ -37431,6 +37435,110 @@ This condition is applied on the quantity of every applicable item in the cart.
37431
37435
}
37432
37436
```
37433
37437
37438
+
### Cart Level Restriction
37439
+
37440
+
The `once` allocation type is available from [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0).
37441
+
37442
+
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.
37443
+
37444
+
In this scenario, the Promotion Module prioritizes which applicable items the promotion is applied to based on the following rules:
37445
+
37446
+
1. Prioritize items with the lowest price.
37447
+
2. Distribute the promotion sequentially until the `max_quantity` is reached.
37448
+
37449
+
#### Example 1
37450
+
37451
+
Consider:
37452
+
37453
+
- A promotion whose application method has its `allocation` property set to `once` and `max_quantity` set to `2`.
37454
+
- A cart with three items having different prices, each with a quantity of `1`.
37455
+
37456
+
The Promotion Module will apply the promotion to the two items with the lowest price.
37457
+
37458
+
```json title="Example Cart"
37459
+
{
37460
+
"cart": {
37461
+
"items": [
37462
+
{
37463
+
"id": "item_1",
37464
+
"price": 10,
37465
+
"quantity": 1 // The promotion is applied to this item
37466
+
},
37467
+
{
37468
+
"id": "item_2",
37469
+
"price": 20,
37470
+
"quantity": 1 // The promotion is applied to this item
37471
+
},
37472
+
{
37473
+
"id": "item_3",
37474
+
"price": 30,
37475
+
"quantity": 1 // The promotion is NOT applied to this item
37476
+
}
37477
+
]
37478
+
}
37479
+
}
37480
+
```
37481
+
37482
+
#### Example 2
37483
+
37484
+
Consider:
37485
+
37486
+
- A promotion whose application method has its `allocation` property set to `once` and `max_quantity` set to `2`.
37487
+
- A cart with two items having different prices and quantities greater than `2`.
37488
+
37489
+
The Promotion Module will try to apply the promotion to the item with the lowest price first:
37490
+
37491
+
```json title="Example Cart"
37492
+
{
37493
+
"cart": {
37494
+
"items": [
37495
+
{
37496
+
"id": "item_1",
37497
+
"price": 10,
37498
+
"quantity": 3 // The promotion is applied to 2 of this item
37499
+
},
37500
+
{
37501
+
"id": "item_2",
37502
+
"price": 20,
37503
+
"quantity": 4 // The promotion is NOT applied to this item
37504
+
}
37505
+
]
37506
+
}
37507
+
}
37508
+
```
37509
+
37510
+
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.
37511
+
37512
+
#### Example 3
37513
+
37514
+
Consider:
37515
+
37516
+
- A promotion whose application method has its `allocation` property set to `once` and `max_quantity` set to `5`.
37517
+
- A cart with two items having different prices and quantities less than `5`.
37518
+
37519
+
The Promotion Module will try to apply the promotion to the item with the lowest price first:
37520
+
37521
+
```json title="Example Cart"
37522
+
{
37523
+
"cart": {
37524
+
"items": [
37525
+
{
37526
+
"id": "item_1",
37527
+
"price": 10,
37528
+
"quantity": 3 // The promotion is applied to all 3 of this item
37529
+
},
37530
+
{
37531
+
"id": "item_2",
37532
+
"price": 20,
37533
+
"quantity": 4 // The promotion is applied to 2 of this item
37534
+
}
37535
+
]
37536
+
}
37537
+
}
37538
+
```
37539
+
37540
+
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.
0 commit comments