chore(docs): Generated API Reference (#4706)

Co-authored-by: olivermrbl <olivermrbl@users.noreply.github.com>
Co-authored-by: Shahed Nasser <shahednasser@gmail.com>

docs/api/store/components/schemas/StorePostCartsCartReq.yaml

@@ -2,10 +2,14 @@ type: object
 properties:
   region_id:
     type: string
-    description: The id of the Region to create the Cart in.
+    description: >-
+      The ID of the Region to create the Cart in. Setting the cart's region can
+      affect the pricing of the items in the cart as well as the used currency.
   country_code:
     type: string
-    description: The 2 character ISO country code to create the Cart in.
+    description: >-
+      The 2 character ISO country code to create the Cart in. Setting this
+      parameter will set the country code of the shipping address.
     externalDocs:
       url: >-
         https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
@@ -16,7 +20,13 @@ properties:
     format: email
   sales_channel_id:
     type: string
-    description: The ID of the Sales channel to update the Cart with.
+    description: >-
+      The ID of the Sales channel to create the Cart in. The cart's sales
+      channel affects which products can be added to the cart. If a product does
+      not exist in the cart's sales channel, it cannot be added to the cart. If
+      you add a publishable API key in the header of this request and specify a
+      sales channel ID, the specified sales channel must be within the scope of
+      the publishable API key's resources.
   billing_address:
     description: The Address to be used for billing purposes.
     anyOf:
@@ -25,7 +35,7 @@ properties:
       - type: string
         description: The billing address ID
   shipping_address:
-    description: The Address to be used for shipping.
+    description: The Address to be used for shipping purposes.
     anyOf:
       - $ref: ./AddressPayload.yaml
         description: A full shipping address object.
@@ -40,7 +50,7 @@ properties:
         - code
       properties:
         code:
-          description: The code that a Gift Card is identified by.
+          description: The code of a gift card.
           type: string
   discounts:
     description: An array of Discount codes to add to the Cart.
@@ -51,13 +61,15 @@ properties:
         - code
       properties:
         code:
-          description: The code that a Discount is identified by.
+          description: The code of the discount.
           type: string
   customer_id:
     description: The ID of the Customer to associate the Cart with.
     type: string
   context:
-    description: An optional object to provide context to the Cart.
+    description: >-
+      An object to provide context to the Cart. The `context` field is
+      automatically populated with `ip` and `user_agent`
     type: object
     example:
       ip: '::1'