solidus_api 3.0.0.rc2 → 3.1.0

data/openapi/main.hub.yml

@@ -38,11 +38,11 @@ pages:
             path: /authentication
           data:
             $ref: ./authentication.md
-        - title: Pagination
+        - title: Pagination and Filtering
           route:
-            path: /pagination
+            path: /pagination-and-filtering
           data:
-            $ref: ./pagination.md
+            $ref: ./pagination-and-filtering.md
         - title: Errors
           route:
             path: /errors

data/openapi/pagination-and-filtering.md

@@ -0,0 +1,23 @@
+# Pagination and Filtering
+
+## Pagination
+
+Most endpoints that return a collection are paginated. A paginated response contains metadata about the current page at the root level and the resources in the current page in a child key named after the resource (e.g. `orders`).
+
+You can pass the `page` and `per_page` parameters to set the current page and the desired number of items per page. Note that the default and the maximum number of items per page is decided at the application level.
+
+All pagination metadata is documented in the individual API endpoints, so take a look there if you're unsure what data you can expect.
+
+## Filtering
+
+Most endpoints that return a collection also have the ability to filter data using query params. This works taking advantage of the search filters provided by [Ransack](https://github.com/activerecord-hackery/ransack/).
+
+For example, if we want to retrieve only products that contain the word "Watch" in their title we can make the following request:
+
+```
+GET /products?q[name_cont]=Watch
+```
+
+The `name_cont` matcher will generate a query using `LIKE` to retrieve all the products that contain the value specified. For an extensive list of search matchers supported, please refer to the Ransack documentation.
+
+The result will be paginated as described in the paragraph above.

data/openapi/solidus-api.oas.yml

@@ -38,6 +38,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
+        - $ref: '#/components/parameters/q'
       security:
         - api-key: []
     post:
@@ -60,7 +61,37 @@ paths:
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/product-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                product:
+                  $ref: '#/components/schemas/product-input'
+            examples:
+              Example:
+                value:
+                  product:
+                    name: The Majestic Product
+                    price: '19.99'
+                    shipping_category_id: 8
+                    product_properties_attributes:
+                      - property_name: fabric
+                        value: cotton
+                    option_types:
+                      - size
+                      - color
+                    taxon_ids: '2,4'
+                    variants:
+                      - price: 19.99
+                        cost_price: 17
+                        sku: SKU-3
+                        track_inventory: true
+                        options:
+                          - name: size
+                            value: small
+                          - name: color
+                            value: black
   /orders/mine:
     get:
       responses:
@@ -87,6 +118,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
+        - $ref: '#/components/parameters/q'
       security:
         - api-key: []
   '/orders/{number}':
@@ -116,6 +148,7 @@ paths:
         required: true
         schema:
           type: string
+        description: The order number
     patch:
       responses:
         '200':
@@ -131,7 +164,10 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Update order
-      description: Updates an order.
+      description: |-
+        Updates an order.
+
+        To perform this operation the request should be made as the order's owner or with the order token in case of unauthenitcated checkouts (es. guest checkout).
       operationId: update-order
       tags:
         - Orders
@@ -139,7 +175,42 @@ paths:
         - api-key: []
         - order-token: []
       requestBody:
-        $ref: '#/components/requestBodies/order-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                order:
+                  $ref: '#/components/schemas/order-input'
+            examples:
+              Updating Billing Address:
+                value:
+                  order:
+                    use_billing: true
+                    ship_address_attributes:
+                      name: Jane Doe
+                      address1: 2191  Calico Drive
+                      city: Phoenix
+                      country_id: 22
+                      state_id: 31
+                      zipcode: '85022'
+                      phone: 509-644-9988
+                      company: Acme Inc.
+              Select a Shipment's Shipping Rate:
+                value:
+                  order:
+                    shipments_attributes:
+                      - id: 2
+                        selected_shipping_rate_id: 23
+              Updating Payment:
+                value:
+                  order:
+                    payments_attributes:
+                      - amount: '42.42'
+                        payment_method_id: 1
+                        source_attributes:
+                          gateway_payment_profile_id: super-secret-token-2131m3n13bv3hv1vasda
+        description: ''
   /orders/current:
     get:
       responses:
@@ -188,6 +259,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
+        - $ref: '#/components/parameters/q'
   '/countries/{id}':
     get:
       responses:
@@ -344,7 +416,19 @@ paths:
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/product-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                product:
+                  $ref: '#/components/schemas/product-input'
+            examples:
+              Example:
+                value:
+                  product:
+                    name: The Majestic Product
+                    price: '22.22'
   '/products/{product_id}/images':
     get:
       responses:
@@ -391,14 +475,23 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Create product image
-      description: Creates an image for a product.
+      description: |-
+        Creates an image for a product.
+
+        Only users with the `create` permission on `Spree::Image` can perform this action.
       operationId: create-product-image
       tags:
         - Images
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/image-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                image:
+                  $ref: '#/components/schemas/image-input'
   '/products/{product_id}/variants':
     get:
       responses:
@@ -426,6 +519,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
+        - $ref: '#/components/parameters/q'
       security:
         - api-key: []
     parameters:
@@ -456,7 +550,38 @@ paths:
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/variant-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                variant:
+                  $ref: '#/components/schemas/variant-input'
+            examples:
+              Example with Option Value Ids:
+                value:
+                  variant:
+                    price: '11.22'
+                    cost_price: '9'
+                    position: 1
+                    track_inventory: true
+                    sku: AWSOME-1122
+                    cost_currency: USD
+                    option_value_ids:
+                      - 1
+                      - 2
+              Example with Option Value Text:
+                value:
+                  variant:
+                    price: '11.22'
+                    cost_price: '9'
+                    position: 1
+                    track_inventory: true
+                    sku: AWSOME-1122
+                    cost_currency: USD
+                    options:
+                      name: Color
+                      value: White
   '/products/{product_id}/images/{id}':
     get:
       responses:
@@ -483,11 +608,13 @@ paths:
         required: true
         schema:
           type: string
+        description: 'The id of the Spree::Product'
       - name: id
         in: path
         required: true
         schema:
           type: string
+        description: 'The id of the Spree::Image'
     delete:
       responses:
         '204':
@@ -524,14 +651,23 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Update product image
-      description: Updates a product's image.
+      description: |-
+        Updates a product's image.
+
+        Only users with the `update` permission on the image can perform this action.
       operationId: update-product-image
       tags:
         - Images
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/image-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                image:
+                  $ref: '#/components/schemas/image-input'
   '/products/{product_id}/variants/{id}':
     get:
       responses:
@@ -606,7 +742,38 @@ paths:
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/variant-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                variant:
+                  $ref: '#/components/schemas/variant-input'
+            examples:
+              Example with Option Value Ids:
+                value:
+                  variant:
+                    price: '11.22'
+                    cost_price: '9'
+                    position: 1
+                    track_inventory: true
+                    sku: AWSOME-1122
+                    cost_currency: USD
+                    option_value_ids:
+                      - 1
+                      - 2
+              Example with Option Value Text:
+                value:
+                  variant:
+                    price: '11.22'
+                    cost_price: '9'
+                    position: 1
+                    track_inventory: true
+                    sku: AWSOME-1122
+                    cost_currency: USD
+                    options:
+                      name: Color
+                      value: White
   /states:
     get:
       responses:
@@ -674,6 +841,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
+        - $ref: '#/components/parameters/q'
       security:
         - api-key: []
     post:
@@ -689,14 +857,49 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Create variant
-      description: Creates a variant.
+      description: 'Creates a variant. Only users with `can :create, Variant` permissions can perform this action.'
       operationId: create-variant
       tags:
         - Variants
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/variant-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                product_id:
+                  type: integer
+                variant:
+                  $ref: '#/components/schemas/variant-input'
+            examples:
+              Example with Option Value Ids:
+                value:
+                  product_id: 1
+                  variant:
+                    price: '11.22'
+                    cost_price: '9'
+                    position: 1
+                    track_inventory: true
+                    sku: AWSOME-1122
+                    cost_currency: USD
+                    option_value_ids:
+                      - 1
+                      - 2
+              Example with Option Value Text:
+                value:
+                  product_id: 1
+                  variant:
+                    price: '11.22'
+                    cost_price: '9'
+                    position: 1
+                    track_inventory: true
+                    sku: AWSOME-1122
+                    cost_currency: USD
+                    options:
+                      name: Color
+                      value: White
   '/variants/{id}':
     get:
       responses:
@@ -766,7 +969,38 @@ paths:
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/variant-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                variant:
+                  $ref: '#/components/schemas/variant-input'
+            examples:
+              Example with Option Value Ids:
+                value:
+                  variant:
+                    price: '11.22'
+                    cost_price: '9'
+                    position: 1
+                    track_inventory: true
+                    sku: AWSOME-1122
+                    cost_currency: USD
+                    option_value_ids:
+                      - 1
+                      - 2
+              Example with Option Value Text:
+                value:
+                  variant:
+                    price: '11.22'
+                    cost_price: '9'
+                    position: 1
+                    track_inventory: true
+                    sku: AWSOME-1122
+                    cost_currency: USD
+                    options:
+                      name: Color
+                      value: White
   '/variants/{variant_id}/images':
     get:
       responses:
@@ -813,14 +1047,23 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Create variant image
-      description: Creates an image for a variant.
+      description: |-
+        Creates an image for a variant.
+
+        Only users with the `create` permission on `Spree::Image` can perform this action.
       operationId: create-variant-image
       tags:
         - Images
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/image-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                image:
+                  $ref: '#/components/schemas/image-input'
   '/variants/{variant_id}/images/{id}':
     get:
       responses:
@@ -847,11 +1090,13 @@ paths:
         required: true
         schema:
           type: string
+        description: 'The id of the Spree::Variant'
       - name: id
         in: path
         required: true
         schema:
           type: string
+        description: 'The id of the Spree::Image'
     delete:
       responses:
         '204':
@@ -888,14 +1133,23 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Update variant image
-      description: Updates a variant's image.
+      description: |-
+        Updates a variant's image.
+
+        Only users with the `update` permission on the image can perform this action.
       operationId: update-variant-image
       tags:
         - Images
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/image-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                image:
+                  $ref: '#/components/schemas/image-input'
   '/shipments/{shipment_number}/estimated_rates':
     get:
       responses:
@@ -954,6 +1208,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
+        - $ref: '#/components/parameters/q'
       security:
         - api-key: []
   '/users/{id}':
@@ -982,6 +1237,7 @@ paths:
         required: true
         schema:
           type: string
+        description: 'The ID of the Spree::User'
     delete:
       responses:
         '204':
@@ -1018,14 +1274,23 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Update user
-      description: Updates a user.
+      description: |-
+        Updates a user.
+
+        Only users with the `update` permission on the user can perform this action.
       operationId: update-user
       tags:
         - Users
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/user-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                user:
+                  $ref: '#/components/schemas/user-input'
   '/users/{user_id}/address_book':
     get:
       responses:
@@ -1139,6 +1404,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
+        - $ref: '#/components/parameters/q'
       security:
         - api-key: []
     parameters:
@@ -1203,7 +1469,36 @@ paths:
         - api-key: []
         - order-token: []
       requestBody:
-        $ref: '#/components/requestBodies/address-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                address:
+                  $ref: '#/components/schemas/address-input'
+            examples:
+              Example with state_id:
+                value:
+                  address:
+                    name: Jane Doe
+                    address1: 2191  Calico Drive
+                    city: Phoenix
+                    country_id: 22
+                    state_id: 31
+                    zipcode: '85022'
+                    phone: 509-644-9988
+                    company: Acme Inc.
+              Example with state_name:
+                value:
+                  address:
+                    name: Jane Doe
+                    address1: 2191  Calico Drive
+                    city: Phoenix
+                    country_id: 22
+                    state_name: AZ
+                    zipcode: '85022'
+                    phone: 509-644-9988
+                    company: Acme Inc.
   '/checkouts/{checkout_id}/payments':
     get:
       responses:
@@ -1225,13 +1520,14 @@ paths:
         '404':
           $ref: '#/components/responses/not-found'
       summary: List checkout payments
-      description: Lists a checkout's payments.
+      description: 'Lists a checkout''s payments. The list of payments is only visible by the checkout''s owner and by users authorized to see the order, eg. users with admin role. '
       operationId: list-checkout-payments
       tags:
         - Payments
       parameters:
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
+        - $ref: '#/components/parameters/q'
       security:
         - api-key: []
     parameters:
@@ -1256,7 +1552,7 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Create checkout payment
-      description: Creates a new payment for a checkout.
+      description: Creates a new payment for a checkout. Only the checkout's owner and users that can create a payment (eg. users with admin role) are allowed to perform this action.
       operationId: create-checkout-payment
       tags:
         - Payments
@@ -1264,7 +1560,30 @@ paths:
         - api-key: []
         - order-token: []
       requestBody:
-        $ref: '#/components/requestBodies/payment-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                payment:
+                  $ref: '#/components/schemas/payment-input'
+            examples:
+              Example without a payment source:
+                value:
+                  payment:
+                    amount: '42.42'
+                    payment_method_id: 1
+              Example with a payment source:
+                value:
+                  payment:
+                    amount: '42.42'
+                    payment_method_id: 1
+                    source_attributes:
+                      gateway_payment_profile_id: super-secret-token-2131m3n13bv3hv1vasda
+        description: |-
+          This requests only accepts available Payment Methods in the `payment_method_id` field.
+
+          The Payment Methods available to users for creating a new payment are the ones with both attributes `available_to_users` and `active` set to `true`.
   '/checkouts/{checkout_id}/payments/{id}':
     get:
       responses:
@@ -1296,6 +1615,7 @@ paths:
       - name: id
         in: path
         required: true
+        description: The payment id
         schema:
           type: string
     patch:
@@ -1308,12 +1628,21 @@ paths:
                 $ref: '#/components/schemas/payment'
         '401':
           $ref: '#/components/responses/invalid-api-key'
+        '403':
+          description: 'Forbidden  '
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
         '404':
           $ref: '#/components/responses/not-found'
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Update checkout payment
-      description: Updates a checkout's payment.
+      description: 'Updates a checkout''s payment. Please note that this action can be done by users with the admin permissions on Payments (eg. users with the admin role). Only pending payment can be updated. '
       operationId: update-checkout-payment
       tags:
         - Payments
@@ -1326,12 +1655,13 @@ paths:
             schema:
               type: object
               properties:
-                amount:
-                  type: number
-                payment_method_id:
-                  type: integer
-                payment_method:
-                  $ref: '#/components/schemas/payment-method'
+                payment:
+                  $ref: '#/components/schemas/payment-input'
+            examples:
+              Example:
+                value:
+                  payment:
+                    amount: '12.10'
   '/checkouts/{checkout_id}/return_authorizations':
     get:
       responses:
@@ -1360,6 +1690,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
+        - $ref: '#/components/parameters/q'
       security:
         - api-key: []
     parameters:
@@ -1384,14 +1715,23 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Create checkout return authorization
-      description: Creates a return authorization for a checkout.
+      description: |-
+        Creates a return authorization for a checkout.
+
+        Only users with the `create` permission on `Spree::RetrunAuthorization` can perform this action.
       operationId: create-checkout-return-authorization
       tags:
         - Return authorizations
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/return-authorization-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                return_authorization:
+                  $ref: '#/components/schemas/return-authorization-input'
   '/checkouts/{checkout_id}/return_authorizations/{id}':
     get:
       responses:
@@ -1423,6 +1763,7 @@ paths:
         required: true
         schema:
           type: string
+        description: 'The ID of the Spree::ReturnAuthorization'
     delete:
       responses:
         '204':
@@ -1459,14 +1800,23 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Update checkout return authorization
-      description: Updates a checkout's return authorization.
+      description: |-
+        Updates a checkout's return authorization.
+
+        Only users with the `update` permission on the return authorization can perform this action.
       operationId: update-checkout-return-authorization
       tags:
         - Return authorizations
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/return-authorization-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                return_authorization:
+                  $ref: '#/components/schemas/return-authorization-input'
   '/orders/{order_id}/customer_returns/{id}':
     get:
       responses:
@@ -1496,6 +1846,7 @@ paths:
       - name: id
         in: path
         required: true
+        description: The id of the customer return
         schema:
           type: string
     put:
@@ -1513,12 +1864,21 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Update order customer return
-      description: Updates an orders customer return.
+      description: |-
+        Updates an orders customer return.
+
+        Only users with the `update` permission on the customer return can perform this action.
       operationId: update-order-customer-return
       tags:
         - Customer returns
       requestBody:
-        $ref: '#/components/requestBodies/customer-return-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                customer_return:
+                  $ref: '#/components/schemas/customer-return-input'
       security:
         - api-key: []
   /orders:
@@ -1547,6 +1907,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
+        - $ref: '#/components/parameters/q'
       security:
         - api-key: []
     post:
@@ -1569,7 +1930,21 @@ paths:
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/order-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                order:
+                  $ref: '#/components/schemas/order-input'
+            examples:
+              Example:
+                value:
+                  order:
+                    email: string
+                    line_items_attributes:
+                      - quantity: 1
+                        variant_id: 22
   '/orders/{order_number}/addresses/{id}':
     get:
       responses:
@@ -1595,11 +1970,13 @@ paths:
       - name: order_number
         in: path
         required: true
+        description: The order number
         schema:
           type: string
       - name: id
         in: path
         required: true
+        description: The id of the order's address that we want to retrieve
         schema:
           type: string
     patch:
@@ -1625,7 +2002,36 @@ paths:
         - api-key: []
         - order-token: []
       requestBody:
-        $ref: '#/components/requestBodies/address-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                address:
+                  $ref: '#/components/schemas/address-input'
+            examples:
+              Example with state_id:
+                value:
+                  address:
+                    name: Jane Doe
+                    address1: 2191  Calico Drive
+                    city: Phoenix
+                    country_id: 22
+                    state_id: 31
+                    zipcode: '85022'
+                    phone: 509-644-9988
+                    company: Acme Inc.
+              Example with state_name:
+                value:
+                  address:
+                    name: Jane Doe
+                    address1: 2191  Calico Drive
+                    city: Phoenix
+                    country_id: 22
+                    state_name: AZ
+                    zipcode: '85022'
+                    phone: 509-644-9988
+                    company: Acme Inc.
   '/orders/{order_number}/payments':
     get:
       responses:
@@ -1657,6 +2063,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
+        - $ref: '#/components/parameters/q'
       security:
         - api-key: []
         - order-token: []
@@ -1664,6 +2071,7 @@ paths:
       - name: order_number
         in: path
         required: true
+        description: The order number
         schema:
           type: string
     post:
@@ -1681,7 +2089,7 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Create order payment
-      description: Creates a payment for an order.
+      description: Creates a new payment for a checkout. Only the order's owner and users that can create a payment (eg. users with admin role) are allowed to perform this action.
       operationId: create-order-payment
       tags:
         - Payments
@@ -1689,7 +2097,30 @@ paths:
         - api-key: []
         - order-token: []
       requestBody:
-        $ref: '#/components/requestBodies/payment-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                payment:
+                  $ref: '#/components/schemas/payment-input'
+            examples:
+              Example without a payment source:
+                value:
+                  payment:
+                    amount: '42.42'
+                    payment_method_id: 1
+              Example with a payment source:
+                value:
+                  payment:
+                    amount: '42.42'
+                    payment_method_id: 1
+                    source_attributes:
+                      gateway_payment_profile_id: super-secret-token-2131m3n13bv3hv1vasda
+        description: |-
+          This requests only accepts available Payment Methods in the `payment_method_id` field.
+
+          The Payment Methods available to users for creating a new payment are the ones with both attributes `available_to_users` and `active` set to `true`.
   '/orders/{order_number}/payments/{id}':
     get:
       responses:
@@ -1731,12 +2162,21 @@ paths:
                 $ref: '#/components/schemas/payment'
         '401':
           $ref: '#/components/responses/invalid-api-key'
+        '403':
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
         '404':
           $ref: '#/components/responses/not-found'
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Update order payment
-      description: Updates an order's payment.
+      description: 'Updates a checkout''s payment. Please note that this action can be done by users with the admin permissions on Payments (eg. users with the admin role). Only pending payment can be updated. '
       operationId: update-order-payment
       tags:
         - Payments
@@ -1744,7 +2184,18 @@ paths:
         - api-key: []
         - order-token: []
       requestBody:
-        $ref: '#/components/requestBodies/payment-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                payment:
+                  $ref: '#/components/schemas/payment-input'
+            examples:
+              Example:
+                value:
+                  payment:
+                    amount: '12.10'
   '/orders/{order_number}/return_authorizations':
     get:
       responses:
@@ -1773,6 +2224,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
+        - $ref: '#/components/parameters/q'
       security:
         - api-key: []
     parameters:
@@ -1796,14 +2248,23 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Create order return authorization
-      description: Creates a return authorization for an order.
+      description: |-
+        Creates a return authorization for an order.
+
+        Only users with the `create` permission on `Spree::ReturnAuthorization` can perform this action.
       operationId: create-order-return-authorization
       tags:
         - Return authorizations
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/return-authorization-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                return_authorization:
+                  $ref: '#/components/schemas/return-authorization-input'
   '/orders/{order_number}/return_authorizations/{id}':
     get:
       responses:
@@ -1830,11 +2291,13 @@ paths:
         required: true
         schema:
           type: string
+        description: The Order number
       - name: id
         in: path
         required: true
         schema:
           type: string
+        description: 'The ID of the Spree::ReturnAuthorization'
     delete:
       responses:
         '200':
@@ -1871,14 +2334,23 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Update order return authorization
-      description: Updates an order's return authorization.
+      description: |-
+        Updates an order's return authorization.
+
+        Only users with the `update` permission on the return authorization can perform this action.
       operationId: update-order-return-authorization
       tags:
         - Return authorizations
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/return-authorization-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                return_authorization:
+                  $ref: '#/components/schemas/return-authorization-input'
   /config:
     get:
       responses:
@@ -2071,14 +2543,23 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Create option value
-      description: Creates an option value.
+      description: |-
+        Creates an option value.
+
+        Only users with the `create` permission on `Spree::OptionValue` can perform this action.
       operationId: create-option-value
       tags:
         - Option values
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/option-value-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                option_value:
+                  $ref: '#/components/schemas/option-value-input'
   '/option_values/{id}':
     get:
       responses:
@@ -2105,6 +2586,7 @@ paths:
         required: true
         schema:
           type: string
+        description: 'The ID of the Spree::OptionValue'
     delete:
       responses:
         '204':
@@ -2141,14 +2623,24 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Update option value
-      description: Updates an option value.
+      description: |-
+        Updates an option value.
+
+        Only users with the `update` permission on the option value can perform this action.
       operationId: update-option-value
       tags:
         - Option values
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/option-value-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                option_value:
+                  $ref: '#/components/schemas/option-value-input'
+        description: ''
   '/option_types/{option_type_id}/option_values':
     get:
       responses:
@@ -2177,6 +2669,7 @@ paths:
         required: true
         schema:
           type: string
+        description: 'The ID of the Spree::OptionType'
     post:
       responses:
         '200':
@@ -2192,14 +2685,23 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Create option type value
-      description: Creates an option value for a type.
+      description: |-
+        Creates an option value for a type.
+
+        Only users with the `create` permission on `Spree::OptionValue` can perform this action.
       operationId: create-option-type-value
       tags:
         - Option values
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/option-value-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                option_value:
+                  $ref: '#/components/schemas/option-value-input'
   '/option_types/{option_type_id}/option_values/{id}':
     get:
       responses:
@@ -2225,11 +2727,13 @@ paths:
         required: true
         schema:
           type: string
+        description: 'The ID of the Spree::OptionType'
       - name: id
         in: path
         required: true
         schema:
           type: string
+        description: The ID of the OptionValue
     delete:
       responses:
         '204':
@@ -2266,14 +2770,23 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Update option type value
-      description: Updates an option type's value.
+      description: |-
+        Updates an option type's value.
+
+        Only users with the `update` permission on the option value can perform this action.
       operationId: update-option-type-value
       tags:
         - Option values
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/option-value-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                option_value:
+                  $ref: '#/components/schemas/option-value-input'
   '/products/{product_id}/product_properties':
     get:
       responses:
@@ -2302,6 +2815,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
+        - $ref: '#/components/parameters/q'
       security:
         - api-key: []
     parameters:
@@ -2325,14 +2839,29 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Create product property
-      description: Creates a product property.
+      description: |-
+        Creates a product property.
+
+        Only users with the `create` permission on `Spree::ProductProperty` can perform this action.
       operationId: create-product-property
       tags:
         - Product properties
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/product-property-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                product_property:
+                  $ref: '#/components/schemas/product-property-input'
+            examples:
+              Example:
+                value:
+                  product_property:
+                    property_name: Fit
+                    value: Loose
   '/products/{product_id}/product_properties/{id}':
     get:
       responses:
@@ -2400,14 +2929,28 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Update product property
-      description: Updates a product's property.
+      description: |-
+        Updates a product's property.
+
+        Only users with the `update` permission on the product property can perform this action.
       operationId: update-product-property
       tags:
         - Product properties
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/product-property-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                product_property:
+                  $ref: '#/components/schemas/product-property-input'
+            examples:
+              Example:
+                value:
+                  product_property:
+                    value: Regular
   /properties:
     get:
       responses:
@@ -2434,6 +2977,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
+        - $ref: '#/components/parameters/q'
       security:
         - api-key: []
     post:
@@ -2449,14 +2993,23 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Create property
-      description: Creates a property.
+      description: |-
+        Creates a property.
+
+        Only users with the `create` permission on `Spree::Propery` can perform this action.
       operationId: create-property
       tags:
         - Properties
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/property-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                property:
+                  $ref: '#/components/schemas/property-input'
   '/properties/{id}':
     get:
       responses:
@@ -2483,6 +3036,7 @@ paths:
         required: true
         schema:
           type: string
+        description: 'The id of the Spree::Property'
     delete:
       responses:
         '204':
@@ -2519,14 +3073,23 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Update property
-      description: Updates a property.
+      description: |-
+        Updates a property.
+
+        Only users with the `update` permission on the property can perform this action.
       operationId: update-property
       tags:
         - Properties
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/property-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                property:
+                  $ref: '#/components/schemas/property-input'
   '/inventory_units/{id}':
     get:
       responses:
@@ -2604,6 +3167,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
+        - $ref: '#/components/parameters/q'
       security:
         - api-key: []
     post:
@@ -2619,14 +3183,29 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Create stock location
-      description: Creates a stock location.
+      description: |-
+        Creates a stock location.
+
+        Only users with the `create` permission on `Spree::StockLocation` can perform this action.
       operationId: create-stock-location
       tags:
         - Stock locations
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/stock-location-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                stock_location:
+                  $ref: '#/components/schemas/stock-location-input'
+            examples:
+              Example:
+                value:
+                  stock_location:
+                    name: North Pole
+                    active: true
   '/stock_locations/{id}':
     get:
       responses:
@@ -2652,6 +3231,7 @@ paths:
         required: true
         schema:
           type: string
+        description: The id of the stock location
     delete:
       responses:
         '204':
@@ -2688,14 +3268,28 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Update stock location
-      description: Updates a stock location.
+      description: |-
+        Updates a stock location.
+
+        Only users with the `update` permission on the stock location can perform this action.
       operationId: update-stock-location
       tags:
         - Stock locations
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/stock-location-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                stock_location:
+                  $ref: '#/components/schemas/stock-location-input'
+            examples:
+              Example:
+                value:
+                  stock_location:
+                    active: false
   '/stock_locations/{stock_location_id}/stock_items':
     get:
       responses:
@@ -2724,6 +3318,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
+        - $ref: '#/components/parameters/q'
       security:
         - api-key: []
     parameters:
@@ -2747,14 +3342,23 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Create stock location item
-      description: Creates a stock item for a stock location.
+      description: |-
+        Creates a stock item for a stock location.
+
+        Only users with the `create` permission on `Spree::StockItem` can perform this action.
       operationId: create-stock-location-item
       tags:
         - Stock items
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/stock-item-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                stock_item:
+                  $ref: '#/components/schemas/stock-item-input'
   '/stock_locations/{stock_location_id}/stock_items/{id}':
     get:
       responses:
@@ -2780,11 +3384,13 @@ paths:
         required: true
         schema:
           type: string
+        description: 'The ID of the Spree::StockLocation'
       - name: id
         in: path
         required: true
         schema:
           type: string
+        description: 'The ID of the Spree::StockItem'
     delete:
       responses:
         '204':
@@ -2821,14 +3427,23 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Update stock location item
-      description: Updates a stock location's item.
+      description: |-
+        Updates a stock location's item.
+
+        Only users with the `update` permission on the stock item can perform this action.
       operationId: update-stock-location-item
       tags:
         - Stock items
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/stock-item-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                stock_item:
+                  $ref: '#/components/schemas/stock-item-input'
   '/stock_locations/{stock_location_id}/stock_movements':
     get:
       responses:
@@ -2855,6 +3470,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
+        - $ref: '#/components/parameters/q'
       security:
         - api-key: []
     parameters:
@@ -3072,6 +3688,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
+        - $ref: '#/components/parameters/q'
       security:
         - api-key: []
     post:
@@ -3087,14 +3704,30 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Create taxonomy
-      description: Creates a taxonomy.
+      description: |-
+        Creates a taxonomy.
+
+        Only users with the `create` permission on `Spree::Taxonomy` can perform this action.
+
+        Creating a taxonomy, its root taxon with the same name will be automatically created. The root taxon's information will be available in the response.
       operationId: create-taxonomy
       tags:
         - Taxonomies
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/taxonomy-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                taxonomy:
+                  $ref: '#/components/schemas/taxonomy-input'
+            examples:
+              Example:
+                value:
+                  taxonomy:
+                    name: Colors
   '/taxonomies/{id}':
     get:
       responses:
@@ -3114,12 +3747,20 @@ paths:
         - Taxonomies
       security:
         - api-key: []
+      parameters:
+        - schema:
+            type: string
+            default: nested
+          in: query
+          name: set
+          description: When `set=nested` it will recoursively return all the taxons of that taxonomy
     parameters:
       - name: id
         in: path
         required: true
         schema:
           type: string
+        description: The id of the taxonomy
     delete:
       responses:
         '204':
@@ -3156,17 +3797,31 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Update taxonomy
-      description: Updates a taxonomy.
+      description: |-
+        Updates a taxonomy.
+
+        Only users with the `update` permission on the taxonomy can perform this action.
       operationId: update-taxonomy
       tags:
         - Taxonomies
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/taxonomy-input'
-  '/taxonomies/{taxonomy_id}/taxons':
-    get:
-      responses:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                taxonomy:
+                  $ref: '#/components/schemas/taxonomy-input'
+            examples:
+              Example:
+                value:
+                  taxonomy:
+                    name: Colours
+  '/taxonomies/{taxonomy_id}/taxons':
+    get:
+      responses:
         '200':
           description: ''
           content:
@@ -3192,6 +3847,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
+        - $ref: '#/components/parameters/q'
       security:
         - api-key: []
     parameters:
@@ -3200,6 +3856,7 @@ paths:
         required: true
         schema:
           type: string
+        description: The id of the taxonomy for which the new taxon will be added
     post:
       responses:
         '200':
@@ -3215,14 +3872,29 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Create taxonomy taxon
-      description: Creates a taxon for a taxonomy.
+      description: |-
+        Creates a taxon for a taxonomy.
+
+        Only users with the `create` permission on `Spree::Taxon` can perform this action.
       operationId: create-taxonomy-taxon
       tags:
         - Taxons
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/taxon-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                taxon:
+                  $ref: '#/components/schemas/taxon-input'
+            examples:
+              Example:
+                value:
+                  taxon:
+                    name: Colors
+                    parent_id: 22
   '/taxonomies/{taxonomy_id}/taxons/{id}':
     get:
       responses:
@@ -3248,11 +3920,13 @@ paths:
         required: true
         schema:
           type: string
+        description: The id of the taxon's taxonomy
       - name: id
         in: path
         required: true
         schema:
           type: string
+        description: The id of the taxon
     delete:
       responses:
         '204':
@@ -3289,14 +3963,28 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Update taxonomy taxon
-      description: Updates a taxonomy's taxon.
+      description: |-
+        Updates a taxonomy's taxon.
+
+        Only users with the `update` permission on the taxon can perform this action.
       operationId: update-taxonomy-taxon
       tags:
         - Taxons
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/taxon-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                taxon:
+                  $ref: '#/components/schemas/taxon-input'
+            examples:
+              Example:
+                value:
+                  taxon:
+                    name: Colours
   /taxons:
     get:
       responses:
@@ -3323,6 +4011,12 @@ paths:
       parameters:
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
+        - $ref: '#/components/parameters/q'
+        - schema:
+            type: boolean
+          in: query
+          name: without_children
+          description: 'When set to `true`, it won''t recursively return all the taxons'' children.'
       security:
         - api-key: []
   /users:
@@ -3350,6 +4044,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
+        - $ref: '#/components/parameters/q'
       security:
         - api-key: []
     post:
@@ -3365,14 +4060,24 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Create user
-      description: Creates a user.
+      description: |
+        Creates a user.
+
+        Only users with the `create` permission on `Spree::User` can perform this action.
       operationId: create-user
       tags:
         - Users
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/user-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                user:
+                  $ref: '#/components/schemas/user-input'
+        description: ''
   /zones:
     get:
       responses:
@@ -3399,6 +4104,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
+        - $ref: '#/components/parameters/q'
       security:
         - api-key: []
     post:
@@ -3414,14 +4120,32 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Create zone
-      description: Creates a zone.
+      description: |-
+        Creates a zone.
+
+        Only users with the `create` permission on `Spree::Zone` can perform this action.
       operationId: create-zone
       tags:
         - Zones
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/zone-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                zone:
+                  $ref: '#/components/schemas/zone-input'
+            examples:
+              Example:
+                value:
+                  zone:
+                    name: North Pole
+                    description: The coldest one.
+                    zone_members_attributes:
+                      - zoneable_type: 'Spree::Country'
+                        zoneable_id: 1
   '/zones/{id}':
     get:
       responses:
@@ -3448,6 +4172,7 @@ paths:
         required: true
         schema:
           type: string
+        description: The ID of the zone we want to update
     delete:
       responses:
         '204':
@@ -3484,14 +4209,28 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Update zone
-      description: Updates a zone.
+      description: |-
+        Updates a zone.
+
+        Only users with the `update` permission on the zone can perform this action.
       operationId: update-zone
       tags:
         - Zones
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/zone-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                zone:
+                  $ref: '#/components/schemas/zone-input'
+            examples:
+              Example:
+                value:
+                  zone:
+                    description: Brrr. The coldest one.
   '/promotions/{id}':
     get:
       responses:
@@ -3546,7 +4285,7 @@ paths:
         - $ref: '#/components/parameters/per_page'
       security:
         - api-key: []
-  '/checkouts/{checkout_id}/line_items/{id}':
+  '/orders/{order_number}/coupon_codes/{id}':
     delete:
       responses:
         '204':
@@ -3554,34 +4293,43 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/line-item'
+                $ref: '#/components/schemas/coupon-code-handler'
         '401':
           $ref: '#/components/responses/invalid-api-key'
         '404':
           $ref: '#/components/responses/not-found'
         '422':
-          $ref: '#/components/responses/delete-restriction'
-      summary: Delete checkout line item
-      description: Deletes a checkout's line item.
-      operationId: delete-checkout-line-item
+          description: Unprocessable Entity (WebDAV)
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/coupon-code-handler'
+      summary: Delete order coupon code
+      description: |-
+        Deletes an order's coupon code.
+
+        To perform this operation the request should be made as the order's owner or with the order token in case of unauthenitcated checkouts (es. guest checkout).
+      operationId: delete-order-coupon-code
       tags:
-        - Line items
+        - Coupon codes
       security:
         - api-key: []
         - order-token: []
     parameters:
-      - name: checkout_id
+      - name: order_number
         in: path
         required: true
-        description: The order number
         schema:
           type: string
+        description: The order number
       - name: id
         in: path
         required: true
+        description: This is the coupon code
         schema:
           type: string
-    patch:
+  '/orders/{order_number}/line_items':
+    post:
       responses:
         '200':
           description: ''
@@ -3595,9 +4343,12 @@ paths:
           $ref: '#/components/responses/not-found'
         '422':
           $ref: '#/components/responses/unprocessable-entity'
-      summary: Update checkout line item
-      description: Updates a checkout's line item.
-      operationId: update-checkout-line-item
+      summary: Create order line item
+      description: |-
+        Create a line item in an order not yet completed.
+
+        To perform this operation the request should be made as the order owner or with the order token in case of unauthenitcated checkouts (es. guest checkout).
+      operationId: create-order-line-item
       tags:
         - Line items
       security:
@@ -3609,47 +4360,21 @@ paths:
             schema:
               type: object
               properties:
-                line_items_attributes:
-                  allOf:
-                    - properties:
-                        id:
-                          type: integer
-                  type: object
-  '/orders/{order_number}/coupon_codes/{id}':
-    delete:
-      responses:
-        '204':
-          description: ''
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/coupon-code-handler'
-        '401':
-          $ref: '#/components/responses/invalid-api-key'
-        '404':
-          $ref: '#/components/responses/not-found'
-        '422':
-          $ref: '#/components/responses/delete-restriction'
-      summary: Delete order coupon code
-      description: Deletes an order's coupon code.
-      operationId: delete-order-coupon-code
-      tags:
-        - Coupon codes
-      security:
-        - api-key: []
-        - order-token: []
+                line_item:
+                  $ref: '#/components/schemas/line-item-input'
+            examples:
+              Example:
+                value:
+                  line_item:
+                    quantity: 1
+                    variant_id: 22
+        description: ''
     parameters:
       - name: order_number
         in: path
         required: true
         schema:
           type: string
-      - name: id
-        in: path
-        required: true
-        description: This is the coupon code
-        schema:
-          type: string
   '/orders/{order_number}/line_items/{id}':
     delete:
       responses:
@@ -3679,11 +4404,13 @@ paths:
         required: true
         schema:
           type: string
+        description: The order number
       - name: id
         in: path
         required: true
         schema:
           type: string
+        description: The id of the line item to update
     patch:
       responses:
         '200':
@@ -3699,7 +4426,10 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Update order line item
-      description: Updates an order's line item.
+      description: |-
+        Update line item's information in an order not yet completed.
+
+        To perform this operation the request should be made as the order owner or with the order token in case of unauthenitcated checkouts (es. guest checkout).
       operationId: update-order-line-item
       tags:
         - Line items
@@ -3707,7 +4437,18 @@ paths:
         - api-key: []
         - order-token: []
       requestBody:
-        $ref: '#/components/requestBodies/line-item-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                line_item:
+                  $ref: '#/components/schemas/line-item-input'
+            examples:
+              example-1:
+                value:
+                  line_item:
+                    quantity: 1
   '/stock_items/{id}':
     delete:
       responses:
@@ -3736,6 +4477,7 @@ paths:
         required: true
         schema:
           type: string
+        description: 'The ID of the Stock::Item'
     patch:
       responses:
         '200':
@@ -3751,14 +4493,23 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Update stock item
-      description: Updates a stock item.
+      description: |-
+        Updates a stock item.
+
+        Only users with the `update` permission on the stock item can perform this action.
       operationId: update-stock-item
       tags:
         - Stock items
       security:
         - api-key: []
       requestBody:
-        $ref: '#/components/requestBodies/stock-item-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                stock_item:
+                  $ref: '#/components/schemas/stock-item-input'
   '/checkouts/{id}':
     patch:
       responses:
@@ -3776,7 +4527,9 @@ paths:
           $ref: '#/components/responses/unprocessable-entity'
       summary: Update checkout
       description: |-
-        Updates a checkout.
+        Updates a checkout and moves the order to the next checkout step. A request with an empty body is legit and only tries to move the order to the next step.
+
+        To perform this operation the request should be made as the order owner or with the order token in case of unauthenitcated checkouts (es. guest checkout).
 
         **Note:** In addition to the order update, this action always attempts to perform an order state machine transition which results in a `422` response if it cannot be transitioned.
       operationId: update-checkout
@@ -3789,13 +4542,17 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/checkout-input'
+              type: object
+              properties:
+                order:
+                  $ref: '#/components/schemas/order-input'
     parameters:
       - name: id
         in: path
         required: true
         schema:
           type: string
+        description: The order number
   '/credit_cards/{id}':
     patch:
       responses:
@@ -3845,7 +4602,10 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Update shipment
-      description: Updates a shipment.
+      description: |-
+        Updates a shipment.
+
+        Please note that this request can be only performed by users with the `update` permission on the shipment.
       operationId: update-shipment
       tags:
         - Shipments
@@ -3855,7 +4615,15 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/shipment-input'
+              type: object
+              properties:
+                shipment:
+                  $ref: '#/components/schemas/shipment-input'
+            examples:
+              Example:
+                value:
+                  shipment:
+                    tracking: tracking-identifier-provided-by-shipping-provider
     parameters:
       - name: number
         in: path
@@ -4160,6 +4928,131 @@ paths:
         description: The order number
         schema:
           type: string
+  '/checkouts/{checkout_id}/line_items':
+    post:
+      responses:
+        '200':
+          description: ''
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/line-item'
+        '401':
+          $ref: '#/components/responses/invalid-api-key'
+        '404':
+          $ref: '#/components/responses/not-found'
+        '422':
+          $ref: '#/components/responses/unprocessable-entity'
+      summary: Create checkout line item
+      description: |-
+        Create a line item in an checkout not yet completed.
+
+        To perform this operation the request should be made as the order owner or with the order token in case of unauthenitcated checkouts (es. guest checkout).
+
+        It is not possible to add a line item to a completed order.
+      operationId: create-checkout-line-item
+      tags:
+        - Line items
+      security:
+        - api-key: []
+        - order-token: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                line_item:
+                  $ref: '#/components/schemas/line-item-input'
+            examples:
+              Example:
+                value:
+                  line_item:
+                    quantity: 1
+                    variant_id: 22
+    parameters:
+      - name: checkout_id
+        in: path
+        required: true
+        description: The order number
+        schema:
+          type: string
+  '/checkouts/{checkout_id}/line_items/{id}':
+    delete:
+      responses:
+        '204':
+          description: ''
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/line-item'
+        '401':
+          $ref: '#/components/responses/invalid-api-key'
+        '404':
+          $ref: '#/components/responses/not-found'
+        '422':
+          $ref: '#/components/responses/delete-restriction'
+      summary: Delete checkout line item
+      description: Deletes a checkout's line item.
+      operationId: delete-checkout-line-item
+      tags:
+        - Line items
+      security:
+        - api-key: []
+        - order-token: []
+    parameters:
+      - name: checkout_id
+        in: path
+        required: true
+        description: The order number
+        schema:
+          type: string
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+        description: The id of the line item to update
+    patch:
+      responses:
+        '200':
+          description: ''
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/line-item'
+        '401':
+          $ref: '#/components/responses/invalid-api-key'
+        '404':
+          $ref: '#/components/responses/not-found'
+        '422':
+          $ref: '#/components/responses/unprocessable-entity'
+      summary: Update checkout line item
+      description: |-
+        Update line item's information in an checkout not yet completed.
+
+        To perform this operation the request should be made as the order owner or with the order token in case of unauthenitcated checkouts (es. guest checkout).
+
+        It is not possible to add a line item to a completed order.
+      operationId: update-checkout-line-item
+      tags:
+        - Line items
+      security:
+        - api-key: []
+        - order-token: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                line_item:
+                  $ref: '#/components/schemas/line-item-input'
+            examples:
+              Example:
+                value:
+                  line_item:
+                    quantity: 2
   /classifications:
     put:
       responses:
@@ -4612,7 +5505,7 @@ paths:
         required: true
         schema:
           type: string
-  '/checkouts/{checkout_id}/line_items':
+  '/orders/{order_number}/coupon_codes':
     post:
       responses:
         '200':
@@ -4620,47 +5513,22 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/line-item'
+                $ref: '#/components/schemas/coupon-code-handler'
         '401':
           $ref: '#/components/responses/invalid-api-key'
         '404':
           $ref: '#/components/responses/not-found'
         '422':
-          $ref: '#/components/responses/unprocessable-entity'
-      summary: Create checkout line item
-      description: Creates a new line item for a checkout.
-      operationId: create-checkout-line-item
-      tags:
-        - Line items
-      security:
-        - api-key: []
-        - order-token: []
-      requestBody:
-        $ref: '#/components/requestBodies/line-item-input'
-    parameters:
-      - name: checkout_id
-        in: path
-        required: true
-        description: The order number
-        schema:
-          type: string
-  '/orders/{order_number}/coupon_codes':
-    post:
-      responses:
-        '200':
           description: ''
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/coupon-code-handler'
-        '401':
-          $ref: '#/components/responses/invalid-api-key'
-        '404':
-          $ref: '#/components/responses/not-found'
-        '422':
-          $ref: '#/components/responses/unprocessable-entity'
       summary: Create order coupon code
-      description: Creates a coupon code for an order.
+      description: |-
+        Creates a coupon code for an order.
+
+        To perform this operation the request should be made as the order's owner or with the order token in case of unauthenitcated checkouts (es. guest checkout).
       operationId: create-order-coupon-code
       tags:
         - Coupon codes
@@ -4668,44 +5536,21 @@ paths:
         - api-key: []
         - order-token: []
       requestBody:
-        $ref: '#/components/requestBodies/coupon-code-input'
-    parameters:
-      - name: order_number
-        in: path
-        required: true
-        schema:
-          type: string
-  '/orders/{order_number}/line_items':
-    post:
-      responses:
-        '200':
-          description: ''
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/line-item'
-        '401':
-          $ref: '#/components/responses/invalid-api-key'
-        '404':
-          $ref: '#/components/responses/not-found'
-        '422':
-          $ref: '#/components/responses/unprocessable-entity'
-      summary: Create order line item
-      description: Creates a line item for an order.
-      operationId: create-order-line-item
-      tags:
-        - Line items
-      security:
-        - api-key: []
-        - order-token: []
-      requestBody:
-        $ref: '#/components/requestBodies/line-item-input'
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/coupon-code-input'
+            examples:
+              Example:
+                value:
+                  coupon_code: off-20
     parameters:
       - name: order_number
         in: path
         required: true
         schema:
           type: string
+        description: The order number
   /shipments:
     post:
       responses:
@@ -4720,7 +5565,10 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Create shipment
-      description: Creates a shipment.
+      description: |-
+        Creates a shipment.
+
+        Please note that this request can be only performed by users with the `create` permission on the shipment.
       operationId: create-shipment
       tags:
         - Shipments
@@ -4738,6 +5586,12 @@ paths:
                   type: integer
                 quantity:
                   type: integer
+            examples:
+              Example:
+                value:
+                  stock_location_id: 0
+                  variant_id: 0
+                  quantity: 0
   /shipments/transfer_to_location:
     post:
       responses:
@@ -4846,12 +5700,15 @@ paths:
           name: id
           schema:
             type: integer
+          description: The id of the Taxon
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
+        - $ref: '#/components/parameters/q'
         - in: query
           name: simple
           schema:
             type: boolean
+          description: Returns a simplified version of the JSON
       security:
         - api-key: []
   '/orders/{order_number}/customer_returns':
@@ -4882,6 +5739,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/page'
         - $ref: '#/components/parameters/per_page'
+        - $ref: '#/components/parameters/q'
       security:
         - api-key: []
     parameters:
@@ -4890,6 +5748,7 @@ paths:
         schema:
           type: string
         required: true
+        description: The order number
     post:
       responses:
         '200':
@@ -4905,12 +5764,21 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Create order customer return
-      description: Creates a customer return for an order.
+      description: |-
+        Creates a customer return for an order.
+
+        Only users with the `create` permission on `Spree::CustomerReturn` can perform this action.
       operationId: create-order-customer-return
       tags:
         - Customer returns
       requestBody:
-        $ref: '#/components/requestBodies/customer-return-input'
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                customer_return:
+                  $ref: '#/components/schemas/customer-return-input'
       security:
         - api-key: []
 tags:
@@ -4964,6 +5832,12 @@ components:
       schema:
         type: integer
         default: 25
+    q:
+      name: q
+      in: query
+      schema:
+        example: '?q[attribute_eq]=value'
+      description: 'Allows to query results based on search filters provided by Ransack (https://github.com/activerecord-hackery/ransack/).'
   responses:
     not-found:
       description: ''
@@ -5004,96 +5878,6 @@ components:
               message:
                 type: string
   requestBodies:
-    taxon-input:
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/taxon-input'
-    line-item-input:
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/line-item-input'
-    payment-input:
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/payment-input'
-    zone-input:
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/zone-input'
-    product-property-input:
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/product-property-input'
-    stock-location-input:
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/stock-location-input'
-    product-input:
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/product-input'
-    property-input:
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/property-input'
-    address-input:
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/address-input'
-    order-input:
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/order-input'
-    image-input:
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/image-input'
-    variant-input:
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/variant-input'
-    user-input:
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/user-input'
-    return-authorization-input:
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/return-authorization-input'
-    customer-return-input:
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/customer-return-input'
-    option-value-input:
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/option-value-input'
-    stock-item-input:
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/stock-item-input'
-    taxonomy-input:
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/taxonomy-input'
     complete-checkoutBody:
       content:
         application/json:
@@ -5102,11 +5886,6 @@ components:
             properties:
               expected_total:
                 type: string
-    coupon-code-input:
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/coupon-code-input'
     add-shipment-itemBody:
       content:
         application/json:
@@ -6043,12 +6822,18 @@ components:
       properties:
         success:
           type: string
+          description: Message returned if the coupon has been applied.
         error:
           type: string
+          description: Message returned if there are errors applying the coupon.
         successful:
           type: boolean
         status_code:
           type: string
+          description: |-
+            When applying a coupon code, it can be: `coupon_code_applied`, `coupon_code_unknown_error`, `coupon_code_max_usage`, `coupon_code_not_eligible`, `coupon_code_already_applied`, `coupon_code_expired` or `coupon_code_not_found`.
+
+            When removing a coupon code, it can be: `coupon_code_removed`, `coupon_code_not_present`, `coupon_code_not_found`.
     address-book:
       type: array
       title: Address book
@@ -6128,19 +6913,20 @@ components:
               type: string
             abbr:
               type: string
+      description: ''
     line-item-input:
       type: object
       title: Line item input
       properties:
         quantity:
           type: integer
-          description: 'Passing `0`, the line item will be removed.'
+          description: 'Passing `0`, the line item will be removed. When omitted creating a line item, quantity will be `1`.'
         options:
           type: object
           description: 'This field can be used to pass custom line item attributes. When used, it will force a new price calculation, unless `price` is one of the options.'
         id:
           type: integer
-          description: Required for existing line items only.
+          description: 'Required when updating existing line items, only when not already present in the Path Parameters.'
         variant_id:
           type: integer
           description: Required for new line items only.
@@ -6164,30 +6950,6 @@ components:
           type: string
         presentation:
           type: string
-    checkout-input:
-      type: object
-      title: Checkout input
-      properties:
-        coupon_code:
-          type: string
-        email:
-          type: string
-        special_instructions:
-          type: string
-        use_billing:
-          type: boolean
-        bill_address_attributes:
-          $ref: '#/components/schemas/address-input'
-        ship_address_attributes:
-          $ref: '#/components/schemas/address-input'
-        payments_attributes:
-          type: array
-          items:
-            $ref: '#/components/schemas/payment-input'
-        shipments_attributes:
-          type: array
-          items:
-            $ref: '#/components/schemas/shipment-input'
     credit-card-update-input:
       type: object
       title: Credit card update input
@@ -6222,10 +6984,9 @@ components:
           type: string
         payment_method_id:
           type: integer
-        payment_method:
-          type: string
         source_attributes:
           type: object
+          description: This field is required for Payment Method that has source_required? returning true.
           properties:
             number:
               type: string
@@ -6271,14 +7032,29 @@ components:
           type: integer
     order-input:
       title: Order input
-      allOf:
-        - $ref: '#/components/schemas/checkout-input'
-        - type: object
-          properties:
-            line_items_attributes:
-              type: array
-              items:
-                $ref: '#/components/schemas/line-item-input'
+      properties:
+        email:
+          type: string
+        special_instructions:
+          type: string
+        use_billing:
+          type: boolean
+        bill_address_attributes:
+          $ref: '#/components/schemas/address-input'
+        ship_address_attributes:
+          $ref: '#/components/schemas/address-input'
+        payments_attributes:
+          type: array
+          items:
+            $ref: '#/components/schemas/payment-input'
+        shipments_attributes:
+          type: array
+          items:
+            $ref: '#/components/schemas/shipment-input'
+        line_items_attributes:
+          type: array
+          items:
+            $ref: '#/components/schemas/line-item-input'
     product-input:
       type: object
       title: Product input
@@ -6289,8 +7065,6 @@ components:
           type: string
         available_on:
           type: string
-        permalink:
-          type: string
         meta_description:
           type: string
         meta_keywords:
@@ -6316,13 +7090,11 @@ components:
         tax_category_id:
           type: integer
         taxon_ids:
-          type: array
-          items:
-            type: integer
+          type: string
+          description: 'Comma separated list of taxon ids. Eg. "1,2"'
         option_type_ids:
-          type: array
-          items:
-            type: integer
+          description: 'Comma separated list of option type ids ids. Eg. "1,2"'
+          type: string
         cost_currency:
           type: string
         cost_price:
@@ -6359,28 +7131,16 @@ components:
       type: object
       title: Variant input
       properties:
-        name:
-          type: string
-        presentation:
+        price:
           type: string
         cost_price:
           type: string
-        lock_version:
-          type: string
         position:
           type: integer
         track_inventory:
           type: boolean
         product_id:
           type: integer
-        product:
-          type: integer
-        option_values_attributes:
-          type: array
-          items:
-            $ref: '#/components/schemas/option-value-input'
-        price:
-          type: string
         weight:
           type: string
         height:
@@ -6397,13 +7157,20 @@ components:
           type: array
           items:
             type: integer
+        option_values_attributes:
+          type: array
+          items:
+            $ref: '#/components/schemas/option-value-input'
         options:
           type: object
+          description: '`Name` will be the name/presentation of the option type and `Value` will be the name/presentation of the option value. They will be created if not exist.'
           properties:
             name:
               type: string
             value:
               type: string
+      required:
+        - price
     property-input:
       type: object
       title: Property input
@@ -6480,6 +7247,8 @@ components:
       properties:
         name:
           type: string
+      required:
+        - name
     taxon-input:
       type: object
       title: Taxon input