Fix silent cart mutation failures and preserve location on quantity updates

[mzaintariq]

Type: Bug / reliability
Package: @elasticpath/plasmic-ep-commerce-elastic-path
Area: Add to Cart and cart drawer mutations

Problem

Cart mutations can fail without giving the shopper or designer a clear indication of what went wrong.

Add to Cart can encounter real Elastic Path or proxy failures, such as insufficient stock or a missing multilocation stock location, but those failures may be converted into a null result rather than reaching the component’s error state.

Cart quantity updates can also lose the line item’s stock location. For multilocation products, this can cause quantity controls to work once and then fail, or produce an incorrect insufficient-stock error during later increments or decrements.

Elastic Path SDK mutation responses containing an error may also be treated as successful responses.

Proposed change

Mutation error handling

• Make Add to Cart, quantity update, and remove mutations reject with the underlying proxy or Elastic Path error instead of silently returning null.
• Treat Elastic Path SDK soft-error responses as failures.
• Reject an Add to Cart operation when it returns an unsuccessful or unexpectedly empty cart.
• Preserve explicit fallback behaviour for read and Studio preview paths.
• Ensure failed Add to Cart operations do not invoke success callbacks.

Multilocation quantity updates

• Pass the cart line’s stock location when updating its quantity.
• Allow the server mutation to accept an optional location.
• Recover the location from the current cart line when it was not supplied by the client.
• Preserve support for single-location and non-location carts.

Quantity-control reliability

• Prevent overlapping quantity requests.
• Optimistically update the displayed quantity.
• Restore the previous quantity when the mutation fails.
• Prevent incrementing beyond known available stock where that information is available.
• Preserve correct disabled and accessibility behaviour during loading, stock-limit, and Studio preview states.

Impact

Designers using Plasmic Studio

Add to Cart failures will be available through:

$ctx.addToCartState.error

Designers can bind error text, a banner, a visibility condition, or another UI element to this value.

The component will not automatically render a default error message or toast. Existing designs will only show an error where the designer has explicitly bound UI to the error state.

The existing Add to Cart error preview state can be used to design this state in Studio.

Quantity and remove errors will not be exposed through designer-facing error values in this MR. Quantity failures will revert the displayed quantity and be logged. Remove failures will leave the item in the cart and be logged.

Implementors

No checkout host route or host API change is required.

Mutation calls that previously resolved to null may now reject. Custom callers must catch the rejected promise or use the component-provided error state.

Read and Studio preview operations that intentionally require soft failure must continue passing an explicit fallback value.

Multilocation Add to Cart still requires a valid location to be selected. This change preserves or recovers that location for subsequent quantity updates.

When location is not supplied by the client, the server may perform an additional cart lookup to recover it from the existing cart line.

Shoppers

• Add to Cart failures can display a meaningful error when the Studio design binds to the existing error state.
• Quantity controls work reliably across repeated updates for multilocation products.
• Failed optimistic quantity changes return to the previous value.
• Quantity controls prevent overlapping updates when clicked repeatedly.
• Remove failures no longer appear successful when the item was not removed.

Error behaviour

Add to Cart

A failed Add to Cart request will:

• Return a failed proxy or Elastic Path response.
• Reject rather than resolving to null.
• Be visible in the browser Network tab.
• Be logged by the component or server.
• Populate $ctx.addToCartState.error.
• Only appear to the shopper if the Studio design binds UI to that value.

Quantity update

A failed quantity update will:

• Reject and be logged.
• Restore the previously displayed quantity.
• Revalidate the cart state.
• Not expose an error message through Studio in this MR.

Remove item

A failed remove request will:

• Reject and be logged.
• Leave the item in the cart.
• Not expose an error message through Studio in this MR.