solidus_api 2.11.10 → 3.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8bd456dd76809794ef738af43d0351f17310aaed11df375a59605bcc4cf84279
-  data.tar.gz: 11a016339bab6d9ce6869e5362f880060812247a8b5c0049fa91e8fc3bfecaab
+  metadata.gz: c75f80bedcb1079be3b929bf5793b5df00cd0c2c829da77e07afc3fe6a16af8c
+  data.tar.gz: 0afcfe13f9333eb287537f12c8a81b9607650d809e1a0db92237d60819543db3
 SHA512:
-  metadata.gz: 473dcab1dabd89b3fe938d2f70a390def49fd43a23ef2a70f4648365d9d5a9812bf3c934fc3b7fef6029bef5bcbaa37724e7deaba582ff8884c2975ac64c293f
-  data.tar.gz: 71aa0b757e05201fb02654b4f85c11d79faf2cd6d1d7eb060a788c7bc0dd4d691aa65ac66018df1320dde41f37179c952f93b32b193d980a89a0fd7155121c3b
+  metadata.gz: fd7e12b7b7640b4dab2de02b28b4d12fd6639360831c8b4f1363415f2a53226469253b25e440084090eecc3ac577eeb47c19b821cc1952f9da0db970a297eaec
+  data.tar.gz: 1535fe8316f622eb26d2eb1947e7c8013aee95c87244aeeabcafb7869945654a8de62b722a021d181d5ea568891acdce56651b182d0dee701ec84db6493eb53d

data/app/controllers/spree/api/base_controller.rb

@@ -104,7 +104,7 @@ module Spree
       end
 
       def api_key
-        bearer_token || spree_token || params[:token]
+        bearer_token || params[:token]
       end
       helper_method :api_key
 
@@ -114,17 +114,6 @@ module Spree
         header.gsub(pattern, '') if header.present? && header.match(pattern)
       end
 
-      def spree_token
-        token = request.headers["X-Spree-Token"]
-        return if token.blank?
-
-        Spree::Deprecation.warn(
-          'The custom X-Spree-Token request header is deprecated and will be removed in the next release.' \
-          ' Please use bearer token authorization header instead.'
-        )
-        token
-      end
-
       def order_token
         request.headers["X-Spree-Order-Token"] || params[:order_token]
       end

data/app/controllers/spree/api/checkouts_controller.rb

@@ -9,11 +9,10 @@ module Spree
 
       rescue_from Spree::Order::InsufficientStock, with: :insufficient_stock_error
 
-      include Spree::Core::ControllerHelpers::Order
-
-      # TODO: Remove this after deprecated usage in #update is removed
       include Spree::Core::ControllerHelpers::PaymentParameters
 
+      include Spree::Core::ControllerHelpers::Order
+
       def next
         authorize! :update, @order, order_token
         if !expected_total_ok?(params[:expected_total])
@@ -95,7 +94,7 @@ module Spree
         massaged_params
       end
 
-      # Should be overriden if you have areas of your checkout that don't match
+      # Should be overridden if you have areas of your checkout that don't match
       # up to a step within checkout_steps, such as a registration step
       def skip_state_validation?
         false
@@ -116,17 +115,6 @@ module Spree
       end
 
       def after_update_attributes
-        if params[:order] && params[:order][:coupon_code].present?
-          Spree::Deprecation.warn('This method is deprecated. Please use `Spree::Api::CouponCodesController#create` endpoint instead.')
-          handler = PromotionHandler::Coupon.new(@order)
-          handler.apply
-
-          if handler.error.present?
-            @coupon_message = handler.error
-            respond_with(@order, default_template: 'spree/api/orders/could_not_apply_coupon', status: 422)
-            return true
-          end
-        end
         false
       end
 

data/app/controllers/spree/api/orders_controller.rb

@@ -12,8 +12,6 @@ module Spree
       class_attribute :admin_payment_attributes
       self.admin_payment_attributes = [:payment_method, :amount, :state, source: {}]
 
-      skip_before_action :authenticate_user, only: :apply_coupon_code
-
       before_action :find_order, except: [:create, :mine, :current, :index]
       around_action :lock_order, except: [:create, :mine, :current, :index, :show]
 
@@ -104,20 +102,6 @@ module Spree
         end
       end
 
-      def apply_coupon_code
-        Spree::Deprecation.warn('This method is deprecated. Please use `Spree::Api::CouponCodesController#create` endpoint instead.')
-
-        authorize! :update, @order, order_token
-        @order.coupon_code = params[:coupon_code]
-        @handler = PromotionHandler::Coupon.new(@order).apply
-        if @handler.successful?
-          render "spree/api/promotions/handler", status: 200
-        else
-          logger.error("apply_coupon_code_error=#{@handler.error.inspect}")
-          render "spree/api/promotions/handler", status: 422
-        end
-      end
-
       private
 
       def order_params

data/app/controllers/spree/api/taxonomies_controller.rb

@@ -15,12 +15,6 @@ module Spree
         respond_with(taxonomy)
       end
 
-      # Because JSTree wants parameters in a *slightly* different format
-      def jstree
-        Spree::Deprecation.warn("Please don't use `/api/taxonomies/:taxonomy_id/jstree` endpoint. It is deprecated and will be removed in the next future.", caller)
-        show
-      end
-
       def create
         authorize! :create, Taxonomy
         @taxonomy = Spree::Taxonomy.new(taxonomy_params)

data/app/controllers/spree/api/taxons_controller.rb

@@ -29,11 +29,6 @@ module Spree
         respond_with(@taxon)
       end
 
-      def jstree
-        Spree::Deprecation.warn("Please don't use `/api/taxonomies/:taxonomy_id/taxons/:taxon_id/jstree` endpoint. It is deprecated and will be removed in the next future.", caller)
-        show
-      end
-
       def create
         authorize! :create, Taxon
         @taxon = Spree::Taxon.new(taxon_params)

data/app/helpers/spree/api/api_helpers.rb

@@ -126,19 +126,12 @@ module Spree
         :id, :number, :state, :order_id, :memo, :created_at, :updated_at
       ]
 
-      @@address_base_attributes = [
+      @@address_attributes = [
         :id, :name, :address1, :address2, :city, :zipcode, :phone, :company,
         :alternative_phone, :country_id, :country_iso, :state_id, :state_name,
         :state_text
       ]
 
-      @@address_attributes = if Spree::Config.use_combined_first_and_last_name_in_address
-                               @@address_base_attributes
-                             else
-                               @@address_base_attributes +
-                                 Spree::Address::LEGACY_NAME_ATTRS.map(&:to_sym)
-                             end
-
       @@country_attributes = [:id, :iso_name, :iso, :iso3, :name, :numcode]
 
       @@state_attributes = [:id, :name, :abbr, :country_id]

data/app/views/spree/api/config/show.json.jbuilder

@@ -1,4 +1,3 @@
 # frozen_string_literal: true
 
-json.default_country_id(Spree::Country.default.id)
 json.default_country_iso(Spree::Config[:default_country_iso])

data/config/routes.rb

@@ -4,11 +4,6 @@ Spree::Core::Engine.routes.draw do
   namespace :admin do
     resources :users do
       resource :api_key, controller: 'users/api_key', only: [:create, :destroy]
-
-      member do
-        put :generate_api_key # Deprecated
-        put :clear_api_key # Deprecated
-      end
     end
   end
 
@@ -68,7 +63,6 @@ Spree::Core::Engine.routes.draw do
       member do
         put :cancel
         put :empty
-        put :apply_coupon_code
       end
 
       resources :coupon_codes, only: [:create, :destroy]
@@ -99,14 +93,7 @@ Spree::Core::Engine.routes.draw do
     resources :states, only: [:index, :show]
 
     resources :taxonomies do
-      member do
-        get :jstree
-      end
-      resources :taxons do
-        member do
-          get :jstree
-        end
-      end
+      resources :taxons
     end
 
     resources :taxons, only: [:index]

data/lib/spree/api/engine.rb

@@ -8,7 +8,7 @@ module Spree
       isolate_namespace Spree
       engine_name 'spree_api'
 
-      # Leave initializer empty for backwards-compatability. Other apps
+      # Leave initializer empty for backwards-compatibility. Other apps
       # might still rely on this event.
       initializer "spree.api.environment", before: :load_config_initializers do; end
     end

data/lib/spree/api/responders/jbuilder_template.rb

@@ -16,8 +16,6 @@ module Spree
           options[:default_template]
         end
       end
-
-      RablTemplate = ActiveSupport::Deprecation::DeprecatedConstantProxy.new('RablTemplate', 'JbuilderTemplate')
     end
   end
 end

data/lib/spree/api/testing_support/helpers.rb

@@ -27,7 +27,7 @@ module Spree
           allow(Spree.user_class).to receive(:find_by).with(hash_including(:spree_api_key)) { current_api_user }
         end
 
-        # This method can be overriden (with a let block) inside a context
+        # This method can be overridden (with a let block) inside a context
         # For instance, if you wanted to have an admin user instead.
         def current_api_user
           @current_api_user ||= stub_model(Spree::LegacyUser, email: "solidus@example.com", spree_roles: [])

data/openapi/solidus-api.oas.yml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: Solidus API
-  version: "1.0"
+  version: '1.0'
   description: The standard Solidus API.
   contact:
     name: Solidus
@@ -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:
@@ -1067,12 +1326,10 @@ paths:
         '422':
           $ref: '#/components/responses/delete-restriction'
       summary: Remove address from user address book
-      description: >-
+      description: |-
         Removes an address from a user's address book.
 
-
-        **Note:** Rather than delete a `Spree::UserAddress` record this action
-        set its `archived` attribute to `true`.
+        **Note:** Rather than delete a `Spree::UserAddress` record this action set its `archived` attribute to `true`.
       operationId: remove-address-from-user-address-book
       tags:
         - Address books
@@ -1101,16 +1358,10 @@ paths:
       operationId: update-user-address-book
       tags:
         - Address books
-      description: >-
+      description: |-
         Updates a user's address book.
 
-
-        **Note:** if the passed `id` matches an existing `address` a new
-        `Spree::Address` record will be created and the matched `address`
-        `archived` on `Spree::UserAddress`. For a similar logic, if the passed
-        `id` matches an existing `address` which is in `archived` state, the
-        `Spree::UserAddress#archived` record will be restored to `false`.
-
+        **Note:** if the passed `id` matches an existing `address` a new `Spree::Address` record will be created and the matched `address` `archived` on `Spree::UserAddress`. For a similar logic, if the passed `id` matches an existing `address` which is in `archived` state, the `Spree::UserAddress#archived` record will be restored to `false`.
         See `user_address_book.rb` for further information.
       security:
         - api-key: []
@@ -1211,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:
@@ -1233,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
@@ -1264,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
@@ -1272,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:
@@ -1304,6 +1607,7 @@ paths:
       - name: id
         in: path
         required: true
+        description: The payment id
         schema:
           type: string
     patch:
@@ -1316,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
@@ -1334,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:
@@ -1392,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:
@@ -1431,6 +1754,7 @@ paths:
         required: true
         schema:
           type: string
+        description: 'The ID of the Spree::ReturnAuthorization'
     delete:
       responses:
         '204':
@@ -1467,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:
@@ -1504,6 +1837,7 @@ paths:
       - name: id
         in: path
         required: true
+        description: The id of the customer return
         schema:
           type: string
     put:
@@ -1521,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:
@@ -1577,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:
@@ -1603,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:
@@ -1633,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:
@@ -1672,6 +2060,7 @@ paths:
       - name: order_number
         in: path
         required: true
+        description: The order number
         schema:
           type: string
     post:
@@ -1689,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
@@ -1697,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:
@@ -1739,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
@@ -1752,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:
@@ -1804,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:
@@ -1838,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':
@@ -1879,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:
@@ -1897,8 +2349,6 @@ paths:
               schema:
                 type: object
                 properties:
-                  default_country_id:
-                    type: integer
                   default_country_iso:
                     type: string
         '401':
@@ -2081,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:
@@ -2115,6 +2574,7 @@ paths:
         required: true
         schema:
           type: string
+        description: 'The ID of the Spree::OptionValue'
     delete:
       responses:
         '204':
@@ -2151,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:
@@ -2187,6 +2657,7 @@ paths:
         required: true
         schema:
           type: string
+        description: 'The ID of the Spree::OptionType'
     post:
       responses:
         '200':
@@ -2202,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:
@@ -2235,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':
@@ -2276,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:
@@ -2335,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:
@@ -2410,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:
@@ -2459,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:
@@ -2493,6 +3022,7 @@ paths:
         required: true
         schema:
           type: string
+        description: 'The id of the Spree::Property'
     delete:
       responses:
         '204':
@@ -2529,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:
@@ -2629,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:
@@ -2662,6 +3216,7 @@ paths:
         required: true
         schema:
           type: string
+        description: The id of the stock location
     delete:
       responses:
         '204':
@@ -2698,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:
@@ -2757,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:
@@ -2790,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':
@@ -2831,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:
@@ -3097,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:
@@ -3130,6 +3735,7 @@ paths:
         required: true
         schema:
           type: string
+        description: The id of the taxonomy
     delete:
       responses:
         '204':
@@ -3166,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:
@@ -3210,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':
@@ -3225,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:
@@ -3258,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':
@@ -3299,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:
@@ -3375,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:
@@ -3424,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:
@@ -3458,6 +4138,7 @@ paths:
         required: true
         schema:
           type: string
+        description: The ID of the zone we want to update
     delete:
       responses:
         '204':
@@ -3494,73 +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'
-  '/taxonomies/{taxonomy_id}/jstree':
-    get:
-      responses:
-        '200':
-          description: ''
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/jstree'
-        '401':
-          $ref: '#/components/responses/invalid-api-key'
-        '404':
-          $ref: '#/components/responses/not-found'
-      summary: Get taxonomy jsTree
-      description: Builds a taxonomy's jsTree.
-      operationId: get-taxonomy-jstree
-      tags:
-        - Taxonomies
-      security:
-        - api-key: []
-    parameters:
-      - name: taxonomy_id
-        in: path
-        required: true
-        schema:
-          type: string
-  '/taxonomies/{taxonomy_id}/taxons/{taxon_id}/jstree':
-    get:
-      responses:
-        '200':
-          description: ''
-          content:
-            application/json:
-              schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/jstree'
-        '401':
-          $ref: '#/components/responses/invalid-api-key'
-        '404':
-          $ref: '#/components/responses/not-found'
-      summary: Get taxon jsTree
-      description: Builds a taxon's jsTree.
-      operationId: get-taxon-jstree
-      tags:
-        - Taxons
-      security:
-        - api-key: []
-    parameters:
-      - name: taxonomy_id
-        in: path
-        required: true
-        schema:
-          type: string
-      - name: taxon_id
-        in: path
-        required: true
-        schema:
-          type: string
+        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:
@@ -3615,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':
@@ -3623,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: ''
@@ -3664,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:
@@ -3678,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:
@@ -3748,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':
@@ -3768,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
@@ -3776,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:
@@ -3805,6 +4443,7 @@ paths:
         required: true
         schema:
           type: string
+        description: 'The ID of the Stock::Item'
     patch:
       responses:
         '200':
@@ -3820,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:
@@ -3844,13 +4492,12 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Update checkout
-      description: >-
-        Updates a checkout.
+      description: |-
+        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.
+        **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
       tags:
         - Checkouts
@@ -3861,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:
@@ -3917,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
@@ -3927,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
@@ -4232,78 +4894,167 @@ paths:
         description: The order number
         schema:
           type: string
-  /classifications:
-    put:
+  '/checkouts/{checkout_id}/line_items':
+    post:
       responses:
         '200':
           description: ''
           content:
             application/json:
               schema:
-                type: object
-                properties: {}
+                $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 classification
+      summary: Create checkout line item
       description: |-
-        Updates a classification.
+        Create a line item in an checkout not yet completed.
 
-        This method only updates the classification position.
-      operationId: update-classification
+        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:
-        - Classifications
+        - Line items
       security:
         - api-key: []
+        - order-token: []
       requestBody:
         content:
           application/json:
             schema:
               type: object
               properties:
-                product_id:
-                  type: integer
-                taxon_id:
-                  type: integer
-                position:
-                  type: integer
-  '/orders/{order_number}/apply_coupon_code':
-    put:
+                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:
-        '200':
+        '204':
           description: ''
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/coupon-code-handler'
+                $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: Apply order coupon code
-      deprecated: true
-      description: >-
-        **Deprecated:** This method is deprecated. Please use
-        `Spree::Api::CouponCodesController#create` endpoint instead.
-
-        Applies a coupon code on the order.
-      operationId: apply-order-coupon-code
+          $ref: '#/components/responses/delete-restriction'
+      summary: Delete checkout line item
+      description: Deletes a checkout's line item.
+      operationId: delete-checkout-line-item
       tags:
-        - Coupon codes
+        - Line items
       security:
         - api-key: []
         - order-token: []
-      requestBody:
-        $ref: '#/components/requestBodies/coupon-code-input'
     parameters:
-      - name: order_number
+      - 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:
+        '200':
+          description: ''
+          content:
+            application/json:
+              schema:
+                type: object
+                properties: {}
+        '401':
+          $ref: '#/components/responses/invalid-api-key'
+        '422':
+          $ref: '#/components/responses/unprocessable-entity'
+      summary: Update classification
+      description: |-
+        Updates a classification.
+
+        This method only updates the classification position.
+      operationId: update-classification
+      tags:
+        - Classifications
+      security:
+        - api-key: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                product_id:
+                  type: integer
+                taxon_id:
+                  type: integer
+                position:
+                  type: integer
   '/orders/{order_number}/cancel':
     put:
       responses:
@@ -4720,7 +5471,7 @@ paths:
         required: true
         schema:
           type: string
-  '/checkouts/{checkout_id}/line_items':
+  '/orders/{order_number}/coupon_codes':
     post:
       responses:
         '200':
@@ -4728,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
@@ -4776,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:
@@ -4828,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
@@ -4846,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:
@@ -4983,7 +5695,7 @@ paths:
         '404':
           $ref: '#/components/responses/not-found'
       summary: List order customer returns
-      description: "Lists an order's customer returns."
+      description: Lists an order's customer returns.
       operationId: list-order-customer-returns
       tags:
         - Customer returns
@@ -4998,6 +5710,7 @@ paths:
         schema:
           type: string
         required: true
+        description: The order number
     post:
       responses:
         '200':
@@ -5013,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:
@@ -5112,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:
@@ -5210,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:
@@ -5675,20 +6302,8 @@ components:
           type: integer
         country_iso:
           type: string
-        firstname:
-          type: string
-          deprecated: true
-          description: '*Deprecated: will be removed in Solidus 3.0, please use `name` property*'
-        full_name:
-          type: string
-          deprecated: true
-          description: '*Deprecated: will be removed in Solidus 3.0, please use `name` property*'
         id:
           type: integer
-        lastname:
-          type: string
-          deprecated: true
-          description: '*Deprecated: will be removed in Solidus 3.0, please use `name` property*'
         name:
           type: string
         phone:
@@ -6117,23 +6732,6 @@ components:
         root:
           $ref: '#/components/schemas/taxon'
       title: Taxonomy
-    jstree:
-      type: array
-      items:
-        type: object
-        properties:
-          attr:
-            type: object
-            properties:
-              id:
-                type: integer
-              name:
-                type: string
-          data:
-            type: string
-          state:
-            type: string
-      title: jsTree
     promotion:
       type: object
       properties:
@@ -6180,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
@@ -6225,14 +6829,6 @@ components:
           type: integer
         name:
           type: string
-        firstname:
-          type: string
-          deprecated: true
-          description: '*Deprecated: will be removed in Solidus 3.0, please use `name` property*'
-        lastname:
-          type: string
-          deprecated: true
-          description: '*Deprecated: will be removed in Solidus 3.0, please use `name` property*'
         address1:
           type: string
         address2:
@@ -6273,22 +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.
+          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.
@@ -6312,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
@@ -6370,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
@@ -6399,8 +6968,6 @@ components:
               type: string
             encrypted_data:
               type: string
-            existing_card_id:
-              type: integer
             wallet_payment_source_id:
               type: integer
             address_attributes:
@@ -6421,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
@@ -6466,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:
@@ -6509,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:
@@ -6547,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
@@ -6630,6 +7205,8 @@ components:
       properties:
         name:
           type: string
+      required:
+        - name
     taxon-input:
       type: object
       title: Taxon input