Read-Only Shopping Cart Items

Overview

The Read_Only__c field on Shopping_Cart_Item__c prevents buyers from editing protected lines through the storefront cart experience. Use it when the business needs a cart row to stay visible but not buyer-editable, such as auto-added service items, protected bundle rows, or summary-driven charges.

Interactive storefront flows treat the field as a hard lock. Public Apex API maintenance flows can update read-only items in controlled scenarios without weakening that buyer-facing protection.

Declarative Controls (Admins)

Direct field update: Any tool that can edit welisacommerce__Shopping_Cart_Item__c.welisacommerce__Read_Only__c (Record-Triggered Flow, Process Builder, Data Loader, or inline edit in the cart item list view) will immediately enforce the lock.
Automate after add-to-cart: Build a record-triggered Flow on welisacommerce__Shopping_Cart_Item__c with After Insert scope, add entry criteria (e.g., welisacommerce__Web_Product__c in a protected SKU list), then set welisacommerce__Read_Only__c = true via a standard Update Records element.
Automate during updates: Extend the same Flow with After Update to re-assert the flag when conditions change (for example, when an autopriced bundle is toggled back on).
Bulk operations: Populate the checkbox through Data Loader/Data Import Wizard when seeding carts for demos or migrations; downstream services respect the field immediately, so no manual UI changes are needed.

Tip: Keep system automation idempotent; setting welisacommerce__Read_Only__c back to false re-enables editing everywhere, so only flip it off deliberately.

Programmatic controls (developers)

Use programmatic controls differently depending on who is initiating the change.

Buyer-facing storefront controllers continue to enforce read-only behavior.
Admin automation and controlled Apex integrations can still maintain protected lines when that work is performed outside the buyer interaction path.
ShoppingCartApi.AddToCartItem.isReadOnly is the supported way to create a protected line through the public Apex API.
ShoppingCartApi.UpdateCartItemRequest.isReadOnly should be documented as a lock-on-update flag. Do not describe it as a guaranteed unlock flag.

Add via welisacommerce__ShoppingCartApi.addToCart

DTOs: welisacommerce__ShoppingCartApi.AddToCartItem.isReadOnly flows into welisacommerce__AddShoppingCartItemDto.readOnly (core/cart/classes/ShoppingCartApi.cls, core/cart/classes/dtos/AddShoppingCartItemDto.cls).
Service layer: welisacommerce__ShoppingCartService copies the flag onto every new parent item and any generated children (grouped option rows, auto-addons, shipment children) so the entire bundle stays locked (core/cart/classes/services/ShoppingCartService.cls).

welisacommerce__ShoppingCartApi.AddToCartRequest request = new welisacommerce__ShoppingCartApi.AddToCartRequest();
request.contactId = contactId;
request.items = new List<welisacommerce__ShoppingCartApi.AddToCartItem>();

welisacommerce__ShoppingCartApi.AddToCartItem item = new welisacommerce__ShoppingCartApi.AddToCartItem();
item.webProductId = protectedProductId;
item.quantity = 1;
item.isReadOnly = true; // locks the item once created

request.items.add(item);
welisacommerce__ShoppingCartApi.AddToCartResult result = welisacommerce__ShoppingCartApi.addToCart(request);

Update via welisacommerce__ShoppingCartApi.updateCartItem

welisacommerce__ShoppingCartApi.UpdateCartItemRequest.isReadOnly injects the flag into the same DTO pipeline, and the service updates existing cart items (plus their descendants) accordingly.

welisacommerce__ShoppingCartApi.UpdateCartItemRequest updateRequest = new welisacommerce__ShoppingCartApi.UpdateCartItemRequest();
updateRequest.shoppingCartId = cartId;
updateRequest.shoppingCartItemId = cartItemId;
updateRequest.isReadOnly = true; // prevent further edits

welisacommerce__ShoppingCartApi.UpdateCartItemResult result = welisacommerce__ShoppingCartApi.updateCartItem(updateRequest);

Direct Service Usage

Internal Apex can set welisacommerce__AddShoppingCartItemDto.readOnly before calling welisacommerce__ShoppingCartService.addItemsToUserShoppingCart. The service applies welisacommerce__Read_Only__c automatically and cascades the state to auto-generated items (core/cart/classes/services/ShoppingCartService.cls).

welisacommerce__AddShoppingCartItemDto dto = new welisacommerce__AddShoppingCartItemDto();
dto.webProductId = protectedProductId;
dto.quantity = 1;
dto.readOnly = true;

welisacommerce__AddShoppingCartItemsRequest svcRequest = new welisacommerce__AddShoppingCartItemsRequest();
svcRequest.items = new List<welisacommerce__AddShoppingCartItemDto>{ dto };
// ...populate remaining request fields...
welisacommerce__ShoppingCartService.addItemsToUserShoppingCart(svcRequest, uow1, uow2);

Validation & Behavior

Setting welisacommerce__Read_Only__c = true blocks buyer-facing UI edits such as quantity changes, delete actions, and addon toggles. If a storefront flow attempts to update a protected item, the service returns "This shopping cart item can no longer be edited."
Controlled Apex maintenance can still update protected items through the public API when the work is performed outside the buyer interaction path.
Clearing the stored field should be treated as an administrative or governed automation action, not as a guaranteed isReadOnly = false API contract.
The flag is honored during cart recalculations, addon auto-selection, and grouped product management, preventing indirect edits.

When to use each path

Use buyer-facing enforcement when the goal is to stop shoppers from changing a line in the cart UI.

Use admin automation or controlled integration maintenance when the platform must still adjust the same line behind the scenes, for example when:

a background process needs to correct quantity or related data on a protected line
an integration manages addons or derived values after the line has already been locked
Flow or other administrative automation sets or clears the stored field as part of a governed business process

Keep the guide clear that this is not a general shopper bypass. It is a controlled implementation path for admins and developers.

Troubleshooting

Symptom: Item still editable after automation. Fix: Ensure Flow runs after insert/update and that no later automation clears welisacommerce__Read_Only__c.
Symptom: Documentation says isReadOnly = false unlocks an item, but the integration still cannot rely on that behavior. Fix: Document the public isReadOnly request property as a lock-oriented flag. If an implementation needs to clear the stored field, describe that as an administrative or governed field-update scenario rather than as a guaranteed isReadOnly = false API contract.
Symptom: Child addon remains editable. Fix: Verify the parent item’s flag; the service mirrors the state downward, so missing propagation usually indicates the parent never received the flag.

Documentation Index