feat(checkout): CHECKOUT-7756 Update docs around item-level discount

reference/checkouts.v3.yml

@@ -1599,12 +1599,19 @@ paths:
       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.
-
-        This endpoint splits the discount between line items based on the item value.
-
+        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 items 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 along with a cart level discount.
+
+        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 against a specific line item if you have already applied a coupon/automatic promotion to this item.
+
         Required Fields
-        * discounted_amount
+        * discounted_amount at the cart level or at the item level
+
       operationId: post-store_hash-v3-checkouts-checkoutId-discounts
       parameters:
         - $ref: '#/components/parameters/storeHash'
@@ -1633,6 +1640,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':