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
Added external references to line items, fulfillments and returns (V-3735) (#14897)
Łukasz Adamczyk85afe28b237c
diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yamlindex d1ff0c7097..c80fd4395c 100644--- a/docs/api-reference/admin.yaml+++ b/docs/api-reference/admin.yaml@@ -9933,6 +9933,7 @@ paths:created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'shipping_label_id:+ external_references: {}metadata: {}created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'@@ -10044,6 +10045,7 @@ paths:created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'shipping_label_id:+ external_references: {}metadata: {}created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'@@ -10176,6 +10178,7 @@ paths:created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'shipping_label_id:+ external_references: {}metadata: {}created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'@@ -10279,6 +10282,7 @@ paths:created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'shipping_label_id:+ external_references: {}metadata: {}created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'@@ -10388,6 +10392,7 @@ paths:created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'shipping_label_id:+ external_references: {}metadata: {}created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'@@ -10500,6 +10505,7 @@ paths:created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'shipping_label_id:+ external_references: {}metadata: {}created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'@@ -10617,6 +10623,7 @@ paths:created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'shipping_label_id:+ external_references: {}metadata: {}created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'@@ -10718,6 +10725,7 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1deliveries: []+ external_references: {}metadata: {}created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'@@ -16945,6 +16953,7 @@ paths:created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'digital_links: []+ external_references: {}metadata: {}price_source:created_at: '2026-01-15T12:00:00.000Z'@@ -17053,6 +17062,7 @@ paths:created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'digital_links: []+ external_references: {}metadata: {}price_source:created_at: '2026-01-15T12:00:00.000Z'@@ -17175,6 +17185,7 @@ paths:created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'digital_links: []+ external_references: {}metadata: {}price_source:created_at: '2026-01-15T12:00:00.000Z'@@ -17278,6 +17289,7 @@ paths:created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'digital_links: []+ external_references: {}metadata: {}price_source:created_at: '2026-01-15T12:00:00.000Z'@@ -19121,6 +19133,7 @@ paths:received_at:refunded_at:canceled_at:+ external_references: {}memo: Item did not fitmetadata: {}created_at: '2026-01-15T12:00:00.000Z'@@ -19276,6 +19289,7 @@ paths:received_at:refunded_at:canceled_at:+ external_references: {}memo: Item did not fitmetadata: {}created_at: '2026-01-15T12:00:00.000Z'@@ -19355,6 +19369,7 @@ paths:received_at:refunded_at:canceled_at:+ external_references: {}memo: Too smallmetadata: {}created_at: '2026-01-15T12:00:00.000Z'@@ -19437,6 +19452,7 @@ paths:received_at:refunded_at:canceled_at:+ external_references: {}memo: Customer shipped it back with a tracking numbermetadata: {}created_at: '2026-01-15T12:00:00.000Z'@@ -19509,6 +19525,7 @@ paths:received_at: '2026-01-15T12:00:00Z'refunded_at:canceled_at:+ external_references: {}memo: Item did not fitmetadata: {}created_at: '2026-01-15T12:00:00.000Z'@@ -19580,6 +19597,7 @@ paths:received_at: '2026-01-15T12:00:00Z'refunded_at: '2026-01-15T12:00:00Z'canceled_at:+ external_references: {}memo: Item did not fitmetadata: {}created_at: '2026-01-15T12:00:00.000Z'@@ -19651,6 +19669,7 @@ paths:received_at:refunded_at:canceled_at: '2026-01-15T12:00:00Z'+ external_references: {}memo: |-Item did not fitCustomer changed their mind@@ -56887,6 +56906,8 @@ components:type: arrayitems:"$ref": "#/components/schemas/TaxLine"+ external_references:+ type: objectmetadata:type: objectcreated_at:@@ -56939,6 +56960,7 @@ components:- delivered_at- items- deliveries+ - external_references- metadata- created_at- updated_at@@ -57930,6 +57952,8 @@ components:type: arrayitems:"$ref": "#/components/schemas/TaxLine"+ external_references:+ type: objectmetadata:type: objectprice_source:@@ -57987,6 +58011,7 @@ components:- thumbnail_url- option_values- digital_links+ - external_references- metadata- price_source- created_at@@ -62932,6 +62957,8 @@ components:type: arrayitems:"$ref": "#/components/schemas/ReturnLineItem"+ external_references:+ type: objectmemo:type: stringnullable: true@@ -62995,6 +63022,7 @@ components:- received_at- refunded_at- canceled_at+ - external_references- memo- metadata- created_at@@ -73286,6 +73314,13 @@ components:FulfillmentCreateParams:type: objectproperties:+ external_references:+ type: object+ additionalProperties: true+ description: 'Identities the record has in external systems, keyed by system:+ the same `{ system: external_id }` map the Admin API renders, so what+ you read can be sent straight back. Systems you do not name keep the reference+ they have. A list of `{ system, external_id }` entries is accepted too.'stock_location_id:type: stringdescription: The location the fulfillment ships from. On update, moving@@ -73401,6 +73436,13 @@ components:FulfillmentUpdateParams:type: objectproperties:+ external_references:+ type: object+ additionalProperties: true+ description: 'Identities the record has in external systems, keyed by system:+ the same `{ system: external_id }` map the Admin API renders, so what+ you read can be sent straight back. Systems you do not name keep the reference+ they have. A list of `{ system, external_id }` entries is accepted too.'stock_location_id:type: stringdescription: The location the fulfillment ships from. On update, moving@@ -73630,6 +73672,13 @@ components:LineItemCreateParams:type: objectproperties:+ external_references:+ type: object+ additionalProperties: true+ description: 'Identities the record has in external systems, keyed by system:+ the same `{ system: external_id }` map the Admin API renders, so what+ you read can be sent straight back. Systems you do not name keep the reference+ they have. A list of `{ system, external_id }` entries is accepted too.'variant_id:type: stringquantity:@@ -73653,6 +73702,13 @@ components:LineItemUpdateParams:type: objectproperties:+ external_references:+ type: object+ additionalProperties: true+ description: 'Identities the record has in external systems, keyed by system:+ the same `{ system: external_id }` map the Admin API renders, so what+ you read can be sent straight back. Systems you do not name keep the reference+ they have. A list of `{ system, external_id }` entries is accepted too.'quantity:type: integerdescription: Defaults to 1 when adding an item.@@ -76121,6 +76177,13 @@ components:ReturnCreateParams:type: objectproperties:+ external_references:+ type: object+ additionalProperties: true+ description: 'Identities the record has in external systems, keyed by system:+ the same `{ system: external_id }` map the Admin API renders, so what+ you read can be sent straight back. Systems you do not name keep the reference+ they have. A list of `{ system, external_id }` entries is accepted too.'items:type: arrayitems:@@ -76184,6 +76247,13 @@ components:ReturnUpdateParams:type: objectproperties:+ external_references:+ type: object+ additionalProperties: true+ description: 'Identities the record has in external systems, keyed by system:+ the same `{ system: external_id }` map the Admin API renders, so what+ you read can be sent straight back. Systems you do not name keep the reference+ they have. A list of `{ system, external_id }` entries is accepted too.'stock_location_id:type: stringdescription: Where the goods come back to. Defaults to the location thatdiff --git a/docs/developer/core-concepts/external-references.mdx b/docs/developer/core-concepts/external-references.mdxindex 94bfca2680..c9da96e43f 100644--- a/docs/developer/core-concepts/external-references.mdx+++ b/docs/developer/core-concepts/external-references.mdx@@ -60,6 +60,9 @@ The system does not have to be a connected [integration](/developer/providers/ov| Stock locations | ERP warehouse code || Stock levels | ERP inventory record || Orders | ERP sales order number, written back after the order is sent there |+| Line items | The order line's key in the system the order was sent to, which that system's shipments and refunds name |+| Fulfillments | The shipment's key in the system that shipped it, so a repeated update changes the tracking instead of shipping twice |+| Returns | The refund's key in the system it came from, so a repeated message never refunds twice || Companies | ERP or CRM account number (B2B) || Sellers | Payout provider account, recorded by the [payout provider](/developer/providers/payouts) itself |diff --git a/packages/admin-sdk/src/types/generated/Fulfillment.ts b/packages/admin-sdk/src/types/generated/Fulfillment.tsindex 3aa0d4c3ae..c8a356d550 100644--- a/packages/admin-sdk/src/types/generated/Fulfillment.ts+++ b/packages/admin-sdk/src/types/generated/Fulfillment.ts@@ -1,4 +1,4 @@-// Typelizer digest f1296ae1785d1e0631ccd2cf877e60f5+// Typelizer digest 3685ae389170e27b399962a159f71382//// DO NOT MODIFY: This file was automatically generated by Typelizer.import type {Delivery, DeliveryMethod, StockLocation, DeliveryRate, TaxLine, ShippingLabel, FulfillmentItem, Order, FulfillmentStatus} from '@/types'@@ -27,6 +27,7 @@ interface Fulfillment {stock_location?: StockLocation;delivery_rates?: Array<DeliveryRate>;tax_lines?: Array<TaxLine>;+ external_references: Record<string, string>;metadata: Record<string, unknown>;created_at: string;updated_at: string;diff --git a/packages/admin-sdk/src/types/generated/LineItem.ts b/packages/admin-sdk/src/types/generated/LineItem.tsindex a79601810c..9ffc42f4e9 100644--- a/packages/admin-sdk/src/types/generated/LineItem.ts+++ b/packages/admin-sdk/src/types/generated/LineItem.ts@@ -1,4 +1,4 @@-// Typelizer digest e677dbe6c3a3f2067dbf6c3c24267c4b+// Typelizer digest 40364c1ff116729227cf89d3115714d7//// DO NOT MODIFY: This file was automatically generated by Typelizer.import type {Seller, OptionValue, DigitalLink, TaxLine, Variant, TaxCategory, CurrencyCode} from '@/types'@@ -37,6 +37,7 @@ interface LineItem {option_values: Array<OptionValue>;digital_links: Array<DigitalLink>;tax_lines?: Array<TaxLine>;+ external_references: Record<string, string>;metadata: Record<string, unknown>;price_source: string | null;created_at: string;diff --git a/packages/admin-sdk/src/types/generated/Return.ts b/packages/admin-sdk/src/types/generated/Return.tsindex 6afaf2a331..d85f2d5309 100644--- a/packages/admin-sdk/src/types/generated/Return.ts+++ b/packages/admin-sdk/src/types/generated/Return.ts@@ -1,4 +1,4 @@-// Typelizer digest b11c05b949749b2f487202329a910134+// Typelizer digest 6448d004d7a749aba6bf142762d627e2//// DO NOT MODIFY: This file was automatically generated by Typelizer.import type {ReturnReason, ReturnLineItem, Actor, Order, StockLocation, Refund, ShippingLabel, Delivery, ReturnStatus, ActorKind} from '@/types'@@ -17,6 +17,7 @@ interface Return {canceled_at: string | null;reason?: ReturnReason;return_line_items?: Array<ReturnLineItem>;+ external_references: Record<string, string>;memo: string | null;metadata: Record<string, unknown>;created_at: string;diff --git a/packages/admin-sdk/src/types/params/FulfillmentCreateParams.ts b/packages/admin-sdk/src/types/params/FulfillmentCreateParams.tsindex 14485fd2e0..b3b21cbd0b 100644--- a/packages/admin-sdk/src/types/params/FulfillmentCreateParams.ts+++ b/packages/admin-sdk/src/types/params/FulfillmentCreateParams.ts@@ -1,6 +1,13 @@// This file is auto-generated from the request schemas in docs/api-reference by `pnpm generate:params`. Do not edit directly.export type FulfillmentCreateParams = {+ /**+ * Identities the record has in external systems, keyed by system: the same+ * `{ system: external_id }` map the Admin API renders, so what you read can be sent straight+ * back. Systems you do not name keep the reference they have. A list of `{ system, external_id }`+ * entries is accepted too.+ */+ external_references?: Record<string, unknown>/*** The location the fulfillment ships from. On update, moving it re-prices the fulfillment against* that location's rates.diff --git a/packages/admin-sdk/src/types/params/FulfillmentUpdateParams.ts b/packages/admin-sdk/src/types/params/FulfillmentUpdateParams.tsindex 9c4173e1ad..068508f4d6 100644--- a/packages/admin-sdk/src/types/params/FulfillmentUpdateParams.ts+++ b/packages/admin-sdk/src/types/params/FulfillmentUpdateParams.ts@@ -1,6 +1,13 @@// This file is auto-generated from the request schemas in docs/api-reference by `pnpm generate:params`. Do not edit directly.export type FulfillmentUpdateParams = {+ /**+ * Identities the record has in external systems, keyed by system: the same+ * `{ system: external_id }` map the Admin API renders, so what you read can be sent straight+ * back. Systems you do not name keep the reference they have. A list of `{ system, external_id }`+ * entries is accepted too.+ */+ external_references?: Record<string, unknown>/*** The location the fulfillment ships from. On update, moving it re-prices the fulfillment against* that location's rates.diff --git a/packages/admin-sdk/src/types/params/LineItemCreateParams.ts b/packages/admin-sdk/src/types/params/LineItemCreateParams.tsindex 221890429a..a6e534e147 100644--- a/packages/admin-sdk/src/types/params/LineItemCreateParams.ts+++ b/packages/admin-sdk/src/types/params/LineItemCreateParams.ts@@ -1,6 +1,13 @@// This file is auto-generated from the request schemas in docs/api-reference by `pnpm generate:params`. Do not edit directly.export type LineItemCreateParams = {+ /**+ * Identities the record has in external systems, keyed by system: the same+ * `{ system: external_id }` map the Admin API renders, so what you read can be sent straight+ * back. Systems you do not name keep the reference they have. A list of `{ system, external_id }`+ * entries is accepted too.+ */+ external_references?: Record<string, unknown>variant_id: string/** Defaults to 1 when adding an item. */quantity?: numberdiff --git a/packages/admin-sdk/src/types/params/LineItemUpdateParams.ts b/packages/admin-sdk/src/types/params/LineItemUpdateParams.tsindex 61d3576963..477ce9834b 100644--- a/packages/admin-sdk/src/types/params/LineItemUpdateParams.ts+++ b/packages/admin-sdk/src/types/params/LineItemUpdateParams.ts@@ -1,6 +1,13 @@// This file is auto-generated from the request schemas in docs/api-reference by `pnpm generate:params`. Do not edit directly.export type LineItemUpdateParams = {+ /**+ * Identities the record has in external systems, keyed by system: the same+ * `{ system: external_id }` map the Admin API renders, so what you read can be sent straight+ * back. Systems you do not name keep the reference they have. A list of `{ system, external_id }`+ * entries is accepted too.+ */+ external_references?: Record<string, unknown>/** Defaults to 1 when adding an item. */quantity?: number/**diff --git a/packages/admin-sdk/src/types/params/ReturnCreateParams.ts b/packages/admin-sdk/src/types/params/ReturnCreateParams.tsindex a872cbb49b..d8c32a3a43 100644--- a/packages/admin-sdk/src/types/params/ReturnCreateParams.ts+++ b/packages/admin-sdk/src/types/params/ReturnCreateParams.ts@@ -1,6 +1,13 @@// This file is auto-generated from the request schemas in docs/api-reference by `pnpm generate:params`. Do not edit directly.export type ReturnCreateParams = {+ /**+ * Identities the record has in external systems, keyed by system: the same+ * `{ system: external_id }` map the Admin API renders, so what you read can be sent straight+ * back. Systems you do not name keep the reference they have. A list of `{ system, external_id }`+ * entries is accepted too.+ */+ external_references?: Record<string, unknown>/** Fulfilled units coming back, and how many of each. */items: {fulfillment_item_id: stringdiff --git a/packages/admin-sdk/src/types/params/ReturnUpdateParams.ts b/packages/admin-sdk/src/types/params/ReturnUpdateParams.tsindex 811676fa23..0197323704 100644--- a/packages/admin-sdk/src/types/params/ReturnUpdateParams.ts+++ b/packages/admin-sdk/src/types/params/ReturnUpdateParams.ts@@ -1,6 +1,13 @@// This file is auto-generated from the request schemas in docs/api-reference by `pnpm generate:params`. Do not edit directly.export type ReturnUpdateParams = {+ /**+ * Identities the record has in external systems, keyed by system: the same+ * `{ system: external_id }` map the Admin API renders, so what you read can be sent straight+ * back. Systems you do not name keep the reference they have. A list of `{ system, external_id }`+ * entries is accepted too.+ */+ external_references?: Record<string, unknown>/** Where the goods come back to. Defaults to the location that shipped them. */stock_location_id?: string/** One of the store's return reasons. */diff --git a/packages/admin-sdk/src/zod/generated/Fulfillment.ts b/packages/admin-sdk/src/zod/generated/Fulfillment.tsindex 719d180d8d..6447cdb314 100644--- a/packages/admin-sdk/src/zod/generated/Fulfillment.ts+++ b/packages/admin-sdk/src/zod/generated/Fulfillment.ts@@ -33,6 +33,7 @@ export const FulfillmentSchema = z.object({stock_location: StockLocationSchema.optional(),delivery_rates: z.array(DeliveryRateSchema).optional(),tax_lines: z.array(TaxLineSchema).optional(),+ external_references: z.record(z.string(), z.string()),metadata: z.record(z.string(), z.unknown()),created_at: z.string(),updated_at: z.string(),diff --git a/packages/admin-sdk/src/zod/generated/LineItem.ts b/packages/admin-sdk/src/zod/generated/LineItem.tsindex e65f23bb0e..623336dc2b 100644--- a/packages/admin-sdk/src/zod/generated/LineItem.ts+++ b/packages/admin-sdk/src/zod/generated/LineItem.ts@@ -32,6 +32,7 @@ export const LineItemSchema = z.object({get option_values() { return z.array(OptionValueSchema); },digital_links: z.array(DigitalLinkSchema),tax_lines: z.array(TaxLineSchema).optional(),+ external_references: z.record(z.string(), z.string()),metadata: z.record(z.string(), z.unknown()),price_source: z.string().nullable(),created_at: z.string(),diff --git a/packages/admin-sdk/src/zod/generated/Return.ts b/packages/admin-sdk/src/zod/generated/Return.tsindex 2ecff51da2..f7b7070d3e 100644--- a/packages/admin-sdk/src/zod/generated/Return.ts+++ b/packages/admin-sdk/src/zod/generated/Return.ts@@ -23,6 +23,7 @@ export const ReturnSchema = z.object({canceled_at: z.string().nullable(),reason: ReturnReasonSchema.optional(),return_line_items: z.array(ReturnLineItemSchema).optional(),+ external_references: z.record(z.string(), z.string()),memo: z.string().nullable(),metadata: z.record(z.string(), z.unknown()),created_at: z.string(),diff --git a/spree/api/app/controllers/spree/api/v3/admin/concerns/external_references.rb b/spree/api/app/controllers/spree/api/v3/admin/concerns/external_references.rbindex 2b92c82a5e..4f0d27a53c 100644--- a/spree/api/app/controllers/spree/api/v3/admin/concerns/external_references.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/concerns/external_references.rb@@ -75,6 +75,9 @@ module Spree@resource = existingauthorize_resource!(@resource, :update)+ # This runs before a nested controller's own parent check, and+ # rendering here ends the request before it would run.+ authorize_parent!(@parent) if @parent.present?normalize_upsert_params!updateenddiff --git a/spree/api/app/controllers/spree/api/v3/admin/orders/fulfillments_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/orders/fulfillments_controller.rbindex a149acb0ef..1e537edd29 100644--- a/spree/api/app/controllers/spree/api/v3/admin/orders/fulfillments_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/orders/fulfillments_controller.rb@@ -15,6 +15,7 @@ module Spreescoped_resource :fulfillmentsrequest_params :fulfillment do |body|+ body.external_referencesbody.attribute :stock_location_id, :id,required: true, on: :create,description: "The location the fulfillment ships from. On update, moving it re-prices the fulfillment against that location's rates."@@ -140,6 +141,13 @@ module Spreeparams.permit(*permitted_attributes)end+ # A replayed create runs the update action, which takes neither the+ # units to move nor how the parcel was registered: those only shape+ # a new fulfillment.+ def normalize_upsert_params!+ %i[items source_fulfillment_id delivery_method_id cost status metadata].each { |key| params.delete(key) }+ end+private# Forcing past a stock or payment guard is the operator's call.diff --git a/spree/api/app/controllers/spree/api/v3/admin/orders/items_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/orders/items_controller.rbindex 088515b33e..9b9a1449c9 100644--- a/spree/api/app/controllers/spree/api/v3/admin/orders/items_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/orders/items_controller.rb@@ -5,6 +5,7 @@ module Spreemodule Ordersclass ItemsController < BaseControllerrequest_params :line_item do |body|+ body.external_referencesbody.attribute :variant_id, :id, required: true, only: :createbody.attribute :quantity, :integer, example: 1, description: 'Defaults to 1 when adding an item.'body.attribute :price, :decimal,diff --git a/spree/api/app/controllers/spree/api/v3/admin/orders/returns_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/orders/returns_controller.rbindex 34e50edc65..b60325c2fb 100644--- a/spree/api/app/controllers/spree/api/v3/admin/orders/returns_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/orders/returns_controller.rb@@ -20,6 +20,7 @@ module Spreescoped_resource :ordersrequest_params :return do |body|+ body.external_referencesbody.attribute :items, :array,required: true, on: :create,only: :create,@@ -89,6 +90,12 @@ module Spreeparams.permit(*permitted_attributes)end+ # A replayed create runs the update action, and the units coming+ # back are fixed once the return exists.+ def normalize_upsert_params!+ params.delete(:items)+ end+private# The ids are resolved through the store rather than assigned raw,diff --git a/spree/api/app/controllers/spree/api/v3/admin/orders_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/orders_controller.rbindex b30b10d66e..f6270c105f 100644--- a/spree/api/app/controllers/spree/api/v3/admin/orders_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/orders_controller.rb@@ -295,8 +295,8 @@ module Spree# reads it — otherwise a page of orders costs a query per# fulfillment for a field that is nil on every parcel order.[:customer, :channel, :seller, :external_references, :cancel_reason,- :market, { fulfillments: :selected_delivery_rate },- { line_items: [{ variant: :prices }, { price_list: :catalog }] },+ :market, { fulfillments: %i[selected_delivery_rate external_references] },+ { line_items: [:external_references, { variant: :prices }, { price_list: :catalog }] },{ po_document_attachment: :blob }]enddiff --git a/spree/api/app/serializers/spree/api/v3/admin/fulfillment_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/fulfillment_serializer.rbindex c3546e7a61..9dd0b63454 100644--- a/spree/api/app/serializers/spree/api/v3/admin/fulfillment_serializer.rb+++ b/spree/api/app/serializers/spree/api/v3/admin/fulfillment_serializer.rb@@ -3,6 +3,8 @@ module Spreemodule V3module Adminclass FulfillmentSerializer < V3::FulfillmentSerializer+ include Concerns::ExternalReferencesAttribute+without_formatted_money# The Admin API has no guest gating — money fields inherited from thediff --git a/spree/api/app/serializers/spree/api/v3/admin/line_item_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/line_item_serializer.rbindex eaab44d093..596d70ae7f 100644--- a/spree/api/app/serializers/spree/api/v3/admin/line_item_serializer.rb+++ b/spree/api/app/serializers/spree/api/v3/admin/line_item_serializer.rb@@ -5,6 +5,8 @@ module Spree# Admin API Line Item Serializer# Extends the store serializer with metadata visibilityclass LineItemSerializer < V3::LineItemSerializer+ include Concerns::ExternalReferencesAttribute+without_formatted_money# The Admin API has no guest gating — money fields inherited from thediff --git a/spree/api/app/serializers/spree/api/v3/admin/return_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/return_serializer.rbindex 73af5dbf9c..7f9f233973 100644--- a/spree/api/app/serializers/spree/api/v3/admin/return_serializer.rb+++ b/spree/api/app/serializers/spree/api/v3/admin/return_serializer.rb@@ -5,6 +5,8 @@ module Spreemodule V3module Adminclass ReturnSerializer < V3::ReturnSerializer+ include Concerns::ExternalReferencesAttribute+without_formatted_moneytypelize memo: [:string, nullable: true],diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/fulfillments_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/fulfillments_controller_spec.rbindex c1cb6309cf..55fd48f36b 100644--- a/spree/api/spec/controllers/spree/api/v3/admin/orders/fulfillments_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/fulfillments_controller_spec.rb@@ -32,6 +32,35 @@ RSpec.describe Spree::Api::V3::Admin::Orders::FulfillmentsController, type: :conexpect(json_response['number']).to eq(shipment.number)expect(json_response['status']).to eq(shipment.state)end++ it 'finds the fulfillment by the key the shipping system knows it by' do+ shipment.set_external_id('wms', 'SHIP-1')++ get :show, params: { order_id: order.prefixed_id, id: 'external:wms:SHIP-1' }, as: :json++ expect(response).to have_http_status(:ok)+ expect(json_response['id']).to eq(shipment.prefixed_id)+ expect(json_response['external_references']).to eq('wms' => 'SHIP-1')+ end++ # A replayed create becomes an update, which must not receive the keys+ # that only shape a new fulfillment.+ it 'updates rather than re-creating when a shipping system replays a known key' do+ shipment.set_external_id('wms', 'SHIP-1')++ expect do+ post :create, params: {+ order_id: order.prefixed_id, stock_location_id: shipment.stock_location.prefixed_id, tracking: 'TRACK-9',+ status: 'shipped', cost: '9.99', items: [{ item_id: order.line_items.first.prefixed_id, quantity: 1 }],+ external_references: { wms: 'SHIP-1' }+ }, as: :json+ end.not_to change(Spree::Fulfillment, :count)++ expect(response).to have_http_status(:ok)+ shipment.reload+ expect(shipment.tracking).to eq('TRACK-9')+ expect(shipment.status).to eq('unfulfilled')+ endenddescribe 'POST #create' dodiff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/items_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/items_controller_spec.rbindex e9de191fdf..985290d45c 100644--- a/spree/api/spec/controllers/spree/api/v3/admin/orders/items_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/items_controller_spec.rb@@ -154,6 +154,35 @@ RSpec.describe Spree::Api::V3::Admin::Orders::ItemsController, type: :controllerexpect(line_item.reload.quantity).to eq(5)end+ it 'addresses the line item by the key the order system knows it by' do+ line_item.set_external_id('oms', 'LINE-1')++ patch :update, params: { order_id: order.prefixed_id, id: 'external:oms:LINE-1', quantity: 3 }, as: :json++ expect(response).to have_http_status(:ok)+ expect(line_item.reload.quantity).to eq(3)+ expect(json_response['external_references']).to eq('oms' => 'LINE-1')+ end++ it 'checks access to the order before a known key turns a create into an update' do+ line_item.set_external_id('oms', 'LINE-1')+ allow(controller).to receive(:authorize_parent!).and_raise(CanCan::AccessDenied)++ post :create, params: { order_id: order.prefixed_id, variant_id: variant.prefixed_id, quantity: 5,+ external_references: { oms: 'LINE-1' } }, as: :json++ expect(response).to have_http_status(:forbidden)+ expect(line_item.reload.quantity).to eq(1)+ end++ it 'records the key a connector sends' do+ patch :update, params: { order_id: order.prefixed_id, id: line_item.prefixed_id,+ external_references: { oms: 'LINE-2' } }, as: :json++ expect(response).to have_http_status(:ok)+ expect(line_item.reload.external_id_for('oms')).to eq('LINE-2')+ end+context 'with a negotiated price' dosubject { patch :update, params: { order_id: order.prefixed_id, id: line_item.prefixed_id, price: '7.20' }, as: :json }diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/returns_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/returns_controller_spec.rbindex 8f9804d4d6..0ef8968c11 100644--- a/spree/api/spec/controllers/spree/api/v3/admin/orders/returns_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/returns_controller_spec.rb@@ -78,6 +78,33 @@ RSpec.describe Spree::Api::V3::Admin::Orders::ReturnsController, type: :controllexpect(json_response['id']).to eq(return_record.prefixed_id)expect(json_response['refund_total']).to be_presentend++ it 'finds the return by the key the refunding system knows it by' do+ return_record = create_return+ return_record.set_external_id('oms', 'REFUND-1')++ get :show, params: { order_id: order.prefixed_id, id: 'external:oms:REFUND-1' }, as: :json++ expect(response).to have_http_status(:ok)+ expect(json_response['id']).to eq(return_record.prefixed_id)+ expect(json_response['external_references']).to eq('oms' => 'REFUND-1')+ end++ it 'updates rather than re-creating when the refunding system replays a known key' do+ return_record = create_return+ return_record.set_external_id('oms', 'REFUND-1')++ expect do+ post :create, params: {+ order_id: order.prefixed_id, memo: 'Replayed',+ items: [{ fulfillment_item_id: fulfillment_item.prefixed_id, quantity: 1 }],+ external_references: { oms: 'REFUND-1' }+ }, as: :json+ end.not_to change(Spree::Return, :count)++ expect(response).to have_http_status(:ok)+ expect(return_record.reload.memo).to eq('Replayed')+ endenddescribe 'PATCH #update' dodiff --git a/spree/core/app/models/concerns/spree/has_external_references.rb b/spree/core/app/models/concerns/spree/has_external_references.rbindex 86af6c5077..754051e089 100644--- a/spree/core/app/models/concerns/spree/has_external_references.rb+++ b/spree/core/app/models/concerns/spree/has_external_references.rb@@ -11,13 +11,14 @@ module Spree# Scope-friendly so controllers can chain it onto an already store-scoped# relation: `current_store.products.with_external_id('erp', 'MAT-100')`.# Scoping the lookup to the store is the caller's job, exactly as with any- # other id coming off a request.+ # other id coming off a request. A subquery rather than a join, so a+ # relation that also preloads `external_references` still loads every+ # key, not only the matched one.scope :with_external_id, lambda { |system, external_id|- joins(:external_references).where(- spree_external_references: {- system: Spree::ExternalReference.normalize_system(system),- external_id: external_id.to_s.strip- }+ where(+ id: Spree::ExternalReference.for_system(system).+ where(resource_type: polymorphic_name, external_id: external_id.to_s.strip).+ select(:resource_id))}enddiff --git a/spree/core/app/models/spree/cart.rb b/spree/core/app/models/spree/cart.rbindex 7b466df004..f26c0a49ea 100644--- a/spree/core/app/models/spree/cart.rb+++ b/spree/core/app/models/spree/cart.rb@@ -179,6 +179,7 @@ module Spreefulfillment_ids = fulfillments.map(&:id)DeliveryRate.where(fulfillment_id: fulfillment_ids).delete_all+ Spree::ExternalReference.where(resource_type: Spree::Fulfillment.name, resource_id: fulfillment_ids).delete_all if fulfillment_ids.any?fulfillments.delete_allfulfillment_items.resetreturn fulfillments.reload unless can_propose_deliveries?diff --git a/spree/core/app/models/spree/fulfillment.rb b/spree/core/app/models/spree/fulfillment.rbindex 7ea75af444..78a7917f9e 100644--- a/spree/core/app/models/spree/fulfillment.rb+++ b/spree/core/app/models/spree/fulfillment.rb@@ -5,6 +5,7 @@ module Spreeinclude Spree::DerivedNumberderives_number infix: 'F'include Spree::HasCustomFields+ include Spree::HasExternalReferencesinclude Spree::Metadatainclude Spree::StorePreferencesif defined?(Spree::Security::Shipments)diff --git a/spree/core/app/models/spree/line_item.rb b/spree/core/app/models/spree/line_item.rbindex d854b19fce..98b6cf12ba 100644--- a/spree/core/app/models/spree/line_item.rb+++ b/spree/core/app/models/spree/line_item.rb@@ -3,6 +3,7 @@ module Spreehas_prefix_id :li # Spree-specific: line iteminclude Spree::HasCustomFields+ include Spree::HasExternalReferencesinclude Spree::Metadatapublishes_lifecycle_eventsdiff --git a/spree/core/app/models/spree/order.rb b/spree/core/app/models/spree/order.rbindex b3aee4f6bd..f89e33bd78 100644--- a/spree/core/app/models/spree/order.rb+++ b/spree/core/app/models/spree/order.rb@@ -921,6 +921,9 @@ module Spreeshipment_ids = fulfillments.map(&:id)DeliveryRate.where(fulfillment_id: shipment_ids).delete_all+ # A connector's key for a fulfillment that is going away would otherwise+ # outlive it and block the key from naming the rebuilt one.+ Spree::ExternalReference.where(resource_type: Spree::Fulfillment.name, resource_id: shipment_ids).delete_all if shipment_ids.any?fulfillments.delete_alldiff --git a/spree/core/app/models/spree/return.rb b/spree/core/app/models/spree/return.rbindex 95c5987e4a..ea880bdfe8 100644--- a/spree/core/app/models/spree/return.rb+++ b/spree/core/app/models/spree/return.rb@@ -19,6 +19,7 @@ module Spreeinclude Spree::SingleStoreResourceinclude Spree::HasStatusinclude Spree::HasCustomFields+ include Spree::HasExternalReferencesinclude Spree::Metadatainclude Spree::PostSale::Taxationdiff --git a/spree/core/spec/models/concerns/spree/has_external_references_spec.rb b/spree/core/spec/models/concerns/spree/has_external_references_spec.rbindex d445aeb39a..b79ecf7c08 100644--- a/spree/core/spec/models/concerns/spree/has_external_references_spec.rb+++ b/spree/core/spec/models/concerns/spree/has_external_references_spec.rb@@ -84,6 +84,15 @@ RSpec.describe Spree::HasExternalReferences doexpect(store.products.with_external_id('erp', 'MAT-100')).to be_emptyexpect(other_store.products.with_external_id('erp', 'MAT-100').take).to eq(other_product)end++ it 'leaves the found record with every key when references are preloaded' do+ product.set_external_id('erp', 'MAT-100')+ product.set_external_id('pim', 'SKU-1')++ found = Spree::Product.includes(:external_references).with_external_id('erp', 'MAT-100').take++ expect(found.external_references.map(&:system)).to contain_exactly('erp', 'pim')+ endenddescribe '#assign_external_references' dodiff --git a/spree/core/spec/models/spree/line_item_spec.rb b/spree/core/spec/models/spree/line_item_spec.rbindex f292fa352d..6c723bd87e 100644--- a/spree/core/spec/models/spree/line_item_spec.rb+++ b/spree/core/spec/models/spree/line_item_spec.rb@@ -883,4 +883,11 @@ describe Spree::LineItem, type: :model doendendend++ describe 'external references' do+ let(:other_store) { create(:store) }+ let(:record) { create(:order_with_line_items, line_items_count: 1, store: other_store).line_items.first }++ it_behaves_like 'files external references under its store'+ endenddiff --git a/spree/core/spec/models/spree/order_spec.rb b/spree/core/spec/models/spree/order_spec.rbindex 95ad4ff2fb..1f12239e82 100644--- a/spree/core/spec/models/spree/order_spec.rb+++ b/spree/core/spec/models/spree/order_spec.rb@@ -891,6 +891,16 @@ describe Spree::Order, type: :model doenddescribe '#rebuild_fulfillments!' do+ it 'drops the external references of the fulfillments it replaces' do+ order = create(:order_ready_to_ship, store: store)+ old = order.fulfillments.first+ old.set_external_id('wms', 'SHIP-1')++ order.rebuild_fulfillments!++ expect(Spree::ExternalReference.where(resource_type: 'Spree::Fulfillment', resource_id: old.id)).to be_empty+ end+context 'has unassociated inventory units' dolet!(:inventory_unit) { create(:fulfillment_item, order: subject) }diff --git a/spree/core/spec/models/spree/return_spec.rb b/spree/core/spec/models/spree/return_spec.rbindex dda9df0401..eb832eb211 100644--- a/spree/core/spec/models/spree/return_spec.rb+++ b/spree/core/spec/models/spree/return_spec.rb@@ -155,4 +155,11 @@ RSpec.describe Spree::Return doexpect { return_record.reload.to_package }.not_to change { fulfillment_item.reload.quantity }endend++ describe 'external references' do+ let(:other_store) { create(:store) }+ let(:record) { create(:return, store: other_store, order: create(:shipped_order, store: other_store)) }++ it_behaves_like 'files external references under its store'+ endenddiff --git a/spree/core/spec/models/spree/shipment_spec.rb b/spree/core/spec/models/spree/shipment_spec.rbindex 4a8747e823..ed8629a3f9 100644--- a/spree/core/spec/models/spree/shipment_spec.rb+++ b/spree/core/spec/models/spree/shipment_spec.rb@@ -1065,4 +1065,11 @@ describe Spree::Fulfillment, type: :model doexpect(shipment.reload.tracking).to eq('OTHER-1')endend++ describe 'external references' do+ let(:other_store) { create(:store) }+ let(:record) { create(:order_ready_to_ship, store: other_store).fulfillments.first }++ it_behaves_like 'files external references under its store'+ endenddiff --git a/spree/core/spec/support/shared_examples/external_references.rb b/spree/core/spec/support/shared_examples/external_references.rbnew file mode 100644index 0000000000..5571c8d2b5--- /dev/null+++ b/spree/core/spec/support/shared_examples/external_references.rb@@ -0,0 +1,11 @@+# For a model that opts in to Spree::HasExternalReferences: its references+# are filed under the store the record belongs to. The including spec gives+# `record` (in `other_store`) and `other_store`.+shared_examples 'files external references under its store' do+ it "files the reference under the record's store" do+ reference = record.set_external_id('connector', 'KEY-1')++ expect(reference.store).to eq(other_store)+ expect(record.class.with_external_id('connector', 'KEY-1')).to contain_exactly(record)+ end+end