@open-mercato/core 0.6.5-develop.4534.1.b459babe6d → 0.6.5-develop.4559.1.839e136509

package/src/modules/sales/commands/returns.ts

@@ -12,7 +12,7 @@ import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/
 import { SalesDocumentNumberGenerator } from '../services/salesDocumentNumberGenerator'
 import type { SalesCalculationService } from '../services/salesCalculationService'
 import type { SalesAdjustmentDraft, SalesLineSnapshot, SalesDocumentCalculationResult } from '../lib/types'
-import { cloneJson, ensureOrganizationScope, ensureSameScope, ensureTenantScope, extractUndoPayload, toNumericString } from './shared'
+import { cloneJson, ensureOrganizationScope, ensureSameScope, ensureTenantScope, extractUndoPayload, toNumericString, enforceSalesDocumentOptimisticLock, SALES_RESOURCE_KIND_ORDER } from './shared'
 import { SalesOrder, SalesOrderAdjustment, SalesOrderLine, SalesReturn, SalesReturnLine } from '../data/entities'
 import { returnCreateSchema, type ReturnCreateInput } from '../data/validators'
 import { E } from '#generated/entities.ids.generated'
@@ -286,6 +286,7 @@ const createReturnCommand: CommandHandler<ReturnCreateInput, { returnId: string
         throw new CrudHttpError(404, { error: translate('sales.returns.orderMissing', 'Order not found.') })
       }
       ensureSameScope(order, input.organizationId, input.tenantId)
+      enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER)
 
       const orderLines = await findWithDecryption(
         tx,
@@ -476,11 +477,12 @@ const createReturnCommand: CommandHandler<ReturnCreateInput, { returnId: string
     // Line reversals, adjustment/return removals, and the order-total recompute
     // interleave queries on the same EntityManager with scalar mutations, so they
     // must run inside an atomic flush to avoid lost updates and partial commits.
+    let lines: SalesOrderLine[] = []
     await withAtomicFlush(
       em,
       [
         async () => {
-          const lines = await findWithDecryption(
+          lines = await findWithDecryption(
             em,
             SalesOrderLine,
             { order: order.id, deletedAt: null },
@@ -496,7 +498,14 @@ const createReturnCommand: CommandHandler<ReturnCreateInput, { returnId: string
             line.updatedAt = new Date()
             em.persist(line)
           })
-
+        },
+        // The line returnedQuantity reversals above are persisted by
+        // withAtomicFlush's per-phase flush boundary before the adjustment /
+        // header / return-line lookups below run any query on this
+        // EntityManager. MikroORM v7 would otherwise silently discard the pending
+        // scalar changes on the managed `lines` when the next read resets the
+        // changeset (see SPEC-018).
+        async () => {
           if (after.adjustmentIds.length) {
             const adjustments = await findWithDecryption(
               em,

package/src/modules/sales/commands/shared.ts

@@ -2,10 +2,46 @@ import type { EntityManager } from '@mikro-orm/postgresql'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import type { CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 export { assertFound } from '@open-mercato/shared/lib/crud/errors'
 export { ensureOrganizationScope, ensureSameScope, ensureTenantScope } from '@open-mercato/shared/lib/commands/scope'
 export { extractUndoPayload } from '@open-mercato/shared/lib/commands/undo'
 
+/** Resource kinds used by the document-aggregate optimistic-lock check. */
+export const SALES_RESOURCE_KIND_ORDER = 'sales.order'
+export const SALES_RESOURCE_KIND_QUOTE = 'sales.quote'
+
+/**
+ * Enforce the document-aggregate OSS optimistic lock for a sales sub-resource
+ * command (lines, adjustments, shipments, payments, returns, quote
+ * conversion). The client sends the parent order/quote's expected `updated_at`
+ * via the optimistic-lock extension header; this compares it against the
+ * already-loaded document and throws the structured 409 on mismatch.
+ *
+ * The parent document is the consistency boundary: sub-resource mutations
+ * recalculate document totals (or transition the document), which dirties the
+ * parent so its `updated_at` advances on flush — meaning concurrent sub-edits
+ * observe each other and conflict. Call this AFTER loading + scope-checking the
+ * document and BEFORE mutating, so `document.updatedAt` is the pre-mutation
+ * version.
+ *
+ * Strictly additive: when the client sends no header the check is a no-op, so
+ * existing API consumers are unaffected. Respects `OM_OPTIMISTIC_LOCK`.
+ */
+export function enforceSalesDocumentOptimisticLock(
+  ctx: CommandRuntimeContext,
+  document: { id: string; updatedAt?: Date | string | null } | null | undefined,
+  resourceKind: string,
+): void {
+  if (!document) return
+  enforceCommandOptimisticLock({
+    resourceKind,
+    resourceId: document.id,
+    current: document.updatedAt ?? null,
+    request: ctx.request ?? null,
+  })
+}
+
 export function cloneJson<T>(value: T): T {
   if (value === null || value === undefined) return value
   return JSON.parse(JSON.stringify(value)) as T

package/src/modules/sales/commands/shipments.ts

@@ -657,11 +657,17 @@ const updateShipmentCommand: CommandHandler<ShipmentUpdateInput, { shipmentId: s
         : null
       const normalizedItems = validatedItems?.items ?? null
       const lineMap = validatedItems?.lineMap ?? new Map<string, SalesOrderLine>()
+      // Resolve the status label BEFORE mutating shipment scalars so this
+      // dictionary read does not interleave with (and drop) the pending
+      // shipment changeset under MikroORM v7 (SPEC-018 / #2453 class).
+      const resolvedShipmentStatus = input.statusEntryId !== undefined
+        ? await resolveDictionaryEntryValue(tx, input.statusEntryId ?? null)
+        : undefined
       if (input.shipmentNumber !== undefined) shipmentEntity.shipmentNumber = input.shipmentNumber ?? null
       if (input.shippingMethodId !== undefined) shipmentEntity.shippingMethodId = input.shippingMethodId ?? null
       if (input.statusEntryId !== undefined) {
         shipmentEntity.statusEntryId = input.statusEntryId ?? null
-        shipmentEntity.status = await resolveDictionaryEntryValue(tx, input.statusEntryId ?? null)
+        shipmentEntity.status = resolvedShipmentStatus ?? null
       }
       if (input.carrierName !== undefined) shipmentEntity.carrierName = input.carrierName ?? null
       if (input.trackingNumbers !== undefined) shipmentEntity.trackingNumbers = parseTrackingNumbers(input.trackingNumbers)
@@ -685,6 +691,13 @@ const updateShipmentCommand: CommandHandler<ShipmentUpdateInput, { shipmentId: s
       }
       shipmentEntity.updatedAt = new Date()
 
+      // Persist the shipment scalar mutations before the item reads below run on
+      // the same EntityManager. Under MikroORM v7 an interleaved query (the
+      // findWithDecryption on SalesShipmentItem here and in the snapshot step)
+      // resets the identity-map changeset, so shippingMethodId/status/carrier/etc.
+      // would silently not persist even though the write returns 200 (#2453).
+      await tx.flush()
+
       const shouldLoadItems = Boolean(normalizedItems || input.lineStatusEntryId !== undefined)
       const existingItems = shouldLoadItems ? await findWithDecryption(tx, SalesShipmentItem, { shipment: shipmentEntity }, {}, { tenantId: shipmentEntity.tenantId, organizationId: shipmentEntity.organizationId }) : []
       const newItems: SalesShipmentItem[] = []
@@ -758,6 +771,9 @@ const updateShipmentCommand: CommandHandler<ShipmentUpdateInput, { shipmentId: s
         }
       }
 
+      // Flush any order/line status mutations applied above before the snapshot
+      // read below queries the same EntityManager (same interleaved-read hazard).
+      await tx.flush()
       const itemsForSnapshot =
         normalizedItems || shouldLoadItems
           ? (normalizedItems ? newItems : existingItems)

package/src/modules/sales/components/AdjustmentKindSettings.tsx

@@ -16,7 +16,8 @@ import {
 import { Input } from '@open-mercato/ui/primitives/input'
 import { Label } from '@open-mercato/ui/primitives/label'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
-import { apiCall, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { raiseCrudError } from '@open-mercato/ui/backend/utils/serverErrors'
 import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
 import { AppearanceSelector } from '@open-mercato/core/modules/dictionaries/components/AppearanceSelector'
@@ -219,11 +220,15 @@ export function AdjustmentKindSettings() {
           ? JSON.stringify(payload)
           : JSON.stringify({ id: dialog.entry.id, ...payload })
 
-      const call = await apiCall('/api/sales/adjustment-kinds', {
-        method,
-        headers: { 'content-type': 'application/json' },
-        body,
-      })
+      const lockHeader =
+        dialog.mode === 'edit' ? buildOptimisticLockHeader(dialog.entry.updatedAt) : {}
+      const call = await withScopedApiRequestHeaders(lockHeader, () =>
+        apiCall('/api/sales/adjustment-kinds', {
+          method,
+          headers: { 'content-type': 'application/json' },
+          body,
+        })
+      )
       if (!call.ok) {
         await raiseCrudError(call.response, labels.saveError)
       }
@@ -248,11 +253,15 @@ export function AdjustmentKindSettings() {
       })
       if (!confirmed) return
       try {
-        const call = await apiCall('/api/sales/adjustment-kinds', {
-          method: 'DELETE',
-          headers: { 'content-type': 'application/json' },
-          body: JSON.stringify({ id: entry.id }),
-        })
+        const call = await withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(entry.updatedAt),
+          () =>
+            apiCall('/api/sales/adjustment-kinds', {
+              method: 'DELETE',
+              headers: { 'content-type': 'application/json' },
+              body: JSON.stringify({ id: entry.id }),
+            })
+        )
         if (!call.ok) {
           await raiseCrudError(call.response, labels.deleteError)
         }

package/src/modules/sales/components/DocumentNumberSettings.tsx

@@ -128,6 +128,7 @@ export function DocumentNumberSettings() {
         orderNextNumber: Number.parseInt(formState.orderNextNumber, 10) || undefined,
         quoteNextNumber: Number.parseInt(formState.quoteNextNumber, 10) || undefined,
       }
+      // optimistic-lock-exempt: single-row tenant numbering settings blob — no per-record version / concurrent record edit
       const call = await apiCall<SettingsResponse>('/api/sales/settings/document-numbers', {
         method: 'PUT',
         headers: { 'content-type': 'application/json' },

package/src/modules/sales/components/OrderEditingSettings.tsx

@@ -121,6 +121,7 @@ export function OrderEditingSettings() {
         orderCustomerEditableStatuses: customerStatuses,
         orderAddressEditableStatuses: addressStatuses,
       }
+      // optimistic-lock-exempt: single-row tenant order-editing settings blob — no per-record version / concurrent record edit
       const call = await apiCall<SettingsResponse>('/api/sales/settings/order-editing', {
         method: 'PUT',
         headers: { 'content-type': 'application/json' },

package/src/modules/sales/components/PaymentMethodsSettings.tsx

@@ -15,7 +15,9 @@ import {
 import { Label } from '@open-mercato/ui/primitives/label'
 import { CrudForm, type CrudField, type CrudCustomFieldRenderProps } from '@open-mercato/ui/backend/CrudForm'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
-import { apiCall, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { raiseCrudError } from '@open-mercato/ui/backend/utils/serverErrors'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
@@ -291,12 +293,14 @@ export function PaymentMethodsSettings() {
     })
     if (!confirmed) return
     try {
-      const call = await apiCall('/api/sales/payment-methods', {
+      const headers = buildOptimisticLockHeader(entry.updatedAt)
+      const call = await withScopedApiRequestHeaders(headers, () => apiCall('/api/sales/payment-methods', {
         method: 'DELETE',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({ id: entry.id }),
-      })
+      }))
       if (!call.ok) {
+        if (surfaceRecordConflict({ status: call.status, body: call.result }, t)) return
         await raiseCrudError(call.response, translations.errors.delete)
       }
       flash(translations.messages.deleted, 'success')
@@ -325,12 +329,15 @@ export function PaymentMethodsSettings() {
     const method = dialog.mode === 'create' ? 'POST' : 'PUT'
     if (dialog.mode === 'edit') payload.id = dialog.entry.id
     try {
-      const call = await apiCall(path, {
+      const savePaymentMethod = () => apiCall(path, {
         method,
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify(payload),
       })
+      const headers = buildOptimisticLockHeader(dialog.mode === 'edit' ? dialog.entry.updatedAt : null)
+      const call = await withScopedApiRequestHeaders(headers, savePaymentMethod)
       if (!call.ok) {
+        if (surfaceRecordConflict({ status: call.status, body: call.result }, t)) return
         await raiseCrudError(call.response, translations.errors.save)
       }
       flash(translations.messages.saved, 'success')
@@ -466,6 +473,7 @@ export function PaymentMethodsSettings() {
             schema={paymentFormSchema}
             fields={fields}
             initialValues={formValues}
+            optimisticLockUpdatedAt={dialog?.mode === 'edit' ? dialog.entry.updatedAt : null}
             submitLabel={translations.form.save}
             onSubmit={handleSubmit}
             cancelHref={undefined}

package/src/modules/sales/components/ShippingMethodsSettings.tsx

@@ -24,7 +24,9 @@ import { Label } from '@open-mercato/ui/primitives/label'
 import { SwitchField } from '@open-mercato/ui/primitives/switch-field'
 import { CrudForm, type CrudCustomFieldRenderProps, type CrudField } from '@open-mercato/ui/backend/CrudForm'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
-import { apiCall, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { raiseCrudError } from '@open-mercato/ui/backend/utils/serverErrors'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
@@ -549,12 +551,14 @@ export function ShippingMethodsSettings() {
     })
     if (!confirmed) return
     try {
-      const call = await apiCall('/api/sales/shipping-methods', {
+      const headers = buildOptimisticLockHeader(entry.updatedAt)
+      const call = await withScopedApiRequestHeaders(headers, () => apiCall('/api/sales/shipping-methods', {
         method: 'DELETE',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({ id: entry.id }),
-      })
+      }))
       if (!call.ok) {
+        if (surfaceRecordConflict({ status: call.status, body: call.result }, t)) return
         await raiseCrudError(call.response, translations.errors.delete)
       }
       flash(translations.messages.deleted, 'success')
@@ -642,12 +646,15 @@ export function ShippingMethodsSettings() {
     const method = dialog.mode === 'create' ? 'POST' : 'PUT'
     if (dialog.mode === 'edit') payload.id = dialog.entry.id
     try {
-      const call = await apiCall(path, {
+      const saveShippingMethod = () => apiCall(path, {
         method,
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify(payload),
       })
+      const headers = buildOptimisticLockHeader(dialog.mode === 'edit' ? dialog.entry.updatedAt : null)
+      const call = await withScopedApiRequestHeaders(headers, saveShippingMethod)
       if (!call.ok) {
+        if (surfaceRecordConflict({ status: call.status, body: call.result }, t)) return
         await raiseCrudError(call.response, translations.errors.save)
       }
       flash(translations.messages.saved, 'success')
@@ -770,6 +777,7 @@ export function ShippingMethodsSettings() {
             schema={shippingFormSchema}
             fields={fields}
             initialValues={formValues}
+            optimisticLockUpdatedAt={dialog?.mode === 'edit' ? dialog.entry.updatedAt : null}
             submitLabel={translations.form.save}
             cancelHref={undefined}
             embedded

package/src/modules/sales/components/StatusSettings.tsx

@@ -8,7 +8,8 @@ import {
   DialogTitle,
 } from '@open-mercato/ui/primitives/dialog'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
-import { apiCall, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
@@ -197,11 +198,15 @@ export function StatusSettings() {
     })
     if (!confirmed) return
     try {
-      const call = await apiCall(apiPaths[kind], {
-        method: 'DELETE',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ id: entry.id }),
-      })
+      const call = await withScopedApiRequestHeaders(
+        buildOptimisticLockHeader(entry.updatedAt),
+        () =>
+          apiCall(apiPaths[kind], {
+            method: 'DELETE',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ id: entry.id }),
+          })
+      )
       if (!call.ok) {
         await raiseCrudError(call.response, translate('sales.config.statuses.error.delete', 'Failed to delete status.'))
       }
@@ -238,11 +243,15 @@ export function StatusSettings() {
         if (nextColor !== (entry.color ?? null)) body.color = nextColor
         const nextIcon = values.icon ?? null
         if (nextIcon !== (entry.icon ?? null)) body.icon = nextIcon
-        const call = await apiCall(path, {
-          method: 'PUT',
-          headers: { 'content-type': 'application/json' },
-          body: JSON.stringify(body),
-        })
+        const call = await withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(entry.updatedAt),
+          () =>
+            apiCall(path, {
+              method: 'PUT',
+              headers: { 'content-type': 'application/json' },
+              body: JSON.stringify(body),
+            })
+        )
         if (!call.ok) {
           await raiseCrudError(call.response, translate('sales.config.statuses.error.save', 'Failed to save status.'))
         }

package/src/modules/sales/components/TaxRatesSettings.tsx

@@ -10,7 +10,9 @@ import { Badge } from '@open-mercato/ui/primitives/badge'
 import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@open-mercato/ui/primitives/dialog'
 import { CrudForm, type CrudField } from '@open-mercato/ui/backend/CrudForm'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
-import { readApiResultOrThrow, apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { readApiResultOrThrow, apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { raiseCrudError } from '@open-mercato/ui/backend/utils/serverErrors'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
@@ -206,12 +208,15 @@ export function TaxRatesSettings() {
       payload.id = dialog.entry.id
     }
     try {
-      const call = await apiCall('/api/sales/tax-rates', {
+      const saveTaxRate = () => apiCall('/api/sales/tax-rates', {
         method,
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify(payload),
       })
+      const headers = buildOptimisticLockHeader(dialog.mode === 'edit' ? dialog.entry.updatedAt : null)
+      const call = await withScopedApiRequestHeaders(headers, saveTaxRate)
       if (!call.ok) {
+        if (surfaceRecordConflict({ status: call.status, body: call.result }, t)) return
         await raiseCrudError(call.response, translations.errors.save)
         return
       }
@@ -232,12 +237,14 @@ export function TaxRatesSettings() {
     })
     if (!confirmed) return
     try {
-      const call = await apiCall('/api/sales/tax-rates', {
+      const headers = buildOptimisticLockHeader(entry.updatedAt)
+      const call = await withScopedApiRequestHeaders(headers, () => apiCall('/api/sales/tax-rates', {
         method: 'DELETE',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({ id: entry.id }),
-      })
+      }))
       if (!call.ok) {
+        if (surfaceRecordConflict({ status: call.status, body: call.result }, t)) return
         await raiseCrudError(call.response, translations.errors.delete)
         return
       }
@@ -361,6 +368,7 @@ export function TaxRatesSettings() {
             schema={taxRateFormSchema}
             fields={fields}
             initialValues={dialogValues}
+            optimisticLockUpdatedAt={dialog?.mode === 'edit' ? dialog.entry.updatedAt : null}
             submitLabel={translations.form.save}
             cancelHref={undefined}
             embedded
@@ -387,4 +395,3 @@ function formatLocation(entry: TaxRateRow): string {
   return parts.length ? parts.join(', ') : '—'
 }
 
-

package/src/modules/sales/components/channels/ChannelOfferForm.tsx

@@ -7,7 +7,9 @@ import { CrudForm, type CrudField, type CrudFormGroup, type CrudFormGroupCompone
 import { collectCustomFieldValues } from '@open-mercato/ui/backend/utils/customFieldValues'
 import { createCrud, updateCrud, deleteCrud } from '@open-mercato/ui/backend/utils/crud'
 import { createCrudFormError, type CrudServerFieldErrors } from '@open-mercato/ui/backend/utils/serverErrors'
-import { readApiResultOrThrow, apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { readApiResultOrThrow, apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader, extractOptimisticLockConflict } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { Button } from '@open-mercato/ui/primitives/button'
 import { Input } from '@open-mercato/ui/primitives/input'
@@ -41,6 +43,8 @@ type PriceOverrideDraft = {
   currencyCode?: string | null
   displayMode?: 'including-tax' | 'excluding-tax' | null
   amount?: string
+  /** The price row's version, for the per-price optimistic-lock header (#2332). */
+  updatedAt?: string | null
 }
 
 export type OfferFormValues = {
@@ -51,6 +55,7 @@ export type OfferFormValues = {
   defaultMediaId?: string | null
   isActive: boolean
   priceOverrides: PriceOverrideDraft[]
+  updatedAt?: string | null
 } & Record<string, unknown>
 
 type ChannelOfferFormProps = {
@@ -141,13 +146,15 @@ export function ChannelOfferForm({ channelId: lockedChannelId, offerId, mode }:
   const variantMediaCache = React.useRef<Map<string, VariantThumbnailInfo>>(new Map())
   const [selectedChannelId, setSelectedChannelId] = React.useState<string | null>(lockedChannelId ?? null)
   const manualMediaSelections = React.useRef<Set<string>>(new Set())
-  const initialPriceIdsRef = React.useRef<Set<string>>(new Set())
+  // Map of the loaded price-override id → its `updatedAt`, so deletes during the
+  // offer save can send the price's own optimistic-lock version (#2332).
+  const initialPriceVersionsRef = React.useRef<Map<string, string | null>>(new Map())
   const [currentProductId, setCurrentProductId] = React.useState<string | null>(null)
   React.useEffect(() => {
     if (initialValues) {
-      initialPriceIdsRef.current = collectPriceIds(initialValues.priceOverrides)
+      initialPriceVersionsRef.current = collectPriceVersions(initialValues.priceOverrides)
     } else {
-      initialPriceIdsRef.current = new Set()
+      initialPriceVersionsRef.current = new Map()
     }
   }, [initialValues])
   const channelOffersHref = React.useMemo(
@@ -438,12 +445,16 @@ export function ChannelOfferForm({ channelId: lockedChannelId, offerId, mode }:
     if (!priceId) return true
     if (mode !== 'edit') return true
     try {
-      await deleteCrud('catalog/prices', priceId, {
-        errorMessage: t('sales.channels.offers.errors.removePrice', 'Failed to remove price override.'),
-      })
-      initialPriceIdsRef.current.delete(priceId)
+      await withScopedApiRequestHeaders(
+        buildOptimisticLockHeader(draft.updatedAt),
+        () => deleteCrud('catalog/prices', priceId, {
+          errorMessage: t('sales.channels.offers.errors.removePrice', 'Failed to remove price override.'),
+        }),
+      )
+      initialPriceVersionsRef.current.delete(priceId)
       return true
     } catch (err) {
+      if (surfaceRecordConflict(err, t)) return false
       console.error('sales.channels.pricing.remove', err)
       flash(t('sales.channels.offers.errors.removePrice', 'Failed to remove price override.'), 'error')
       return false
@@ -594,10 +605,11 @@ export function ChannelOfferForm({ channelId: lockedChannelId, offerId, mode }:
     }
     const submittedPriceIds = collectPriceIds(overrides)
     const deletedIdSet = new Set<string>()
-    initialPriceIdsRef.current.forEach((id) => {
+    initialPriceVersionsRef.current.forEach((_version, id) => {
       if (!submittedPriceIds.has(id)) deletedIdSet.add(id)
     })
     const deletedIds = Array.from(deletedIdSet)
+    const deletedVersions = new Map(deletedIds.map((id) => [id, initialPriceVersionsRef.current.get(id) ?? null]))
     let savedId = offerId ?? null
     try {
       if (mode === 'create') {
@@ -612,6 +624,13 @@ export function ChannelOfferForm({ channelId: lockedChannelId, offerId, mode }:
         savedId = offerId
       }
     } catch (err) {
+      // Let an optimistic-lock 409 propagate untouched so CrudForm's
+      // extractOptimisticLockConflict still sees the top-level `code` /
+      // `currentUpdatedAt` / `expectedUpdatedAt` and surfaces the unified
+      // conflict bar. Re-wrapping via createCrudFormError below would drop them.
+      if (extractOptimisticLockConflict(err)) {
+        throw err
+      }
       const details = (err as { details?: unknown })?.details
       const rawFieldErrors = (err as { fieldErrors?: unknown })?.fieldErrors
       const fieldErrors = rawFieldErrors && typeof rawFieldErrors === 'object'
@@ -634,15 +653,16 @@ export function ChannelOfferForm({ channelId: lockedChannelId, offerId, mode }:
       await syncPriceOverrides({
         overrides,
         deletedIds,
+        deletedVersions,
         offerId: savedId,
         channelId,
         productId,
       })
-      initialPriceIdsRef.current = submittedPriceIds
+      initialPriceVersionsRef.current = collectPriceVersions(overrides)
     }
     flash(t('sales.channels.offers.messages.saved', 'Offer saved.'), 'success')
     router.push(buildChannelOffersHref(channelId))
-  }, [attachmentCache, initialPriceIdsRef, lockedChannelId, mode, offerId, router, selectedChannelId, t])
+  }, [attachmentCache, lockedChannelId, mode, offerId, router, selectedChannelId, t])
 
   const handleDelete = React.useCallback(async () => {
     if (!offerId) return
@@ -669,6 +689,7 @@ export function ChannelOfferForm({ channelId: lockedChannelId, offerId, mode }:
         fields={fields}
         groups={groups}
         initialValues={initialValues ?? undefined}
+        optimisticLockUpdatedAt={initialValues?.updatedAt}
         isLoading={loading}
         loadingMessage={t('sales.channels.offers.form.loading', 'Loading offer…')}
         submitLabel={mode === 'create'
@@ -706,6 +727,11 @@ function mapOfferToFormValues(item: Record<string, unknown>, lockedChannelId?: s
         : null,
     isActive: item.isActive === true || item.is_active === true,
     priceOverrides: [],
+    updatedAt: typeof item.updatedAt === 'string'
+      ? item.updatedAt
+      : typeof item.updated_at === 'string'
+        ? item.updated_at
+        : null,
   }
   mergeCustomFieldValues(values, item)
   return values
@@ -742,6 +768,11 @@ function mapPriceRow(row: Record<string, unknown>): PriceOverrideDraft {
           : typeof row.unit_price_gross === 'string'
             ? row.unit_price_gross
             : '',
+    updatedAt: typeof row.updatedAt === 'string'
+      ? row.updatedAt
+      : typeof row.updated_at === 'string'
+        ? row.updated_at
+        : null,
   }
 }
 
@@ -753,6 +784,17 @@ function collectPriceIds(source: PriceOverrideDraft[] | null | undefined): Set<s
   return new Set(ids)
 }
 
+function collectPriceVersions(source: PriceOverrideDraft[] | null | undefined): Map<string, string | null> {
+  const versions = new Map<string, string | null>()
+  if (!Array.isArray(source)) return versions
+  for (const entry of source) {
+    if (typeof entry?.priceId === 'string' && entry.priceId) {
+      versions.set(entry.priceId, typeof entry.updatedAt === 'string' ? entry.updatedAt : null)
+    }
+  }
+  return versions
+}
+
 function mergeCustomFieldValues(target: Record<string, unknown>, source: Record<string, unknown> | null | undefined) {
   Object.assign(target, extractCustomFieldEntries(source ?? {}))
 }
@@ -766,11 +808,12 @@ function buildChannelOffersHref(channelId?: string | null): string {
 async function syncPriceOverrides(params: {
   overrides: PriceOverrideDraft[]
   deletedIds: string[]
+  deletedVersions: Map<string, string | null>
   offerId: string
   channelId: string
   productId: string
 }) {
-  const { overrides, deletedIds, offerId, channelId, productId } = params
+  const { overrides, deletedIds, deletedVersions, offerId, channelId, productId } = params
   for (const draft of overrides) {
     if (!draft.priceKindId || !draft.amount) continue
     const amount = Number(draft.amount)
@@ -788,7 +831,14 @@ async function syncPriceOverrides(params: {
       payload.unitPriceNet = amount
     }
     if (draft.priceId) {
-      await updateCrud('catalog/prices', { id: draft.priceId, ...payload })
+      // Send the PRICE's own version, overriding the offer header the parent
+      // CrudForm submit scope put on the stack (otherwise the price guard would
+      // compare the offer's `updated_at` and 409 falsely). #2332.
+      const priceId = draft.priceId
+      await withScopedApiRequestHeaders(
+        buildOptimisticLockHeader(draft.updatedAt),
+        () => updateCrud('catalog/prices', { id: priceId, ...payload }),
+      )
     } else {
       await createCrud('catalog/prices', payload)
     }
@@ -799,7 +849,10 @@ async function syncPriceOverrides(params: {
   for (const id of uniqueDeletedIds) {
     if (!id) continue
     try {
-      await deleteCrud('catalog/prices', id)
+      await withScopedApiRequestHeaders(
+        buildOptimisticLockHeader(deletedVersions.get(id) ?? null),
+        () => deleteCrud('catalog/prices', id),
+      )
     } catch (err) {
       console.error('catalog.prices.delete', err)
     }