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.

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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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.rb
index 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 Spree
fulfillment.stock_location&.name
end
- 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 }
end
end
diff --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.rb
index 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 Spree
quantity: :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, :currency
diff --git a/spree/api/app/serializers/spree/api/v3/seller/order_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/order_serializer.rb
index 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 Spree
total_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.rb
new file mode 100644
index 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
+end
diff --git a/spree/api/spec/integration/spree/api/v3/seller/orders_spec.rb b/spree/api/spec/integration/spree/api/v3/seller/orders_spec.rb
new file mode 100644
index 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