advancedUpdated June 28, 2026·2 min read

Composable Storefront OCC Contract Hardening

How to keep Spartacus and custom composable storefronts stable while SAP Commerce OCC endpoints evolve behind them.

Commerce Cloud Integrations

SAP Commerce engineering team

Architecture, integrations, performance, upgrades, and Composable Storefront on SAP Commerce Cloud.

composablespartacusoccstorefrontapi

Composable Storefront projects stall when the frontend and SAP Commerce backend share assumptions informally. OCC contracts need explicit ownership, versioning, and regression tests. Without that, a checkout enhancement can break CMS rendering, price display, or cart restoration weeks later.

Own the Boundary#

The boundary is not just /occ/v2. It includes DTO fields, enum values, CMS component models, anonymous cart behaviour, user session rules, consent flow, cache headers, and error shapes.

Contract surface	Typical failure	Control
Product details	Missing classification attributes	DTO snapshot tests
Cart	Promotion and delivery mode drift	Checkout journey replay
CMS	Component type mismatch	CMS model registry checks
User	Anonymous to registered cart merge	Auth state matrix
Search	Solr facet naming changes	Search response fixtures

If the frontend team cannot name the backend owner for each surface, the contract is not hardened.

Stabilize DTO Extensions#

SAP Commerce teams often extend OCC DTOs quickly and leave the contract undocumented. Make extensions explicit and test them as API surface.

java

public class CciProductWsDTO extends ProductWsDTO {
  private String merchandisingBadge;
  private List<String> variantMerchandisingLabels;

  public String getMerchandisingBadge() {
    return merchandisingBadge;
  }
}

The DTO is now a frontend dependency. Treat field removal, type changes, and nullability changes as breaking changes.

Version by Use Case#

Avoid one generic endpoint that tries to serve PDP, listing, cart, and recommendations. OCC responses should be sized for the route they support.

http

GET /occ/v2/{baseSiteId}/products/{code}?fields=FULL
GET /occ/v2/{baseSiteId}/products/{code}?fields=PDP
GET /occ/v2/{baseSiteId}/products/{code}?fields=LISTING

Field sets need ownership. A performance optimization that removes fields from FULL can become a production defect if Spartacus expects those fields on route activation.

Regression Harness#

Use route-level contract tests. Capture representative requests for PDP, PLP, cart, checkout, login, registration, and CMS page rendering. Replay them against the backend build before releasing the storefront.

Delivery Rule#

Composable Storefront succeeds when OCC behaves like a product interface, not an implementation detail. The contract should be documented, versioned, tested, and owned across backend and frontend release cycles.