feat(promotions): PROMO-1064 Add shipping discount action

docs/store-operations/promotions/examples/shipping.mdx

@@ -283,7 +283,7 @@
 
 <Tabs items={['Request', 'Response']}>
   <Tab>
-  
+
     ```json filename="Example request" showLineNumbers copy
     {
       "name": "Order at least 2X of product and get free shipping",
@@ -419,3 +419,79 @@
 
   </Tab>
 </Tabs>
+
+## Spend at least $100 and get $10 off shipping (specific methods)
+
+<Tabs items={['Request', 'Response']}>
+  <Tab>
+    ```json filename="Example request" showLineNumbers copy
+    {
+      "name": "Spend at least $100 and get $10 off shipping (specific methods)",
+      "redemption_type": "AUTOMATIC",
+      "rules": [
+        {
+          "action": {
+            "shipping_discount": {
+              "discount": { "fixed_amount": 10 },
+              "method_ids": [1, 3]
+            }
+          },
+          "apply_once": true,
+          "stop": false,
+          "condition": { "cart": { "minimum_spend": 100 } }
+        }
+      ],
+      "notifications": [],
+      "stop": false,
+      "status": "ENABLED",
+      "currency_code": "USD",
+      "start_date": "2025-10-01T00:00:00-05:00",
+      "end_date": null
+    }
+    ```
+
+  </Tab>
+  <Tab>
+    ```json filename="Example response" showLineNumbers copy
+      {
+      "data": {
+        "id": 1,
+        "name": "Spend at least $100 and get $10 off shipping (specific methods)",
+        "created_from": "api",
+        "customer": {
+          "group_ids": [],
+          "minimum_order_count": 0,
+          "excluded_group_ids": [],
+          "segments": null
+        },
+        "rules": [
+          {
+            "action": {
+              "shipping_discount": {
+                "discount": { "fixed_amount": "10" },
+                "method_ids": [1, 3]
+              }
+            },
+            "apply_once": true,
+            "stop": false,
+            "condition": { "cart": { "minimum_spend": "100" } }
+          }
+        ],
+        "notifications": [],
+        "stop": false,
+        "currency_code": "USD",
+        "redemption_type": "AUTOMATIC",
+        "shipping_address": null,
+        "current_uses": 0,
+        "max_uses": null,
+        "start_date": "2025-10-01T05:00:00+00:00",
+        "end_date": null,
+        "status": "ENABLED",
+        "schedule": null,
+        "can_be_used_with_other_promotions": true
+      },
+      "meta": {}
+    }
+    ```
+  </Tab>
+</Tabs>

docs/store-operations/promotions/index.mdx

@@ -9,6 +9,7 @@
   * Cart value **action** applies to the promotion value of the entire cart.
   * Gift item **action** gives a free gift item.
   * Fixed price set **action** applies a fixed price for a set of items.
+  * Shipping discount **action** applies discounts to the selected or all shipping methods.
 </Callout>
 
 

reference/promotions.v3.yml

@@ -1076,6 +1076,35 @@ components:
                     minimum: 1
           required:
             - zone_ids
+    ShippingDiscountAction:
+      title: Shipping Discount Action
+      type: object
+      description: |-
+        **Shipping Discount Action**
+        Discounts shipping, optionally restricted to specific shipping methods.
+      properties:
+        shipping_discount:
+          type: object
+          properties:
+            discount:
+              $ref: '#/components/schemas/Discount'
+            method_ids:
+              description: ''
+              oneOf:
+                - type: string
+                  enum:
+                    - '*'
+                  description: All configured shipping methods.
+                - type: array
+                  uniqueItems: true
+                  description: List of shipping method IDs to which the shipping discount can apply.
+                  items:
+                    type: integer
+                    minimum: 1
+                    maximum: 250
+          required:
+            - method_ids
+            - discount
     Discount:
       title: Discount
       description: '**Discount**'
@@ -1346,6 +1375,7 @@ components:
         - $ref: '#/components/schemas/GiftItemAction'
         - $ref: '#/components/schemas/FixedPriceSetAction'
         - $ref: '#/components/schemas/ShippingAction'
+        - $ref: '#/components/schemas/ShippingDiscountAction'
     ProductOptionsItemMatcher:
       title: Product Options Item Matcher
       type: object