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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Publish the seller orders and fulfillments reference
Damian Legawiec585d7537bb2b
diff --git a/packages/seller-dashboard/src/pages/order.tsx b/packages/seller-dashboard/src/pages/order.tsxindex 07f4bc4c66..1c9016755f 100644--- a/packages/seller-dashboard/src/pages/order.tsx+++ b/packages/seller-dashboard/src/pages/order.tsx@@ -169,7 +169,7 @@ function FulfillmentCard({ orderId, fulfillment }: { orderId: string; fulfillmen</p>)}- {fulfillment.items?.map((item) => (+ {fulfillment.fulfillment_items?.map((item) => (<div key={item.id} className="flex items-center justify-between gap-3 text-sm"><span className="truncate">{item.name}</span><span className="text-muted-foreground">× {item.quantity}</span>diff --git a/packages/seller-sdk/src/types/generated/Fulfillment.ts b/packages/seller-sdk/src/types/generated/Fulfillment.tsindex 59cf6483b2..d2851e8e1f 100644--- a/packages/seller-sdk/src/types/generated/Fulfillment.ts+++ b/packages/seller-sdk/src/types/generated/Fulfillment.ts@@ -1,4 +1,4 @@-// Typelizer digest 1c54efc582de5122eb1e857fb0f14d71+// Typelizer digest 0f435cdfec74916fc1add4ec0f65dc9d//// DO NOT MODIFY: This file was automatically generated by Typelizer.import type {FulfillmentItem} from '@/types'@@ -11,13 +11,13 @@ type Fulfillment = {tracking_url: string | null;tracking_carrier: string | null;tracking_status: string | null;- fulfilled_at: string;+ fulfilled_at: string | null;created_at: string;updated_at: string;fulfillment_type: string | null;delivery_method_name: string | null;stock_location_name: string | null;- items: Array<FulfillmentItem>;+ fulfillment_items: Array<FulfillmentItem>;}export default Fulfillment;diff --git a/packages/seller-sdk/src/types/generated/Order.ts b/packages/seller-sdk/src/types/generated/Order.tsindex e9e98c3e6a..672819bd46 100644--- a/packages/seller-sdk/src/types/generated/Order.ts+++ b/packages/seller-sdk/src/types/generated/Order.ts@@ -1,4 +1,4 @@-// Typelizer digest cc44b646cbe77e1e3454fa3625348cbb+// Typelizer digest 4c6809e63915964d3a02857daa2a7874//// DO NOT MODIFY: This file was automatically generated by Typelizer.import type {OrderLineItem, Fulfillment, Address} from '@/types'@@ -16,12 +16,12 @@ type Order = {completed_at: string;created_at: string;updated_at: string;- item_total: unknown;- display_item_total: unknown;- tax_total: unknown;- display_tax_total: unknown;- total: unknown;- display_total: unknown;+ item_total: string | null;+ display_item_total: string | null;+ tax_total: string | null;+ display_tax_total: string | null;+ total: string | null;+ display_total: string | null;items: Array<OrderLineItem>;fulfillments: Array<Fulfillment>;shipping_address: Address;diff --git a/packages/seller-sdk/src/types/generated/OrderLineItem.ts b/packages/seller-sdk/src/types/generated/OrderLineItem.tsindex 9d882da5ba..a6f4e59a9c 100644--- a/packages/seller-sdk/src/types/generated/OrderLineItem.ts+++ b/packages/seller-sdk/src/types/generated/OrderLineItem.ts@@ -1,4 +1,4 @@-// Typelizer digest c36756c7df6d9fddfa747db960c36235+// Typelizer digest f5cd2d99ff8cf72ea5d0916fcd86fa92//// DO NOT MODIFY: This file was automatically generated by Typelizer.@@ -8,10 +8,10 @@ type OrderLineItem = {options_text: string | null;quantity: number;currency: string;- price: unknown;- display_price: unknown;- total: unknown;- display_total: unknown;+ price: string | null;+ display_price: string | null;+ total: string | null;+ display_total: string | null;variant_id: string | null;sku: string | null;thumbnail_url: string | null;diff --git a/spree/api/app/serializers/spree/api/v3/seller/fulfillment_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/fulfillment_serializer.rbindex 649ddae0cd..17c6dca8d8 100644--- a/spree/api/app/serializers/spree/api/v3/seller/fulfillment_serializer.rb+++ b/spree/api/app/serializers/spree/api/v3/seller/fulfillment_serializer.rb@@ -23,6 +23,9 @@ module Spree:tracking_status,fulfilled_at: :iso8601, created_at: :iso8601, updated_at: :iso8601+ # Null until the parcel actually ships, which is most of its life.+ typelize fulfilled_at: [:string, nullable: true]+attribute :fulfillment_type do |fulfillment|fulfillment.fulfillment_type.presence || (fulfillment.digital? ? 'digital' : 'shipping')end@@ -37,7 +40,11 @@ module Spreefulfillment.stock_location&.nameend- many :fulfillment_items, key: :items,+ # Deliberately not `items`: the store's fulfillment answers with a+ # manifest under that name, and the shared OpenAPI patch rewrites it+ # to that shape — a seller's rows would be documented as somebody+ # else's. These are the persisted fulfillment items, so they say so.+ many :fulfillment_items,resource: proc { Spree.api.seller_fulfillment_item_serializer }endenddiff --git a/spree/api/app/serializers/spree/api/v3/seller/order_line_item_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/order_line_item_serializer.rbindex 6e2b463572..f8cb6aadc1 100644--- a/spree/api/app/serializers/spree/api/v3/seller/order_line_item_serializer.rb+++ b/spree/api/app/serializers/spree/api/v3/seller/order_line_item_serializer.rb@@ -17,7 +17,9 @@ module Spreequantity: :number,currency: :string,variant_id: [:string, nullable: true],- thumbnail_url: [:string, nullable: true]+ thumbnail_url: [:string, nullable: true],+ price: [:string, nullable: true], display_price: [:string, nullable: true],+ total: [:string, nullable: true], display_total: [:string, nullable: true]attributes :name, :options_text, :quantity, :currencydiff --git a/spree/api/app/serializers/spree/api/v3/seller/order_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/order_serializer.rbindex 6a665f02bc..43728755f2 100644--- a/spree/api/app/serializers/spree/api/v3/seller/order_serializer.rb+++ b/spree/api/app/serializers/spree/api/v3/seller/order_serializer.rb@@ -20,7 +20,10 @@ module Spreetotal_quantity: :number,fulfillment_status: [:string, nullable: true],payment_status: [:string, nullable: true],- status: :string+ status: :string,+ item_total: [:string, nullable: true], display_item_total: [:string, nullable: true],+ tax_total: [:string, nullable: true], display_tax_total: [:string, nullable: true],+ total: [:string, nullable: true], display_total: [:string, nullable: true]attributes :number, :email, :customer_note, :currency, :total_quantity,:status, :fulfillment_status, :payment_status,diff --git a/spree/api/spec/integration/spree/api/v3/seller/fulfillments_spec.rb b/spree/api/spec/integration/spree/api/v3/seller/fulfillments_spec.rbnew file mode 100644index 0000000000..64dd45d701--- /dev/null+++ b/spree/api/spec/integration/spree/api/v3/seller/fulfillments_spec.rb@@ -0,0 +1,111 @@+# frozen_string_literal: true++require 'swagger_helper'++RSpec.describe 'Seller Fulfillments API', type: :request, swagger_doc: 'api-reference/seller.yaml' do+ include_context 'API v3 Seller'++ # The seeded role rather than the shared context's products-only one —+ # fulfilling is gated on the `fulfillments` permission.+ let(:seller_user) do+ create(:admin_user, :without_admin_role).tap { |user| seller.add_user(user) }+ end++ let!(:order) { create(:order_ready_to_ship, store: store, seller: seller) }+ let(:fulfillment) { order.fulfillments.first }++ path '/api/v3/seller/orders/{order_id}/fulfillments' do+ parameter name: :order_id, in: :path, type: :string, description: 'Prefixed order ID'++ get 'List fulfillments' do+ tags 'Fulfillments'+ produces 'application/json'+ security [bearer_auth: []]+ description <<~DESC+ The parcels this seller owes on one order.++ Reached through the order, which is itself fetched through the acting+ seller — so a fulfillment on somebody else's order is unreachable+ whatever ids are sent.+ DESC++ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true++ response '200', 'fulfillments listed' do+ let(:Authorization) { "Bearer #{seller_jwt_token}" }+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }+ let(:order_id) { order.prefixed_id }++ schema type: :object,+ properties: {+ data: { type: :array, items: { '$ref' => '#/components/schemas/Fulfillment' } }+ },+ required: %w[data]++ run_test! do |response|+ data = JSON.parse(response.body)['data']+ expect(data.map { |item| item['id'] }).to include(fulfillment.prefixed_id)+ end+ end+ end+ end++ path '/api/v3/seller/orders/{order_id}/fulfillments/{id}/fulfill' do+ parameter name: :order_id, in: :path, type: :string, description: 'Prefixed order ID'+ parameter name: :id, in: :path, type: :string, description: 'Prefixed fulfillment ID'++ patch 'Fulfill (ship) a parcel' do+ tags 'Fulfillments'+ consumes 'application/json'+ produces 'application/json'+ security [bearer_auth: []]+ description <<~DESC+ Marks the parcel shipped.++ This is the same workflow the marketplace operator runs, so the+ customer's dispatch email, the label purchase and any extension hooks+ happen exactly as they would had the operator shipped it.++ `items` narrows the dispatch to part of what the fulfillment holds; the+ remainder splits onto a new one. Omit it to ship the lot.+ DESC++ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true+ parameter name: :body, in: :body, required: false, schema: {+ type: :object,+ properties: {+ tracking: { type: :string, description: 'Carrier tracking number' },+ tracking_carrier: { type: :string, description: 'Carrier name' },+ notify_customer: { type: :boolean, description: 'Send the dispatch email (default true)' },+ items: {+ type: :array,+ description: 'Ship only these lines; the rest split onto a new fulfillment',+ items: {+ type: :object,+ properties: {+ item_id: { type: :string, description: 'Prefixed line item ID' },+ quantity: { type: :integer }+ },+ required: %w[item_id quantity]+ }+ }+ }+ }++ response '200', 'parcel shipped' do+ let(:Authorization) { "Bearer #{seller_jwt_token}" }+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }+ let(:order_id) { order.prefixed_id }+ let(:id) { fulfillment.prefixed_id }+ let(:body) { { tracking: 'TRACK-1' } }++ schema '$ref' => '#/components/schemas/Fulfillment'++ run_test! do+ expect(fulfillment.reload).to be_fulfilled+ expect(fulfillment.tracking).to eq('TRACK-1')+ end+ end+ end+ end+enddiff --git a/spree/api/spec/integration/spree/api/v3/seller/orders_spec.rb b/spree/api/spec/integration/spree/api/v3/seller/orders_spec.rbnew file mode 100644index 0000000000..b99d46c2e0--- /dev/null+++ b/spree/api/spec/integration/spree/api/v3/seller/orders_spec.rb@@ -0,0 +1,138 @@+# frozen_string_literal: true++require 'swagger_helper'++RSpec.describe 'Seller Orders API', type: :request, swagger_doc: 'api-reference/seller.yaml' do+ include_context 'API v3 Seller'++ # The seeded role rather than the shared context's products-only one —+ # orders are gated on the `orders` permission, which that role omits.+ let(:seller_user) do+ create(:admin_user, :without_admin_role).tap { |user| seller.add_user(user) }+ end++ let!(:order) { create(:completed_order_with_totals, store: store, seller: seller) }++ path '/api/v3/seller/orders' do+ get 'List orders' do+ tags 'Orders'+ produces 'application/json'+ security [bearer_auth: []]+ description <<~DESC+ What this seller has sold.++ On a marketplace a basket spanning several sellers is split into one+ order each, so these are the seller's own orders rather than a filtered+ view of somebody else's — another seller's order is never reachable,+ whatever id is sent.++ Checkouts still in flight are left out: until one completes it is+ nobody's order.+ DESC++ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Records per page (max 100)'+ parameter name: :sort, in: :query, type: :string, required: false, description: 'Sort field; prefix with `-` for descending'++ response '200', 'orders listed' do+ let(:Authorization) { "Bearer #{seller_jwt_token}" }+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }++ schema type: :object,+ properties: {+ data: { type: :array, items: { '$ref' => '#/components/schemas/Order' } },+ meta: { '$ref' => '#/components/schemas/PaginationMeta' }+ },+ required: %w[data meta]++ run_test! do |response|+ data = JSON.parse(response.body)['data']+ expect(data.map { |item| item['number'] }).to include(order.number)+ end+ end+ end+ end++ path '/api/v3/seller/orders/{id}' do+ parameter name: :id, in: :path, type: :string, description: 'Prefixed order ID'++ get 'Get an order' do+ tags 'Orders'+ produces 'application/json'+ security [bearer_auth: []]+ description <<~DESC+ One order, as the seller needs it to pack and post the parcel: the+ lines with their SKUs, where it ships to, and a fulfillment per parcel.++ How the customer paid the marketplace is deliberately absent — that is+ between the buyer and the operator.+ DESC++ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true++ response '200', 'order found' do+ let(:Authorization) { "Bearer #{seller_jwt_token}" }+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }+ let(:id) { order.prefixed_id }++ schema '$ref' => '#/components/schemas/Order'++ run_test! do |response|+ expect(JSON.parse(response.body)['number']).to eq(order.number)+ end+ end++ response '404', "another seller's order" do+ let(:Authorization) { "Bearer #{seller_jwt_token}" }+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }+ let(:id) do+ create(:completed_order_with_totals,+ store: store, seller: create(:seller, :approved, store: store)).prefixed_id+ end++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end+ end++ path '/api/v3/seller/orders/{id}/cancel' do+ parameter name: :id, in: :path, type: :string, description: 'Prefixed order ID'++ patch 'Cancel an order' do+ tags 'Orders'+ consumes 'application/json'+ produces 'application/json'+ security [bearer_auth: []]+ description <<~DESC+ Withdraws from an order this seller cannot fulfil.++ Restocking and any refund are the cancellation's own concern, so a+ seller cannot cancel without the money and the stock following.+ DESC++ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true+ parameter name: :body, in: :body, required: false, schema: {+ type: :object,+ properties: {+ notify_customer: { type: :boolean, description: 'Email the customer about the cancellation' }+ }+ }++ response '200', 'order canceled' do+ let(:Authorization) { "Bearer #{seller_jwt_token}" }+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }+ let(:id) { order.prefixed_id }+ let(:body) { {} }++ schema '$ref' => '#/components/schemas/Order'++ run_test! do+ expect(order.reload).to be_canceled+ end+ end+ end+ end+end