The B2C Commerce Cartridge Path: How Modules Actually Compose

The cartridge path is the single most consequential configuration in any B2C Commerce site. It is one string in Business Manager that lists cartridges in order. That order decides which controller fires for a given route, which template renders a given page, and which model definition wins when two cartridges define the same thing. Get it right and the codebase composes cleanly. Get it wrong and overrides land in the wrong order, the same logic runs twice, and the team spends afternoons debugging which cartridge actually served the request.

Sapota's Salesforce team has triaged enough cartridge-path incidents to treat the composition as a first-class architectural artifact rather than a Business Manager setting nobody documented.

What the cartridge path actually does

The platform processes each request by walking the cartridge path from left to right. The first cartridge that defines the requested artifact wins. Artifacts include:

• Controllers (a route handler like Cart-AddProduct)
• Templates (an ISML file like account/login.isml)
• Models (a JavaScript module like cart.js)
• Scripts (utility files)
• Static resources (CSS, images, client-side JS)

A typical cartridge path for a customized SFRA site:

plugin_payment_avalara:int_marketing_cloud:custom_storefront:app_storefront_base

Reading left to right: the custom storefront cartridge has the highest priority. If it defines Cart.js, that file is used. If not, the platform falls through to int_marketing_cloud, then app_storefront_base. The base cartridge is the last fallback; it provides the SFRA reference implementation.

The composition rules that matter

Four rules separate working cartridge paths from broken ones:

Rule 1: Customizations to the left of bases. Cartridges containing custom code must appear before the base cartridges they extend. A custom_storefront cartridge that overrides Cart.js must be listed before app_storefront_base. The platform walks left to right; the first hit wins.

Rule 2: Plugin cartridges between custom and base. Salesforce LINK cartridges (payment integrations, tax engines, third-party services) typically slot between the custom cartridge and app_storefront_base. They extend base behavior but should be overridable by site-specific customizations.

Rule 3: Order among plugins matters when they touch overlapping concerns. Two payment plugins both extending checkout? The one listed first wins. Document the choice.

Rule 4: Test cartridges only in non-production paths. Cartridges used for testing, staging-only features, or A/B experiments must not appear in the production cartridge path. Audit before each promotion.

A practical path structure

The cartridge path for a typical mid-complexity site, annotated:

# Custom site-specific code (highest priority)
custom_brand_storefront

# Test/experimental cartridges (sandbox only)
# test_holiday_promotions  ← commented out in production

# Plugin and integration cartridges
plugin_apple_pay
plugin_google_pay
plugin_avalara_tax
int_marketing_cloud
int_oms_netsuite

# SFRA plugin cartridges (official Salesforce)
plugin_giftcertificate
plugin_instorepickup
plugin_productcompare
plugin_wishlists

# SFRA base (lowest priority, fallback)
app_storefront_base

The layering is intentional. The site's own customizations sit at the top. Integration plugins occupy the middle, extending base behavior with vendor-specific functionality. Salesforce's optional SFRA plugins enable opt-in features. The base cartridge anchors the path.

A clean path makes upgrades safer. When Salesforce updates app_storefront_base, the changes flow through to the site automatically unless an upstream cartridge overrides the affected file.

How conflicts emerge

Three patterns produce confusion:

1. Duplicate controllers across cartridges. Five cartridges in the path all define Cart.js. The leftmost wins; the others are silently ignored. The team writes code in a controller that "should be running" but the path puts it third, so it never executes.

The diagnostic: ask the platform which file actually served. Business Manager's Site Studio shows the resolved file for any request. Run that query before assuming code is live.

2. ISML template overrides without controller overrides. A custom cartridge overrides the template but not the controller. The base controller runs with the new template and passes data the template does not expect. Page breaks subtly. Hard to diagnose because both files look correct in isolation.

The fix: when overriding either a template or its controller, override both, or carefully document why only one half is overridden.

3. Static resource path mismatches. Client-side JS and CSS reference paths assume specific cartridge structure. A path reorganization moves files; references break; pages render without styling. The build pipeline catches some of these; manual review catches the rest.

The hot reload trap

SFCC sandboxes support hot reload: code changes propagate without a full deploy. The cartridge path is the exception. Changing the path requires a new "Code Version" activation. Code that "should be" in the path because the developer added the cartridge folder, but the path was not updated, simply does not run.

The first hour of every junior developer's life on SFCC includes this discovery. The senior fix: a documented cartridge path activation step in the onboarding runbook, plus a script that compares the active path to the source-controlled expected path on every deploy.

Path management as a discipline

Sapota's standard practices for cartridge path management:

Version control the expected path. The cartridge path string lives in a config file in source control, not only in Business Manager. CI verifies the active path on each deploy.

Document the role of each cartridge. A README in the repository explains why each cartridge is in the path, what it extends, and what depends on it. New cartridges added without a documented purpose get pushed back in code review.

Audit the path quarterly. Cartridges become orphans over time. A LINK integration installed two years ago for a vendor no longer in use still sits in the path consuming resolution time. Remove them deliberately.

Test path changes in a sandbox first. A cartridge path change in production rarely produces an immediate incident; it produces silent behavioral drift discoverable only by careful regression testing. Run the full smoke test before promoting a path change.

Use cartridge paths per site, not per realm. Multi-site realms can configure different paths per site. A B2B-only site does not need consumer plugin cartridges loaded. Trim accordingly.

Common cartridge-path mistakes

Five patterns from real triage engagements:

• The "everything in one cartridge" anti-pattern. All custom code in a single custom_site cartridge. No separation of integration code, brand-specific code, and experimental features. Refactoring becomes invasive.
• Tests living in the production path. A test_* cartridge somehow shipped to production years ago. Removed during audit, no incident, but the team had no idea it was there.
• Plugin cartridges left behind. A payment provider was switched out three years ago. The old plugin cartridge still loads on every request. Resolution slower, incidents bigger when the unused code paths trigger.
• Custom override of a single file in a heavily customized cartridge. A team needs to override one helper script. They copy the entire 200-file plugin cartridge into a new custom cartridge, change one function, and put it in front of the original. Now there are two cartridges with 199 identical files plus one different one. Maintenance nightmare. Use the Salesforce extension point pattern instead.
• Production hotfix bypassing the path. Production incident under pressure; team uploads a hotfix directly to a production-only cartridge that has no source control. Six months later nobody remembers what is in that cartridge.

What good cartridge path management looks like

A B2C Commerce site with healthy cartridge architecture:

• Active cartridge path matches a source-controlled expected path.
• Each cartridge has a documented purpose in the repository README.
• Test and experimental cartridges never appear in production paths.
• Quarterly cleanup removes unused cartridges.
• CI verifies path consistency on every deploy.
• Onboarding runbook covers cartridge path activation.

The cartridge path is configuration that compiles into behavior. Treating it as a config string nobody owns produces incidents quarterly. Treating it as an architectural artifact with documentation and CI checks produces orgs that survive multi-year team turnover. Sapota's Salesforce team has shipped this pattern on production B2C Commerce engagements.

---

Auditing or restructuring a B2C Commerce cartridge path? Sapota's Salesforce team handles cartridge architecture, plugin integration, and path governance on production engagements. Get in touch ->

See our full platform services for the stack we cover.