POST /on-demand-ordering/cart uses the existing authorized principal/program/account scope. Every request requires request_id and lines.
With operation: "add_items", lines are additions to the durable current cart. Product lines merge only when product, dated-offer identity and variant selections match. Grouped/configuration products retain quantity one and accumulate matching selection quantities. Configuration identity comes from the stored product type. New lines receive unique server IDs; existing IDs survive additions.
Additions preserve the cart's shipping/payment selection, department, address and delivery date. time_cycle_period_id can establish an empty cart's period but cannot switch a populated cart to another period. Period-bound offers resolve again against the order-wide date; native dated offers retain their identity. Fulfillment fields in an add command do not replace current context. Normal cart evaluation still determines eligibility, quotes and bounded draft issues.
Without operation, lines replace the current set for existing deployed consumers. Replacement requests can supply expected_cart_version; a mismatch returns HTTP 409 with checkout.cart_version_conflict, without saving or retaining the rejected request. A successful replay is checked before version and returns current evaluated state with the original applied version. Supplied replacement line IDs are retained and duplicates rejected.
The unique carts.scope_key row serializes creation, replay decisions, mutation evaluation and saving in one MariaDB transaction. The scope upsert acquires its write lock; state/replay reads and persistence share that transaction. Rejected mutations roll back. Process projections are published after commit. Checkout metadata updates lock the same row before updating it; cart reads load durable state rather than relying on another process's cached projection.
Clearing a previously mutated cart advances its version and retains the bounded request replay history. Retrying an earlier successful add therefore does not repopulate a cleared cart. Replay retention remains 128 requests per scope.
Deploy and restart Platform before enabling the client's add command. Older servers interpret the existing lines shape as replacement and must not receive the new operation. Existing replacement clients continue to work. No new properties or migration are required; the existing unique scope index is required. Verify database locking/replay through concurrent requests on the target test installation before enabling the new client path.