solidus_api 3.0.1 → 3.0.5

data/openapi/solidus-api.oas.yml

@@ -60,7 +60,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:
@@ -116,6 +146,7 @@ paths:
         required: true
         schema:
           type: string
+        description: The order number
     patch:
       responses:
         '200':
@@ -131,7 +162,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 +173,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:
@@ -344,7 +413,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 +472,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:
@@ -456,7 +546,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 +604,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 +647,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 +738,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:
@@ -689,14 +852,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 +964,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 +1042,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 +1085,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 +1128,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:
@@ -982,6 +1231,7 @@ paths:
         required: true
         schema:
           type: string
+        description: 'The ID of the Spree::User'
     delete:
       responses:
         '204':
@@ -1018,14 +1268,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:
@@ -1203,7 +1462,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,7 +1513,7 @@ 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
@@ -1256,7 +1544,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 +1552,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 +1607,7 @@ paths:
       - name: id
         in: path
         required: true
+        description: The payment id
         schema:
           type: string
     patch:
@@ -1308,12 +1620,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 +1647,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:
@@ -1384,14 +1706,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 +1754,7 @@ paths:
         required: true
         schema:
           type: string
+        description: 'The ID of the Spree::ReturnAuthorization'
     delete:
       responses:
         '204':
@@ -1459,14 +1791,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 +1837,7 @@ paths:
       - name: id
         in: path
         required: true
+        description: The id of the customer return
         schema:
           type: string
     put:
@@ -1513,12 +1855,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:
@@ -1569,7 +1920,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 +1960,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 +1992,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:
@@ -1664,6 +2060,7 @@ paths:
       - name: order_number
         in: path
         required: true
+        description: The order number
         schema:
           type: string
     post:
@@ -1681,7 +2078,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 +2086,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 +2151,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 +2173,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:
@@ -1796,14 +2236,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 +2279,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 +2322,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 +2531,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 +2574,7 @@ paths:
         required: true
         schema:
           type: string
+        description: 'The ID of the Spree::OptionValue'
     delete:
       responses:
         '204':
@@ -2141,14 +2611,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 +2657,7 @@ paths:
         required: true
         schema:
           type: string
+        description: 'The ID of the Spree::OptionType'
     post:
       responses:
         '200':
@@ -2192,14 +2673,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 +2715,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 +2758,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:
@@ -2325,14 +2826,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 +2916,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:
@@ -2449,14 +2979,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 +3022,7 @@ paths:
         required: true
         schema:
           type: string
+        description: 'The id of the Spree::Property'
     delete:
       responses:
         '204':
@@ -2519,14 +3059,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:
@@ -2619,14 +3168,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 +3216,7 @@ paths:
         required: true
         schema:
           type: string
+        description: The id of the stock location
     delete:
       responses:
         '204':
@@ -2688,14 +3253,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:
@@ -2747,14 +3326,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 +3368,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 +3411,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:
@@ -3087,14 +3686,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:
@@ -3120,6 +3735,7 @@ paths:
         required: true
         schema:
           type: string
+        description: The id of the taxonomy
     delete:
       responses:
         '204':
@@ -3156,14 +3772,28 @@ 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'
+        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:
@@ -3200,6 +3830,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 +3846,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 +3894,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 +3937,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:
@@ -3365,14 +4027,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:
@@ -3414,14 +4086,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 +4138,7 @@ paths:
         required: true
         schema:
           type: string
+        description: The ID of the zone we want to update
     delete:
       responses:
         '204':
@@ -3484,14 +4175,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 +4251,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 +4259,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 +4309,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 +4326,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 +4370,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 +4392,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 +4403,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 +4443,7 @@ paths:
         required: true
         schema:
           type: string
+        description: 'The ID of the Stock::Item'
     patch:
       responses:
         '200':
@@ -3751,14 +4459,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 +4493,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 +4508,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 +4568,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 +4581,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 +4894,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 +5471,7 @@ paths:
         required: true
         schema:
           type: string
-  '/checkouts/{checkout_id}/line_items':
+  '/orders/{order_number}/coupon_codes':
     post:
       responses:
         '200':
@@ -4620,47 +5479,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 +5502,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 +5531,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 +5552,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:
@@ -4890,6 +5710,7 @@ paths:
         schema:
           type: string
         required: true
+        description: The order number
     post:
       responses:
         '200':
@@ -4905,12 +5726,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:
@@ -5004,96 +5834,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 +5842,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 +6778,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 +6869,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 +6906,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 +6940,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 +6988,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
@@ -6316,13 +7048,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 +7089,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 +7115,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 +7205,8 @@ components:
       properties:
         name:
           type: string
+      required:
+        - name
     taxon-input:
       type: object
       title: Taxon input