From e9f32d9ea6234ade8dd9678cbce98d963e86783a Mon Sep 17 00:00:00 2001
From: paige <31039783+YevenLourance@users.noreply.github.com>
Date: Wed, 24 Dec 2025 10:42:55 +1100
Subject: [PATCH] docs(promotions): PROMO-1368 update to
 coupon_overrides_other_promotions

update to coupon_overrides_other_promotions
---
 reference/promotions.v3.yml | 60 +++++++++++++++++++++----------------
 1 file changed, 34 insertions(+), 26 deletions(-)

diff --git a/reference/promotions.v3.yml b/reference/promotions.v3.yml
index 849e2c101..1b22eae76 100644
--- a/reference/promotions.v3.yml
+++ b/reference/promotions.v3.yml
@@ -510,15 +510,10 @@ components:
           properties:
             codes:
               $ref: '#/components/schemas/CouponCode'
+            coupon_overrides_other_promotions:
+              $ref: '#/components/schemas/CouponOverridesOtherPromotions'
             coupon_overrides_automatic_when_offering_higher_discounts:
-              type: boolean
-              example: false
-              default: false
-              description: |-
-                This field only has effect when `can_be_used_with_other_promotions` is `false`:
-                - When the property is set to `true`, the coupon will override the applied automatic promotions if it provides a greater discount.
-                - When the property is set to `fasle`, the coupon will not be applied if automatic promotions are already applied.
-                Trying to set the value of this field to `true` when `can_be_used_with_other_promotions` is `true` will yield a 422 error response.
+              $ref: '#/components/schemas/CouponOverridesAutomaticWhenOfferingHigherDiscounts'
             coupon_type:
               type: string
               enum:
@@ -538,15 +533,10 @@ components:
           properties:
             codes:
               $ref: '#/components/schemas/CouponCode'
+            coupon_overrides_other_promotions:
+              $ref: '#/components/schemas/CouponOverridesOtherPromotions'
             coupon_overrides_automatic_when_offering_higher_discounts:
-              type: boolean
-              example: false
-              default: false
-              description: |-
-                This field only has effect when `can_be_used_with_other_promotions` is `false`:
-                - When the property is set to `true`, the coupon will override the applied automatic promotions if it provides a greater discount.
-                - When the property is set to `fasle`, the coupon will not be applied if automatic promotions are already applied.
-                Trying to set the value of this field when `can_be_used_with_other_promotions` is `true` will yield a 422 error response.
+              $ref: '#/components/schemas/CouponOverridesAutomaticWhenOfferingHigherDiscounts'
             redemption_type:
               type: string
               description: The type of the promotion. Promotions applied automatically have a value of `AUTOMATIC` whereas promotions requiring a coupon have a value of `COUPON`.
@@ -580,16 +570,12 @@ components:
               $ref: '#/components/schemas/CreatedFrom'
             codes:
               $ref: '#/components/schemas/CouponCode'
-            coupon_overrides_automatic_when_offering_higher_discounts:
-              type: boolean
-              example: false
-              default: false
-              description: |-
-                This field only has effect when the `redemption_type` is `COUPON` and `can_be_used_with_other_promotions` is `false`:
-                - When the property is set to `true`, the coupon will override the applied automatic promotions if it provides a greater discount.
-                - When the property is set to `fasle`, the coupon will not be applied if automatic promotions are already applied.
 
-                Trying to set the value of this field to `true` when the `redemption_type` is not `COUPON`, or when `can_be_used_with_other_promotions` is `true` will yield a 422 error response.
+            coupon_overrides_other_promotions:
+              $ref: '#/components/schemas/CouponOverridesOtherPromotions'
+
+            coupon_overrides_automatic_when_offering_higher_discounts:
+              $ref: '#/components/schemas/CouponOverridesAutomaticWhenOfferingHigherDiscounts'
             redemption_type:
               type: string
               description: The type of the promotion. Promotions applied automatically have a value of `AUTOMATIC` whereas promotions requiring a coupon have a value of `COUPON`.
@@ -624,7 +610,7 @@ components:
         - start_date
         - status
         - can_be_used_with_other_promotions
-        - coupon_overrides_automatic_when_offering_higher_discounts
+        - coupon_overrides_other_promotions
         - coupon_type
     PatchAutomaticPromotion:
       title: Patch Automatic Promotion
@@ -1733,6 +1719,28 @@ components:
           $ref: '#/components/schemas/CustomerSegmentIdLimitation'
       required:
         - not
+    CouponOverridesAutomaticWhenOfferingHigherDiscounts:
+      title: CouponOverridesAutomaticWhenOfferingHigherDiscounts
+      deprecated: true
+      type: boolean
+      example: false
+      default: false
+      description: |-
+        This property has been deprecated and `coupon_overrides_other_promotions` should be used instead.
+        This field only has effect when the `redemption_type` is `COUPON` and `can_be_used_with_other_promotions` is `false`:
+        - When the property is set to `true`, the coupon will override the applied automatic promotions if it provides a greater discount.
+        - When the property is set to `false`, the coupon will not be applied if automatic promotions are already applied.
+        Trying to set the value of this field to `true` when the `redemption_type` is not `COUPON`, or when `can_be_used_with_other_promotions` is `true` will yield a 422 error response.
+    CouponOverridesOtherPromotions:
+      title: CouponOverridesOtherPromotions
+      type: boolean
+      example: false
+      default: false
+      description: |-
+        - When this property is set to `true`, the coupon will always override all applied promotions, including both automatic and coupon promotions.
+        - When this property is set to `false`, the coupon will not be applied if any promotions are already applied.
+        
+        N.B.: This field only has effect when `can_be_used_with_other_promotions` is `false`. Trying to set the value of this field when `can_be_used_with_other_promotions` is `true` will yield a 422 error response.
     Channel:
       title: Channel
       type: object