Guide: Upgrade and customization for Salesforce Commerce Cloud cartridge

In this guide, discover the importance and process of upgrading your Salesforce Commerce Cloud (SFCC) cartridge to the latest version to create a hassle-free integration and seamless checkout experience benefitting both you and your customers. We'll highlight best practices for customizations and walk you through the process of adding custom code to a new cartridge, ensuring a smooth transition to the latest releases.

As an online business owner, ensuring a smooth and seamless checkout experience for your shoppers is vital to success. To achieve this, customizations are often necessary to tailor your checkout process to meet specific needs. To take advantage of new features, bug fixes, and security patches, you’ll need to stay up-to-date with the latest cartridge version.

This guide is specifically tailored to users of the Salesforce Commerce Cloud Storefront Reference Architecture (SFRA). If your e-commerce platform does not utilize SFRA, some of the outlined steps and procedures may not be directly applicable.

The benefits of upgrading your cartridge

Upgrading your cartridge to the latest version offers several benefits that can significantly enhance your checkout experience. Here's why you should consider upgrading:

1. Access to new features: Each cartridge release comes with exciting new features that can improve the overall functionality and usability of your checkout process. This ensures that you offer your customers the best shopping experience.

2. Bug fixes and security patches: As with any software, cartridges might have bugs or security vulnerabilities. Regular updates and upgrades address these issues, not only ensuring that your checkout process remains secure, but also improving the authorization rate.

3. Compatibility with integrations: Third-party integrations and platforms continually evolve, and cartridge updates often ensure compatibility with the latest versions of these integrations. Upgrading your cartridge reduces the risk of conflicts and ensures a seamless connection with your preferred tools.

4. Continued Cartridge support: We provide support and assistance for the latest versions, making it easier to troubleshoot issues and seek guidance whenever needed.

Customization guide for smoother upgrade (SFRA)

Merchants use customizations to communicate their brand value to shoppers. Customizations are a great way to offer a unique shopper experience. Unfortunately, if customizations are implemented inside of the cartridge, they obscure future cartridge upgrades and introduce technology bottlenecks. We've created a 4-minute video to help you decouple your customizations and upgrade a customized cartridge to the latest version. You can skip the video if you prefer a step-by-step text guide.

Step 1: Add custom code to a new cartridge

To make future upgrades and troubleshooting easier, add your custom code to the int_custom_cartridge folder in your src/cartridges directory. If this folder is not available in your version, create a new folder and name it; int_custom_cartridge and add your custom code. This setup will allow you to temporarily remove custom code during upgrades or troubleshooting.

# Add your custom code to the int_custom_cartridge folder
# Modify the code as needed to customize the checkout experience. For example, in JavaScript:

# File: int_custom_cartridge/scripts/customization.js

function customizeCheckout() {
  // Your custom code here
  console.log("Custom checkout code executed.");
}

Step 2: Include custom cartridge in package.json file

Update the name property in the package.json file to int_custom_cartridge or the name you chose for your custom cartridge.

# Update package.json to support the custom cartridge
# File: int_custom_cartridge/package.json
{
  "name": "int_custom_cartridge",
  "version": "1.0.0",
  "description": "Custom cartridge for checkout customization",
  // Other package.json properties
}

# Update root package.json to contain the new cartridge in the build step
# Make sure you are in the root directory of your project and run

npm install
npm run build

Step 3: Add the new cartridge to your cartridge path

In the Business Manager, navigate to Administration > Sites > Manage Sites > [yourSite] > Settings. In the Cartridges field, add the new cartridge before the Adyen cartridges. Click “Apply” to save your changes.

Step 4: Modify or add end-to-end tests (optional)

To ensure your custom code works correctly, modify or add end-to-end tests as needed. Running these tests will validate the functionality of your customizations.

Upgrade guide for different integrations

Depending on your integration type (Default or Customized), the upgrade process varies:

Default integration

• Check which SFRA version is required for the upgrade and migrate if necessary, aiming to use the highest available SFRA version
• Download the desired Adyen cartridge version from GitHub
• Transpile, compile, and upload the compatible, auto-generated code using npm run build
• Re-upload the metadata

# Download the desired Adyen cartridge version from GitHub
# Replace '23.1.0' with the version you want to upgrade to
git clone https://github.com/adyen/adyen-salesforce-commerce-cloud.git --branch 23.1.0

# Re-upload the metadata
# Make sure you are in the root directory of your project
cd adyen-salesforce-commerce-cloud

# Transpile, compile, and upload the compatible, auto-generated code
npm run build

# Zip the site_import folder
zip -r adyen_integration.zip package/metadata/site_import/sites

# In Business Manager, go to Administration > Site Development > Site Import & Export
# Import the zipped file (site_import.zip)

Customized integration

For a quick demo of how to upgrade the SFCC cartridge with customization, watch this 2 mins video.

Steps:

• Extract any custom code from the cartridge and place it in the custom cartridge (int_custom_cartridge) folder. Create a new folder if not available in your version.
• Check SFRA version requirements and migrate if needed
• Download the desired Adyen cartridge version from GitHub
• Update the package.json as explained above and run npm run build
• Re-upload the metadata
• Update the cartridge path in the Business Manager to include your customizations

Conclusion

In today's competitive e-commerce landscape, the checkout experience can make or break a customer's decision to complete a purchase. As an online business owner, customizing your checkout process is essential to cater to your unique requirements and create a branded experience that resonates with your audience. However, these customizations must not come at the cost of missing out on crucial updates and improvements.

By following this guide to upgrading your cartridge to the latest version, you can strike the perfect balance between customization and innovation. Embrace the latest features, bug fixes, and security patches to ensure a seamless and secure checkout journey for your shoppers.

Upgrading your cartridge to the latest version is more than just a technical necessity - it's an investment in your business's success. Stay ahead of the competition by accessing new capabilities that improve the functionality of your checkout process and enhance customer satisfaction. Take your e-commerce venture one step closer to excellence.

So, are you ready to unlock the full potential of your checkout process? Your dedication to providing the best checkout experience will not only increase conversion rates but also foster customer loyalty.

Upgrade today and let your checkout experience set the gold standard for online shopping!