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
Teach the admin SDK about transfers, suppliers and purchase orders
Łukasz Adamczyk19e968c41864
diff --git a/packages/admin-sdk/src/admin-client.ts b/packages/admin-sdk/src/admin-client.tsindex 2aaad4ca54..4c3cd8c4fa 100644--- a/packages/admin-sdk/src/admin-client.ts+++ b/packages/admin-sdk/src/admin-client.ts@@ -212,6 +212,9 @@ import type {PromotionRuleCreateParams,PromotionRuleUpdateParams,PromotionUpdateParams,+ PurchaseOrderCreateParams,+ PurchaseOrderReceiveParams,+ PurchaseOrderUpdateParams,ReasonCreateParams,ReasonUpdateParams,ResourceTypeDefinition,@@ -242,11 +245,16 @@ import type {StockLevelUpdateParams,StockLocationCreateParams,StockLocationUpdateParams,+ StockTransferCancelParams,StockTransferCreateParams,+ StockTransferReceiveParams,+ StockTransferUpdateParams,StoreCreditApplyParams,StoreDataSources,StorePayoutProvider,StoreUpdateParams,+ SupplierCreateParams,+ SupplierUpdateParams,TaxCategoryCreateParams,TaxCategoryUpdateParams,TaxExemptionCertificateParams,@@ -328,6 +336,7 @@ import type {Promotion,PromotionAction,PromotionRule,+ PurchaseOrder,Refund,RefundReason,ResourceTranslations,@@ -349,6 +358,7 @@ import type {StockTransfer,Store,StoreCredit,+ Supplier,TaxCategory,TaxExemptionCertificate,TaxIdentifier,@@ -5011,9 +5021,10 @@ export class AdminClient {// ============================================/**- * Inventory movement between stock locations, or external → location for- * receives. Pass `source_location_id` for transfers; omit it to record a- * seller receive (external stock arriving at the destination).+ * Stock moving between two of the merchant's own warehouses. A transfer is a+ * trip: `create` records a plan, `markInTransit` takes the units off the+ * source shelf, and `receive` lands what actually arrived. Receiving from a+ * supplier is a purchase order, not a transfer.*/readonly stockTransfers = {list: (@@ -5035,11 +5046,167 @@ export class AdminClient {params: getParams(params),}),+ /** Persists a draft. Nothing moves until `markInTransit`. */create: (params: StockTransferCreateParams, options?: RequestOptions): Promise<StockTransfer> =>this.request<StockTransfer>('POST', '/stock_transfers', { ...options, body: params }),+ /** Drafts only: past that, what is in the box is a matter of record. */+ update: (+ id: string,+ params: StockTransferUpdateParams,+ options?: RequestOptions,+ ): Promise<StockTransfer> =>+ this.request<StockTransfer>('PATCH', `/stock_transfers/${id}`, { ...options, body: params }),++ /** Drafts only: anything that has shipped is cancelled, not deleted. */delete: (id: string, options?: RequestOptions): Promise<void> =>this.request<void>('DELETE', `/stock_transfers/${id}`, options),++ /** Freezes the lines without taking anything off the shelf. */+ markReady: (id: string, options?: RequestOptions): Promise<StockTransfer> =>+ this.request<StockTransfer>('PATCH', `/stock_transfers/${id}/mark_ready`, options),++ /**+ * The van has left: writes the source's `shipped` movements. Pass+ * `force` to ship anyway when the shelf cannot cover it.+ */+ markInTransit: (+ id: string,+ params?: { force?: boolean },+ options?: RequestOptions,+ ): Promise<StockTransfer> =>+ this.request<StockTransfer>('PATCH', `/stock_transfers/${id}/mark_in_transit`, {+ ...options,+ body: params,+ }),++ /** Lands what the destination counted in; partial receipt is normal. */+ receive: (+ id: string,+ params?: StockTransferReceiveParams,+ options?: RequestOptions,+ ): Promise<StockTransfer> =>+ this.request<StockTransfer>('PATCH', `/stock_transfers/${id}/receive`, {+ ...options,+ body: params,+ }),++ cancel: (+ id: string,+ params?: StockTransferCancelParams,+ options?: RequestOptions,+ ): Promise<StockTransfer> =>+ this.request<StockTransfer>('PATCH', `/stock_transfers/${id}/cancel`, {+ ...options,+ body: params,+ }),+ }++ // ============================================+ // Suppliers+ // ============================================++ /** The merchant's supplier address book. */+ readonly suppliers = {+ list: (+ params?: ListParams & Record<string, unknown>,+ options?: RequestOptions,+ ): Promise<PaginatedResponse<Supplier>> =>+ this.request<PaginatedResponse<Supplier>>('GET', '/suppliers', {+ ...options,+ params: params ? transformListParams(params) : undefined,+ }),++ get: (+ id: string,+ params?: { expand?: string[] },+ options?: RequestOptions,+ ): Promise<Supplier> =>+ this.request<Supplier>('GET', `/suppliers/${id}`, {+ ...options,+ params: getParams(params),+ }),++ create: (params: SupplierCreateParams, options?: RequestOptions): Promise<Supplier> =>+ this.request<Supplier>('POST', '/suppliers', { ...options, body: params }),++ update: (+ id: string,+ params: SupplierUpdateParams,+ options?: RequestOptions,+ ): Promise<Supplier> =>+ this.request<Supplier>('PATCH', `/suppliers/${id}`, { ...options, body: params }),++ delete: (id: string, options?: RequestOptions): Promise<void> =>+ this.request<void>('DELETE', `/suppliers/${id}`, options),+ }++ // ============================================+ // Purchase Orders+ // ============================================++ /**+ * Goods bought from a supplier. Ordered units never count toward+ * availability: nothing reaches the shelf until `receive`.+ */+ readonly purchaseOrders = {+ list: (+ params?: ListParams & Record<string, unknown>,+ options?: RequestOptions,+ ): Promise<PaginatedResponse<PurchaseOrder>> =>+ this.request<PaginatedResponse<PurchaseOrder>>('GET', '/purchase_orders', {+ ...options,+ params: params ? transformListParams(params) : undefined,+ }),++ get: (+ id: string,+ params?: { expand?: string[] },+ options?: RequestOptions,+ ): Promise<PurchaseOrder> =>+ this.request<PurchaseOrder>('GET', `/purchase_orders/${id}`, {+ ...options,+ params: getParams(params),+ }),++ create: (params: PurchaseOrderCreateParams, options?: RequestOptions): Promise<PurchaseOrder> =>+ this.request<PurchaseOrder>('POST', '/purchase_orders', { ...options, body: params }),++ /** Drafts only: a placed order is a matter of record with the supplier. */+ update: (+ id: string,+ params: PurchaseOrderUpdateParams,+ options?: RequestOptions,+ ): Promise<PurchaseOrder> =>+ this.request<PurchaseOrder>('PATCH', `/purchase_orders/${id}`, { ...options, body: params }),++ delete: (id: string, options?: RequestOptions): Promise<void> =>+ this.request<void>('DELETE', `/purchase_orders/${id}`, options),++ /** Sends the order: freezes the lines and starts the expected-date clock. */+ markOrdered: (id: string, options?: RequestOptions): Promise<PurchaseOrder> =>+ this.request<PurchaseOrder>('PATCH', `/purchase_orders/${id}/mark_ordered`, options),++ /** Books in what the supplier actually delivered, at the line's cost. */+ receive: (+ id: string,+ params?: PurchaseOrderReceiveParams,+ options?: RequestOptions,+ ): Promise<PurchaseOrder> =>+ this.request<PurchaseOrder>('PATCH', `/purchase_orders/${id}/receive`, {+ ...options,+ body: params,+ }),++ cancel: (+ id: string,+ params?: { reason?: string },+ options?: RequestOptions,+ ): Promise<PurchaseOrder> =>+ this.request<PurchaseOrder>('PATCH', `/purchase_orders/${id}/cancel`, {+ ...options,+ body: params,+ }),}// ============================================diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.tsindex f260ebcc7d..7a75096afc 100644--- a/packages/admin-sdk/src/params.ts+++ b/packages/admin-sdk/src/params.ts@@ -1489,12 +1489,92 @@ export interface StockLevelBulkUpsertRow {backorderable?: boolean}+export interface StockTransferItemParams {+ variant_id: string+ quantity_shipped: number+}+export interface StockTransferCreateParams {- /** Omit for a seller receive (external stock arriving at the destination). */- source_location_id?: string+ source_location_id: string+ destination_location_id: string+ /** The merchant's own label for the trip. */+ reference?: string+ notes?: string+ /**+ * A draft may open empty and gain lines as the merchant packs. Sending the+ * list replaces whatever the draft currently holds.+ */+ items?: StockTransferItemParams[]+ metadata?: Record<string, unknown>+}++export type StockTransferUpdateParams = Partial<StockTransferCreateParams>++export interface StockTransferReceiveParams {+ /**+ * Omit to receive every line in full. `quantity_received` is the running+ * total for the line, so a second delivery tops it up.+ */+ items?: Array<{+ id: string+ quantity_received: number+ discrepancy_reason?: string+ }>+}++export interface StockTransferCancelParams {+ /**+ * Required once the units have left the source: either they come back+ * (`restock`) or they are written off as lost.+ */+ on_in_transit?: 'restock' | 'write_off'+ reason?: string+}++export interface SupplierCreateParams {+ name: string+ contact_name?: string+ email?: string+ phone?: string+ notes?: string+ address1?: string+ address2?: string+ city?: string+ state_name?: string+ state_code?: string+ country_code?: string+ postal_code?: string+ metadata?: Record<string, unknown>+}++export type SupplierUpdateParams = Partial<SupplierCreateParams>++export interface PurchaseOrderItemParams {+ variant_id: string+ quantity_ordered: number+ /** What the merchant agreed to pay per unit, as a decimal string. */+ unit_cost?: string+}++export interface PurchaseOrderCreateParams {+ supplier_id: stringdestination_location_id: string+ /** Defaults to the store's currency; set it for a foreign-currency order. */+ currency?: string+ /** The day the supplier promised, as `yyyy-mm-dd`. */+ expected_at?: string+ /** The supplier's own order number. */reference?: string- variants: Array<{ variant_id: string; quantity: number }>+ notes?: string+ items?: PurchaseOrderItemParams[]+ metadata?: Record<string, unknown>+}++export type PurchaseOrderUpdateParams = Partial<PurchaseOrderCreateParams>++export interface PurchaseOrderReceiveParams {+ /** Omit to receive every line in full. */+ items?: Array<{ id: string; quantity_received: number }>}export interface RoleCreateParams {diff --git a/packages/admin-sdk/src/types/generated/PurchaseOrder.ts b/packages/admin-sdk/src/types/generated/PurchaseOrder.tsnew file mode 100644index 0000000000..7fdab013e1--- /dev/null+++ b/packages/admin-sdk/src/types/generated/PurchaseOrder.ts@@ -0,0 +1,32 @@+// Typelizer digest 0a0ca8f485894ed53d5e8682b73aa571+//+// DO NOT MODIFY: This file was automatically generated by Typelizer.+import type {PurchaseOrderItem, Supplier, StockLocation} from '@/types'++interface PurchaseOrder {+ id: string;+ number: string;+ status: string;+ currency: string;+ reference: string | null;+ notes: string | null;+ metadata: Record<string, unknown>;+ items_count: number;+ quantity_received_total: number;+ ordered_at: string | null;+ received_at: string | null;+ created_at: string;+ updated_at: string;+ expected_at: string | null;+ quantity_ordered_total: number;+ editable: boolean;+ subtotal: string;+ display_subtotal: string;+ supplier_id: string | null;+ destination_location_id: string | null;+ items?: Array<PurchaseOrderItem>;+ supplier?: Supplier;+ destination_location?: StockLocation;+}++export default PurchaseOrder;diff --git a/packages/admin-sdk/src/types/generated/PurchaseOrderItem.ts b/packages/admin-sdk/src/types/generated/PurchaseOrderItem.tsnew file mode 100644index 0000000000..af6eaf4098--- /dev/null+++ b/packages/admin-sdk/src/types/generated/PurchaseOrderItem.ts@@ -0,0 +1,24 @@+// Typelizer digest fda11dd44513672ebab0b0a20186f8af+//+// DO NOT MODIFY: This file was automatically generated by Typelizer.++interface PurchaseOrderItem {+ id: string;+ quantity_ordered: number;+ quantity_received: number;+ outstanding: number;+ currency: string | null;+ created_at: string;+ updated_at: string;+ unit_cost: string;+ total_cost: string;+ display_unit_cost: string;+ display_total_cost: string;+ purchase_order_id: string | null;+ variant_id: string | null;+ variant_name: string | null;+ variant_sku: string | null;+ options_text: string | null;+}++export default PurchaseOrderItem;diff --git a/packages/admin-sdk/src/types/generated/StockMovement.ts b/packages/admin-sdk/src/types/generated/StockMovement.tsindex 490923524e..d41221fb79 100644--- a/packages/admin-sdk/src/types/generated/StockMovement.ts+++ b/packages/admin-sdk/src/types/generated/StockMovement.ts@@ -1,11 +1,11 @@-// Typelizer digest 04b61f6d684b269303d1b5d3fdc19cb3+// Typelizer digest 11f40ca93a3e53f1ff13e7a160c567c3//// DO NOT MODIFY: This file was automatically generated by Typelizer.interface StockMovement {id: string;quantity: number;- kind: 'received' | 'allocated' | 'shipped' | 'released' | 'adjusted' | null;+ kind: string | null;reason: string | null;created_at: string;updated_at: string;@@ -15,6 +15,9 @@ interface StockMovement {return_id: string | null;exchange_id: string | null;stock_transfer_id: string | null;+ purchase_order_id: string | null;+ unit_cost: string | null;+ display_unit_cost: string | null;}export default StockMovement;diff --git a/packages/admin-sdk/src/types/generated/StockTransfer.ts b/packages/admin-sdk/src/types/generated/StockTransfer.tsindex 8171d855d0..f7e00ac829 100644--- a/packages/admin-sdk/src/types/generated/StockTransfer.ts+++ b/packages/admin-sdk/src/types/generated/StockTransfer.ts@@ -1,17 +1,27 @@-// Typelizer digest 409e958482df1f2a172e9eb5b5aea12f+// Typelizer digest 7359ac791fabee3568d9cec1346c353b//// DO NOT MODIFY: This file was automatically generated by Typelizer.-import type {StockLocation} from '@/types'+import type {StockTransferItem, StockLocation} from '@/types'interface StockTransfer {id: string;number: string;reference: string | null;- metadata: Record<string, unknown>;created_at: string;updated_at: string;- source_location_id: string | null;- destination_location_id: string | null;+ source_location_id: string;+ destination_location_id: string;+ status: string;+ notes: string | null;+ metadata: Record<string, unknown>;+ items_count: number;+ quantity_received_total: number;+ shipped_at: string | null;+ received_at: string | null;+ deleted_at: string | null;+ quantity_shipped_total: number;+ editable: boolean;+ items?: Array<StockTransferItem>;source_location?: StockLocation;destination_location?: StockLocation;}diff --git a/packages/admin-sdk/src/types/generated/StockTransferItem.ts b/packages/admin-sdk/src/types/generated/StockTransferItem.tsnew file mode 100644index 0000000000..1f3e664561--- /dev/null+++ b/packages/admin-sdk/src/types/generated/StockTransferItem.ts@@ -0,0 +1,20 @@+// Typelizer digest 1f8e2626b5f2f91f76e9434dfc0f7e12+//+// DO NOT MODIFY: This file was automatically generated by Typelizer.++interface StockTransferItem {+ id: string;+ quantity_shipped: number;+ quantity_received: number;+ outstanding: number;+ discrepancy_reason: string | null;+ created_at: string;+ updated_at: string;+ stock_transfer_id: string | null;+ variant_id: string | null;+ variant_name: string | null;+ variant_sku: string | null;+ options_text: string | null;+}++export default StockTransferItem;diff --git a/packages/admin-sdk/src/types/generated/Supplier.ts b/packages/admin-sdk/src/types/generated/Supplier.tsnew file mode 100644index 0000000000..924fe1f7be--- /dev/null+++ b/packages/admin-sdk/src/types/generated/Supplier.ts@@ -0,0 +1,26 @@+// Typelizer digest 612de3d818dc99033bbcd1c7821ff3ba+//+// DO NOT MODIFY: This file was automatically generated by Typelizer.++interface Supplier {+ id: string;+ name: string;+ contact_name: string | null;+ email: string | null;+ phone: string | null;+ notes: string | null;+ address1: string | null;+ address2: string | null;+ city: string | null;+ state_name: string | null;+ state_code: string | null;+ country_code: string | null;+ postal_code: string | null;+ metadata: Record<string, unknown>;+ created_at: string;+ updated_at: string;+ deleted_at: string | null;+ purchase_orders_count: number;+}++export default Supplier;diff --git a/packages/admin-sdk/src/types/generated/index.ts b/packages/admin-sdk/src/types/generated/index.tsindex b14e890747..8d82597362 100644--- a/packages/admin-sdk/src/types/generated/index.ts+++ b/packages/admin-sdk/src/types/generated/index.ts@@ -1,4 +1,4 @@-// Typelizer digest 8e9f326c6d4de5aad95b1c992038f528+// Typelizer digest ac55b7b5b7cdc4c080ed9d63cf1e675c//// DO NOT MODIFY: This file was automatically generated by Typelizer.export type { ClaimStatus, DataRequestStatus, ExchangeStatus, FeeKind, FulfillmentItemStatus, FulfillmentStatus, GiftCardStatus, ImportRowStatus, ImportStatus, InvitationStatus, PaymentStatus, PriceListStatus, ProductStatus, ProductSubmissionStatus, ReturnStatus, SellerPayoutStatus, SellerRequirementSubmissionStatus, SellerStatus, SellerTransferStatus, ShippingLabelStatus, StockLocationKind, TaxExemptionCertificateStatus } from './Enums'@@ -97,6 +97,8 @@ export type { default as ProductType } from './ProductType'export type { default as PromotionAction } from './PromotionAction'export type { default as PromotionRule } from './PromotionRule'export type { default as Promotion } from './Promotion'+export type { default as PurchaseOrderItem } from './PurchaseOrderItem'+export type { default as PurchaseOrder } from './PurchaseOrder'export type { default as RefundReason } from './RefundReason'export type { default as Refund } from './Refund'export type { default as ReturnLineItem } from './ReturnLineItem'@@ -118,9 +120,11 @@ export type { default as StockLevel } from './StockLevel'export type { default as StockLocation } from './StockLocation'export type { default as StockMovement } from './StockMovement'export type { default as StockReservation } from './StockReservation'+export type { default as StockTransferItem } from './StockTransferItem'export type { default as StockTransfer } from './StockTransfer'export type { default as StoreCredit } from './StoreCredit'export type { default as Store } from './Store'+export type { default as Supplier } from './Supplier'export type { default as TaxCategory } from './TaxCategory'export type { default as TaxExemptionCertificate } from './TaxExemptionCertificate'export type { default as TaxIdentifier } from './TaxIdentifier'diff --git a/packages/admin-sdk/src/types/index.ts b/packages/admin-sdk/src/types/index.tsindex 67ee2e43c5..49ab7004a3 100644--- a/packages/admin-sdk/src/types/index.ts+++ b/packages/admin-sdk/src/types/index.ts@@ -102,6 +102,8 @@ export type { default as ProductType } from './generated/ProductType'export type { default as Promotion } from './generated/Promotion'export type { default as PromotionAction } from './generated/PromotionAction'export type { default as PromotionRule } from './generated/PromotionRule'+export type { default as PurchaseOrder } from './generated/PurchaseOrder'+export type { default as PurchaseOrderItem } from './generated/PurchaseOrderItem'export type { default as Refund } from './generated/Refund'export type { default as RefundReason } from './generated/RefundReason'export type { default as Return } from './generated/Return'@@ -124,8 +126,10 @@ export type { default as StockLocation } from './generated/StockLocation'export type { default as StockMovement } from './generated/StockMovement'export type { default as StockReservation } from './generated/StockReservation'export type { default as StockTransfer } from './generated/StockTransfer'+export type { default as StockTransferItem } from './generated/StockTransferItem'export type { default as Store } from './generated/Store'export type { default as StoreCredit } from './generated/StoreCredit'+export type { default as Supplier } from './generated/Supplier'export type { default as TaxCategory } from './generated/TaxCategory'export type { default as TaxExemptionCertificate } from './generated/TaxExemptionCertificate'export type { default as TaxIdentifier } from './generated/TaxIdentifier'diff --git a/spree/api/app/serializers/spree/api/v3/admin/purchase_order_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/purchase_order_serializer.rbindex 11abd75fb9..b3b5cc673c 100644--- a/spree/api/app/serializers/spree/api/v3/admin/purchase_order_serializer.rb+++ b/spree/api/app/serializers/spree/api/v3/admin/purchase_order_serializer.rb@@ -19,6 +19,8 @@ module Spreesubtotal: :string,display_subtotal: :string,editable: :boolean,+ ordered_at: 'string | null',+ received_at: 'string | null',metadata: 'Record<string, unknown>'attributes :number, :status, :currency, :reference, :notes, :metadata,diff --git a/spree/api/app/serializers/spree/api/v3/admin/stock_transfer_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/stock_transfer_serializer.rbindex 4bfd44c38f..02e73e5056 100644--- a/spree/api/app/serializers/spree/api/v3/admin/stock_transfer_serializer.rb+++ b/spree/api/app/serializers/spree/api/v3/admin/stock_transfer_serializer.rb@@ -12,6 +12,9 @@ module Spreequantity_shipped_total: :number,quantity_received_total: :number,editable: :boolean,+ shipped_at: 'string | null',+ received_at: 'string | null',+ deleted_at: 'string | null',metadata: 'Record<string, unknown>'attributes :status, :notes, :metadata,diff --git a/spree/api/app/serializers/spree/api/v3/admin/supplier_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/supplier_serializer.rbindex 2c84d02b0e..9fe39f46cf 100644--- a/spree/api/app/serializers/spree/api/v3/admin/supplier_serializer.rb+++ b/spree/api/app/serializers/spree/api/v3/admin/supplier_serializer.rb@@ -18,6 +18,7 @@ module Spreecountry_code: 'string | null',postal_code: 'string | null',purchase_orders_count: :number,+ deleted_at: 'string | null',metadata: 'Record<string, unknown>'attributes :name, :contact_name, :email, :phone, :notes,diff --git a/spree/api/config/initializers/typelizer.rb b/spree/api/config/initializers/typelizer.rbindex fe2a2a5d7d..ea9e6dbf56 100644--- a/spree/api/config/initializers/typelizer.rb+++ b/spree/api/config/initializers/typelizer.rb@@ -26,6 +26,7 @@ Rails.application.config.after_initialize doStockLevel StockMovement StockTransferReport Export Import ImportRowTaxCategory Exchange ExchangeLineItem+ SupplierEvent PurchaseOrderEvent].to_set# Store SDK — no prefix, package provides namespace