From 1bcabc537c1292baec547711c844f540b26a441c Mon Sep 17 00:00:00 2001
From: vincent zhao <vincent.zhao@bigcommerce.com>
Date: Mon, 15 Dec 2025 16:52:38 +1100
Subject: [PATCH 1/2] doc(promotions): DEVDOCS-6652 add
 maximum_allowed_discount_amount to promotion api

---
 reference/promotions.v3.yml | 26 +++++++++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)

diff --git a/reference/promotions.v3.yml b/reference/promotions.v3.yml
index 0208aa532..7cfbd73de 100644
--- a/reference/promotions.v3.yml
+++ b/reference/promotions.v3.yml
@@ -985,6 +985,8 @@ components:
           properties:
             discount:
               $ref: '#/components/schemas/Discount'
+            maximum_allowed_discount_amount:
+              $ref: '#/components/schemas/MaximumAllowedDiscountAmount'
       description: |-
         **Cart Value Action**
         Applies discount on the entire cart.
@@ -1054,6 +1056,8 @@ components:
           properties:
             discount:
               $ref: '#/components/schemas/Discount'
+            maximum_allowed_discount_amount:
+              $ref: '#/components/schemas/MaximumAllowedDiscountAmount'
             as_total:
               type: boolean
               description: |-
@@ -1128,6 +1132,8 @@ components:
           type: string
           description: The amount of discount (percentage off) to apply.
       description: '**Percentage Discount**'
+      required:
+        - percentage_amount
     FixedDiscount:
       title: Fixed Discount
       type: object
@@ -1135,6 +1141,8 @@ components:
         fixed_amount:
           $ref: '#/components/schemas/Money'
       description: '**Fixed Discount**'
+      required:
+        - fixed_amount
     Money:
       title: Money
       pattern: '[0-9]+(\.[0-9]+)?'
@@ -1143,6 +1151,17 @@ components:
         **Money**
         Represents a monetary value in the store’s default currency.
       example: '12.95'
+    MaximumAllowedDiscountAmount:
+      type: string
+      nullable: true
+      pattern: '^(0|([1-9][0-9]*))(\.[0-9]+)?$'
+      description: |
+        The maximum monetary value that can be applied as a discount. It can take value from 1 to 10000000.
+        The application of this maximum depends on the discount type:
+          - Discount on shipping: the max limit is distributed to the first number of shipping destinations until it is reached
+          - Discount on products: the max limit is distributed to the first number of eligible products until it is reached
+          - Discount on order subtotal: the max limit is checked against the order discount value
+      example: '10'
     OptionalCursorCollectionMeta:
       title: Collection Meta
       type: object
@@ -1939,8 +1958,8 @@ components:
                 data:
                   - id: 1
                     redemption_type: AUTOMATIC
-                    name: Buy Product X Get Free Shipping
-                    display_name: WOW!!! FREE SHIPPING for Product X
+                    name: Buy Product worth X Get Y% off upto Z
+                    display_name: Shop for X and get Y% off upto Z
                     created_from: api
                     channels:
                       - id: 1
@@ -1961,7 +1980,8 @@ components:
                       - action:
                           cart_value:
                             discount:
-                              fixed_amount: '12.95'
+                              percentage_amount: '10'
+                            maximum_allowed_discount_amount: '20'
                         apply_once: true
                         stop: true
                         condition:

From cd20e6110db8c6dc035d635f63f6e070b262ecd2 Mon Sep 17 00:00:00 2001
From: vincent zhao <vincent.zhao@bigcommerce.com>
Date: Mon, 15 Dec 2025 17:42:13 +1100
Subject: [PATCH 2/2] doc(promotions): DEVDOCS-6652 update regex to disallow
 0.0 value

---
 reference/promotions.v3.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/reference/promotions.v3.yml b/reference/promotions.v3.yml
index 7cfbd73de..acd7f20cd 100644
--- a/reference/promotions.v3.yml
+++ b/reference/promotions.v3.yml
@@ -1154,7 +1154,7 @@ components:
     MaximumAllowedDiscountAmount:
       type: string
       nullable: true
-      pattern: '^(0|([1-9][0-9]*))(\.[0-9]+)?$'
+      pattern: '^(?!0+(?:\.0+)?$)(\d+)(\.[0-9]+)?$'
       description: |
         The maximum monetary value that can be applied as a discount. It can take value from 1 to 10000000.
         The application of this maximum depends on the discount type: