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
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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.rbindex 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: :controlleexpect(json_response['data']).to be_emptyend+ # 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' dodiff --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.rbnew file mode 100644index 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+enddiff --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.rbnew file mode 100644index 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+enddiff --git a/spree/api/spec/integration/spree/api/v3/admin/suppliers_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/suppliers_spec.rbnew file mode 100644index 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