Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

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.yaml
index 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_UkLWZg9DAJ
quantity: 1
deliveries: []
+ 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 fit
metadata: {}
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 fit
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
@@ -19355,6 +19369,7 @@ paths:
received_at:
refunded_at:
canceled_at:
+ external_references: {}
memo: Too small
metadata: {}
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 number
metadata: {}
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 fit
metadata: {}
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 fit
metadata: {}
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 fit
Customer changed their mind
@@ -56887,6 +56906,8 @@ components:
type: array
items:
"$ref": "#/components/schemas/TaxLine"
+ external_references:
+ type: object
metadata:
type: object
created_at:
@@ -56939,6 +56960,7 @@ components:
- delivered_at
- items
- deliveries
+ - external_references
- metadata
- created_at
- updated_at
@@ -57930,6 +57952,8 @@ components:
type: array
items:
"$ref": "#/components/schemas/TaxLine"
+ external_references:
+ type: object
metadata:
type: object
price_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: array
items:
"$ref": "#/components/schemas/ReturnLineItem"
+ external_references:
+ type: object
memo:
type: string
nullable: 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: object
properties:
+ 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: string
description: The location the fulfillment ships from. On update, moving
@@ -73401,6 +73436,13 @@ components:
FulfillmentUpdateParams:
type: object
properties:
+ 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: string
description: The location the fulfillment ships from. On update, moving
@@ -73630,6 +73672,13 @@ components:
LineItemCreateParams:
type: object
properties:
+ 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: string
quantity:
@@ -73653,6 +73702,13 @@ components:
LineItemUpdateParams:
type: object
properties:
+ 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: integer
description: Defaults to 1 when adding an item.
@@ -76121,6 +76177,13 @@ components:
ReturnCreateParams:
type: object
properties:
+ 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: array
items:
@@ -76184,6 +76247,13 @@ components:
ReturnUpdateParams:
type: object
properties:
+ 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: string
description: Where the goods come back to. Defaults to the location that
diff --git a/docs/developer/core-concepts/external-references.mdx b/docs/developer/core-concepts/external-references.mdx
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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?: number
diff --git a/packages/admin-sdk/src/types/params/LineItemUpdateParams.ts b/packages/admin-sdk/src/types/params/LineItemUpdateParams.ts
index 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.ts
index 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: string
diff --git a/packages/admin-sdk/src/types/params/ReturnUpdateParams.ts b/packages/admin-sdk/src/types/params/ReturnUpdateParams.ts
index 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.ts
index 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.ts
index 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.ts
index 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.rb
index 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 = existing
authorize_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!
update
end
diff --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.rb
index 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 Spree
scoped_resource :fulfillments
request_params :fulfillment do |body|
+ body.external_references
body.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 Spree
params.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.rb
index 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 Spree
module Orders
class ItemsController < BaseController
request_params :line_item do |body|
+ body.external_references
body.attribute :variant_id, :id, required: true, only: :create
body.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.rb
index 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 Spree
scoped_resource :orders
request_params :return do |body|
+ body.external_references
body.attribute :items, :array,
required: true, on: :create,
only: :create,
@@ -89,6 +90,12 @@ module Spree
params.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.rb
index 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 }]
end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/fulfillment_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/fulfillment_serializer.rb
index 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 Spree
module V3
module Admin
class FulfillmentSerializer < V3::FulfillmentSerializer
+ include Concerns::ExternalReferencesAttribute
+
without_formatted_money
# The Admin API has no guest gating — money fields inherited from the
diff --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.rb
index 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 visibility
class LineItemSerializer < V3::LineItemSerializer
+ include Concerns::ExternalReferencesAttribute
+
without_formatted_money
# The Admin API has no guest gating — money fields inherited from the
diff --git a/spree/api/app/serializers/spree/api/v3/admin/return_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/return_serializer.rb
index 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 Spree
module V3
module Admin
class ReturnSerializer < V3::ReturnSerializer
+ include Concerns::ExternalReferencesAttribute
+
without_formatted_money
typelize 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.rb
index 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: :con
expect(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')
+ end
end
describe 'POST #create' do
diff --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.rb
index 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: :controller
expect(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' do
subject { 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.rb
index 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: :controll
expect(json_response['id']).to eq(return_record.prefixed_id)
expect(json_response['refund_total']).to be_present
end
+
+ 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')
+ end
end
describe 'PATCH #update' do
diff --git a/spree/core/app/models/concerns/spree/has_external_references.rb b/spree/core/app/models/concerns/spree/has_external_references.rb
index 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)
)
}
end
diff --git a/spree/core/app/models/spree/cart.rb b/spree/core/app/models/spree/cart.rb
index 7b466df004..f26c0a49ea 100644
--- a/spree/core/app/models/spree/cart.rb
+++ b/spree/core/app/models/spree/cart.rb
@@ -179,6 +179,7 @@ module Spree
fulfillment_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_all
fulfillment_items.reset
return fulfillments.reload unless can_propose_deliveries?
diff --git a/spree/core/app/models/spree/fulfillment.rb b/spree/core/app/models/spree/fulfillment.rb
index 7ea75af444..78a7917f9e 100644
--- a/spree/core/app/models/spree/fulfillment.rb
+++ b/spree/core/app/models/spree/fulfillment.rb
@@ -5,6 +5,7 @@ module Spree
include Spree::DerivedNumber
derives_number infix: 'F'
include Spree::HasCustomFields
+ include Spree::HasExternalReferences
include Spree::Metadata
include Spree::StorePreferences
if defined?(Spree::Security::Shipments)
diff --git a/spree/core/app/models/spree/line_item.rb b/spree/core/app/models/spree/line_item.rb
index 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 Spree
has_prefix_id :li # Spree-specific: line item
include Spree::HasCustomFields
+ include Spree::HasExternalReferences
include Spree::Metadata
publishes_lifecycle_events
diff --git a/spree/core/app/models/spree/order.rb b/spree/core/app/models/spree/order.rb
index b3aee4f6bd..f89e33bd78 100644
--- a/spree/core/app/models/spree/order.rb
+++ b/spree/core/app/models/spree/order.rb
@@ -921,6 +921,9 @@ module Spree
shipment_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_all
diff --git a/spree/core/app/models/spree/return.rb b/spree/core/app/models/spree/return.rb
index 95c5987e4a..ea880bdfe8 100644
--- a/spree/core/app/models/spree/return.rb
+++ b/spree/core/app/models/spree/return.rb
@@ -19,6 +19,7 @@ module Spree
include Spree::SingleStoreResource
include Spree::HasStatus
include Spree::HasCustomFields
+ include Spree::HasExternalReferences
include Spree::Metadata
include Spree::PostSale::Taxation
diff --git a/spree/core/spec/models/concerns/spree/has_external_references_spec.rb b/spree/core/spec/models/concerns/spree/has_external_references_spec.rb
index 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 do
expect(store.products.with_external_id('erp', 'MAT-100')).to be_empty
expect(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')
+ end
end
describe '#assign_external_references' do
diff --git a/spree/core/spec/models/spree/line_item_spec.rb b/spree/core/spec/models/spree/line_item_spec.rb
index 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 do
end
end
end
+
+ 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'
+ end
end
diff --git a/spree/core/spec/models/spree/order_spec.rb b/spree/core/spec/models/spree/order_spec.rb
index 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 do
end
describe '#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' do
let!(: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.rb
index 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 do
expect { return_record.reload.to_package }.not_to change { fulfillment_item.reload.quantity }
end
end
+
+ 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'
+ end
end
diff --git a/spree/core/spec/models/spree/shipment_spec.rb b/spree/core/spec/models/spree/shipment_spec.rb
index 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 do
expect(shipment.reload.tracking).to eq('OTHER-1')
end
end
+
+ 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'
+ end
end
diff --git a/spree/core/spec/support/shared_examples/external_references.rb b/spree/core/spec/support/shared_examples/external_references.rb
new file mode 100644
index 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