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.

Document the inventory operations endpoints

Łukasz Adamczyk49f1b8495517
diff --git a/packages/admin-sdk/examples/purchase-orders/create.ts b/packages/admin-sdk/examples/purchase-orders/create.ts
new file mode 100644
index 0000000000..cdb8846c51
--- /dev/null
+++ b/packages/admin-sdk/examples/purchase-orders/create.ts
@@ -0,0 +1,18 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+const purchaseOrder = await client.purchaseOrders.create({
+ supplier_id: 'sup_1234567890',
+ destination_location_id: 'sloc_1234567890',
+ expected_at: '2026-10-01',
+ items: [{ variant_id: 'variant_1234567890', quantity_ordered: 100, unit_cost: '12.50' }],
+})
+
+// endregion:example
+
+export { purchaseOrder }
diff --git a/packages/admin-sdk/examples/purchase-orders/list.ts b/packages/admin-sdk/examples/purchase-orders/list.ts
new file mode 100644
index 0000000000..ae172667c8
--- /dev/null
+++ b/packages/admin-sdk/examples/purchase-orders/list.ts
@@ -0,0 +1,16 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+const { data: purchaseOrders } = await client.purchaseOrders.list({
+ q: { status_eq: 'ordered' },
+ expand: ['supplier'],
+})
+
+// endregion:example
+
+export { purchaseOrders }
diff --git a/packages/admin-sdk/examples/purchase-orders/receive.ts b/packages/admin-sdk/examples/purchase-orders/receive.ts
new file mode 100644
index 0000000000..42fca54592
--- /dev/null
+++ b/packages/admin-sdk/examples/purchase-orders/receive.ts
@@ -0,0 +1,17 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+// `quantity_received` is the running total for the line, so a second delivery
+// tops it up rather than starting over. Omit `items` to receive it all.
+const purchaseOrder = await client.purchaseOrders.receive('po_1234567890', {
+ items: [{ id: 'poi_1234567890', quantity_received: 60 }],
+})
+
+// endregion:example
+
+export { purchaseOrder }
diff --git a/packages/admin-sdk/examples/stock-transfers/create.ts b/packages/admin-sdk/examples/stock-transfers/create.ts
new file mode 100644
index 0000000000..dab0793490
--- /dev/null
+++ b/packages/admin-sdk/examples/stock-transfers/create.ts
@@ -0,0 +1,19 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+// A draft: nothing moves until the transfer is marked in transit.
+const stockTransfer = await client.stockTransfers.create({
+ source_location_id: 'sloc_1234567890',
+ destination_location_id: 'sloc_0987654321',
+ reference: 'Weekly restock',
+ items: [{ variant_id: 'variant_1234567890', quantity_shipped: 10 }],
+})
+
+// endregion:example
+
+export { stockTransfer }
diff --git a/packages/admin-sdk/examples/stock-transfers/mark-in-transit.ts b/packages/admin-sdk/examples/stock-transfers/mark-in-transit.ts
new file mode 100644
index 0000000000..922238d4bc
--- /dev/null
+++ b/packages/admin-sdk/examples/stock-transfers/mark-in-transit.ts
@@ -0,0 +1,14 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+// The units leave the source warehouse here.
+const stockTransfer = await client.stockTransfers.markInTransit('st_1234567890')
+
+// endregion:example
+
+export { stockTransfer }
diff --git a/packages/admin-sdk/examples/stock-transfers/receive.ts b/packages/admin-sdk/examples/stock-transfers/receive.ts
new file mode 100644
index 0000000000..09b0ad8c59
--- /dev/null
+++ b/packages/admin-sdk/examples/stock-transfers/receive.ts
@@ -0,0 +1,16 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+// Partial receipt is the normal case: ten left, eight arrived.
+const stockTransfer = await client.stockTransfers.receive('st_1234567890', {
+ items: [{ id: 'sti_1234567890', quantity_received: 8, discrepancy_reason: 'damaged_in_transit' }],
+})
+
+// endregion:example
+
+export { stockTransfer }
diff --git a/packages/admin-sdk/examples/suppliers/create.ts b/packages/admin-sdk/examples/suppliers/create.ts
new file mode 100644
index 0000000000..8197b6243f
--- /dev/null
+++ b/packages/admin-sdk/examples/suppliers/create.ts
@@ -0,0 +1,19 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+const supplier = await client.suppliers.create({
+ name: 'Acme Wholesale',
+ contact_name: 'Dana Okafor',
+ email: '[email protected]',
+ city: 'Brooklyn',
+ country_code: 'US',
+})
+
+// endregion:example
+
+export { supplier }
diff --git a/packages/admin-sdk/examples/suppliers/list.ts b/packages/admin-sdk/examples/suppliers/list.ts
new file mode 100644
index 0000000000..578d47ec64
--- /dev/null
+++ b/packages/admin-sdk/examples/suppliers/list.ts
@@ -0,0 +1,13 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+const { data: suppliers } = await client.suppliers.list({ search: 'Acme' })
+
+// endregion:example
+
+export { suppliers }
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/stock_movements_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/stock_movements_controller_spec.rb
index 552bdf7613..58ee881968 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/stock_movements_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/stock_movements_controller_spec.rb
@@ -51,6 +51,41 @@ RSpec.describe Spree::Api::V3::Admin::StockMovementsController, type: :controlle
expect(json_response['data']).to be_empty
end
+ # The two filters the dashboard's history panels read through: a movement
+ # carries no variant or location of its own, so both reach through the
+ # stock level (docs/plans/6.0-inventory-operations.md).
+ it 'filters by variant, for the history panel on a product' do
+ other_movement = stock_location.adjust(create(:variant), 2, reason: 'Cycle count')
+
+ get :index, params: { q: { stock_level_variant_id_in: [variant.prefixed_id] } }, as: :json
+
+ ids = json_response['data'].map { |m| m['id'] }
+ expect(ids).to include(movement.prefixed_id)
+ expect(ids).not_to include(other_movement.prefixed_id)
+ end
+
+ it 'filters by warehouse, for the activity panel on a stock location' do
+ other_location = create(:stock_location, store: store)
+ other_movement = other_location.adjust(variant, 2, reason: 'Cycle count')
+
+ get :index, params: { q: { stock_level_stock_location_id_eq: stock_location.prefixed_id } }, as: :json
+
+ ids = json_response['data'].map { |m| m['id'] }
+ expect(ids).to include(movement.prefixed_id)
+ expect(ids).not_to include(other_movement.prefixed_id)
+ end
+
+ it 'carries the purchase order and the unit cost on a received row' do
+ purchase_order = create(:purchase_order, :ordered, store: store, quantity: 4, unit_cost: 9.5)
+ Spree::PurchaseOrders::Receive.call(purchase_order: purchase_order)
+
+ get :index, params: { q: { kind_eq: 'received' } }, as: :json
+
+ row = json_response['data'].find { |m| m['purchase_order_id'] == purchase_order.prefixed_id }
+ expect(row['unit_cost']).to eq('9.5')
+ expect(row['display_unit_cost']).to eq('$9.50')
+ end
+
# spree_stock_movements carries no store of its own, so tenancy is the walk
# through stock level → variant → product → store.
it 'excludes movements for another store\'s products' do
diff --git a/spree/api/spec/integration/spree/api/v3/admin/purchase_orders_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/purchase_orders_spec.rb
new file mode 100644
index 0000000000..7ee0e7ee3a
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/purchase_orders_spec.rb
@@ -0,0 +1,352 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Purchase Orders API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let!(:supplier) { create(:supplier, store: store, name: 'Acme Wholesale') }
+ let!(:destination) { create(:stock_location, store: store, name: 'Brooklyn') }
+ let!(:variant) { create(:variant) }
+ let!(:order_record) do
+ Spree::PurchaseOrders::Create.call(
+ store: store, supplier: supplier, destination_location: destination,
+ expected_at: '2026-10-01',
+ items: [{ variant: variant, quantity_ordered: 100, unit_cost: 12.5 }]
+ ).value
+ end
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+
+ path '/api/v3/admin/purchase_orders' do
+ get 'List purchase orders' do
+ tags 'Purchase Orders'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Stock bought from suppliers. A purchase order carries what a purchase
+ has and a stock transfer does not: a supplier, a unit cost per line and
+ an expected arrival date.
+
+ Ordered units never count toward availability. Nothing here changes
+ `count_on_hand` until `receive` runs, because a merchant who has
+ ordered stock does not have it.
+
+ Statuses are `draft`, `ordered`, `partially_received`, `received` and
+ `canceled`. Each move between them is its own endpoint, not a `PATCH`
+ that writes `status`.
+
+ Filter with Ransack predicates such as `q[status_eq]`,
+ `q[supplier_id_eq]` or `q[expected_at_lteq]`. Expand `items`,
+ `supplier` and `destination_location`.
+ DESC
+ admin_scope :read, :purchasing
+
+ admin_sdk_example 'purchase-orders/list'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'
+ parameter name: :'q[status_eq]', in: :query, type: :string, required: false,
+ description: "Filter by status ('draft', 'ordered', 'partially_received', 'received', 'canceled')"
+ parameter name: :expand, in: :query, type: :string, required: false,
+ description: 'Comma-separated associations to embed: items, supplier, destination_location'
+
+ response '200', 'purchase orders found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ schema SwaggerSchemaHelpers.paginated('PurchaseOrder')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ row = data['data'].find { |po| po['id'] == order_record.prefixed_id }
+ expect(row['status']).to eq('draft')
+ expect(row['quantity_ordered_total']).to eq(100)
+ expect(row['subtotal']).to eq('1250.0')
+ end
+ end
+
+ response '401', 'unauthorized' do
+ let(:'x-spree-api-key') { 'invalid' }
+ let(:Authorization) { 'Bearer invalid' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+
+ post 'Create a purchase order' do
+ tags 'Purchase Orders'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Drafts an order. Nothing is on order and nothing touches availability
+ until the order is marked as ordered and then received.
+
+ `currency` defaults to the store's; set it for a foreign-currency
+ order. `expected_at` is a calendar date (`yyyy-mm-dd`) — the day the
+ supplier promised means the same day in every timezone.
+ DESC
+ admin_scope :write, :purchasing
+
+ admin_sdk_example 'purchase-orders/create'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :purchase_order, in: :body, required: true, schema: {
+ type: :object,
+ properties: {
+ supplier_id: { type: :string, example: 'sup_1234567890' },
+ destination_location_id: { type: :string, example: 'sloc_1234567890' },
+ currency: { type: :string, nullable: true, example: 'USD' },
+ expected_at: { type: :string, format: :date, nullable: true, example: '2026-10-01' },
+ reference: { type: :string, nullable: true, description: "The supplier's own order number" },
+ notes: { type: :string, nullable: true },
+ items: {
+ type: :array,
+ items: {
+ type: :object,
+ properties: {
+ variant_id: { type: :string, example: 'variant_1234567890' },
+ quantity_ordered: { type: :integer, example: 100 },
+ unit_cost: { type: :string, example: '12.50' }
+ },
+ required: %w[variant_id quantity_ordered]
+ }
+ },
+ metadata: { type: :object, nullable: true }
+ },
+ required: %w[supplier_id destination_location_id]
+ }
+
+ response '201', 'purchase order created' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:purchase_order) do
+ {
+ supplier_id: supplier.prefixed_id,
+ destination_location_id: destination.prefixed_id,
+ expected_at: '2026-10-01',
+ reference: 'SUP-8891',
+ items: [{ variant_id: variant.prefixed_id, quantity_ordered: 100, unit_cost: '12.50' }]
+ }
+ end
+
+ schema '$ref' => '#/components/schemas/PurchaseOrder'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['status']).to eq('draft')
+ expect(data['number']).to start_with('PO')
+ expect(destination.stock_level(variant.id)&.count_on_hand.to_i).to eq(0)
+ end
+ end
+
+ response '404', 'supplier belongs to another store' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:purchase_order) do
+ {
+ supplier_id: create(:supplier, store: create(:store)).prefixed_id,
+ destination_location_id: destination.prefixed_id,
+ items: [{ variant_id: variant.prefixed_id, quantity_ordered: 1, unit_cost: '1.00' }]
+ }
+ end
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/admin/purchase_orders/{id}' do
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Purchase order ID'
+
+ get 'Get a purchase order' do
+ tags 'Purchase Orders'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ admin_scope :read, :purchasing
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :expand, in: :query, type: :string, required: false,
+ description: 'Comma-separated associations to embed: items, supplier, destination_location'
+
+ response '200', 'purchase order found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { order_record.prefixed_id }
+ let(:expand) { 'items,supplier' }
+
+ schema '$ref' => '#/components/schemas/PurchaseOrder'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['items'].first['unit_cost']).to eq('12.5')
+ expect(data['supplier']['name']).to eq('Acme Wholesale')
+ end
+ end
+
+ response '404', 'purchase order not found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { 'po_nonexistent' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/admin/purchase_orders/{id}/mark_ordered' do
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Purchase order ID'
+
+ patch 'Place the order with the supplier' do
+ tags 'Purchase Orders'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Moves a `draft` to `ordered`: the lines are frozen and `ordered_at` is
+ stamped. Availability is still untouched — ordered stock is not stock
+ the merchant has.
+ DESC
+ admin_scope :write, :purchasing
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+
+ response '200', 'purchase order placed' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { order_record.prefixed_id }
+
+ schema '$ref' => '#/components/schemas/PurchaseOrder'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['status']).to eq('ordered')
+ expect(data['ordered_at']).to be_present
+ end
+ end
+ end
+ end
+
+ path '/api/v3/admin/purchase_orders/{id}/receive' do
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Purchase order ID'
+
+ patch 'Book in a delivery' do
+ tags 'Purchase Orders'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ The moment purchased goods first count toward availability.
+
+ `quantity_received` is the running total for the line, so a second
+ delivery tops it up rather than starting over, and only the difference
+ reaches the shelf. Omit `items` to receive every line in full.
+
+ Each `received` stock movement carries the line's `unit_cost`, which is
+ what a rolling average cost is computed from — including across two
+ deliveries agreed at different prices.
+
+ The order settles in `received` once every line is complete, and stays
+ `partially_received` while any is still owed.
+ DESC
+ admin_scope :write, :purchasing
+
+ admin_sdk_example 'purchase-orders/receive'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :receipt, in: :body, required: false, schema: {
+ type: :object,
+ properties: {
+ items: {
+ type: :array,
+ items: {
+ type: :object,
+ properties: {
+ id: { type: :string, example: 'poi_1234567890' },
+ quantity_received: { type: :integer, example: 60 }
+ },
+ required: %w[id quantity_received]
+ }
+ }
+ }
+ }
+
+ response '200', 'delivery booked in' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { order_record.prefixed_id }
+ let(:receipt) { { items: [{ id: order_record.items.first.prefixed_id, quantity_received: 60 }] } }
+
+ before { Spree::PurchaseOrders::MarkOrdered.call(purchase_order: order_record) }
+
+ schema '$ref' => '#/components/schemas/PurchaseOrder'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['status']).to eq('partially_received')
+ expect(data['quantity_received_total']).to eq(60)
+ expect(destination.stock_level(variant.id).reload.count_on_hand).to eq(60)
+ end
+ end
+
+ response '422', 'order has not been placed yet' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { order_record.prefixed_id }
+ let(:receipt) { {} }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/admin/purchase_orders/{id}/cancel' do
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Purchase order ID'
+
+ patch 'Cancel a purchase order' do
+ tags 'Purchase Orders'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Closes what is still outstanding. Nothing is unwound: a purchase order
+ never moved stock until units were received, and units already received
+ stay on the shelf because the merchant has them.
+
+ A `reason` is appended to the order's notes.
+ DESC
+ admin_scope :write, :purchasing
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :cancellation, in: :body, required: false, schema: {
+ type: :object,
+ properties: { reason: { type: :string, example: 'Supplier went under' } }
+ }
+
+ response '200', 'purchase order cancelled' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { order_record.prefixed_id }
+ let(:cancellation) { { reason: 'Supplier went under' } }
+
+ schema '$ref' => '#/components/schemas/PurchaseOrder'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['status']).to eq('canceled')
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/stock_transfers_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/stock_transfers_spec.rb
new file mode 100644
index 0000000000..6cfc626884
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/stock_transfers_spec.rb
@@ -0,0 +1,455 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Stock Transfers API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let!(:source) { create(:stock_location, store: store, name: 'Warehouse') }
+ let!(:destination) { create(:stock_location, store: store, name: 'Brooklyn shop') }
+ let!(:variant) { create(:variant) }
+ let!(:transfer_record) do
+ Spree::StockTransfers::Create.call(
+ store: store, source_location: source, destination_location: destination,
+ reference: 'Weekly restock',
+ items: [{ variant: variant, quantity_shipped: 10 }]
+ ).value
+ end
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+
+ before { source.restock(variant, 50) }
+
+ path '/api/v3/admin/stock_transfers' do
+ get 'List stock transfers' do
+ tags 'Stock Transfers'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Stock moving between two of the merchant's own warehouses.
+
+ A transfer is a trip, not an instant. Units leave the source when the
+ transfer is marked in transit and land at the destination when somebody
+ counts them in — in between they are in flight, gone from one shelf and
+ not yet on the other.
+
+ Statuses are `draft`, `ready_to_ship`, `in_transit`,
+ `partially_received`, `received` and `canceled`. Each move between them
+ is its own endpoint, not a `PATCH` that writes `status`.
+
+ Receiving from a supplier is a purchase order, not a transfer with a
+ missing source.
+
+ Filter with Ransack predicates such as `q[status_eq]`,
+ `q[source_location_id_eq]` or `q[number_or_reference_cont]`. Expand
+ `items`, `source_location` and `destination_location`.
+ DESC
+ admin_scope :read, :stock
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'
+ parameter name: :'q[status_eq]', in: :query, type: :string, required: false,
+ description: "Filter by status ('draft', 'ready_to_ship', 'in_transit', 'partially_received', 'received', 'canceled')"
+ parameter name: :expand, in: :query, type: :string, required: false,
+ description: 'Comma-separated associations to embed: items, source_location, destination_location'
+
+ response '200', 'stock transfers found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ schema SwaggerSchemaHelpers.paginated('StockTransfer')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ row = data['data'].find { |transfer| transfer['id'] == transfer_record.prefixed_id }
+ expect(row['status']).to eq('draft')
+ expect(row['quantity_shipped_total']).to eq(10)
+ end
+ end
+
+ response '401', 'unauthorized' do
+ let(:'x-spree-api-key') { 'invalid' }
+ let(:Authorization) { 'Bearer invalid' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+
+ post 'Create a stock transfer' do
+ tags 'Stock Transfers'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Persists a draft — a packing list the merchant can still edit. Nothing
+ moves until the transfer is marked in transit.
+
+ A draft may legitimately open empty and gain lines as the merchant
+ packs. Both warehouses are required and must belong to the same store.
+ DESC
+ admin_scope :write, :stock
+
+ admin_sdk_example 'stock-transfers/create'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :stock_transfer, in: :body, required: true, schema: {
+ type: :object,
+ properties: {
+ source_location_id: { type: :string, example: 'sloc_1234567890' },
+ destination_location_id: { type: :string, example: 'sloc_0987654321' },
+ reference: { type: :string, nullable: true, description: "The merchant's own label for the trip" },
+ notes: { type: :string, nullable: true },
+ items: {
+ type: :array,
+ items: {
+ type: :object,
+ properties: {
+ variant_id: { type: :string, example: 'variant_1234567890' },
+ quantity_shipped: { type: :integer, example: 10 }
+ },
+ required: %w[variant_id quantity_shipped]
+ }
+ },
+ metadata: { type: :object, nullable: true }
+ },
+ required: %w[source_location_id destination_location_id]
+ }
+
+ response '201', 'stock transfer created' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:stock_transfer) do
+ {
+ source_location_id: source.prefixed_id,
+ destination_location_id: destination.prefixed_id,
+ reference: 'Weekly restock',
+ items: [{ variant_id: variant.prefixed_id, quantity_shipped: 10 }]
+ }
+ end
+
+ schema '$ref' => '#/components/schemas/StockTransfer'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['status']).to eq('draft')
+ expect(data['number']).to start_with('T')
+ expect(source.stock_level(variant.id).reload.count_on_hand).to eq(50)
+ end
+ end
+
+ response '404', 'warehouse belongs to another store' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:stock_transfer) do
+ {
+ source_location_id: source.prefixed_id,
+ destination_location_id: create(:stock_location, store: create(:store)).prefixed_id,
+ items: [{ variant_id: variant.prefixed_id, quantity_shipped: 1 }]
+ }
+ end
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/admin/stock_transfers/{id}' do
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Stock transfer ID'
+
+ get 'Get a stock transfer' do
+ tags 'Stock Transfers'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ admin_scope :read, :stock
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :expand, in: :query, type: :string, required: false,
+ description: 'Comma-separated associations to embed: items, source_location, destination_location'
+
+ response '200', 'stock transfer found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { transfer_record.prefixed_id }
+ let(:expand) { 'items,source_location,destination_location' }
+
+ schema '$ref' => '#/components/schemas/StockTransfer'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['items'].first['quantity_shipped']).to eq(10)
+ expect(data['source_location']['name']).to eq('Warehouse')
+ end
+ end
+
+ response '404', 'stock transfer not found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { 'st_nonexistent' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+
+ delete 'Delete a stock transfer' do
+ tags 'Stock Transfers'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Drafts only. Past `draft` the transfer describes a box that physically
+ exists, so it is cancelled rather than deleted — a 422 says so.
+ DESC
+ admin_scope :write, :stock
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+
+ response '204', 'stock transfer deleted' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { transfer_record.prefixed_id }
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/admin/stock_transfers/{id}/mark_ready' do
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Stock transfer ID'
+
+ patch 'Mark a transfer ready to ship' do
+ tags 'Stock Transfers'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Freezes the lines so the warehouse and the merchant are looking at the
+ same list. Nothing leaves the shelf yet.
+ DESC
+ admin_scope :write, :stock
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+
+ response '200', 'transfer is ready to ship' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { transfer_record.prefixed_id }
+
+ schema '$ref' => '#/components/schemas/StockTransfer'
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['status']).to eq('ready_to_ship')
+ end
+ end
+ end
+ end
+
+ path '/api/v3/admin/stock_transfers/{id}/mark_in_transit' do
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Stock transfer ID'
+
+ patch 'Send a transfer' do
+ tags 'Stock Transfers'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ The moment stock leaves the source warehouse: `shipped` movements are
+ written against the source's levels and `shipped_at` is stamped. The
+ destination is deliberately untouched — the units are in flight.
+
+ Refused with a 422 when the source does not hold enough. Pass
+ `force: true` to record the departure anyway: a merchant forcing it has
+ decided the box left whatever the ledger claims.
+ DESC
+ admin_scope :write, :stock
+
+ admin_sdk_example 'stock-transfers/mark-in-transit'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :departure, in: :body, required: false, schema: {
+ type: :object,
+ properties: {
+ force: {
+ type: :boolean,
+ description: 'Ship even if it drives the source below zero'
+ }
+ }
+ }
+
+ response '200', 'transfer is in transit' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { transfer_record.prefixed_id }
+ let(:departure) { {} }
+
+ schema '$ref' => '#/components/schemas/StockTransfer'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['status']).to eq('in_transit')
+ expect(data['shipped_at']).to be_present
+ expect(source.stock_level(variant.id).reload.count_on_hand).to eq(40)
+ expect(destination.stock_level(variant.id)&.count_on_hand.to_i).to eq(0)
+ end
+ end
+ end
+ end
+
+ path '/api/v3/admin/stock_transfers/{id}/receive' do
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Stock transfer ID'
+
+ patch 'Receive a transfer' do
+ tags 'Stock Transfers'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Records what the destination warehouse actually counted in.
+
+ Partial receipt is the normal case, not an edge case: ten left, eight
+ arrived, two were crushed in transit. `quantity_received` is the running
+ total for the line, so a second delivery tops it up rather than
+ starting over, and only the difference reaches the shelf. Omit `items`
+ to receive every line in full.
+
+ `discrepancy_reason` records why fewer arrived —
+ `damaged_in_transit`, `lost_in_transit` or `undercount`.
+
+ The transfer settles in `received` once every line is complete, and
+ stays `partially_received` while any is still owed.
+ DESC
+ admin_scope :write, :stock
+
+ admin_sdk_example 'stock-transfers/receive'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :receipt, in: :body, required: false, schema: {
+ type: :object,
+ properties: {
+ items: {
+ type: :array,
+ items: {
+ type: :object,
+ properties: {
+ id: { type: :string, example: 'sti_1234567890' },
+ quantity_received: { type: :integer, example: 8 },
+ discrepancy_reason: { type: :string, nullable: true, example: 'damaged_in_transit' }
+ },
+ required: %w[id quantity_received]
+ }
+ }
+ }
+ }
+
+ response '200', 'transfer received' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { transfer_record.prefixed_id }
+ let(:receipt) do
+ {
+ items: [
+ {
+ id: transfer_record.items.first.prefixed_id,
+ quantity_received: 8,
+ discrepancy_reason: 'damaged_in_transit'
+ }
+ ]
+ }
+ end
+
+ before { Spree::StockTransfers::MarkInTransit.call(stock_transfer: transfer_record) }
+
+ schema '$ref' => '#/components/schemas/StockTransfer'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['status']).to eq('partially_received')
+ expect(data['quantity_received_total']).to eq(8)
+ expect(destination.stock_level(variant.id).reload.count_on_hand).to eq(8)
+ end
+ end
+
+ response '422', 'transfer has not shipped yet' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { transfer_record.prefixed_id }
+ let(:receipt) { {} }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/admin/stock_transfers/{id}/cancel' do
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Stock transfer ID'
+
+ patch 'Cancel a stock transfer' do
+ tags 'Stock Transfers'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Calls the trip off.
+
+ Cancelling a draft or a packed transfer costs nothing — no stock has
+ moved. Cancelling one already in transit needs `on_in_transit`, because
+ the units are physically gone from the source: either they come back
+ (`restock`, as if the transfer had never shipped) or they are written
+ off as lost (`write_off`). There is no default — guessing would either
+ invent stock or destroy it — so an in-flight cancellation without it is
+ refused with a 422.
+ DESC
+ admin_scope :write, :stock
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :cancellation, in: :body, required: false, schema: {
+ type: :object,
+ properties: {
+ on_in_transit: {
+ type: :string,
+ enum: %w[restock write_off],
+ description: 'Required once the units have left the source'
+ },
+ reason: { type: :string, nullable: true, description: 'Recorded against the written-off lines' }
+ }
+ }
+
+ response '200', 'transfer cancelled' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { transfer_record.prefixed_id }
+ let(:cancellation) { { on_in_transit: 'restock' } }
+
+ before { Spree::StockTransfers::MarkInTransit.call(stock_transfer: transfer_record) }
+
+ schema '$ref' => '#/components/schemas/StockTransfer'
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['status']).to eq('canceled')
+ expect(source.stock_level(variant.id).reload.count_on_hand).to eq(50)
+ end
+ end
+
+ response '422', 'in-transit cancellation needs a decision' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { transfer_record.prefixed_id }
+ let(:cancellation) { {} }
+
+ before { Spree::StockTransfers::MarkInTransit.call(stock_transfer: transfer_record) }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/suppliers_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/suppliers_spec.rb
new file mode 100644
index 0000000000..a548fa3ed8
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/suppliers_spec.rb
@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Suppliers API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let!(:supplier_record) { create(:supplier, :with_address, store: store, name: 'Acme Wholesale') }
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+
+ path '/api/v3/admin/suppliers' do
+ get 'List suppliers' do
+ tags 'Suppliers'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Who the merchant buys stock from. A supplier is an address-book entry
+ with a purchasing history — not a party that sells on the store, which
+ is a seller.
+
+ Suppliers belong to one store, and are soft-deleted so the purchase
+ orders that name them stay readable.
+
+ Filter with Ransack predicates such as
+ `q[name_or_contact_name_or_email_cont]` or `q[country_code_eq]`.
+ DESC
+ admin_scope :read, :purchasing
+
+ admin_sdk_example 'suppliers/list'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'
+ parameter name: :'q[name_or_contact_name_or_email_cont]', in: :query, type: :string, required: false,
+ description: 'Search by name, contact name or email'
+
+ response '200', 'suppliers found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ schema SwaggerSchemaHelpers.paginated('Supplier')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data'].map { |row| row['name'] }).to include('Acme Wholesale')
+ end
+ end
+
+ response '401', 'unauthorized' do
+ let(:'x-spree-api-key') { 'invalid' }
+ let(:Authorization) { 'Bearer invalid' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+
+ post 'Create a supplier' do
+ tags 'Suppliers'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Adds a supplier to this store's address book. The address is inline —
+ street, city, state and country live on the supplier itself, the same
+ shape a stock location uses.
+ DESC
+ admin_scope :write, :purchasing
+
+ admin_sdk_example 'suppliers/create'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :supplier, in: :body, required: true, schema: {
+ type: :object,
+ properties: {
+ name: { type: :string, example: 'Northwind Trading' },
+ contact_name: { type: :string, nullable: true, example: 'Dana Okafor' },
+ email: { type: :string, nullable: true, example: '[email protected]' },
+ phone: { type: :string, nullable: true, example: '555-0100' },
+ notes: { type: :string, nullable: true },
+ address1: { type: :string, nullable: true, example: '1 Warehouse Way' },
+ address2: { type: :string, nullable: true },
+ city: { type: :string, nullable: true, example: 'Brooklyn' },
+ state_code: { type: :string, nullable: true, example: 'NY' },
+ state_name: { type: :string, nullable: true },
+ country_code: { type: :string, nullable: true, example: 'US' },
+ postal_code: { type: :string, nullable: true, example: '11201' },
+ metadata: { type: :object, nullable: true }
+ },
+ required: %w[name]
+ }
+
+ response '201', 'supplier created' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:supplier) do
+ {
+ name: 'Northwind Trading',
+ contact_name: 'Dana Okafor',
+ email: '[email protected]',
+ city: 'Brooklyn',
+ country_code: 'US'
+ }
+ end
+
+ schema '$ref' => '#/components/schemas/Supplier'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['name']).to eq('Northwind Trading')
+ expect(data['email']).to eq('[email protected]')
+ end
+ end
+
+ response '422', 'validation error' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:supplier) { { name: '' } }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/admin/suppliers/{id}' do
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Supplier ID'
+
+ get 'Get a supplier' do
+ tags 'Suppliers'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ admin_scope :read, :purchasing
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+
+ response '200', 'supplier found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { supplier_record.prefixed_id }
+
+ schema '$ref' => '#/components/schemas/Supplier'
+
+ run_test!
+ end
+
+ response '404', 'supplier not found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { 'sup_nonexistent' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+
+ patch 'Update a supplier' do
+ tags 'Suppliers'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ admin_scope :write, :purchasing
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :supplier, in: :body, required: true, schema: {
+ type: :object,
+ properties: {
+ name: { type: :string },
+ contact_name: { type: :string, nullable: true },
+ email: { type: :string, nullable: true },
+ phone: { type: :string, nullable: true }
+ }
+ }
+
+ response '200', 'supplier updated' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { supplier_record.prefixed_id }
+ let(:supplier) { { contact_name: 'Sam Reyes' } }
+
+ schema '$ref' => '#/components/schemas/Supplier'
+
+ run_test!
+ end
+ end
+
+ delete 'Delete a supplier' do
+ tags 'Suppliers'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Soft-deletes the supplier, so the purchase orders naming it stay
+ readable. Refused with a 422 while a purchase order still points at it.
+ DESC
+ admin_scope :write, :purchasing
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+
+ response '204', 'supplier deleted' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { supplier_record.prefixed_id }
+
+ run_test!
+ end
+ end
+ end
+end