Sfcc Cartridge Development

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

Related Skills

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

Inventory Sync Integration Cartridge

Problem/Feature Description

Acme Co. runs an SFCC storefront and needs to keep their product inventory levels in sync with an external ERP system. Every hour, the ERP exposes a REST endpoint that returns a JSON payload of SKU-to-quantity mappings. Currently, inventory discrepancies between the ERP and the storefront are causing overselling and customer complaints during peak periods.

Your task is to create a new SFCC cartridge called int_acme_inventory that includes a scheduled job step capable of calling the ERP API and updating the SFCC inventory list. The operations team needs to be able to update ERP connection settings and switch inventory lists without requiring a code deployment. The job must report success or failure accurately so operations staff can monitor it through the Job Framework's built-in reporting.

Output Specification

Produce the cartridge as a set of files in your working directory. The deliverable should include:

• All required cartridge metadata and configuration files at the correct paths
• The job step script at int_acme_inventory/cartridge/scripts/jobs/syncInventory.js
• A package.json at the cartridge root

The ERP API returns JSON in this shape:

{
  "items": [
    { "sku": "ABC-001", "quantity": 50, "inStockDate": "2026-04-01" },
    { "sku": "ABC-002", "quantity": 0 }
  ]
}

Write a brief IMPLEMENTATION_NOTES.md explaining how the job step parameters should be configured in Business Manager, and noting any conventions you followed.

Loyalty Points Display on the Cart Page

Problem/Feature Description

Acme's marketing team has launched a loyalty rewards program. Shoppers earn points on every purchase, and the team wants to display the estimated points they will earn for the current cart contents directly on the cart page. The points calculation is simple: 1 point per whole dollar of the cart subtotal.

You are working on a custom cartridge called int_acme_loyalty that sits on top of the existing app_storefront_base SFRA cartridge. You need to modify the Cart display so it shows the loyalty points estimate, without replacing the original cart logic or breaking any other cartridge extensions. The cart page should also include a new CSS file /css/loyalty/points.css and a JavaScript file /js/loyalty/points.js for the points UI.

Additionally, create a standalone ISML template for a "Loyalty Program Information" page that displays loyalty program details fetched from a content asset. The template should use the site's standard page layout and render the content asset body as HTML (the body is authored in Business Manager as rich text). The template should include a breadcrumb and support the CSS/JS assets described above.

Output Specification

Produce the cartridge files in your working directory under int_acme_loyalty/. Deliverables should include:

• The extended Cart controller at int_acme_loyalty/cartridge/controllers/Cart.js
• The ISML template for the loyalty information page at int_acme_loyalty/cartridge/templates/default/loyalty/infoPage.isml
• A IMPLEMENTATION_NOTES.md describing the approach taken and any SFCC-specific conventions used

Post-Order Analytics Hook and Customer Feedback Form

Problem/Feature Description

Acme's e-commerce platform needs two new integrations in a custom SFCC cartridge called int_acme_engagement:

Order Analytics Hook: The analytics team wants to receive order data in real-time whenever a new order is placed through the OCAPI storefront API. They have provided an endpoint that accepts order summary data as a JSON POST. The hook must be wired in correctly so SFCC calls it automatically after each OCAPI order creation.

Customer Feedback Form: The customer success team needs a feedback form on the storefront where shoppers can submit their name, email, and a message after completing a purchase. The form should validate that all three fields are present before saving the submission. Submissions should be persisted as SFCC Custom Objects. The support team expects to be able to diagnose errors from log files in Business Manager.

Build both features and include a IMPLEMENTATION_NOTES.md that describes the file layout and how the hook registration works.

Output Specification

Produce all files under int_acme_engagement/ in your working directory. The deliverable should include:

• The OCAPI hook implementation and its registration configuration
• The feedback form controller at int_acme_engagement/cartridge/controllers/Feedback.js
• The form handling support files
• IMPLEMENTATION_NOTES.md describing the file layout and approach