doc(orders): ORDERS-7176 new field comparisonShippingCost in SF Order API (#1103)

# [ORDERS-7176]


## What changed?
new fields in SF Order API as implemented in
bigcommerce/bigcommerce#65225:

* `comparisonShippingCost` field in order root

<img width="1598" height="1722" alt="SCR-20251008-l0w"
src="https://github.com/user-attachments/assets/860688c7-8f1b-482d-9749-58a9627e0dcf"
/>


* `comparisonShippingCost` and `shippingCostBeforeDiscount` fields in
`order.consignments.shipping`

<img width="1440" height="1680" alt="SCR-20251008-l1e"
src="https://github.com/user-attachments/assets/5ef1f2f8-b57a-47e4-b477-df9d94b889bd"
/>


## Release notes draft
N/A

## Anything else?
None

ping @bigcommerce/team-orders 


[ORDERS-7176]:
https://bigcommercecloud.atlassian.net/browse/ORDERS-7176?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

Author: donald-nguyen-bc

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 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: 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 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
           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