DEVDOCS-6104: Clarify the meaning of version field in the request/res…

…ponse of cart/checkout API
bigcommerce · Sep 6, 2024 · eed31c9 · eed31c9
1 parent 79d2e21
commit eed31c9
Show file tree

Hide file tree

Showing 4 changed files with 30 additions and 30 deletions.
diff --git a/reference/carts.sf.yml b/reference/carts.sf.yml
@@ -402,7 +402,7 @@ components:
           description: Locale of the cart.
         version:
           type: integer
-          description: The current version of the cart.
+          description: The current version of the cart, which increments with each successful update. It can be used to enable optimistic concurrency control for subsequent updates.
           example: 1
       x-internal: false
     requestCart:
@@ -537,7 +537,7 @@ components:
                 $ref: '#/components/schemas/requestCartPostLineItem'
             version:
               type: integer
-              description: The expected version of the cart.
+              description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
               example: 1
           required:
             - lineItems
@@ -549,7 +549,7 @@ components:
                 $ref: '#/components/schemas/requestLineItemGiftCertificate'
             version:
               type: integer
-              description: The expected version of the cart.
+              description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
               example: 1
           required:
             - giftCertificates
@@ -565,7 +565,7 @@ components:
                 $ref: '#/components/schemas/requestLineItemGiftCertificate'
             version:
               type: integer
-              description: The expected version of the cart.
+              description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
               example: 1
           required:
             - lineItems
@@ -581,7 +581,7 @@ components:
               $ref: '#/components/schemas/requestCartPostLineItem'
             version:
               type: integer
-              description: The expected version of the cart.
+              description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
               example: 1
           required:
             - lineItem
@@ -592,7 +592,7 @@ components:
               $ref: '#/components/schemas/requestLineItemGiftCertificate'
             version:
               type: integer
-              description: The expected version of the cart.
+              description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
               example: 1
           required:
             - giftCertificates
@@ -605,7 +605,7 @@ components:
               $ref: '#/components/schemas/requestLineItemGiftCertificate'
             version:
               type: integer
-              description: The expected version of the cart.
+              description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
               example: 1
           required:
             - lineItem
@@ -617,7 +617,7 @@ components:
       properties:
         version:
           type: integer
-          description: The expected version of the cart.
+          description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
           example: 1
     responseCartCurrency:
       title: Currency

diff --git a/reference/carts.v3.yml b/reference/carts.v3.yml
@@ -1564,7 +1564,7 @@ components:
           type: integer
         version:
           type: integer
-          description: The expected version of the cart.
+          description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
           example: 1
       title: Cart Update Put Request Data
       x-internal: false
@@ -1770,7 +1770,7 @@ components:
                   type: string
         version:
           type: integer
-          description: The current version of the cart.
+          description: The current version of the cart, which increments with each successful update. It can be used to enable optimistic concurrency control for subsequent updates.
           example: 1
     Currency:
       type: object
@@ -2934,14 +2934,14 @@ components:
           $ref: '#/components/schemas/cart_PostCustomItem'
         version:
           type: integer
-          description: The expected version of the cart.
+          description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
           example: 1
     CartLineItemDelete:
       type: object
       properties:
         version:
           type: integer
-          description: The expected version of the cart.
+          description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
           example: 1
     Redirect_urls_Post:
       type: object
@@ -3024,7 +3024,7 @@ components:
           $ref: '#/components/schemas/cart_PostCustomItem'
         version:
           type: integer
-          description: The expected version of the cart.
+          description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
           example: 1
     cart_PostCustomItem:
       type: array

diff --git a/reference/checkouts.sf.yml b/reference/checkouts.sf.yml
@@ -1812,7 +1812,7 @@ paths:
                   description: ''
                 version:
                   type: integer
-                  description: The expected version of the checkout.
+                  description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
                   example: 1
         required: true
       responses:
@@ -2343,7 +2343,7 @@ components:
             `true` value indicates StoreCredit has been applied.
         version:
           type: integer
-          description: The current version of the checkout.
+          description: The current version of the checkout, which increments with each successful update. It can be used to enable optimistic concurrency control for subsequent updates.
           example: 1
       description: ''
       x-internal: false
@@ -2501,7 +2501,7 @@ components:
           properties:
             version:
               type: integer
-              description: The expected version of the checkout.
+              description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
               example: 1
       x-internal: false
     consignment_Full:
@@ -2624,7 +2624,7 @@ components:
           description: ''
         version:
           type: integer
-          description: The expected version of the checkout.
+          description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
           example: 1
       x-internal: false
     checkouts_Resp:
@@ -3534,7 +3534,7 @@ components:
               type: integer
         version:
           type: integer
-          description: The expected version of the checkout.
+          description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
           example: 1
       x-internal: false
     DeleteCouponCodeRequest:
@@ -3543,7 +3543,7 @@ components:
       properties:
         version:
           type: integer
-          description: The expected version of the checkout.
+          description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
           example: 1
       x-internal: false
     DeleteConsignmentRequest:
@@ -3552,7 +3552,7 @@ components:
       properties:
         version:
           type: integer
-          description: The expected version of the checkout.
+          description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
           example: 1
       x-internal: false
     GiftCertificateRequest:
@@ -3662,7 +3662,7 @@ components:
               type: integer
         version:
           type: integer
-          description: The expected version of the checkout.
+          description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
           example: 1
       description: One or more of these three fields is mandatory. You can update address and line items in one request. You have to update shipping option ID or pickup option ID in a separate request since changing the address or line items can invalidate the previously available shipping options.
       x-internal: false

diff --git a/reference/checkouts.v3.yml b/reference/checkouts.v3.yml
@@ -1655,7 +1655,7 @@ paths:
                                 example: 15
                     version:
                       type: integer
-                      description: The expected version of the checkout.
+                      description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
                       example: 1
             example:
               cart:
@@ -8727,7 +8727,7 @@ components:
                       description: Text of the banner.
         version:
           type: integer
-          description: The current version of the checkout.
+          description: The current version of the checkout, which increments with each successful update. It can be used to enable optimistic concurrency control for subsequent updates.
           example: 1
     Checkout_Put:
       title: Checkout_Put
@@ -8740,7 +8740,7 @@ components:
           description: ''
         version:
           type: integer
-          description: The expected version of the checkout.
+          description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
           example: 1
       x-internal: false
     AppliedCoupon:
@@ -8826,7 +8826,7 @@ components:
                 description: 'This can also be an array for fields that need to support a list of values (e.g., a set of check boxes.)'
         version:
           type: integer
-          description: The expected version of the checkout.
+          description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
           example: 1
       x-internal: false
     CreateConsignmentRequest:
@@ -8921,7 +8921,7 @@ components:
                 example: 1
           version:
             type: integer
-            description: The expected version of the checkout.
+            description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
             example: 1
       x-internal: false
     DeleteConsignmentRequest:
@@ -8930,7 +8930,7 @@ components:
       properties:
         version:
           type: integer
-          description: The expected version of the checkout.
+          description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
           example: 1
       x-internal: false
     UpdateConsignmentRequest:
@@ -9031,7 +9031,7 @@ components:
                 example: "custom shipping"
           version:
             type: integer
-            description: The expected version of the checkout.
+            description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
             example: 1
       description: One or more of these three fields are mandatory. `address` and `line_items` can be updated in one request. `shipping_option_id` has to be updated in a separate request because changing the address or line items can invalidate the previously available shipping options.
       x-internal: false
@@ -9044,7 +9044,7 @@ components:
           description: Coupon codes have a 50-character limit.
         version:
           type: integer
-          description: The expected version of the checkout.
+          description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
           example: 1
       x-internal: false
     DeleteCouponCodeRequest:
@@ -9053,7 +9053,7 @@ components:
       properties:
         version:
           type: integer
-          description: The expected version of the checkout.
+          description: The cart version to which updates are expected to apply. If the provided version doesn't match the current cart version, a conflict error will be returned. This field is optional; if not provided, optimistic concurrency control will not apply.
           example: 1
       x-internal: false
     Order: