SFCC Cartridge Development

Overview

Build custom cartridges for Salesforce Commerce Cloud (SFCC) using the Storefront Reference Architecture (SFRA), server-side JavaScript controllers, ISML templates, models, and the B2C Commerce Script API. This skill covers cartridge layering and the override mechanism, route handling with server.js, form handling, OCAPI/SCAPI integration, and Job Framework usage for scheduled data processing.

When to Use This Skill

• When building a custom feature cartridge that extends SFRA functionality
• When overriding or extending existing SFRA controllers, templates, or models
• When implementing custom checkout steps or payment integrations on SFCC
• When creating scheduled jobs for data import/export (product feeds, order sync)
• When building OCAPI hooks or SCAPI integrations for headless storefronts

Core Instructions

1. Set up the cartridge structure and layering

   SFCC uses a cartridge path for layering. Cartridges higher in the path override those lower. A custom cartridge extends app_storefront_base:

   int_acme_custom/
   ├── cartridge/
   │   ├── controllers/       # Server-side JS controllers
   │   ├── models/            # Data model wrappers
   │   ├── scripts/           # Business logic helpers
   │   ├── templates/
   │   │   └── default/       # ISML templates
   │   ├── forms/
   │   │   └── default/       # Form definitions (XML)
   │   ├── static/
   │   │   └── default/
   │   │       ├── css/
   │   │       └── js/
   │   └── int_acme_custom.properties  # Cartridge metadata
   └── package.json
   

   Set the cartridge path in Business Manager:

   int_acme_custom:app_storefront_base
   

   int_acme_custom.properties:

   ## cartridge.properties
   demandware.cartridges.int_acme_custom.multipleLanguageStorefront=true
   

2. Create a server-side controller

   Controllers in SFRA use server.js for route registration:

   // controllers/CustomPage.js
   'use strict';
   
   var server = require('server');
   var cache = require('*/cartridge/scripts/middleware/cache');
   var consentTracking = require('*/cartridge/scripts/middleware/consentTracking');
   
   /**
    * CustomPage-Show : Renders a custom content page
    * @name CustomPage-Show
    * @function
    * @memberof CustomPage
    * @param {middleware} - server.middleware.https
    * @param {middleware} - consentTracking.consent
    * @param {middleware} - cache.applyDefaultCache
    * @param {querystringparameter} - cid : content asset ID
    * @param {renders} - isml
    * @param {serverfunction} - get
    */
   server.get('Show',
       server.middleware.https,
       consentTracking.consent,
       cache.applyDefaultCache,
       function (req, res, next) {
           var ContentMgr = require('dw/content/ContentMgr');
           var ContentModel = require('*/cartridge/models/content');
   
           var contentId = req.querystring.cid;
           var apiContent = ContentMgr.getContent(contentId);
   
           if (!apiContent) {
               res.setStatusCode(404);
               res.render('error/notFound');
               return next();
           }
   
           var contentModel = new ContentModel(apiContent);
   
           res.render('custom/contentPage', {
               content: contentModel,
               breadcrumbs: [
                   { htmlValue: 'Home', url: '/' },
                   { htmlValue: contentModel.name, url: '' }
               ]
           });
   
           next();
       }
   );
   
   /**
    * CustomPage-Submit : Handles form POST submissions
    */
   server.post('Submit',
       server.middleware.https,
       function (req, res, next) {
           var Transaction = require('dw/system/Transaction');
           var CustomObjectMgr = require('dw/object/CustomObjectMgr');
   
           var form = req.form;
           var name = form.name;
           var email = form.email;
   
           // Validate input
           if (!name || !email) {
               res.json({ success: false, error: 'Name and email are required.' });
               return next();
           }
   
           try {
               Transaction.wrap(function () {
                   var co = CustomObjectMgr.createCustomObject('AcmeSubmissions', email);
                   co.custom.name = name;
                   co.custom.submittedAt = new Date();
               });
   
               res.json({ success: true, message: 'Submission received.' });
           } catch (e) {
               var Logger = require('dw/system/Logger');
               Logger.error('Submission failed: {0}', e.message);
               res.json({ success: false, error: 'An error occurred. Please try again.' });
           }
   
           next();
       }
   );
   
   module.exports = server.exports();
   

3. Extend an existing SFRA controller

   Use server.extend to add or modify routes on an existing controller:

   // controllers/Cart.js — extending app_storefront_base Cart
   'use strict';
   
   var server = require('server');
   var page = module.superModule;  // Reference to the base Cart controller
   server.extend(page);
   
   /**
    * Cart-Show : Append custom data to the Cart page
    */
   server.append('Show', function (req, res, next) {
       var viewData = res.getViewData();
   
       // Add custom upsell products to the cart page
       var ProductMgr = require('dw/catalog/ProductMgr');
       var ArrayList = require('dw/util/ArrayList');
       var upsells = new ArrayList();
   
       var basket = require('dw/order/BasketMgr').getCurrentBasket();
       if (basket) {
           var items = basket.getAllProductLineItems();
           for (var i = 0; i < items.length; i++) {
               var recommendations = items[i].product.getRecommendations();
               for (var j = 0; j < Math.min(recommendations.length, 2); j++) {
                   upsells.push(recommendations[j].getRecommendedItem());
               }
           }
       }
   
       viewData.upsellProducts = upsells.toArray().slice(0, 4);
       res.setViewData(viewData);
       next();
   });
   
   /**
    * Cart-AddCustomItem : New route added to the Cart controller
    */
   server.post('AddCustomItem', function (req, res, next) {
       var BasketMgr = require('dw/order/BasketMgr');
       var Transaction = require('dw/system/Transaction');
       var ProductMgr = require('dw/catalog/ProductMgr');
   
       var productId = req.form.pid;
       var quantity = parseInt(req.form.quantity, 10) || 1;
       var product = ProductMgr.getProduct(productId);
   
       if (!product || !product.isOnline()) {
           res.json({ error: true, message: 'Product not available.' });
           return next();
       }
   
       var basket = BasketMgr.getCurrentOrNewBasket();
       Transaction.wrap(function () {
           var pli = basket.createProductLineItem(productId, basket.getDefaultShipment());
           pli.setQuantityValue(quantity);
       });
   
       res.json({ success: true, itemCount: basket.productQuantityTotal });
       next();
   });
   
   module.exports = server.exports();
   

4. Write ISML templates

   <--- templates/default/custom/contentPage.isml --->
   <isdecorate template="common/layout/page">
   
       <isscript>
           var assets = require('*/cartridge/scripts/assets');
           assets.addCss('/css/custom/content.css');
           assets.addJs('/js/custom/content.js');
       </isscript>
   
       <div class="container custom-content-page">
           <div class="row">
               <div class="col-12">
                   <nav aria-label="Breadcrumb">
                       <ol class="breadcrumb">
                           <isloop items="${pdict.breadcrumbs}" var="crumb" status="loopstatus">
                               <isif condition="${loopstatus.last}">
                                   <li class="breadcrumb-item active">${crumb.htmlValue}</li>
                               <iselse/>
                                   <li class="breadcrumb-item">
                                       <a href="${crumb.url}">${crumb.htmlValue}</a>
                                   </li>
                               </isif>
                           </isloop>
                       </ol>
                   </nav>
   
                   <h1>${pdict.content.name}</h1>
                   <div class="content-body">
                       <isprint value="${pdict.content.body}" encoding="off"/>
                   </div>
               </div>
           </div>
       </div>
   
   </isdecorate>
   

5. Create a data model wrapper

   // models/content.js
   'use strict';
   
   var URLUtils = require('dw/web/URLUtils');
   
   /**
    * Content model wrapping a dw.content.Content API object
    * @param {dw.content.Content} contentObj - Content API object
    * @constructor
    */
   function ContentModel(contentObj) {
       this.id = contentObj.ID;
       this.name = contentObj.name || contentObj.ID;
       this.body = contentObj.custom.body ? contentObj.custom.body.markup : '';
       this.online = contentObj.online;
       this.url = URLUtils.url('CustomPage-Show', 'cid', contentObj.ID).toString();
       this.pageTitle = contentObj.pageTitle || this.name;
       this.pageDescription = contentObj.pageDescription || '';
       this.pageKeywords = contentObj.pageKeywords || '';
   }
   
   module.exports = ContentModel;
   

6. Build a scheduled job for data processing

   // scripts/jobs/syncInventory.js
   'use strict';
   
   var Status = require('dw/system/Status');
   var Logger = require('dw/system/Logger').getLogger('inventory-sync', 'acme');
   var HTTPClient = require('dw/net/HTTPClient');
   var Transaction = require('dw/system/Transaction');
   var ProductInventoryMgr = require('dw/catalog/ProductInventoryMgr');
   
   /**
    * Job step: Fetch inventory from external ERP and update SFCC
    * @param {dw.util.HashMap} params - Job step parameters
    * @returns {dw.system.Status} - Job status
    */
   function execute(params) {
       var apiUrl = params.get('apiUrl');
       var apiKey = params.get('apiKey');
       var inventoryListId = params.get('inventoryListId') || 'default';
   
       var httpClient = new HTTPClient();
       httpClient.open('GET', apiUrl);
       httpClient.setRequestHeader('Authorization', 'Bearer ' + apiKey);
       httpClient.setRequestHeader('Accept', 'application/json');
       httpClient.setTimeout(30000);
       httpClient.send();
   
       if (httpClient.statusCode !== 200) {
           Logger.error('ERP API returned status {0}', httpClient.statusCode);
           return new Status(Status.ERROR, 'API_ERROR', 'ERP API returned ' + httpClient.statusCode);
       }
   
       var inventory = JSON.parse(httpClient.text);
       var inventoryList = ProductInventoryMgr.getInventoryList(inventoryListId);
   
       if (!inventoryList) {
           return new Status(Status.ERROR, 'LIST_NOT_FOUND', 'Inventory list not found');
       }
   
       var updated = 0;
       var errors = 0;
   
       inventory.items.forEach(function (item) {
           try {
               Transaction.wrap(function () {
                   var record = inventoryList.getRecord(item.sku);
                   if (!record) {
                       record = inventoryList.createRecord(item.sku);
                   }
                   record.setAllocation(item.quantity);
                   if (item.inStockDate) {
                       record.setInStockDate(new Date(item.inStockDate));
                   }
               });
               updated++;
           } catch (e) {
               Logger.error('Failed to update SKU {0}: {1}', item.sku, e.message);
               errors++;
           }
       });
   
       Logger.info('Inventory sync complete: {0} updated, {1} errors', updated, errors);
       return new Status(Status.OK, 'SYNC_COMPLETE', updated + ' records updated');
   }
   
   module.exports.execute = execute;
   

Examples

OCAPI hook for order creation

// hooks/order/ocapiHooks.js
'use strict';

var Status = require('dw/system/Status');
var Logger = require('dw/system/Logger').getLogger('ocapi-hooks', 'acme');

/**
 * OCAPI after-POST hook for order creation
 * Called after a new order is placed via OCAPI
 */
exports.afterPOST = function (order) {
    try {
        // Send order data to external analytics
        var HTTPClient = require('dw/net/HTTPClient');
        var httpClient = new HTTPClient();
        httpClient.open('POST', 'https://analytics.acme.com/orders');
        httpClient.setRequestHeader('Content-Type', 'application/json');
        httpClient.send(JSON.stringify({
            orderId: order.orderNo,
            total: order.totalGrossPrice.value,
            currency: order.currencyCode,
            itemCount: order.productLineItems.length,
            customerEmail: order.customerEmail,
        }));

        if (httpClient.statusCode !== 200) {
            Logger.warn('Analytics push failed for order {0}: HTTP {1}',
                order.orderNo, httpClient.statusCode);
        }
    } catch (e) {
        Logger.error('OCAPI hook error: {0}', e.message);
    }

    return new Status(Status.OK);
};

Register in hooks.json:

{
    "hooks": [
        {
            "name": "dw.ocapi.shop.order.afterPOST",
            "script": "./hooks/order/ocapiHooks"
        }
    ]
}

Form definition and server-side validation

<!-- forms/default/contactus.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<form xmlns="http://www.demandware.com/xml/form/2008-04-19">
    <field formid="name" label="form.contactus.name"
           type="string" mandatory="true" max-length="100"/>
    <field formid="email" label="form.contactus.email"
           type="string" mandatory="true" max-length="254"
           regexp="^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"/>
    <field formid="message" label="form.contactus.message"
           type="string" mandatory="true" max-length="2000"/>
    <action formid="submit" label="form.contactus.submit" valid-form="true"/>
</form>

// controllers/ContactUs.js
'use strict';
var server = require('server');

server.get('Show', function (req, res, next) {
    var contactForm = server.forms.getForm('contactus');
    contactForm.clear();
    res.render('contactus/form', { contactForm: contactForm });
    next();
});

server.post('Submit', function (req, res, next) {
    var contactForm = server.forms.getForm('contactus');

    if (contactForm.valid) {
        var Transaction = require('dw/system/Transaction');
        var CustomObjectMgr = require('dw/object/CustomObjectMgr');

        Transaction.wrap(function () {
            var co = CustomObjectMgr.createCustomObject(
                'ContactSubmission',
                require('dw/util/UUIDUtils').createUUID()
            );
            co.custom.name = contactForm.name.value;
            co.custom.email = contactForm.email.value;
            co.custom.message = contactForm.message.value;
        });

        res.json({ success: true });
    } else {
        res.json({
            success: false,
            fields: {
                name: contactForm.name.error || null,
                email: contactForm.email.error || null,
                message: contactForm.message.error || null,
            }
        });
    }
    next();
});

module.exports = server.exports();

Best Practices

• Follow the cartridge layering convention -- custom cartridges override base cartridges; use module.superModule to extend rather than replace controllers
• Use server.append over server.replace -- appending preserves the original controller logic and other cartridge extensions; replacing breaks the chain
• Wrap all database writes in Transaction.wrap() -- SFCC requires explicit transactions for all persistent changes; missing transactions cause silent failures
• Use the Script API, not direct database access -- SFCC has no direct SQL access; always use *Mgr classes (ProductMgr, BasketMgr, OrderMgr) for data operations
• Log with categorized loggers -- use Logger.getLogger(category, prefix) so log messages can be filtered in Log Center by category
• Never hardcode site-specific values -- use Site Preferences (custom site preferences in Business Manager) for configurable values like API keys and feature flags
• Test with the SFCC sandbox -- always develop and test on a sandbox instance before deploying to staging or production
• Use the SFCC linting rules -- enforce 'use strict' and check for missing next() calls in controllers, which cause request hanging

Common Pitfalls

Problem	Solution
Controller route not found (404)	Verify the cartridge is in the cartridge path (Business Manager > Sites > Manage Sites > Cartridges) and the controller file name matches the route
module.superModule returns null	Ensure the base cartridge is listed after your custom cartridge in the cartridge path; the order matters
Template changes not appearing	Clear the SFCC template cache in Business Manager (Administration > Sites > Manage Sites > Cache); ISML templates are aggressively cached
Custom Object not persisting	Ensure the operation is inside Transaction.wrap(); check that the Custom Object type is defined in Business Manager (Administration > Site Development > Custom Objects)
Job step fails silently	Return a Status object from every job step; return Status.ERROR on failure so the job framework reports the failure correctly
ISML <isprint> double-escaping HTML	Use encoding="off" in <isprint> for trusted HTML content (e.g., CMS body markup); use default encoding for user-generated content

Related Skills

• @erp-integration
• @ecommerce-caching
• @ecommerce-seo
• @pci-dss-compliance
• @product-data-modeling