chore(customers): CUST-3623 update customers api docs based on cursor…

… pagination (#769)  # [CUST-3623](https://bigcommercecloud.atlassian.net/browse/CUST-3623) ## What changed?  * update v3 get customers api docs based on cursor pagination * update v3 get ffvs api docs based on cursor pagination * correct the value of meta for v3 post/put customers ### Screenshots from swagger.io #### get customers: <img width="711" alt="Screenshot 2025-01-23 at 11 15 39 AM" src="https://github.com/user-attachments/assets/d8bbf78b-52ef-45af-9d10-9f48fa2aab0a" /> <img width="889" alt="Screenshot 2025-01-23 at 11 15 48 AM" src="https://github.com/user-attachments/assets/b8b92203-4a54-4f45-b8fb-f77d52a3b44d" /> <img width="841" alt="Screenshot 2025-01-23 at 11 16 39 AM" src="https://github.com/user-attachments/assets/23910a1b-9905-427e-909d-29717ec1cfc4" /> <img width="791" alt="Screenshot 2025-01-23 at 11 16 50 AM" src="https://github.com/user-attachments/assets/1479e7a7-c62e-4440-b91b-989d668d28dc" /> #### get ffvs: <img width="634" alt="Screenshot 2025-01-23 at 11 17 38 AM" src="https://github.com/user-attachments/assets/be21c283-0ea6-40b2-ad69-adf2d6827149" /> <img width="888" alt="Screenshot 2025-01-23 at 11 17 45 AM" src="https://github.com/user-attachments/assets/18e2e474-c093-458f-b669-4caf82dbbd30" /> <img width="839" alt="Screenshot 2025-01-23 at 11 17 57 AM" src="https://github.com/user-attachments/assets/d2752e44-f619-453e-9f16-4c4cbc18e2c0" /> <img width="835" alt="Screenshot 2025-01-23 at 11 18 07 AM" src="https://github.com/user-attachments/assets/eaa35b49-66b6-4672-a6f6-08d76804f51d" /> ## Release notes draft * Feature: Cursor pagination is now available to Customers V3 - Get All Customers * Feature: Cursor pagination is now available to Customers V3 - Get Customer Form Field Values * Fixed: Corrected the value of meta for the response of Customers V3 - Create/Update Customers [CUST-3623]: https://bigcommercecloud.atlassian.net/browse/CUST-3623?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ
bigcommerce · Jan 28, 2025 · da6cc69 · da6cc69
1 parent a7034b3
commit da6cc69
Showing 1 changed file with 137 additions and 47 deletions.
diff --git a/reference/customers.v3.yml b/reference/customers.v3.yml
@@ -52,7 +52,7 @@ paths:
       parameters:
         - name: page
           in: query
-          description: Page number. `page=1`
+          description: Page number (`page` will be ignored if you provide `before` or `after` in the request). For example `page=1`.
           schema:
             type: integer
         - in: query
@@ -208,9 +208,19 @@ paths:
               - 'last_name:desc'
               - 'date_modified:asc'
               - 'date_modified:desc'
+        - name: after
+          in: query
+          description: 'The cursor reference of the last entry for the previous page. Use the `end_cursor` value from the last response to get the next page (`end_cursor` is only returned on the first page or when the request contains query parameter `before` or `after`). For example `after=eyJpZCI6MjA0fQ`. '
+          schema:
+            type: string
+        - name: before
+          in: query
+          description: 'The cursor reference of the first entry for the next page. Use the `start_cursor` value from the last response to get the previous page (`start_cursor` is only returned on the first page or when the request contains query parameter `before` or `after`). For example `before=eyJpZCI6MjA1fQ`.'
+          schema:
+            type: string
       responses:
         '200':
-          $ref: '#/components/responses/CustomerCollectionResponse'
+          $ref: '#/components/responses/GetCustomerCollectionResponse'
         '422':
           description: |
             The optional filter parameter was not valid. This is the result of missing required fields, or of invalid data. See the response for more details.
@@ -1452,7 +1462,7 @@ paths:
             default: application/json
         - name: page
           in: query
-          description: Page number. `page=1`
+          description: Page number (`page` will be ignored if you provide `before` or `after` in the request). For example `page=1`.
           schema:
             type: integer
         - in: query
@@ -1498,6 +1508,16 @@ paths:
               - radiobuttons
               - text
               - picklist
+        - name: after
+          in: query
+          description: 'The cursor reference of the last entry for the previous page. Use the `end_cursor` value from the last response to get the next page (`end_cursor` is only returned on the first page or when the request contains query parameter `before` or `after`). For example `after=eyJzZXNzaW9uSWQiOjM4LCJmaWVsZElkIjo0MH0`. '
+          schema:
+            type: string
+        - name: before
+          in: query
+          description: 'The cursor reference of the first entry for the next page. Use the `start_cursor` value from the last response to get the previous page (`start_cursor` is only returned on the first page or when the request contains query parameter `before` or `after`). For example `before=eyJzZXNzaW9uSWQiOjgsImZpZWxkSWQiOjMxfQ`.'
+          schema:
+            type: string
     put:
       responses:
         '200':
@@ -2233,7 +2253,55 @@ components:
                 items:
                   $ref: '#/components/schemas/customer_Full'
               meta:
-                $ref: '#/components/schemas/_metaCollection'
+                  $ref: '#/components/schemas/MetaOpen'
+          examples:
+            example-1:
+              value:
+                data:
+                  - email: [email protected]
+                    first_name: string
+                    last_name: string
+                    company: string
+                    phone: string
+                    notes: string
+                    tax_exempt_category: string
+                    customer_group_id: 0
+                    addresses: 
+                      - first_name: string
+                        last_name: string
+                        address1: Addr1
+                        address2: ''
+                        city: string
+                        state_or_province: string
+                        postal_code: string
+                        country_code: st
+                        phone: string
+                        address_type: residential
+                        customer_id: 0
+                        id: 0
+                        country: string 
+                    store_credit_amounts:
+                      - amount: 43.15
+                    accepts_product_review_abandoned_cart_emails: true
+                    channel_ids:
+                      - 1
+                    shopper_profile_id: "82511e54-4040-40fe-b742-2b25655f205b"
+                    segment_ids: 
+                      - "5bb733a9-5491-47b3-9451-9ae8d6a6bc6b"
+                meta: {}
+    GetCustomerCollectionResponse:
+      description: Get Customer Collection Response
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: array
+                items:
+                  $ref: '#/components/schemas/customer_Full'
+              meta:
+                $ref: '#/components/schemas/_metaCollectionWithCursorPagination'
           examples:
             example-1:
               value:
@@ -2279,6 +2347,14 @@ components:
                       previous: string
                       current: string
                       next: string
+                  cursor_pagination:
+                    count: 0
+                    per_page: 0
+                    start_cursor: string
+                    end_cursor: string
+                    links:
+                      previous: string
+                      next: string
     AddressCollectionResponse:
       description: ''
       content:
@@ -2840,49 +2916,7 @@ components:
                       title: Customer Address Form Field Value
                   title: 'Form Field Value '
               meta:
-                title: Collection Meta
-                description: Data about the response, including pagination and collection totals.
-                type: object
-                properties:
-                  pagination:
-                    title: Pagination
-                    description: Data about the response, including pagination and collection totals.
-                    type: object
-                    properties:
-                      total:
-                        description: Total number of items in the result set.
-                        type: integer
-                        format: int32
-                      count:
-                        description: Total number of items in the collection response.
-                        type: integer
-                        format: int32
-                      per_page:
-                        description: 'The amount of items returned in the collection per page, controlled by the limit parameter.'
-                        type: integer
-                        format: int32
-                      current_page:
-                        description: The page you are currently on within the collection.
-                        type: integer
-                        format: int32
-                      total_pages:
-                        description: The total number of pages in the collection.
-                        type: integer
-                        format: int32
-                      links:
-                        title: Links
-                        description: Pagination links for the previous and next parts of the whole collection.
-                        type: object
-                        properties:
-                          previous:
-                            description: Link to the previous page returned in the response.
-                            type: string
-                          current:
-                            description: Link to the current page returned in the response.
-                            type: string
-                          next:
-                            description: Link to the next page returned in the response.
-                            type: string
+                $ref: '#/components/schemas/_metaCollectionWithCursorPagination'
           examples:
             Customer and Customer Address Form Fields example:
               value:
@@ -2939,6 +2973,14 @@ components:
                     per_page: 50
                     total: 15
                     total_pages: 1
+                  cursor_pagination:
+                    count: 0
+                    per_page: 0
+                    start_cursor: string
+                    end_cursor: string
+                    links:
+                      previous: string
+                      next: string
             Customer Form Fields example:
               value:
                 data:
@@ -2958,6 +3000,14 @@ components:
                     per_page: 50
                     total: 3
                     total_pages: 1
+                  cursor_pagination:
+                    count: 0
+                    per_page: 0
+                    start_cursor: string
+                    end_cursor: string
+                    links:
+                      previous: string
+                      next: string
             Customer Address Form Fields example:
               value:
                 data:
@@ -2971,6 +3021,14 @@ components:
                     per_page: 50
                     total: 1
                     total_pages: 1
+                  cursor_pagination:
+                    count: 0
+                    per_page: 0
+                    start_cursor: string
+                    end_cursor: string
+                    links:
+                      previous: string
+                      next: string
     FormFieldValuesResponse:
       description: ''
       content:
@@ -3226,6 +3284,28 @@ components:
         links:
           $ref: '#/components/schemas/Links'
       x-internal: false
+    CursorPagination:
+      title: Cursor Pagination
+      description: Data about cursor pagination.
+      type: object
+      properties:
+        count:
+          description: Total number of items in the collection response.
+          type: integer
+          format: int32
+        per_page:
+          description: The amount of items returned in the collection per page, controlled by the limit parameter.
+          type: integer
+          format: int32
+        start_cursor:
+          description: A string representing the starting point of the current page in the collection
+          type: string
+        end_cursor:
+          description: A string representing the ending point of the current page in the collection.
+          type: string
+        links:
+          $ref: '#/components/schemas/Links'
+      x-internal: false
     _metaCollection:
       title: _metaCollection
       description: Data about the response, including pagination and collection totals.
@@ -3234,6 +3314,16 @@ components:
         pagination:
           $ref: '#/components/schemas/Pagination'
       x-internal: false
+    _metaCollectionWithCursorPagination:
+      title: _metaCollection
+      description: Data about the response, including pagination and collection totals. Both `pagination` and `cursor_pagination` would be returned in the first page. Only `pagination` would be returned when page is greater than 1. Only `cursor_pagination` would be returned when `before` or `after` is provided in the request.
+      type: object
+      properties:
+        pagination:
+          $ref: '#/components/schemas/Pagination'
+        cursor_pagination:
+          $ref: '#/components/schemas/CursorPagination'
+      x-internal: false
     MetaOpen:
       title: Response meta
       type: object