# Composable Storefront OCC Contract Hardening

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

Source: https://www.commercecloudintegrations.com/guides/composable-storefront-occ-contracts
Publisher: Commerce Cloud Integrations
Updated: 2026-06-28
Topics: composable, spartacus, occ, storefront, api

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.