Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Give sellers the post-sale surface on their own orders

Damian Legawiecb74469adca3d
diff --git a/spree/api/app/controllers/spree/api/v3/seller/claim_reasons_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/claim_reasons_controller.rb
new file mode 100644
index 0000000000..7f553cee0f
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/seller/claim_reasons_controller.rb
@@ -0,0 +1,39 @@
+module Spree
+ module Api
+ module V3
+ module Seller
+ # What went wrong with a delivery, as the marketplace defines it.
+ #
+ # Read-only: the vocabulary is the operator's, and a seller picks from
+ # it while filing a return. Gated by `orders` rather than `settings` —
+ # a seller reads these to fill in a form on their own order, and
+ # `settings` is closed to the seller audience entirely.
+ #
+ # Store-scoped rather than seller-scoped, because these are the store's
+ # own rows; retired reasons are hidden so a seller cannot file against
+ # vocabulary the operator has withdrawn.
+ class ClaimReasonsController < Seller::ResourceController
+ scoped_resource :orders
+
+ protected
+
+ def model_class
+ Spree::ClaimReason
+ end
+
+ def serializer_class
+ Spree.api.seller_reason_serializer
+ end
+
+ def read_actions
+ %w[index]
+ end
+
+ def scope
+ current_store.claim_reasons.active
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/seller/orders/claims_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/orders/claims_controller.rb
new file mode 100644
index 0000000000..3b5b14e432
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/seller/orders/claims_controller.rb
@@ -0,0 +1,159 @@
+module Spree
+ module Api
+ module V3
+ module Seller
+ module Orders
+ # Something went wrong with a delivery on one of this seller's
+ # orders, and the seller makes it right — money back, a replacement,
+ # or both — without necessarily asking for the goods back.
+ #
+ # Rooted at the order fetched through `current_seller_orders`, with
+ # the claimed lines and any replacement variant resolved through the
+ # order and the seller's own catalogue.
+ class ClaimsController < Seller::ResourceController
+ include Spree::Api::V3::OrderLock
+
+ # Claims are a subject of the `orders` catalog resource.
+ scoped_resource :orders
+
+ before_action :set_order
+ before_action :set_resource, only: [:show, :approve, :resolve, :deny, :cancel]
+
+ # POST /api/v3/seller/orders/:order_id/claims
+ def create
+ authorize!(:create, Spree::Claim)
+
+ result = Spree.claim_create_workflow.call(
+ order: @order,
+ items: items_for_create,
+ reason: reason_for_create,
+ memo: create_params[:memo],
+ created_by: try_spree_current_user
+ )
+
+ if result.success?
+ render json: serialize_resource(result.value), status: :created
+ else
+ render_result_error(result)
+ end
+ end
+
+ # PATCH /api/v3/seller/orders/:order_id/claims/:id/approve
+ def approve
+ run_workflow(Spree.claim_approve_workflow, approver: try_spree_current_user)
+ end
+
+ # PATCH /api/v3/seller/orders/:order_id/claims/:id/resolve
+ #
+ # Settles the claim: a refund, a replacement shipment, or both.
+ def resolve
+ with_order_lock do
+ run_workflow(Spree.claim_resolve_workflow,
+ resolution: params[:resolution],
+ refund_method: params[:refund_method] || 'store_credit',
+ amount: params[:amount],
+ replacement_line_item_ids: replacement_line_item_ids,
+ resolver: try_spree_current_user)
+ end
+ end
+
+ # PATCH /api/v3/seller/orders/:order_id/claims/:id/deny
+ def deny
+ run_workflow(Spree.claim_deny_workflow, reason: params[:reason])
+ end
+
+ # PATCH /api/v3/seller/orders/:order_id/claims/:id/cancel
+ def cancel
+ run_workflow(Spree.claim_cancel_workflow, reason: params[:reason])
+ end
+
+ protected
+
+ def model_class
+ Spree::Claim
+ end
+
+ def serializer_class
+ Spree.api.seller_claim_serializer
+ end
+
+ def parent_association
+ :claims
+ end
+
+ def read_actions
+ %w[index show]
+ end
+
+ def collection_includes
+ [:reason, { claim_line_items: [:variant, :line_item, :replacement_variant] }]
+ end
+
+ private
+
+ def set_order
+ @order = @parent = current_seller_orders.find_by_prefix_id!(params[:order_id])
+ authorize! :show, @order
+ end
+
+ def run_workflow(workflow, **arguments)
+ result = workflow.call(claim: @resource, **arguments)
+
+ if result.success?
+ render json: serialize_resource(result.value)
+ else
+ render_result_error(result)
+ end
+ end
+
+ def create_params
+ @create_params ||= params.permit(
+ :memo, :reason_id,
+ items: [:line_item_id, :quantity, :description, :send_replacement,
+ :replacement_variant_id, :refund_amount]
+ )
+ end
+
+ def items_for_create
+ Array(create_params[:items]).map do |item|
+ {
+ line_item: @order.line_items.find_by_prefix_id!(item[:line_item_id]),
+ quantity: item[:quantity].to_i,
+ description: item[:description],
+ send_replacement: item[:send_replacement].to_b,
+ replacement_variant: replacement_variant_for(item),
+ refund_amount: item[:refund_amount]
+ }
+ end
+ end
+
+ # The seller's own catalogue: a replacement is stock this seller
+ # sends, so a variant belonging to another seller is not theirs to
+ # promise.
+ def replacement_variant_for(item)
+ return nil if item[:replacement_variant_id].blank?
+
+ current_seller.variants.find_by_prefix_id!(item[:replacement_variant_id])
+ end
+
+ # Which lines to replace, decided at resolution time. Absent means
+ # "leave whatever the claim was opened with".
+ def replacement_line_item_ids
+ return nil unless params.key?(:replacement_line_item_ids)
+
+ Array(params[:replacement_line_item_ids]).map do |id|
+ @resource.claim_line_items.find_by_prefix_id!(id).id
+ end
+ end
+
+ def reason_for_create
+ return nil if create_params[:reason_id].blank?
+
+ current_store.claim_reasons.find_by_prefix_id!(create_params[:reason_id])
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/seller/orders/exchanges_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/orders/exchanges_controller.rb
new file mode 100644
index 0000000000..fbf4236aa6
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/seller/orders/exchanges_controller.rb
@@ -0,0 +1,154 @@
+module Spree
+ module Api
+ module V3
+ module Seller
+ module Orders
+ # Swapping goods on one of this seller's orders — a different size,
+ # colour or product.
+ #
+ # Rooted at the order fetched through `current_seller_orders`. The
+ # replacement variant is resolved through `current_seller.variants`
+ # rather than the store's: a seller exchanges into their own
+ # catalogue, and reaching a rival's variant here would put that
+ # seller's stock on this seller's order.
+ class ExchangesController < Seller::ResourceController
+ include Spree::Api::V3::OrderLock
+
+ # Exchanges are a subject of the `orders` catalog resource.
+ scoped_resource :orders
+
+ before_action :set_order
+ before_action :set_resource, only: [:show, :approve, :receive, :fulfill, :cancel]
+
+ # POST /api/v3/seller/orders/:order_id/exchanges
+ def create
+ authorize!(:create, Spree::Exchange)
+
+ result = Spree.exchange_create_workflow.call(
+ order: @order,
+ items: items_for_create,
+ stock_location: stock_location_for_create,
+ reason: reason_for_create,
+ memo: create_params[:memo],
+ created_by: try_spree_current_user
+ )
+
+ if result.success?
+ render json: serialize_resource(result.value), status: :created
+ else
+ render_result_error(result)
+ end
+ end
+
+ # PATCH /api/v3/seller/orders/:order_id/exchanges/:id/approve
+ def approve
+ run_workflow(Spree.exchange_approve_workflow, approver: try_spree_current_user)
+ end
+
+ # PATCH /api/v3/seller/orders/:order_id/exchanges/:id/receive
+ def receive
+ run_workflow(Spree.exchange_receive_workflow,
+ items: items_for_receive,
+ received_by: try_spree_current_user)
+ end
+
+ # PATCH /api/v3/seller/orders/:order_id/exchanges/:id/fulfill
+ #
+ # Sends the replacement. Settles a price difference at the same
+ # time, which is why it takes a refund method.
+ def fulfill
+ with_order_lock do
+ run_workflow(Spree.exchange_fulfill_workflow,
+ refund_method: params[:refund_method] || 'store_credit',
+ refunder: try_spree_current_user)
+ end
+ end
+
+ # PATCH /api/v3/seller/orders/:order_id/exchanges/:id/cancel
+ def cancel
+ run_workflow(Spree.exchange_cancel_workflow, reason: params[:reason])
+ end
+
+ protected
+
+ def model_class
+ Spree::Exchange
+ end
+
+ def serializer_class
+ Spree.api.seller_exchange_serializer
+ end
+
+ def parent_association
+ :exchanges
+ end
+
+ def read_actions
+ %w[index show]
+ end
+
+ def collection_includes
+ [:reason, :stock_location, { exchange_line_items: [:variant, :new_variant, :line_item] }]
+ end
+
+ private
+
+ def set_order
+ @order = @parent = current_seller_orders.find_by_prefix_id!(params[:order_id])
+ authorize! :show, @order
+ end
+
+ def run_workflow(workflow, **arguments)
+ result = workflow.call(exchange: @resource, **arguments)
+
+ if result.success?
+ render json: serialize_resource(result.value)
+ else
+ render_result_error(result)
+ end
+ end
+
+ def create_params
+ @create_params ||= params.permit(:memo, :reason_id, :stock_location_id,
+ items: [:fulfillment_item_id, :new_variant_id, :quantity])
+ end
+
+ def items_for_create
+ Array(create_params[:items]).map do |item|
+ {
+ fulfillment_item: @order.fulfillment_items.find_by_prefix_id!(item[:fulfillment_item_id]),
+ new_variant: current_seller.variants.find_by_prefix_id!(item[:new_variant_id]),
+ quantity: item[:quantity].to_i
+ }
+ end
+ end
+
+ def items_for_receive
+ return nil if params[:items].blank?
+
+ params.permit(items: [:exchange_line_item_id, :quantity, :resellable])[:items].map do |item|
+ {
+ exchange_line_item: @resource.exchange_line_items.find_by_prefix_id!(item[:exchange_line_item_id]),
+ quantity: item[:quantity].to_i,
+ resellable: item.key?(:resellable) ? item[:resellable].to_b : true
+ }
+ end
+ end
+
+ def stock_location_for_create
+ return nil if create_params[:stock_location_id].blank?
+
+ current_seller.stock_locations.find_by_prefix_id!(create_params[:stock_location_id])
+ end
+
+ def reason_for_create
+ return nil if create_params[:reason_id].blank?
+
+ current_store.return_reasons.find_by_prefix_id!(create_params[:reason_id])
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/seller/orders/fulfillments_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/orders/fulfillments_controller.rb
index 14bfd8448b..d6c8d21f75 100644
--- a/spree/api/app/controllers/spree/api/v3/seller/orders/fulfillments_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/seller/orders/fulfillments_controller.rb
@@ -19,7 +19,8 @@ module Spree
scoped_resource :fulfillments
before_action :set_order
- before_action :set_fulfillment, only: [:show, :fulfill]
+ before_action :set_fulfillment,
+ only: [:show, :update, :fulfill, :cancel, :resume, :split, :mark_delivered]
def index
# This action builds its own collection rather than going through
@@ -59,6 +60,74 @@ module Spree
end
end
+ # PATCH /api/v3/seller/orders/:order_id/fulfillments/:id
+ #
+ # The tracking number and its carrier, and nothing else. Where a
+ # parcel ships from and which service carries it are the
+ # marketplace's arrangements, so this deliberately does not accept
+ # the origin and rate the operator's endpoint does.
+ def update
+ if @fulfillment.update(update_params)
+ render json: serialize(@fulfillment.reload)
+ else
+ render_validation_error(@fulfillment.errors)
+ end
+ end
+
+ # PATCH /api/v3/seller/orders/:order_id/fulfillments/:id/cancel
+ #
+ # A parcel this seller is not going to send after all. Restocking
+ # and standing the carrier down happen inside the workflow.
+ def cancel
+ run_workflow(Spree.fulfillment_cancel_workflow)
+ end
+
+ # PATCH /api/v3/seller/orders/:order_id/fulfillments/:id/resume
+ def resume
+ run_workflow(Spree.fulfillment_resume_workflow)
+ end
+
+ # PATCH /api/v3/seller/orders/:order_id/fulfillments/:id/mark_delivered
+ #
+ # Confirms the customer received the goods — the anchor the
+ # returns window runs from, and recordable by hand for a seller
+ # posting parcels without a carrier integration.
+ def mark_delivered
+ with_order_lock do
+ result = Spree.fulfillment_mark_delivered_workflow.call(
+ fulfillment: @fulfillment,
+ delivered_at: params[:delivered_at],
+ notify_customer: notify_customer?(params[:notify_customer])
+ )
+
+ render_workflow_result(result)
+ end
+ end
+
+ # PATCH /api/v3/seller/orders/:order_id/fulfillments/:id/split
+ #
+ # Moves part of what this parcel holds onto one of its own, for
+ # goods leaving separately. The variant is resolved through the
+ # order rather than the catalogue: what may be split is what this
+ # parcel is actually carrying.
+ def split
+ with_order_lock do
+ variant = @order.variants.find_by_prefix_id!(params[:variant_id])
+
+ changer = @fulfillment.transfer_to_location(
+ variant, params[:quantity].to_i, split_stock_location
+ )
+
+ if changer.run!
+ render json: {
+ data: @order.reload.fulfillments.map { |fulfillment| serialize(fulfillment) }
+ }
+ else
+ render_validation_error(changer.errors)
+ end
+ end
+ end
+
protected
def read_actions
@@ -72,9 +141,11 @@ module Spree
authorize! :show, @order
end
+ WRITE_ACTIONS = %w[update fulfill cancel resume split mark_delivered].freeze
+
def set_fulfillment
@fulfillment = @order.fulfillments.find_by_prefix_id!(params[:id])
- authorize! :update, @fulfillment if action_name == 'fulfill'
+ authorize! :update, @fulfillment if WRITE_ACTIONS.include?(action_name)
end
def fulfill_params
@@ -83,6 +154,32 @@ module Spree
)
end
+ def update_params
+ params.permit(:tracking, :tracking_carrier)
+ end
+
+ # Where the split half ships from. The seller's own shelves only —
+ # defaulting to where this parcel already sits.
+ def split_stock_location
+ return @fulfillment.stock_location if params[:stock_location_id].blank?
+
+ current_seller.stock_locations.find_by_prefix_id!(params[:stock_location_id])
+ end
+
+ def run_workflow(workflow)
+ with_order_lock do
+ render_workflow_result(workflow.call(fulfillment: @fulfillment))
+ end
+ end
+
+ def render_workflow_result(result)
+ if result.success?
+ render json: serialize(result.value)
+ else
+ render_service_error(@fulfillment.errors.presence || result.error)
+ end
+ end
+
# The workflow addresses what to ship by line item, and the lookup
# runs through the order so an id from elsewhere cannot be shipped.
def items_for_fulfill
diff --git a/spree/api/app/controllers/spree/api/v3/seller/orders/returns_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/orders/returns_controller.rb
new file mode 100644
index 0000000000..961dfae7b4
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/seller/orders/returns_controller.rb
@@ -0,0 +1,168 @@
+module Spree
+ module Api
+ module V3
+ module Seller
+ module Orders
+ # Goods coming back on one of this seller's orders.
+ #
+ # Rooted at the order fetched through `current_seller_orders`, so a
+ # return on somebody else's order reads as missing rather than
+ # denied, and every id the payload names — the units returned, the
+ # shelf they go back to, the reason — is resolved through the
+ # seller's own records.
+ #
+ # Every status move reuses the operator's workflow, so restocking,
+ # the tax credit, the refund and the ledger reversal all happen
+ # exactly as they do when the marketplace handles the return itself.
+ class ReturnsController < Seller::ResourceController
+ include Spree::Api::V3::OrderLock
+
+ # Returns are a subject of the `orders` catalog resource, so
+ # `read_orders`/`write_orders` gate these endpoints. Naming
+ # `:returns` here would name a key no catalog knows.
+ scoped_resource :orders
+
+ before_action :set_order
+ before_action :set_resource, only: [:show, :approve, :receive, :refund, :cancel]
+
+ # POST /api/v3/seller/orders/:order_id/returns
+ def create
+ authorize!(:create, Spree::Return)
+
+ result = Spree.return_create_workflow.call(
+ order: @order,
+ items: items_for_create,
+ stock_location: stock_location_for_create,
+ reason: reason_for_create,
+ memo: create_params[:memo],
+ created_by: try_spree_current_user
+ )
+
+ if result.success?
+ render json: serialize_resource(result.value), status: :created
+ else
+ render_result_error(result)
+ end
+ end
+
+ # PATCH /api/v3/seller/orders/:order_id/returns/:id/approve
+ def approve
+ run_workflow(Spree.return_approve_workflow, approver: try_spree_current_user)
+ end
+
+ # PATCH /api/v3/seller/orders/:order_id/returns/:id/receive
+ #
+ # `items` carries what actually arrived; omitting it receives
+ # everything as requested and resellable.
+ def receive
+ run_workflow(Spree.return_receive_workflow,
+ items: items_for_receive,
+ received_by: try_spree_current_user)
+ end
+
+ # PATCH /api/v3/seller/orders/:order_id/returns/:id/refund
+ #
+ # The seller took the money for their own child order, so giving it
+ # back is theirs. What can be given back is bounded by the return
+ # itself and, on a split checkout, by this order's share of the
+ # group's payment — never a sibling's.
+ def refund
+ with_order_lock do
+ run_workflow(Spree.return_refund_workflow,
+ amount: params[:amount],
+ refund_method: params[:refund_method] || 'original_payment',
+ refunder: try_spree_current_user)
+ end
+ end
+
+ # PATCH /api/v3/seller/orders/:order_id/returns/:id/cancel
+ def cancel
+ run_workflow(Spree.return_cancel_workflow, reason: params[:reason])
+ end
+
+ protected
+
+ def model_class
+ Spree::Return
+ end
+
+ def serializer_class
+ Spree.api.seller_return_serializer
+ end
+
+ def parent_association
+ :returns
+ end
+
+ def read_actions
+ %w[index show]
+ end
+
+ def collection_includes
+ [:reason, :stock_location, { return_line_items: [:variant, :line_item] }]
+ end
+
+ private
+
+ def set_order
+ @order = @parent = current_seller_orders.find_by_prefix_id!(params[:order_id])
+ authorize! :show, @order
+ end
+
+ def run_workflow(workflow, **arguments)
+ result = workflow.call(return_record: @resource, **arguments)
+
+ if result.success?
+ render json: serialize_resource(result.value)
+ else
+ render_result_error(result)
+ end
+ end
+
+ def create_params
+ @create_params ||= params.permit(:memo, :reason_id, :stock_location_id,
+ items: [:fulfillment_item_id, :quantity])
+ end
+
+ # Addressed by fulfillment item and resolved through the order, so
+ # units belonging to another seller's order cannot be returned here.
+ def items_for_create
+ Array(create_params[:items]).map do |item|
+ {
+ fulfillment_item: @order.fulfillment_items.find_by_prefix_id!(item[:fulfillment_item_id]),
+ quantity: item[:quantity].to_i
+ }
+ end
+ end
+
+ def items_for_receive
+ return nil if params[:items].blank?
+
+ params.permit(items: [:return_line_item_id, :quantity, :resellable])[:items].map do |item|
+ {
+ return_line_item: @resource.return_line_items.find_by_prefix_id!(item[:return_line_item_id]),
+ quantity: item[:quantity].to_i,
+ resellable: item.key?(:resellable) ? item[:resellable].to_b : true
+ }
+ end
+ end
+
+ # The seller's own shelves only — goods coming back to a
+ # marketplace warehouse is not this endpoint's business.
+ def stock_location_for_create
+ return nil if create_params[:stock_location_id].blank?
+
+ current_seller.stock_locations.find_by_prefix_id!(create_params[:stock_location_id])
+ end
+
+ def reason_for_create
+ return nil if create_params[:reason_id].blank?
+
+ current_store.return_reasons.find_by_prefix_id!(create_params[:reason_id])
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/seller/return_reasons_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/return_reasons_controller.rb
new file mode 100644
index 0000000000..ba7d228f49
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/seller/return_reasons_controller.rb
@@ -0,0 +1,39 @@
+module Spree
+ module Api
+ module V3
+ module Seller
+ # Why goods come back, as the marketplace defines it.
+ #
+ # Read-only: the vocabulary is the operator's, and a seller picks from
+ # it while filing a return. Gated by `orders` rather than `settings` —
+ # a seller reads these to fill in a form on their own order, and
+ # `settings` is closed to the seller audience entirely.
+ #
+ # Store-scoped rather than seller-scoped, because these are the store's
+ # own rows; retired reasons are hidden so a seller cannot file against
+ # vocabulary the operator has withdrawn.
+ class ReturnReasonsController < Seller::ResourceController
+ scoped_resource :orders
+
+ protected
+
+ def model_class
+ Spree::ReturnReason
+ end
+
+ def serializer_class
+ Spree.api.seller_reason_serializer
+ end
+
+ def read_actions
+ %w[index]
+ end
+
+ def scope
+ current_store.return_reasons.active
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/seller/tracking_carriers_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/tracking_carriers_controller.rb
new file mode 100644
index 0000000000..8dbf2f7734
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/seller/tracking_carriers_controller.rb
@@ -0,0 +1,35 @@
+module Spree
+ module Api
+ module V3
+ module Seller
+ # The registered carriers a tracking number can be pinned to.
+ #
+ # Registry data (`Spree.tracking_carriers`) rather than store records,
+ # so the seller's carrier picker renders from the same list the
+ # operator's does and a carrier added by an extension appears without
+ # a client change. Gated by `fulfillments`: a seller reads these while
+ # marking a parcel sent.
+ class TrackingCarriersController < Seller::BaseController
+ scoped_resource :fulfillments
+
+ # GET /api/v3/seller/tracking_carriers
+ def index
+ authorize! :update, Spree::Fulfillment
+
+ data = Spree.tracking_carriers.map do |slug, carrier|
+ { id: slug, name: carrier[:name] }
+ end
+
+ render json: { data: data.sort_by { |carrier| carrier[:name] } }
+ end
+
+ protected
+
+ def read_actions
+ %w[index]
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/seller/claim_line_item_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/claim_line_item_serializer.rb
new file mode 100644
index 0000000000..45a22e4513
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/seller/claim_line_item_serializer.rb
@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Spree
+ module Api
+ module V3
+ module Seller
+ # One line of a claim — what went wrong, and what is being sent or
+ # refunded to put it right.
+ class ClaimLineItemSerializer < V3::ClaimLineItemSerializer
+ one :variant, resource: proc { Spree.api.seller_variant_serializer }, if: proc { expand?('variant') }
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/seller/claim_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/claim_serializer.rb
new file mode 100644
index 0000000000..c0ba2dfb50
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/seller/claim_serializer.rb
@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Spree
+ module Api
+ module V3
+ module Seller
+ # A claim on one of this seller's orders.
+ #
+ # Built on the shared V3 serializer rather than the admin one, which
+ # expands the order and the customer behind it.
+ class ClaimSerializer < V3::ClaimSerializer
+ typelize memo: [:string, nullable: true],
+ resolution: [:string, nullable: true]
+
+ attributes :memo, :resolution
+
+ many :claim_line_items,
+ resource: proc { Spree.api.seller_claim_line_item_serializer },
+ if: proc { expand?('claim_line_items') }
+
+ one :reason, resource: proc { Spree.api.seller_reason_serializer }, if: proc { expand?('reason') }
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/seller/exchange_line_item_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/exchange_line_item_serializer.rb
new file mode 100644
index 0000000000..2e1ecbbb60
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/seller/exchange_line_item_serializer.rb
@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Spree
+ module Api
+ module V3
+ module Seller
+ # One line of an exchange — what came back and what goes out in its
+ # place. Both variants expand through the seller's own serializer.
+ class ExchangeLineItemSerializer < V3::ExchangeLineItemSerializer
+ one :original_variant, resource: proc { Spree.api.seller_variant_serializer },
+ if: proc { expand?('original_variant') }
+ one :new_variant, resource: proc { Spree.api.seller_variant_serializer },
+ if: proc { expand?('new_variant') }
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/seller/exchange_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/exchange_serializer.rb
new file mode 100644
index 0000000000..e2adeb8d4a
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/seller/exchange_serializer.rb
@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Spree
+ module Api
+ module V3
+ module Seller
+ # An exchange on one of this seller's orders.
+ #
+ # Built on the shared V3 serializer rather than the admin one, which
+ # expands the order and the customer behind it.
+ class ExchangeSerializer < V3::ExchangeSerializer
+ typelize memo: [:string, nullable: true],
+ stock_location_id: [:string, nullable: true]
+
+ attributes :memo
+
+ attribute :stock_location_id do |exchange|
+ exchange.stock_location&.prefixed_id
+ end
+
+ many :exchange_line_items,
+ resource: proc { Spree.api.seller_exchange_line_item_serializer },
+ if: proc { expand?('exchange_line_items') }
+
+ one :reason, resource: proc { Spree.api.seller_reason_serializer }, if: proc { expand?('reason') }
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/seller/reason_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/reason_serializer.rb
new file mode 100644
index 0000000000..8c06e2dda7
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/seller/reason_serializer.rb
@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Spree
+ module Api
+ module V3
+ module Seller
+ # One entry of a marketplace-owned vocabulary — why goods came back,
+ # or what went wrong with a delivery.
+ #
+ # One serializer for both: a reason is a name and whether it is still
+ # offered, and Spree::ReturnReason and Spree::ClaimReason answer that
+ # identically. Read-only on this branch, so nothing here is writable.
+ class ReasonSerializer < V3::BaseSerializer
+ typelize name: :string, active: :boolean
+
+ attributes :name, :active
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/seller/return_line_item_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/return_line_item_serializer.rb
new file mode 100644
index 0000000000..5c88765268
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/seller/return_line_item_serializer.rb
@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Spree
+ module Api
+ module V3
+ module Seller
+ # One line of a return. The variant expands through the seller's own
+ # variant serializer, so nothing operator-only rides along with it.
+ class ReturnLineItemSerializer < V3::ReturnLineItemSerializer
+ one :variant, resource: proc { Spree.api.seller_variant_serializer }, if: proc { expand?('variant') }
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/seller/return_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/return_serializer.rb
new file mode 100644
index 0000000000..94bc861d11
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/seller/return_serializer.rb
@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Spree
+ module Api
+ module V3
+ module Seller
+ # A return on one of this seller's orders.
+ #
+ # Built on the shared V3 serializer rather than the admin one, which
+ # expands the order and the customer behind it — a seller reads their
+ # own order's goods coming back, never the buyer's record.
+ #
+ # What it adds over the shared one is the pair of figures a seller
+ # needs to settle: what has already gone back, and what may still.
+ class ReturnSerializer < V3::ReturnSerializer
+ typelize memo: [:string, nullable: true],
+ stock_location_id: [:string, nullable: true],
+ refunded_total: :string,
+ refundable_total: :string,
+ display_refunded_total: :string
+
+ attributes :memo
+
+ attribute :stock_location_id do |return_record|
+ return_record.stock_location&.prefixed_id
+ end
+
+ attribute :refunded_total do |return_record|
+ return_record.refunded_total.to_s
+ end
+
+ # What the refund dialog opens on — never more than this may be
+ # given back, whatever amount is typed.
+ attribute :refundable_total do |return_record|
+ return_record.refundable_total.to_s
+ end
+
+ attribute :display_refunded_total do |return_record|
+ return_record.display_refunded_total.to_s
+ end
+
+ many :return_line_items,
+ resource: proc { Spree.api.seller_return_line_item_serializer },
+ if: proc { expand?('return_line_items') }
+
+ one :reason, resource: proc { Spree.api.seller_reason_serializer }, if: proc { expand?('reason') }
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rb
index 5ee278bf75..b91b2ca8b8 100644
--- a/spree/api/config/routes.rb
+++ b/spree/api/config/routes.rb
@@ -863,9 +863,46 @@ Spree::Core::Engine.add_routes do
patch :cancel
end
- resources :fulfillments, only: [:index, :show], controller: 'orders/fulfillments' do
+ resources :fulfillments, only: [:index, :show, :update], controller: 'orders/fulfillments' do
member do
patch :fulfill
+ patch :cancel
+ patch :resume
+ patch :split
+ patch :mark_delivered
+ end
+ end
+
+ # Putting a sale right. The seller is merchant of record for their
+ # own child order, so taking the goods back and giving the money
+ # back are theirs (docs/plans/6.0-seller-order-management.md).
+ # Every status move is its own action, because each carries
+ # arguments of its own — receiving records what actually arrived,
+ # refunding names a method and an amount.
+ resources :returns, only: [:index, :show, :create], controller: 'orders/returns' do
+ member do
+ patch :approve
+ patch :receive
+ patch :refund
+ patch :cancel
+ end
+ end
+
+ resources :exchanges, only: [:index, :show, :create], controller: 'orders/exchanges' do
+ member do
+ patch :approve
+ patch :receive
+ patch :fulfill
+ patch :cancel
+ end
+ end
+
+ resources :claims, only: [:index, :show, :create], controller: 'orders/claims' do
+ member do
+ patch :approve
+ patch :resolve
+ patch :deny
+ patch :cancel
end
resources :deliveries, controller: 'orders/deliveries', only: [:index, :show, :create, :update, :destroy]
@@ -877,6 +914,14 @@ Spree::Core::Engine.add_routes do
end
end
+ # The marketplace's own vocabularies. Read-only: a seller picks a
+ # reason, the operator decides what the reasons are.
+ resources :return_reasons, only: [:index]
+ resources :claim_reasons, only: [:index]
+
+ # Registry data — which carriers a tracking number can be pinned to.
+ resources :tracking_carriers, only: [:index]
+
resources :direct_uploads, only: [:create]
# CSV of what this seller sold, or of their catalogue. Created, polled
diff --git a/spree/api/lib/spree/api/dependencies.rb b/spree/api/lib/spree/api/dependencies.rb
index e608137638..46786f8770 100644
--- a/spree/api/lib/spree/api/dependencies.rb
+++ b/spree/api/lib/spree/api/dependencies.rb
@@ -190,6 +190,13 @@ module Spree
seller_fulfillment_item_serializer: 'Spree::Api::V3::Seller::FulfillmentItemSerializer',
seller_delivery_serializer: 'Spree::Api::V3::Seller::DeliverySerializer',
seller_shipping_label_serializer: 'Spree::Api::V3::Seller::ShippingLabelSerializer',
+ seller_return_serializer: 'Spree::Api::V3::Seller::ReturnSerializer',
+ seller_return_line_item_serializer: 'Spree::Api::V3::Seller::ReturnLineItemSerializer',
+ seller_exchange_serializer: 'Spree::Api::V3::Seller::ExchangeSerializer',
+ seller_exchange_line_item_serializer: 'Spree::Api::V3::Seller::ExchangeLineItemSerializer',
+ seller_claim_serializer: 'Spree::Api::V3::Seller::ClaimSerializer',
+ seller_claim_line_item_serializer: 'Spree::Api::V3::Seller::ClaimLineItemSerializer',
+ seller_reason_serializer: 'Spree::Api::V3::Seller::ReasonSerializer',
seller_stock_location_serializer: 'Spree::Api::V3::Seller::StockLocationSerializer',
seller_requirement_custom_field_serializer: 'Spree::Api::V3::Seller::RequirementCustomFieldSerializer',
seller_tax_identifier_serializer: 'Spree::Api::V3::Seller::TaxIdentifierSerializer',
diff --git a/spree/api/spec/controllers/spree/api/v3/seller/orders/claims_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/seller/orders/claims_controller_spec.rb
new file mode 100644
index 0000000000..c6035ea1ca
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/seller/orders/claims_controller_spec.rb
@@ -0,0 +1,107 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Seller::Orders::ClaimsController, type: :controller do
+ render_views
+
+ include_context 'API v3 Seller'
+
+ let(:seller_user) do
+ create(:admin_user, :without_admin_role).tap { |user| seller.add_user(user) }
+ end
+ let(:token) do
+ Spree::Api::V3::TestingSupport.generate_jwt(
+ seller_user, audience: Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_SELLER
+ )
+ end
+
+ let!(:order) { create(:shipped_order, store: store, seller: seller, line_items_count: 1) }
+ let(:line_item) { order.line_items.first }
+ let(:other_seller) { create(:seller, :approved, store: store) }
+
+ before do
+ request.headers['Authorization'] = "Bearer #{token}"
+ request.headers['X-Spree-Seller-Id'] = seller.prefixed_id
+ end
+
+ def open_claim
+ Spree::Claims::Create.call(
+ order: order, items: [{ line_item: line_item, quantity: 1 }]
+ ).value
+ end
+
+ describe 'POST #create' do
+ it 'opens a claim on the seller’s own order' do
+ post :create, params: {
+ order_id: order.prefixed_id,
+ items: [{ line_item_id: line_item.prefixed_id, quantity: 1, description: 'Arrived broken' }]
+ }, as: :json
+
+ expect(response).to have_http_status(:created)
+ expect(order.claims.count).to eq(1)
+ end
+
+ it 'refuses a replacement variant belonging to another seller' do
+ theirs = create(:variant, seller: other_seller)
+
+ post :create, params: {
+ order_id: order.prefixed_id,
+ items: [{
+ line_item_id: line_item.prefixed_id, quantity: 1,
+ send_replacement: true, replacement_variant_id: theirs.prefixed_id
+ }]
+ }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ expect(order.claims).to be_empty
+ end
+
+ it 'cannot open a claim on another seller’s order' do
+ their_order = create(:shipped_order, store: store, seller: other_seller, line_items_count: 1)
+
+ post :create, params: {
+ order_id: their_order.prefixed_id,
+ items: [{ line_item_id: their_order.line_items.first.prefixed_id, quantity: 1 }]
+ }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ end
+ end
+
+ describe 'status moves' do
+ let(:claim) { open_claim }
+
+ it 'approves' do
+ patch :approve, params: { order_id: order.prefixed_id, id: claim.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(claim.reload).to be_approved
+ end
+
+ it 'denies' do
+ patch :deny, params: { order_id: order.prefixed_id, id: claim.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(claim.reload).to be_denied
+ end
+
+ it 'cancels' do
+ patch :cancel, params: { order_id: order.prefixed_id, id: claim.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(claim.reload).to be_canceled
+ end
+
+ it 'resolves with a refund' do
+ Spree::Claims::Approve.call(claim: claim)
+ allow_any_instance_of(Spree::Refund).to receive(:perform!).and_return(true)
+
+ patch :resolve, params: {
+ order_id: order.prefixed_id, id: claim.prefixed_id,
+ resolution: 'refund', refund_method: 'store_credit', amount: 5
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(claim.reload).to be_resolved
+ end
+ end
+end
diff --git a/spree/api/spec/controllers/spree/api/v3/seller/orders/exchanges_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/seller/orders/exchanges_controller_spec.rb
new file mode 100644
index 0000000000..89b0fd1500
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/seller/orders/exchanges_controller_spec.rb
@@ -0,0 +1,109 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Seller::Orders::ExchangesController, type: :controller do
+ render_views
+
+ include_context 'API v3 Seller'
+
+ let(:seller_user) do
+ create(:admin_user, :without_admin_role).tap { |user| seller.add_user(user) }
+ end
+ let(:token) do
+ Spree::Api::V3::TestingSupport.generate_jwt(
+ seller_user, audience: Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_SELLER
+ )
+ end
+
+ let!(:order) { create(:shipped_order, store: store, seller: seller, line_items_count: 1) }
+ let(:fulfillment_item) { order.fulfillment_items.first }
+
+ let(:other_seller) { create(:seller, :approved, store: store) }
+ let(:replacement) { create(:variant, seller: seller) }
+
+ before do
+ request.headers['Authorization'] = "Bearer #{token}"
+ request.headers['X-Spree-Seller-Id'] = seller.prefixed_id
+ end
+
+ def create_params(variant: replacement, order_record: order)
+ {
+ order_id: order_record.prefixed_id,
+ items: [{
+ fulfillment_item_id: order_record.fulfillment_items.first.prefixed_id,
+ new_variant_id: variant.prefixed_id,
+ quantity: 1
+ }]
+ }
+ end
+
+ describe 'POST #create' do
+ it 'opens an exchange into the seller’s own catalogue' do
+ post :create, params: create_params, as: :json
+
+ expect(response).to have_http_status(:created)
+ expect(order.exchanges.count).to eq(1)
+ end
+
+ # The replacement is stock this seller sends, so a rival's variant is not
+ # theirs to promise — and reaching one here would put another seller's
+ # goods on this order.
+ it 'refuses a replacement variant belonging to another seller' do
+ theirs = create(:variant, seller: other_seller)
+
+ post :create, params: create_params(variant: theirs), as: :json
+
+ expect(response).to have_http_status(:not_found)
+ expect(order.exchanges).to be_empty
+ end
+
+ it 'cannot open an exchange on another seller’s order' do
+ their_order = create(:shipped_order, store: store, seller: other_seller, line_items_count: 1)
+
+ post :create, params: create_params(order_record: their_order), as: :json
+
+ expect(response).to have_http_status(:not_found)
+ end
+ end
+
+ describe 'status moves' do
+ let(:exchange) do
+ Spree::Exchanges::Create.call(
+ order: order,
+ items: [{ fulfillment_item: fulfillment_item, new_variant: replacement, quantity: 1 }]
+ ).value
+ end
+
+ it 'approves' do
+ patch :approve, params: { order_id: order.prefixed_id, id: exchange.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(exchange.reload).to be_approved
+ end
+
+ it 'receives' do
+ Spree::Exchanges::Approve.call(exchange: exchange)
+
+ patch :receive, params: { order_id: order.prefixed_id, id: exchange.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(exchange.reload).to be_received
+ end
+
+ it 'fulfills, sending the replacement' do
+ Spree::Exchanges::Approve.call(exchange: exchange)
+ Spree::Exchanges::Receive.call(exchange: exchange)
+
+ patch :fulfill, params: { order_id: order.prefixed_id, id: exchange.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(exchange.reload).to be_fulfilled
+ end
+
+ it 'cancels' do
+ patch :cancel, params: { order_id: order.prefixed_id, id: exchange.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(exchange.reload).to be_canceled
+ end
+ end
+end
diff --git a/spree/api/spec/controllers/spree/api/v3/seller/orders/fulfillments_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/seller/orders/fulfillments_controller_spec.rb
index 26d9596a38..0ed61e441d 100644
--- a/spree/api/spec/controllers/spree/api/v3/seller/orders/fulfillments_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/seller/orders/fulfillments_controller_spec.rb
@@ -95,4 +95,111 @@ RSpec.describe Spree::Api::V3::Seller::Orders::FulfillmentsController, type: :co
expect(theirs.reload).not_to be_fulfilled
end
end
+
+ describe 'PATCH #update' do
+ it 'records a tracking number and its carrier' do
+ patch :update, params: {
+ order_id: order.prefixed_id, id: fulfillment.prefixed_id,
+ tracking: 'TRACK123', tracking_carrier: 'ups'
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(fulfillment.reload.tracking).to eq('TRACK123')
+ expect(fulfillment.tracking_carrier).to eq('ups')
+ end
+
+ # Where a parcel ships from and which service carries it are the
+ # marketplace's arrangements — this endpoint takes the tracking pair only.
+ it 'ignores an attempt to move the parcel to another origin' do
+ elsewhere = create(:stock_location, store: store, seller: seller)
+ original = fulfillment.stock_location_id
+
+ patch :update, params: {
+ order_id: order.prefixed_id, id: fulfillment.prefixed_id,
+ tracking: 'TRACK123', stock_location_id: elsewhere.prefixed_id
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(fulfillment.reload.stock_location_id).to eq(original)
+ end
+ end
+
+ describe 'PATCH #cancel and #resume' do
+ it 'cancels a parcel the seller will not send' do
+ patch :cancel, params: { order_id: order.prefixed_id, id: fulfillment.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(fulfillment.reload).to be_canceled
+ end
+
+ it 'resumes a canceled parcel' do
+ Spree::Fulfillments::Cancel.call(fulfillment: fulfillment)
+
+ patch :resume, params: { order_id: order.prefixed_id, id: fulfillment.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(fulfillment.reload).not_to be_canceled
+ end
+
+ it "404s cancelling through another seller's order" do
+ other = create(:order_ready_to_ship, store: store, seller: create(:seller, :approved, store: store))
+
+ patch :cancel, params: { order_id: other.prefixed_id, id: other.fulfillments.first.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ expect(other.fulfillments.first.reload).not_to be_canceled
+ end
+ end
+
+ describe 'PATCH #mark_delivered' do
+ it 'confirms the customer received the goods' do
+ Spree.fulfillment_fulfill_workflow.call(fulfillment: fulfillment)
+
+ patch :mark_delivered, params: { order_id: order.prefixed_id, id: fulfillment.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(fulfillment.reload).to be_delivered
+ end
+ end
+
+ describe 'PATCH #split' do
+ let!(:order) { create(:order_ready_to_ship, store: store, seller: seller, line_items_count: 2) }
+
+ it 'moves part of the parcel onto one of its own' do
+ variant = fulfillment.fulfillment_items.first.variant
+
+ expect {
+ patch :split, params: {
+ order_id: order.prefixed_id, id: fulfillment.prefixed_id,
+ variant_id: variant.prefixed_id, quantity: 1
+ }, as: :json
+ }.to change { order.fulfillments.count }.by(1)
+
+ expect(response).to have_http_status(:ok)
+ end
+
+ # What may be split is what this parcel is carrying, so a variant from
+ # elsewhere in the catalogue is not addressable here.
+ it '404s on a variant the order does not carry' do
+ patch :split, params: {
+ order_id: order.prefixed_id, id: fulfillment.prefixed_id,
+ variant_id: create(:variant, seller: seller).prefixed_id, quantity: 1
+ }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ end
+
+ it 'refuses a destination belonging to another seller' do
+ variant = fulfillment.fulfillment_items.first.variant
+ theirs = create(:stock_location, store: store, seller: create(:seller, :approved, store: store))
+
+ patch :split, params: {
+ order_id: order.prefixed_id, id: fulfillment.prefixed_id,
+ variant_id: variant.prefixed_id, quantity: 1,
+ stock_location_id: theirs.prefixed_id
+ }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ end
+ end
end
diff --git a/spree/api/spec/controllers/spree/api/v3/seller/orders/returns_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/seller/orders/returns_controller_spec.rb
new file mode 100644
index 0000000000..3c2a85a700
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/seller/orders/returns_controller_spec.rb
@@ -0,0 +1,172 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Seller::Orders::ReturnsController, type: :controller do
+ render_views
+
+ include_context 'API v3 Seller'
+
+ let(:seller_user) do
+ create(:admin_user, :without_admin_role).tap { |user| seller.add_user(user) }
+ end
+ let(:token) do
+ Spree::Api::V3::TestingSupport.generate_jwt(
+ seller_user, audience: Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_SELLER
+ )
+ end
+
+ let!(:order) { create(:shipped_order, store: store, seller: seller, line_items_count: 1) }
+ let(:fulfillment_item) { order.fulfillment_items.first }
+
+ let(:other_seller) { create(:seller, :approved, store: store) }
+ let!(:their_order) { create(:shipped_order, store: store, seller: other_seller, line_items_count: 1) }
+
+ before do
+ request.headers['Authorization'] = "Bearer #{token}"
+ request.headers['X-Spree-Seller-Id'] = seller.prefixed_id
+ end
+
+ def open_return(on: order)
+ Spree::Returns::Create.call(
+ order: on,
+ items: [{ fulfillment_item: on.fulfillment_items.first, quantity: 1 }]
+ ).value
+ end
+
+ describe 'POST #create' do
+ it 'opens a return on the seller’s own order' do
+ post :create, params: {
+ order_id: order.prefixed_id,
+ items: [{ fulfillment_item_id: fulfillment_item.prefixed_id, quantity: 1 }]
+ }, as: :json
+
+ expect(response).to have_http_status(:created)
+ expect(order.returns.count).to eq(1)
+ end
+
+ it 'records the seller user who filed it' do
+ post :create, params: {
+ order_id: order.prefixed_id,
+ items: [{ fulfillment_item_id: fulfillment_item.prefixed_id, quantity: 1 }]
+ }, as: :json
+
+ expect(order.returns.last.created_by).to eq(seller_user)
+ end
+
+ # Tenancy is the fetch: another seller's order is not found here, so it
+ # reads as missing rather than denied.
+ it 'cannot open a return on another seller’s order' do
+ post :create, params: {
+ order_id: their_order.prefixed_id,
+ items: [{ fulfillment_item_id: their_order.fulfillment_items.first.prefixed_id, quantity: 1 }]
+ }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ expect(their_order.returns).to be_empty
+ end
+
+ it 'refuses a stock location belonging to another seller' do
+ their_location = create(:stock_location, store: store, seller: other_seller)
+
+ post :create, params: {
+ order_id: order.prefixed_id,
+ stock_location_id: their_location.prefixed_id,
+ items: [{ fulfillment_item_id: fulfillment_item.prefixed_id, quantity: 1 }]
+ }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ end
+ end
+
+ describe 'GET #index' do
+ it 'lists returns on the order' do
+ open_return
+
+ get :index, params: { order_id: order.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['data'].size).to eq(1)
+ end
+
+ it 'cannot read returns on another seller’s order' do
+ open_return(on: their_order)
+
+ get :index, params: { order_id: their_order.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ end
+ end
+
+ describe 'status moves' do
+ let(:return_record) { open_return }
+
+ it 'approves' do
+ patch :approve, params: { order_id: order.prefixed_id, id: return_record.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(return_record.reload).to be_approved
+ end
+
+ it 'receives' do
+ Spree::Returns::Approve.call(return_record: return_record)
+
+ patch :receive, params: { order_id: order.prefixed_id, id: return_record.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(return_record.reload).to be_received
+ end
+
+ it 'cancels' do
+ patch :cancel, params: { order_id: order.prefixed_id, id: return_record.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(return_record.reload).to be_canceled
+ end
+
+ # The money half. A seller is merchant of record for their own child
+ # order, so refunding it is theirs — see the seller order management plan.
+ describe 'refunding' do
+ before do
+ Spree::Returns::Approve.call(return_record: return_record)
+ Spree::Returns::Receive.call(return_record: return_record)
+ allow_any_instance_of(Spree::Refund).to receive(:perform!).and_return(true)
+ end
+
+ it 'refunds to store credit' do
+ patch :refund, params: {
+ order_id: order.prefixed_id, id: return_record.prefixed_id,
+ refund_method: 'store_credit'
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(return_record.reload).to be_refunded
+ end
+
+ it 'refuses more than the return is owed' do
+ patch :refund, params: {
+ order_id: order.prefixed_id, id: return_record.prefixed_id,
+ refund_method: 'store_credit', amount: 10_000
+ }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_entity)
+ expect(return_record.reload).not_to be_refunded
+ end
+ end
+ end
+
+ describe 'authorization' do
+ # A seller whose role carries only the read key may look but not file.
+ it 'refuses to open a return without the write key' do
+ allow(controller).to receive(:current_ability).
+ and_return(Spree::Ability.new(seller_user, resource: seller).tap do |ability|
+ ability.cannot :create, Spree::Return
+ end)
+
+ post :create, params: {
+ order_id: order.prefixed_id,
+ items: [{ fulfillment_item_id: fulfillment_item.prefixed_id, quantity: 1 }]
+ }, as: :json
+
+ expect(response).to have_http_status(:forbidden)
+ end
+ end
+end
diff --git a/spree/api/spec/controllers/spree/api/v3/seller/return_reasons_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/seller/return_reasons_controller_spec.rb
new file mode 100644
index 0000000000..94068394ca
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/seller/return_reasons_controller_spec.rb
@@ -0,0 +1,51 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Seller::ReturnReasonsController, type: :controller do
+ render_views
+
+ include_context 'API v3 Seller'
+
+ let(:seller_user) do
+ create(:admin_user, :without_admin_role).tap { |user| seller.add_user(user) }
+ end
+ let(:token) do
+ Spree::Api::V3::TestingSupport.generate_jwt(
+ seller_user, audience: Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_SELLER
+ )
+ end
+
+ before do
+ request.headers['Authorization'] = "Bearer #{token}"
+ request.headers['X-Spree-Seller-Id'] = seller.prefixed_id
+ end
+
+ describe 'GET #index' do
+ let!(:reason) { create(:return_reason, store: store, name: 'Damaged') }
+
+ it 'lists the marketplace’s reasons' do
+ get :index, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['data'].map { |row| row['name'] }).to include('Damaged')
+ end
+
+ # A withdrawn reason must not be offered: a seller filing against it would
+ # be using vocabulary the operator has retired.
+ it 'leaves out retired reasons' do
+ create(:return_reason, store: store, name: 'Obsolete', active: false)
+
+ get :index, as: :json
+
+ expect(json_response['data'].map { |row| row['name'] }).not_to include('Obsolete')
+ end
+
+ it 'leaves out another store’s reasons' do
+ other_store = create(:store)
+ create(:return_reason, store: other_store, name: 'Elsewhere')
+
+ get :index, as: :json
+
+ expect(json_response['data'].map { |row| row['name'] }).not_to include('Elsewhere')
+ end
+ end
+end