---
id: ADR-COM-FUL-019
title: Replace configuration at the read version with explicit clearing rules
product_area: commerce
module: fulfillment
revision: 1
status: proposed
design_intent: proposed
source_sha:
  services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b
decision: >-
  Retain versioned replacement and explicit clearing behavior; propose
  complete-payload enforcement as additional work.
constrains:
  - DOM-COM-FUL-002
  - DOM-COM-FUL-004
  - DOM-COM-FUL-005
  - SVC-COM-FUL-fulfillment
  - SVC-COM-FUL-shipping
  - SVC-COM-FUL-inventory
origin: >-
  Q06, Andrew 2026-10-19 (blank values refused; only null clears):
  services-commerce:docs/migrations/shipping/README.md#D-P8S-17; the
  complete-payload rule adopted for CRM (OQ-CRM-ENT-001 decided 2026-10-22: A)
  proposed here for Commerce configuration
alternatives:
  - option: Introduce partial configuration updates.
    why_not: >-
      Current configuration operations replace records; patch behavior would
      need a distinct contract.
  - option: Continue defaulting omitted replacement properties.
    why_not: >-
      Omitted properties can reset or clear values; refusing them is proposed
      rather than established.
consequences:
  - Replacement checks the version supplied by the editor.
  - >-
    Some writable properties remain optional, so complete-payload refusal is
    proposed.
supersedes: []
evidence:
  - >-
    services-commerce at c8b66a98: modules/shipping/aws/api/shipping.schemas.ts
    (replacement schemas, strict), shipping-api-mapper.ts;
    modules/configuration/aws/api/schema-helpers.ts (validateConfigurationBody);
    modules/fulfillment/services/persistence/fulfillment-policies.ts;
    modules/inventory/services/persistence/warehouses.ts.
---

# Replace configuration at the read version with explicit clearing rules

## Context

Administrators need version checks and deliberate clearing semantics when replacing configuration.

## Decision

Retain versioned replacement and explicit clearing behavior; propose complete-payload enforcement as additional work.

## Alternatives Considered

Introduce partial configuration updates. Current configuration operations replace records; patch behavior would need a distinct contract.

Continue defaulting omitted replacement properties. Omitted properties can reset or clear values; refusing them is proposed rather than established.

## Consequences

The current schemas still allow some omitted properties. Product must decide whether to adopt the separately approved CRM approach for Commerce.