From 1e90f8251195842f0ad7000a47a663c11300197b Mon Sep 17 00:00:00 2001
From: "donald.nguyen" <donald.nguyen@bigcommerce.com>
Date: Wed, 8 Oct 2025 15:10:32 +1100
Subject: [PATCH 1/2] doc(orders): ORDERS-7176 new field comparisonShippingCost
 in SF Order API

---
 reference/orders.sf.yml | 24 +++++++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)

diff --git a/reference/orders.sf.yml b/reference/orders.sf.yml
index 20719ac44..af5a599cb 100644
--- a/reference/orders.sf.yml
+++ b/reference/orders.sf.yml
@@ -146,11 +146,18 @@ components:
           type: string
           description: Shopperʼs provided message for the order.
         shippingCostTotal:
-          type: integer
+          type: number
         shippingCostBeforeDiscount:
-          type: integer
+          type: number
+          description: Estimated total shipping cost before any shipping discounts have been applied.
+        comparisonShippingCost:
+          type: number
+          description: |
+            The total shipping cost to be shown to shopper in the summary as struck-through.
+            - If the entered-price and display-price have same tax setting (e.g.: both are tax-inclusive), this field will be the estimated total shipping cost before any coupons applied (but after automatic promotions applied).
+            - If the entered-price and display-price have different tax setting (e.g.: one is tax-inclusive, and one is tax-exclusive), this field will be the estimated total shipping cost before any discounts applied, similar to the `shippingCostBeforeDiscount`.
         handlingCostTotal:
-          type: integer
+          type: number
         customerCanBeCreated:
           type: boolean
         taxes:
@@ -907,6 +914,15 @@ components:
         costTaxClassId:
           type: integer
           example: 2
+        shippingCostBeforeDiscount:
+          type: number
+          description: Estimated consignment shipping cost before any shipping discounts have been applied.
+        comparisonShippingCost:
+          type: number
+          description: |
+            The consignment shipping cost to be shown to shopper in the summary as struck-through.
+            - If the entered-price and display-price have same tax setting (e.g.: both are tax-inclusive), this field will be the estimated shipping cost before any coupons applied (but after automatic promotions applied).
+            - If the entered-price and display-price have different tax setting (e.g.: one is tax-inclusive, and one is tax-exclusive), this field will be the estimated shipping cost before any discounts applied, similar to the `shippingCostBeforeDiscount`.
         baseHandlingCost:
           type: number
           example: 0.00
@@ -958,6 +974,8 @@ components:
           costIncTax: 16.7
           costTax: 1.2
           costTaxClassId: 2
+          shippingCostBeforeDiscount: 17.5
+          comparisonShippingCost: 16.5
           baseHandlingCost: 0
           handlingCostExTax: 0
           handlingCostIncTax: 0

From f450b84d9c2ca1af6e14d8e90d4fa074962fcd9f Mon Sep 17 00:00:00 2001
From: "donald.nguyen" <donald.nguyen@bigcommerce.com>
Date: Thu, 9 Oct 2025 09:21:48 +1100
Subject: [PATCH 2/2] doc(orders): ORDERS-7176 fix some typos

---
 reference/orders.sf.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/reference/orders.sf.yml b/reference/orders.sf.yml
index af5a599cb..6c9ecd2f9 100644
--- a/reference/orders.sf.yml
+++ b/reference/orders.sf.yml
@@ -154,7 +154,7 @@ components:
           type: number
           description: |
             The total shipping cost to be shown to shopper in the summary as struck-through.
-            - If the entered-price and display-price have same tax setting (e.g.: both are tax-inclusive), this field will be the estimated total shipping cost before any coupons applied (but after automatic promotions applied).
+            - If the entered-price and display-price have the same tax setting (e.g.: both are tax-inclusive), this field will be the estimated total shipping cost before any coupons applied (but after automatic promotions applied).
             - If the entered-price and display-price have different tax setting (e.g.: one is tax-inclusive, and one is tax-exclusive), this field will be the estimated total shipping cost before any discounts applied, similar to the `shippingCostBeforeDiscount`.
         handlingCostTotal:
           type: number
@@ -921,7 +921,7 @@ components:
           type: number
           description: |
             The consignment shipping cost to be shown to shopper in the summary as struck-through.
-            - If the entered-price and display-price have same tax setting (e.g.: both are tax-inclusive), this field will be the estimated shipping cost before any coupons applied (but after automatic promotions applied).
+            - If the entered-price and display-price have the same tax setting (e.g.: both are tax-inclusive), this field will be the estimated shipping cost before any coupons applied (but after automatic promotions applied).
             - If the entered-price and display-price have different tax setting (e.g.: one is tax-inclusive, and one is tax-exclusive), this field will be the estimated shipping cost before any discounts applied, similar to the `shippingCostBeforeDiscount`.
         baseHandlingCost:
           type: number