doc(checkout): CHECKOUT-8739 update doc to reflect new feature of ord…

…er level fees. (#642)

<!-- Ticket number or summary of work -->
#
[CHECKOUT-8739](https://bigcommercecloud.atlassian.net/browse/CHECKOUT-8739)


## What changed?

<details open>
<summary> <h3> bulk Fees APIs</h3>
</summary>

v3 checkout api changes:

Have 3 endpoints to support bulk operations on fees:
- POST v3/checkouts/:checkoutId/fees
- PUT v3/checkouts/:checkoutId/fees
- DELETE v3/checkouts/:checkoutId/fees

storefront checkout api:
- response of checkout object added applied fees (fees:)

### Overall 

![image](https://github.com/user-attachments/assets/b4164b80-0d1c-42f5-a2d9-c780cf1d15e0)

### bulk POST

![image](https://github.com/user-attachments/assets/c37b721a-736f-4a34-b03d-320631f3fff0)

### bulk PUT
<img width="1221" alt="Screenshot 2024-11-28 at 10 11 24 AM"
src="https://github.com/user-attachments/assets/6bfb89a7-6a04-49c8-8e47-b15d3358106b">

### bulk DELETE

![image](https://github.com/user-attachments/assets/65d20c64-6f50-401f-994a-7eab883b4e18)

</details>


## Release notes draft

* The newly-released custom order level fees on the checkout is now
available to use. Now, you’ll be able to apply and manage the checkout's
order level fees via v3 management api, and fetch any checkout's applied
fees on storefront checkout api and v3 management checkout api.

## Anything else?

ping @bigcommerce/team-checkout @bigcommerce/dev-docs 


[CHECKOUT-8739]:
https://bigcommercecloud.atlassian.net/browse/CHECKOUT-8739?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

reference/checkouts.sf.yml

@@ -898,7 +898,15 @@ components:
             discountedAmount: 5
             displayName: $5.00 off the order total
             id: 1
-        customer: 
+        fees:
+          - id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
+            type: custom_fee
+            name: AAINS
+            displayName: Package Protection Insurance
+            cost: 12.02
+            source: AA
+            taxClassId: 12
+        customer:
           addresses: [{}]
           customerGroup:
             id: 1
@@ -965,6 +973,11 @@ components:
           description: Coupons applied at the checkout level.
           items:
             $ref: '#/components/schemas/CheckoutCoupon'
+        fees:
+          type: array
+          description: Fees applied at the checkout level.
+          items:
+            $ref: '#/components/schemas/CheckoutFee'
         createdTime:
           type: string
           description: Time when the cart was created.
@@ -1134,7 +1147,42 @@ components:
           type: number
           description: The discounted amount applied within a given context.
           format: double
-    Customer: 
+    CheckoutFee:
+      title: Checkout Fee
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: The fee ID.
+          example: 497f6eca-6276-4993-bfeb-53cbbbba6f08
+        type:
+          type: string
+          description: The type of the fee.
+          enum:
+            - custom_fee
+        name:
+          type: string
+          description: Name of the fee.
+          example: AAINS
+        displayName:
+          type: string
+          description: Display name of the fee targeting customers/shoppers.
+          example: Package Protection Insurance
+        cost:
+          type: number
+          description: Cost of the fee (include or exclude tax dependent on tax settings, same as shipping cost).
+          example: 10.0
+        source:
+          type: string
+          description: The source of the request.
+          example: AA
+        taxClassId:
+          type: integer
+          description: The tax class ID.
+          example: 1
+      x-internal: false
+    Customer:
       type: object
       description: Customer details.
       properties:

reference/checkouts.v3.yml

@@ -27,6 +27,7 @@ tags:
   - name: Checkout Orders
   - name: Checkout Settings
   - name: Checkout Token
+  - name: Checkout Fees
 security:
   - X-Auth-Token: []
 paths:
@@ -7764,6 +7765,102 @@ paths:
                 meta: {}
         '409':
           $ref: '#/components/responses/CartConflictErrorResponse'
+  '/checkouts/{checkoutId}/fees':
+    post:
+      tags:
+        - Checkout Fees
+      summary: Add order level fees to a checkout
+      description: |-
+        Adds order level fees to a checkout. 
+        
+        Limits: 
+          - Maximum of 5 fees per checkout.
+      operationId: CheckoutsFeesByCheckoutIdPost
+      parameters:
+        - $ref: '#/components/parameters/checkoutId'
+        - $ref: '#/components/parameters/Accept'
+        - $ref: '#/components/parameters/Content-Type'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AddFeesRequest'
+        required: true
+      responses:
+        '200':
+          description: ''
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    $ref: '#/components/schemas/Checkout'
+                  meta:
+                    $ref: '#/components/schemas/MetaOpen'
+      x-unitTests: []
+      x-operation-settings:
+        CollectParameters: false
+        AllowDynamicQueryParameters: false
+        AllowDynamicFormParameters: false
+        IsMultiContentStreaming: false
+      x-codegen-request-body-name: body
+    put:
+      tags:
+        - Checkout Fees
+      summary: Update order level fees in a checkout
+      description: |-
+        Updates order level fees in a checkout.
+        > We do not support partial updates, so please send the total entity values for each fee to be updated.
+      operationId: CheckoutsFeesByCheckoutIdPut
+      parameters:
+        - $ref: '#/components/parameters/checkoutId'
+        - $ref: '#/components/parameters/Accept'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateFeesRequest'
+        required: true
+      responses:
+        '200':
+          description: ''
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    $ref: '#/components/schemas/Checkout'
+                  meta:
+                    $ref: '#/components/schemas/MetaOpen'
+    delete:
+      tags:
+        - Checkout Fees
+      summary: Delete order level fees from a checkout.
+      description: Delete fees from a checkout.
+      operationId: CheckoutsFeesByCheckoutIdDelete
+      parameters:
+        - $ref: '#/components/parameters/checkoutId'
+        - $ref: '#/components/parameters/Accept'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DeleteFeesRequest'
+        required: true
+      responses:
+        '200':
+          description: ''
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    $ref: '#/components/schemas/Checkout'
+                  meta:
+                    $ref: '#/components/schemas/MetaOpen'
   '/checkouts/{checkoutId}/orders':
     post:
       tags:
@@ -8655,6 +8752,11 @@ components:
           description: Coupons applied at checkout level.
           items:
             $ref: '#/components/schemas/AppliedCoupon'
+        fees:
+          type: array
+          description: Fees applied at the checkout level.
+          items:
+            $ref: '#/components/schemas/CheckoutFee'
         order_id:
           type: string
           description: ''
@@ -8767,6 +8869,46 @@ components:
           format: float
           example: 0.9
       x-internal: false
+    CheckoutFee:
+      title: Checkout Fee
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: The fee ID.
+          example: 497f6eca-6276-4993-bfeb-53cbbbba6f08
+        type:
+          type: string
+          description: The type of the fee.
+          enum:
+            - custom_fee
+        name:
+          type: string
+          description: Name of the fee.
+          example: AAINS
+        display_name:
+          type: string
+          description: Display name of the fee targeting customers/shoppers.
+          example: Package Protection Insurance
+        cost_inc_tax:
+          type: number
+          description: Cost of the fee including tax.
+          example: 10.0
+        cost_ex_tax:
+          type: number
+          description: Cost of the fee excluding tax.
+          example: 9.9
+        source:
+          type: string
+          description: The source of the request.
+          example: AA
+        tax_class_id:
+          type: integer
+          nullable: true
+          description: The tax class ID.
+          example: 1
+      x-internal: false
     AddressProperties:
       title: Address Properties
       required:
@@ -9047,6 +9189,98 @@ components:
           description: The cart version that you expect to apply the updates. If the provided version doesn't match the current cart version, you will receive a conflict error. This field is optional; if not provided, optimistic concurrency control will not apply.
           example: 1
       x-internal: false
+    BaseFee:
+      type: object
+      required:
+        - type
+        - name
+        - display_name
+        - cost
+        - source
+      properties:
+        type:
+          type: string
+          description: The type of the fee.
+          enum:
+            - custom_fee
+        name:
+          type: string
+          minLength: 1
+          maxLength: 50
+          description: The name of the fee.
+          example: AAINS
+        display_name:
+          type: string
+          minLength: 1
+          maxLength: 200
+          description: The display name of the fee targeting customers/shoppers.
+          example: Package Protection Insurance
+        cost:
+          type: number
+          description: The cost of the fee.
+          example: 7.12
+        source:
+          type: string
+          minLength: 1
+          maxLength: 50
+          description: The source of the request.
+          example: AA
+        tax_class_id:
+          type: integer
+          description: The tax class ID applied to this fee (you can retrieve the tax class ID from our management API - v2/tax_classes). If the tax class is not provided or is null, the tax class set in the control panel is applied.
+          example: 1
+    FeeWithId:
+      allOf:
+        - $ref: '#/components/schemas/BaseFee'
+        - type: object
+          properties:
+            id:
+              type: string
+              description: ID of the fee.
+              example: 3c26f3e6-146d-4dce-8159-2a77c0bba409
+          required:
+            - id
+    AddFeesRequest:
+      title: Fees POST request
+      type: object
+      required:
+        - fees
+      properties:
+        fees:
+          type: array
+          description: The fees to be added to a checkout.
+          items:
+            $ref: '#/components/schemas/BaseFee'
+          minItems: 1
+      x-internal: false
+    UpdateFeesRequest:
+      title: Fees PUT request
+      type: object
+      required:
+        - fees
+      properties:
+        fees:
+          type: array
+          description: The fees to be updated in a checkout.
+          items:
+            $ref: '#/components/schemas/FeeWithId'
+          minItems: 1
+      x-internal: false
+    DeleteFeesRequest:
+      title: Fees DELETE request
+      type: object
+      required:
+        - ids
+      properties:
+        ids:
+          type: array
+          description: The IDs of the fees to be deleted from a checkout.
+          items:
+            type: string
+            description: The ID of the fee.
+            example: 3c26f3e6-146d-4dce-8159-2a77c0bba409
+          minItems: 1
+      x-internal: false
     DeleteCouponCodeRequest:
       title: Delete Coupon Request
       type: object