Skip to content
Log in

Upgrade guide — v20 to v21

On this page

v21 is a significant release across promotions, payments, and account security, and introduces StoreConnect Bundles. This guide gives you a plain-English overview of what has changed, followed by detailed upgrade steps in each subsection. Most changes switch on automatically where your theme uses the base templates, or are opt-in. The items that need action are the removed package fields, the picklist values a package upgrade does not add, two customized account templates, and the base-theme templates a custom theme may override.

The guide assumes you are on the latest v20 website release. Changes that already shipped in v20 patch releases are not repeated here. The package that pairs with v21 is package v21.0, and the package releases during the v20 cycle, from v20.1 to v20.25, are included because the previous upgrade guide did not cover them. Later v21 package releases are covered by the v21 to v22 upgrade guide. The StoreConnect POS is treated as new in v21, so this guide has no POS section; POS upgrade steps start with the v21 to v22 guide.

View the full Version 21 release notes for feature details.

Advanced promotions

A new Advanced promotions engine runs alongside the existing promotions with its own Salesforce data model: Promotion2__c, Condition__c, Reward__c, Cart_Promotion2__c, Promotion2_Condition__c, Promotion2_Product_Scope__c, Promotion2_Usage__c, Reward_Usage__c, and Order_Item_Reward__c. It supports promo codes, automatic promotions, free product rewards, and free shipping rewards. Permissions for all nine objects are included in the standard StoreConnect permission sets, and products can be kept out of promotions with the new Exclude From Price Reductions field.

StoreConnect Bundles

StoreConnect Bundles is a native bundle solution for stores that do not use Salesforce CPQ, built on three new objects: Product_Component__c, Component_Group__c, and Component_Pricing__c. A product can be flagged as bundle-only on its price book entry so it is sold only as a component.

Payments

Refunds from within StoreConnect extend to Adyen, Adyen ACH, ZippayAu, Windcave, Tyro, PayWay, CyberSource, and NMI, and to a customer’s account credit or loyalty points. Pre-authorized payments can be captured in several partial installments, recorded as Payment_Installment__c records, and a product can set how its payment is captured. Saved cards are stored as Payment_Method__c records. NMI, Flywire, and StoreConnect Pay are new web gateways, NMI and Westpac Online Pay support 3D Secure 2, and the CyberSource card form offers more networks by default, which needs a check if your account does not accept them. The legacy Zippay v1 integration is replaced by ZippayAu.

Multi-channel shipping, tax, and scripts

A Channels field on shipping rates, tax providers, payment providers, shipping providers, script blocks, and style blocks scopes each record to the web store, the POS, or both, so a web-only script or rate can be kept off the POS. Existing shipping rates and tax providers are backfilled with both channels during the package upgrade.

Vouchers and subscriptions

Vouchers gain a PIN, a status, an activation code and deadline, asset backing, a sales mechanism that creates and activates the voucher when a voucher product is sold, and an audit log in Voucher_Log__c. Subscriptions gain a plan change mode with proration, a Subscription_Change__c audit record, validation fields, a Pay Owing page for failed renewals, and purchase through wallets and express checkout.

Account security

New customer accounts created at checkout must confirm their email before they can log in, password changes require the current password, password reset links expire, customer sessions time out, accounts lock after repeated failed logins, and login and password reset forms no longer reveal whether an email address has an account. All of the timeouts and lockouts ship with safe defaults and can be tuned with store variables. Two customized account templates need updating; see the E-commerce section.

Site Builder and Liquid

Sections of a page can be rendered as components that load or refresh independently, and the base theme’s cart, mini-cart, checkout payment step, vouchers, and order summary now are components. A Content Security Policy header ships in report-only mode, stealth mode hides a store from search engines, a first-party Google Tag Manager gateway is available, theme controllers are imported with themes, theme files larger than 128 KB are supported, and pages and articles can be served in alternative formats such as JSON or XML.

Salesforce console and sync

The Salesforce console is redesigned around a setup wizard, and gains a Media Manager with folders, a Schema Explorer, and a picklist updater that adds new picklist values after a package upgrade. Custom objects can be synced to the store with a Flow using the StoreConnect: Sync Record Changes action, route mappings are created automatically when a path or slug changes, and sync can be limited to records you opt in.

Deprecated metadata cleanup

The package no longer contains eighteen fields that earlier releases deprecated. After upgrading, they remain in your org until you delete them. Running the cleanup is recommended to keep your org tidy.

Warning: Deleting deprecated metadata permanently removes the fields and all data stored in them. Review each field before proceeding. If a field still holds data you rely on, export or migrate it first. This action cannot be undone.

The removed fields are listed, with their replacements, under Removed deprecated fields in the E-commerce section: three on Order, two on Discount, two on Shipment, one on Shipping Rate, two on Stock Location, the Slug on Article Category and Product Category, and six image and file fields on Media.

Follow the How to delete deprecated metadata guide to deploy the cleanup zip file using Workbench.

Upgrade steps

Work through the sections that apply to your implementation:

Test your store after upgrading

This guide covers the changes StoreConnect has identified for this release. It cannot anticipate every custom Flow, integration, report, or third-party package in your org. Do not rely on this guide alone. Plan and run your own thorough testing after upgrading.

At a minimum, test every function that is critical to your business:

  1. Place a test order end-to-end through checkout and confirm it syncs to Salesforce correctly.
  2. Confirm payment processing works for each of your active payment providers. If you process refunds through StoreConnect, test a refund as well.
  3. If you use the StoreConnect POS, complete a test sale and confirm it syncs.
  4. If you use subscriptions, confirm renewals and payment collection work correctly.
  5. Check the Sync Error log in the StoreConnect Console for new sync errors and review your error logs.
  6. Test any custom Flows, automations, and integrations that touch StoreConnect objects.

See the post-upgrade tasks in Managing StoreConnect upgrades for the full checklist.

Related articles

Documentation Managing StoreConnect upgrades Documentation How to delete deprecated metadata Documentation Version 21 release notes

Was this article helpful?

Was this article helpful?