DEVDOCS-5646 [update] Checkouts, changes to discounts

reference/checkouts.v3.yml

@@ -1604,14 +1604,19 @@ paths:
         - Checkout Discounts
       summary: Add Discount to Checkout
       description: |-
-        Adds a discount to an existing *checkout*.
-
-        This discount only applies to `line_items`. When you call this API, you clear out all existing discounts applied to line items, including product and order-based discounts.
+        Adds a discount to an existing checkout.
+
+        Use this endpoint to apply the following discounts:
+        * Apply a manual discount to a cart. In this case, you can distribute the discount between each line item in the cart based on the item value.
+        * Apply a manual discount against a specific line item.
+        * Apply a manual discount at the item-level with a cart-level discount.
 
-        This endpoint splits the discount between line items based on the item value.
+        Notes:
+        * When you call this API, you clear out all existing discounts applied to line items, including product and order-based discounts.
+        * You cannot apply a manual discount to a specific line item if you have already applied a coupon or automatic promotion to it.
 
-        Required Fields
-        * discounted_amount
+        Required Fields:
+        * `discounted_amount` at the cart-level or at the item-level
       operationId: addCheckoutDiscount
       parameters:
         - $ref: '#/components/parameters/checkoutId'
@@ -1639,6 +1644,17 @@ paths:
                           name:
                             type: string
                             example: manual
+                    line_items:
+                        type: array
+                        items:
+                          type: object
+                          properties:
+                              id:
+                                type: string
+                                example: 8edef915-8e8e-4ebd-bece-31fbb1191a7e
+                              discounted_amount:
+                                type: number
+                                example: 15
         required: false
       responses:
         '200':