Skip to content
Log in

Upgrade guide — v21 to v22

On this page

v22 is a large release across the web store, the POS, and payments. This guide gives you a plain-English overview of what has changed, followed by detailed upgrade steps in each subsection. Most changes are opt-in, or switch on automatically where your theme uses the base templates. The items that need action before or straight after the upgrade are the removed Price Book Entry fields, the change to how Liquid tag option values are rendered, the base-theme templates that custom themes may override, and the promotions.version store variable on any store that uses Advanced promotions. The guide assumes you are on the latest v21 website release; changes that already shipped in v21 patch releases are not repeated. If you are on an earlier version, upgrade through v21 first using the v20 to v21 upgrade guide.

The package that pairs with v22 is package v22.0. Package releases during the v21 cycle, from v21.1 to v21.14, are included here as well, because they were not covered by the previous upgrade guide. If you are already on a late v21 package, some of the Salesforce changes below are already in your org. After the package upgrade, add the new picklist values with the Console’s Manage picklist values tool; the E-commerce section lists them.

Customer address book

Signed-in customers can save any number of addresses in their account area, flag a default shipping and billing address, and pick a saved address at checkout. The addresses are stored in a new Address__c object with an Addresses tab and related lists on Account and Contact. The existing billing and shipping fields on Account are unchanged and are still used when no saved address exists.

Audit log and fraud review

A new Audit_Log__c object records security-relevant activity: sign in and sign out, failed logins, signup, password changes and resets, invitations, email changes, payment attempts and outcomes, POS register logins and shifts, and fraud screening decisions. Recording starts at the STANDARD level on upgrade, each store can set its own level and retention, and viewing records needs the new StoreConnect Audit Viewer permission set. Orders can also be screened by a fraud provider before the gateway is charged; a new Risk Review field and a Fraud Review Queue list view hold flagged orders. Screening is off until a provider is configured.

AI agents and content change review

AI agents can be connected to a store from the StoreConnect Console with a per-user token, and a new API Scopes field on Store Role sets what each role can do. Everything an agent or editor stages is a content change that must be published by an approver, who by default cannot be the author. A new StoreConnect Content Change Approver permission set and a Preview URL on each change support the review. If one person both edits and publishes today, see the E-commerce section before upgrading.

Saved payment methods, deposits, and multi-shipping

Customers on Stripe, Stripe ACH, or Square can save a card and reuse it at checkout, and products can be sold as save-card-only or preauthorize-only. Web checkout can take a deposit instead of the full amount when a store variable is set. A cart whose items cannot ship together can check out as several deliveries when multi-shipping is enabled. PayPal Fastlane is a new payment option, and Vii gift cards move into the vouchers component.

Product channels and rich results

A product can be hidden from the web store or the POS with the new Excluded Channels field, with a blank value meaning sold everywhere. Products also gain rating, shipping, warranty, return policy, and attribute fields that the storefront publishes as structured data for search engine rich results, and the Color, Material, Size, and Pattern fields fill themselves from traits.

URLs and caching

A store can rename its built-in URL segments, such as /cart to /panier, treat legacy .html URLs as optional, and let a CDN serve its public pages from a cached copy. All three are off until a store variable turns them on. A product or category can also declare a canonical path override for the URL search engines already index.

Feeds

Store data can be published as a paginated feed in JSON, XML, CSV, HTML, Markdown, or text, defined entirely in Salesforce with the new Query__c, Feed__c, and Store_Feed__c objects. The existing Data_Feed__c object continues to work.

Liquid changes

A value passed to a tag option from a variable is now read as data rather than executed as a template. This closes a path where merchant-entered or customer-entered text could run as code. Markup written directly in the template still renders. Templates that relied on the old behavior report an error in the Web Console and need a small change, described in the E-commerce section. Themes also gain programmatic shipping actions, image filters, and deferred components. The shipping.set action is deprecated in favor of shipping.update. Advanced promotions now respect products excluded from price reductions, no longer stack on sale prices, and can be limited to the web store or the POS. Each store now runs one promotions engine on the web store: set the store variable promotions.version to v2 to keep Advanced promotions working online, which turns off standard promotion codes on that store. Custom cart fields are copied to the order at checkout.

POS

The POS gains fulfillment stations for routing orders to preparation areas such as a kitchen or bar, open orders for tabs and table service, fast checkout, tipping, smart cash, typeable quantities, and an unsaved changes view that shows what is still waiting to reach the server while a device is offline. Payment method settings are now read from synced store variables, and a register can override cash on or off locally unless the store locks it. The Layouts section in POS Settings has been removed in favor of layout records with identifiers, the sidebar and topbar are redrawn with a More menu, layout page titles are hidden by default, and a customer can be saved with only a phone number. Linkly and Latitude payments can be recovered after an interruption, subscriptions sold at the POS capture a card for later billing, and a store can keep its POS devices on a dedicated hostname while the storefront moves domain.

Payments

Refunds from within StoreConnect extend to SecurePay. The eWay preauthorization setting, previously ignored, now takes effect, so eWay stores with it switched on should check the Payments section before upgrading. An eWay charge whose answer is lost is now held and re-checked instead of being retried, Latitude web payments settle per outlet, and vouchers can be applied on the order balance payment page.

Subscriptions

Fixed-term subscriptions paid upfront are charged their term once, correcting an overcharge. Plan-change orders complete like renewal orders. Renewal orders are populated before charging and are not populated twice, partially paid renewals charge only the balance, and a renewal order can be paid without signing in when a store variable allows it.

Sync

Failed change events retry automatically, failures caused by a missing parent record are retried in the background without appearing in the sync error list, and duplicate-rule failures are marked permanent with opt-in settings that let StoreConnect attach the incoming record to the matching account or contact. Orgs with Person Accounts can convert new customers automatically by naming a record type in a setting.

Console, email, and account security

Product traits can be built and assigned from the Console, and the Console header searches StoreConnect records, including theme templates and assets that Salesforce global search cannot find. Orgs that grant Console access through custom permission sets need to add the search class to them. The eighteen package email templates have been redesigned for new installs; existing orgs keep their current templates and can request the new design from StoreConnect support. A guest can set a password after checkout only from the session that placed the order, and Pay by Account now requires the contact’s flag to be set. login.gov is available as a single sign-on provider.

Deprecated metadata cleanup

Two unused subscription pricing fields, Subscription Balloon Price and Subscription Setup Price, have been removed from Price Book Entry. 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 following fields are removed:

PricebookEntry - s_c__Balloon_Price__c (Subscription Balloon Price). Not read by StoreConnect. The field of the same name on s_c__Subscription__c is unaffected. - s_c__Setup_Price__c (Subscription Setup Price). Not read by StoreConnect. The field of the same name on s_c__Subscription__c is unaffected.

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. If you use promotions, apply a promo code to a test cart and confirm the discount shows in the cart totals.
  3. Confirm payment processing works for each of your active payment providers. If you process refunds through StoreConnect, test a refund as well.
  4. If you use the StoreConnect POS, complete a test sale and confirm it syncs.
  5. If you use subscriptions, confirm renewals and payment collection work correctly.
  6. Check the Sync Error log in the StoreConnect Console for new sync errors and review your error logs.
  7. 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 Upgrade guide — v20 to v21

Was this article helpful?

Was this article helpful?