spree_api 6.0.0.rc1 → 6.0.0.rc3

data/app/controllers/spree/api/v3/store/carts/items_controller.rb

@@ -9,6 +9,22 @@ module Spree
 
             before_action :find_cart!
 
+            request_params 'AddLineItemParams', action: :create do |body|
+              body.attribute :variant_id, :id, required: true, example: 'variant_abc123'
+              body.attribute :quantity, :integer, example: 2, description: 'Defaults to 1.'
+              body.attribute :metadata, :hash,
+                example: { gift_message: 'Happy Birthday!' },
+                description: 'Write-only key-value metadata.'
+              body.attribute :options, :hash, description: 'Values for line item attributes an extension adds.'
+            end
+
+            request_params 'UpdateLineItemParams', action: :update do |body|
+              body.attribute :quantity, :integer, example: 5, description: 'At least 1. Remove an item with DELETE.'
+              body.attribute :metadata, :hash,
+                example: { engraving: 'J.D.' },
+                description: 'Write-only key-value metadata, merged with what the line item has.'
+            end
+
             # POST  /api/v3/store/carts/:cart_id/items
             def create
               with_order_lock do
@@ -113,11 +129,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(
-                :id, :variant_id, :quantity,
-                *Spree::LineItem.additional_permitted_attributes,
-                { metadata: {}, options: {} }
-              )
+              params.permit(*declared_permitted_attributes, *Spree::LineItem.additional_permitted_attributes)
             end
           end
         end

data/app/controllers/spree/api/v3/store/carts/payment_sessions_controller.rb

@@ -10,6 +10,24 @@ module Spree
             before_action :find_cart!
             before_action :set_payment_session, only: [:show, :update, :complete]
 
+            request_params 'CreatePaymentSessionParams', action: :create do |body|
+              body.attribute :payment_method_id, :id, required: true, example: 'pm_abc123'
+              body.attribute :amount, :decimal,
+                example: '99.99',
+                description: 'Defaults to the order total minus store credits.'
+              body.attribute :external_data, :hash, description: 'Provider-specific data passed to the gateway.'
+            end
+
+            request_params 'UpdatePaymentSessionParams', action: :update do |body|
+              body.attribute :amount, :decimal, example: '50.00'
+              body.attribute :external_data, :hash, description: 'Provider-specific data to update.'
+            end
+
+            request_params 'CompletePaymentSessionParams', action: :complete do |body|
+              body.attribute :session_result, :string, description: 'Provider-specific session result token.'
+              body.attribute :external_data, :hash, description: 'Provider-specific completion data.'
+            end
+
             # POST /api/v3/store/carts/:cart_id/payment_sessions
             def create
               with_order_lock do
@@ -94,15 +112,11 @@ module Spree
             end
 
             def permitted_params
-              params.permit(
-                :amount, :payment_method_id,
-                *Spree::PaymentSession.additional_permitted_attributes,
-                { external_data: {} }
-              )
+              params.permit(*declared_permitted_attributes, *Spree::PaymentSession.additional_permitted_attributes)
             end
 
             def complete_params
-              params.permit(:session_result, { external_data: {} })
+              params.permit(*declared_permitted_attributes)
             end
 
             private

data/app/controllers/spree/api/v3/store/carts/payments_controller.rb

@@ -8,6 +8,17 @@ module Spree
 
             before_action :find_cart!
 
+            request_params 'CreatePaymentParams', action: :create do |body|
+              body.attribute :payment_method_id, :id,
+                required: true,
+                example: 'pm_abc123',
+                description: 'A payment method that needs no payment session.'
+              body.attribute :amount, :decimal,
+                example: '99.99',
+                description: 'Defaults to the order total minus store credits.'
+              body.attribute :metadata, :hash, description: 'Key-value metadata to attach to the payment.'
+            end
+
             # POST /api/v3/store/carts/:cart_id/payments
             # Creates a payment for non-session payment methods (e.g. Check, Cash on Delivery, Bank Transfer)
             def create

data/app/controllers/spree/api/v3/store/carts/po_documents_controller.rb

@@ -12,7 +12,7 @@ module Spree
           # unconditional presigner would let anyone holding one mint blobs in
           # the merchant's bucket. Reaching this action means holding the cart.
           #
-          # Blobs are minted on private storage, because attaching a signed id
+          # Files are minted on private storage, because attaching a signed id
           # never moves a blob between services and a purchase order carries the
           # buyer's prices, terms and internal cost codes.
           class PoDocumentsController < Store::BaseController
@@ -21,10 +21,20 @@ module Spree
 
             before_action :find_cart!
 
+            request_params 'CreatePoDocumentParams', action: :create do |body|
+              body.attribute :filename, :string, required: true
+              body.attribute :content_type, :string, required: true
+              body.attribute :byte_size, :integer, required: true
+              body.attribute :checksum, :string,
+                required: true,
+                description: 'Base64-encoded MD5 digest of the file; the storage service checks the bytes against it.'
+            end
+
             # POST /api/v3/store/carts/:cart_id/po_document
             #
-            # Exchanges blob metadata for an upload URL. The returned signed id
-            # is then sent back as `po_document` on a cart update, which is what
+            # Takes the same flat request as the Admin API's `POST /files` and
+            # answers with the same shape. The returned signed id is then sent
+            # back as `po_document_signed_id` on a cart update, which is what
             # actually attaches it.
             #
             # The declared size and type are checked here, before any URL is
@@ -34,20 +44,20 @@ module Spree
             # only runs once the bytes are already stored. It is a gate on the
             # cheap lie, not a substitute: the attach-time check still reads
             # the stored object, which is what catches an under-declared size.
+            # Bytes in the request itself are not accepted here: a publishable
+            # key is public.
             def create
-              return render_po_document_invalid unless acceptable_upload?
-
-              blob = ActiveStorage::Blob.create_before_direct_upload!(
-                service_name: Spree.private_storage_service_name, **blob_params
+              file_upload = Spree::FileUpload.new(
+                store: current_store,
+                visibility: 'private',
+                max_byte_size: Spree::Purchase::PurchaseOrder::MAX_PO_DOCUMENT_SIZE,
+                allowed_content_types: Spree::Purchase::PurchaseOrder::PO_DOCUMENT_CONTENT_TYPES,
+                **params.permit(*declared_permitted_attributes).to_h.symbolize_keys
               )
 
-              render json: {
-                direct_upload: {
-                  url: blob.service_url_for_direct_upload,
-                  headers: blob.service_headers_for_direct_upload
-                },
-                signed_id: blob.signed_id
-              }, status: :created
+              return render_po_document_invalid unless file_upload.save
+
+              render json: Spree.api.file_upload_serializer.new(file_upload, params: serializer_params).to_h, status: :created
             end
 
             # GET /api/v3/store/carts/:cart_id/po_document
@@ -79,18 +89,6 @@ module Spree
 
             private
 
-            def blob_params
-              params.require(:blob).permit(:filename, :byte_size, :checksum, :content_type).to_h.symbolize_keys
-            end
-
-            def acceptable_upload?
-              declared_size = Integer(blob_params[:byte_size].to_s, exception: false)
-
-              declared_size&.positive? &&
-                declared_size <= Spree::Purchase::PurchaseOrder::MAX_PO_DOCUMENT_SIZE &&
-                Spree::Purchase::PurchaseOrder::PO_DOCUMENT_CONTENT_TYPES.include?(blob_params[:content_type])
-            end
-
             def render_po_document_invalid
               render_error(
                 code: ERROR_CODES[:parameter_invalid],

data/app/controllers/spree/api/v3/store/carts/store_credits_controller.rb

@@ -9,13 +9,20 @@ module Spree
 
             before_action :require_authentication!
             before_action :find_cart!
+            before_action :stringify_numeric_amount, only: :create
+
+            request_params 'ApplyStoreCreditParams', action: :create do |body|
+              body.attribute :amount, :decimal,
+                example: '10.00',
+                description: 'Defaults to as much as the cart can use. A JSON number is still read until 6.1, with a deprecation warning.'
+            end
 
             # POST /api/v3/store/carts/:cart_id/store_credits
             def create
               with_order_lock do
                 result = Spree.store_credit_apply_service.call(
                   order: @cart,
-                  amount: params[:amount].try(:to_f)
+                  amount: money_param(:amount, @cart.currency)
                 )
 
                 if result.success?
@@ -40,6 +47,17 @@ module Spree
                 end
               end
             end
+
+            private
+
+            # 5.6 storefronts sent a JSON number; read it through its text so no
+            # float reaches the money math.
+            def stringify_numeric_amount
+              return unless params[:amount].is_a?(Numeric)
+
+              Spree::Deprecation.warn('Sending the store credit amount as a JSON number is deprecated and will be refused in Spree 6.1. Send a decimal string such as "25.00".')
+              params[:amount] = params[:amount].to_s
+            end
           end
         end
       end

data/app/controllers/spree/api/v3/store/carts/tax_identifiers_controller.rb

@@ -25,6 +25,10 @@ module Spree
             # frozen onto the order at completion.
             before_action :require_kind_and_value!, only: :update
 
+            request_params('TaxIdentifierParams', action: :update) do |body|
+              body.include_attributes Spree::Api::V3::TaxIdentifierRequestSchema
+            end
+
             # GET /api/v3/store/carts/:cart_id/tax_identifier
             #
             # The registration this cart will be taxed against — the override
@@ -73,7 +77,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(:kind, :value)
+              params.permit(*declared_permitted_attributes)
             end
 
             private

data/app/controllers/spree/api/v3/store/carts_controller.rb

@@ -5,15 +5,64 @@ module Spree
         class CartsController < Store::ResourceController
           include Spree::Api::V3::CartResolvable
           include Spree::Api::V3::OrderLock
-          # The cart accepts a `po_document` signed blob id.
+          # The cart accepts a `po_document_signed_id`.
           include ActiveStorage::SetCurrent
 
-          # A tampered signed id would otherwise surface as a 500.
-          rescue_from ActiveSupport::MessageVerifier::InvalidSignature, with: :render_invalid_po_document
-
           skip_before_action :set_resource
           prepend_before_action :require_authentication!, only: [:index, :associate]
 
+          CART_ADDRESS = Spree::Api::V3::RequestSchema.shape('CartAddressParams') do |schema|
+            schema.attribute :id, :id,
+              description: 'An existing address of the customer to use. The other fields are then ignored.'
+            schema.include_attributes Spree::Api::V3::Store::AddressRequestSchema
+          end
+
+          # Creating and updating a cart accept the same fields.
+          CART_FIELDS = Spree::Api::V3::RequestSchema.new do |schema|
+            schema.attribute :email, :string, format: :email, example: 'customer@example.com'
+            schema.attribute :customer_note, :string, example: 'Leave at door'
+            schema.attribute :market_id, :id
+            schema.attribute :currency, :currency
+            schema.attribute :locale, :locale
+            schema.attribute :shipping_address_id, :id,
+              description: 'An existing address to ship to.',
+              example: 'addr_abc123'
+            schema.attribute :billing_address_id, :id,
+              description: 'An existing address to bill.',
+              example: 'addr_def456'
+            schema.attribute :preferred_stock_location_id, :id
+            schema.attribute :company_id, :id, nullable: true, description: <<~TEXT.squish
+              The company node this purchase is for. The buyer must have standing over it: a membership
+              on that node or one of its ancestors. Null clears it, and with it the company's catalog,
+              pricing and tax anchoring.
+            TEXT
+            schema.attribute :po_number, :string, nullable: true, description: <<~TEXT.squish
+              The buyer's own purchase-order reference. Their accounting reconciles the order, the
+              invoice and the payment against it. Blank clears it.
+            TEXT
+            schema.attribute :po_document_signed_id, :string, nullable: true, description: <<~TEXT.squish
+              The `signed_id` of the buyer's purchase order, from `POST /store/carts/:id/po_document`.
+              Blank detaches the document.
+            TEXT
+            schema.attribute :use_shipping, :boolean,
+              description: 'When true, copies the shipping address to the billing address.'
+            schema.attribute :shipping_address, :object, shape: CART_ADDRESS, description: 'A new shipping address.'
+            schema.attribute :billing_address, :object, shape: CART_ADDRESS, description: 'A new billing address.'
+            schema.attribute :metadata, :hash,
+              description: 'Write-only key-value metadata, merged with what the cart has.'
+            schema.attribute :items, :array,
+              as: 'LineItemInputParams',
+              description: 'Items to upsert: sets the quantity of a variant already in the cart, adds the others.' do |item|
+              item.attribute :variant_id, :id, required: true, example: 'variant_abc123'
+              item.attribute :quantity, :integer, example: 2, description: 'Defaults to 1.'
+              item.attribute :metadata, :hash, description: 'Key-value metadata, merged with what the line item has.'
+              item.attribute :options, :hash
+            end
+          end
+
+          request_params('CreateCartParams', action: :create) { |body| body.include_attributes CART_FIELDS }
+          request_params('UpdateCartParams', action: :update) { |body| body.include_attributes CART_FIELDS }
+
           # GET /api/v3/store/carts/:id
           # Returns cart by prefixed ID
           # Auto-advances the checkout state machine so that shipments and
@@ -184,50 +233,8 @@ module Spree
 
           private
 
-          def render_invalid_po_document
-            render_error(
-              code: ERROR_CODES[:validation_error],
-              message: I18n.t('spree.po_document_invalid_signed_id'),
-              status: :unprocessable_content
-            )
-          end
-
           def permitted_params
-            params.permit(
-              *model_additional_permitted_attributes,
-              :email,
-              :customer_note,
-              :market_id,
-              :currency,
-              :locale,
-              :shipping_address_id,
-              :billing_address_id,
-              :preferred_stock_location_id,
-              :company_id,
-              # The buyer's own purchase-order reference, and the signed blob id
-              # of the document behind it (from POST .../carts/:id/po_document).
-              :po_number,
-              :po_document,
-              :use_shipping,
-              shipping_address: address_params,
-              billing_address: address_params,
-              metadata: {},
-              items: item_params
-            )
-          end
-
-          def address_params
-            [
-              :id, :first_name, :last_name,
-              :address1, :address2,
-              :city, :postal_code, :phone, :company,
-              # country_iso and state_abbr are the legacy write names, accepted until 6.1.
-              :country_code, :country_iso, :state_code, :state_abbr, :state_name, :quick_checkout
-            ]
-          end
-
-          def item_params
-            [:variant_id, :quantity, { metadata: {}, options: {} }]
+            params.permit(*permitted_attributes)
           end
 
           # Find incomplete cart for associate action.

data/app/controllers/spree/api/v3/store/companies/addresses_controller.rb

@@ -9,6 +9,18 @@ module Spree
           class AddressesController < BaseController
             include Spree::Api::V3::CompanyAddressWrites
 
+            request_params :company_address do |body|
+              body.include_attributes Spree::Api::V3::AddressRequestSchema
+              body.require_attributes :first_name, :last_name, :address1, :city, :country_code, on: :create
+              body.attribute :zipcode, :string, deprecated: 'Use `postal_code`. Removed in 6.1.'
+              body.attribute :default_billing, :boolean,
+                permit: false,
+                description: "True makes this the node's default billing address, false gives that up, and leaving it out changes nothing."
+              body.attribute :default_shipping, :boolean,
+                permit: false,
+                description: "True makes this the node's default shipping address, false gives that up, and leaving it out changes nothing."
+            end
+
             # POST /api/v3/store/companies/:company_id/addresses
             def create
               result = Spree.address_create_service.call(
@@ -65,10 +77,6 @@ module Spree
             def scope
               action_name == 'index' ? @parent.address_book : @parent.addresses
             end
-
-            def permitted_params
-              params.permit(:label, *Spree::Api::V3::AddressParams::ADDRESS_KEYS)
-            end
           end
         end
       end

data/app/controllers/spree/api/v3/store/companies/members_controller.rb

@@ -11,6 +11,10 @@ module Spree
           # email has an account. Any member can invite; restraint is
           # Enterprise's policy layer.
           class MembersController < BaseController
+            request_params 'AddCompanyMemberParams', action: :create do |body|
+              body.attribute :customer_email, :string, required: true, example: 'colleague@acme.test'
+            end
+
             # POST /api/v3/store/companies/:company_id/members
             def create
               result = Spree.company_add_member_service.call(

data/app/controllers/spree/api/v3/store/companies_controller.rb

@@ -10,6 +10,10 @@ module Spree
         class CompaniesController < ResourceController
           prepend_before_action :require_authentication!
 
+          request_params 'UpdateCompanyParams', action: :update do |body|
+            body.attribute :name, :string, example: 'Acme Industrial Group'
+          end
+
           # PATCH /api/v3/store/companies/:id
           def update
             authorize_storefront_write!(@resource)
@@ -38,7 +42,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(:name)
+            params.permit(*declared_permitted_attributes)
           end
         end
       end

data/app/controllers/spree/api/v3/store/company_invitations_controller.rb

@@ -17,6 +17,14 @@ module Spree
           # standing scope would 404 the unauthenticated invitee.
           skip_before_action :set_resource
 
+          request_params 'AcceptCompanyInvitationParams', action: :accept do |body|
+            body.attribute :first_name, :string, example: 'Ada'
+            body.attribute :last_name, :string, example: 'Lovelace'
+            body.attribute :phone, :string
+            body.attribute :password, :string, example: 'a-strong-password'
+            body.attribute :password_confirmation, :string, example: 'a-strong-password'
+          end
+
           # GET /api/v3/store/company_invitations/:token — what is being
           # joined. Expired and revoked tokens 404.
           def show
@@ -81,7 +89,7 @@ module Spree
           end
 
           def registration_params
-            params.permit(:first_name, :last_name, :phone, :password, :password_confirmation)
+            params.permit(*declared_permitted_attributes)
           end
         end
       end

data/app/controllers/spree/api/v3/store/customer/addresses_controller.rb

@@ -7,6 +7,13 @@ module Spree
             prepend_before_action :require_authentication!
             before_action :set_resource, only: [:show, :update, :destroy]
 
+            request_params :address do |body|
+              body.include_attributes Spree::Api::V3::Store::AddressRequestSchema
+              body.require_attributes :first_name, :last_name, :address1, :city, :country_code, on: :create
+              body.attribute :is_default_billing, :boolean, description: 'Makes this the default billing address.'
+              body.attribute :is_default_shipping, :boolean, description: 'Makes this the default shipping address.'
+            end
+
             # POST /api/v3/store/customers/me/addresses
             def create
               result = Spree.address_create_service.call(
@@ -58,13 +65,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(
-                *model_additional_permitted_attributes,
-                :first_name, :last_name, :address1, :address2, :city,
-                # country_iso and state_abbr are the legacy write names, accepted until 6.1.
-                :postal_code, :phone, :company, :country_code, :country_iso, :state_code, :state_abbr, :state_name,
-                :is_default_billing, :is_default_shipping
-              )
+              params.permit(*permitted_attributes)
             end
           end
         end

data/app/controllers/spree/api/v3/store/customer/data_requests_controller.rb

@@ -15,6 +15,11 @@ module Spree
 
             prepend_before_action :require_authentication!
 
+            request_params 'CreateDataRequestParams', action: :create do |body|
+              body.attribute :kind, :string, choices: Spree::DataRequest::KINDS, description: 'Defaults to `access`.'
+              body.attribute :current_password, :string, description: 'Required for `erasure`.'
+            end
+
             # POST /api/v3/store/customers/me/data_requests
             def create
               return render_current_password_invalid if erasure? && !valid_current_password?

data/app/controllers/spree/api/v3/store/customer/password_resets_controller.rb

@@ -14,6 +14,23 @@ module Spree
 
             skip_before_action :authenticate_user
 
+            request_params 'RequestPasswordResetParams', action: :create do |body|
+              body.attribute :email, :string,
+                required: true,
+                format: :email,
+                example: 'customer@example.com',
+                description: 'The email of the account to reset.'
+              body.attribute :redirect_url, :string,
+                format: :uri,
+                example: 'https://myshop.com/reset-password',
+                description: "Where the reset link sends the customer. Ignored unless it matches one of the store's allowed origins."
+            end
+
+            request_params 'ResetPasswordParams', action: :update do |body|
+              body.attribute :password, :string, required: true, example: 'newsecurepassword'
+              body.attribute :password_confirmation, :string, required: true, example: 'newsecurepassword'
+            end
+
             # POST /api/v3/store/password_resets
             def create
               redirect_url = params[:redirect_url]

data/app/controllers/spree/api/v3/store/customer/payment_setup_sessions_controller.rb

@@ -9,6 +9,15 @@ module Spree
             skip_before_action :set_resource
             before_action :set_payment_setup_session, only: [:show, :complete]
 
+            request_params 'CreatePaymentSetupSessionParams', action: :create do |body|
+              body.attribute :payment_method_id, :id, required: true, example: 'pm_abc123'
+              body.attribute :external_data, :hash, description: 'Provider-specific data passed to the gateway.'
+            end
+
+            request_params 'CompletePaymentSetupSessionParams', action: :complete do |body|
+              body.attribute :external_data, :hash, description: 'Provider-specific completion data.'
+            end
+
             # POST /api/v3/store/customer/payment_setup_sessions
             def create
               payment_method = current_store.payment_methods.find_by_prefix_id!(params[:payment_method_id])
@@ -58,12 +67,8 @@ module Spree
               Spree.api.payment_setup_session_serializer
             end
 
-            def resource_permitted_attributes
-              [:payment_method_id, { external_data: {} }]
-            end
-
             def complete_params
-              params.permit({ external_data: {} })
+              params.permit(*declared_permitted_attributes)
             end
 
             private

data/app/controllers/spree/api/v3/store/customer/tax_identifiers_controller.rb

@@ -18,6 +18,10 @@ module Spree
             # the buyer never named and could not predict.
             before_action :require_kind!, only: %i[show update destroy]
 
+            request_params('TaxIdentifierParams', action: :update) do |body|
+              body.include_attributes Spree::Api::V3::TaxIdentifierRequestSchema
+            end
+
             # GET /api/v3/store/customers/me/tax_identifiers
             #
             # Everything the buyer could choose between at checkout. Small and
@@ -65,7 +69,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(:kind, :value)
+              params.permit(*declared_permitted_attributes)
             end
 
             private

data/app/controllers/spree/api/v3/store/customers_controller.rb

@@ -11,6 +11,33 @@ module Spree
           skip_before_action :authenticate_user, only: [:create]
           prepend_before_action :require_authentication!, only: [:show, :update]
 
+          CUSTOMER_FIELDS = Spree::Api::V3::RequestSchema.new do |schema|
+            schema.attribute :first_name, :string, example: 'John'
+            schema.attribute :last_name, :string, example: 'Doe'
+            schema.attribute :phone, :string, example: '+1 555 123 4567'
+            schema.attribute :accepts_email_marketing, :boolean
+            schema.attribute :metadata, :hash, description: 'Write-only key-value metadata.'
+          end
+
+          request_params 'RegisterParams', action: :create do |body|
+            body.attribute :email, :string, required: true, format: :email, example: 'newuser@example.com'
+            body.attribute :password, :string, required: true, example: 'password123'
+            body.attribute :password_confirmation, :string, example: 'password123'
+            body.include_attributes CUSTOMER_FIELDS
+            body.attribute :terms_of_service, :boolean,
+              permit: false,
+              description: "Whether the customer ticked the storefront's terms of service box. Recorded as their consent."
+          end
+
+          request_params 'UpdateCustomerParams', action: :update do |body|
+            body.attribute :email, :string, format: :email, example: 'customer@example.com'
+            body.attribute :password, :string
+            body.attribute :password_confirmation, :string
+            body.attribute :current_password, :string,
+              description: 'Required when changing the email or the password.'
+            body.include_attributes CUSTOMER_FIELDS
+          end
+
           # POST /api/v3/store/customers
           # Registration runs through the customer_create_workflow seam
           # (password requirement, newsletter-subscriber linking, registration
@@ -83,8 +110,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(:email, :password, :password_confirmation, :first_name, :last_name,
-                          :accepts_email_marketing, :phone, :current_password, metadata: {})
+            params.permit(*declared_permitted_attributes)
           end
 
           private

data/app/controllers/spree/api/v3/store/newsletter_subscribers_controller.rb

@@ -10,6 +10,28 @@ module Spree
                      only: [:create, :verify, :request_unsubscribe],
                      with: -> { render_rate_limited(limit: Spree::Api::Config[:rate_limit_register]) }
 
+          request_params 'CreateNewsletterSubscriberParams', action: :create do |body|
+            body.attribute :email, :string, required: true, format: :email, example: 'subscriber@example.com'
+            body.attribute :redirect_url, :string,
+              format: :uri,
+              example: 'https://your-store.com/newsletter/confirm',
+              description: "The storefront URL the verification token is appended to. Left out of the webhook payload unless it matches one of the store's allowed origins."
+          end
+
+          request_params 'VerifyNewsletterSubscriberParams', action: :verify do |body|
+            body.attribute :token, :string,
+              required: true,
+              example: 'abc123def456',
+              description: 'The verification token from the confirmation email.'
+          end
+
+          request_params 'RequestNewsletterUnsubscribeParams', action: :request_unsubscribe do |body|
+            body.attribute :email, :string, format: :email, example: 'subscriber@example.com'
+            body.attribute :redirect_url, :string,
+              format: :uri,
+              description: "The storefront URL the unsubscribe token is appended to in the email. Left out of the event payload unless it matches one of the store's allowed origins."
+          end
+
           # POST /api/v3/store/newsletter_subscribers
           def create
             subscriber = Spree::NewsletterSubscriber.subscribe(