{"title":"Upgrade guide — v21 to v22","slug":"upgrade-guide-v21-to-v22","url":"https://support.storeconnect.com/articles/upgrade-guide-v21-to-v22","url_markdown":"https://support.storeconnect.com/articles/upgrade-guide-v21-to-v22.md","subtitle":null,"summary":"A plain-English overview of what changed in v22, including the customer address book, audit log and fraud review, AI agent access with content change approvals, saved payment methods, POS fulfillment stations and open orders, and the change to how Liquid tag options are rendered, with links to detailed upgrade steps.","type":"Release_Notes","video_url":"","keywords":null,"last_modified":"2026-10-29T05:10:46+0000","body_markdown":"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](upgrade-guide-v20-to-v21).\n\nThe 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.\n\n## Customer address book\n\nSigned-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.\n\n## Audit log and fraud review\n\nA 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.\n\n## AI agents and content change review\n\nAI 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.\n\n## Saved payment methods, deposits, and multi-shipping\n\nCustomers 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.\n\n## Product channels and rich results\n\nA 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.\n\n## URLs and caching\n\nA 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.\n\n## Feeds\n\nStore 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.\n\n## Liquid changes\n\nA 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.\n\n## POS\n\nThe 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.\n\n## Payments\n\nRefunds 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.\n\n## Subscriptions\n\nFixed-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.\n\n## Sync\n\nFailed 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.\n\n## Console, email, and account security\n\nProduct 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.\n\n## Deprecated metadata cleanup\n\nTwo 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.\n\n:::warning\nDeleting 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.\n:::\n\nThe following fields are removed:\n\n**`PricebookEntry`**\n- `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.\n- `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.\n\nFollow the [How to delete deprecated metadata](how-to-delete-deprecated-metadata) guide to deploy the cleanup zip file using Workbench.\n\n## Upgrade steps\n\nWork through the sections that apply to your implementation:\n\n- [Upgrade guide — v21 to v22 — E-commerce](upgrade-guide-v21-to-v22-ecommerce), applies to all stores\n- [Upgrade guide — v21 to v22 — POS](upgrade-guide-v21-to-v22-pos), POS users only\n- [Upgrade guide — v21 to v22 — Subscriptions](upgrade-guide-v21-to-v22-subscriptions), subscription users only\n- [Upgrade guide — v21 to v22 — Payments](upgrade-guide-v21-to-v22-payments), if adopting a new gateway or if you use eWay, Latitude, SecurePay, or Vii gift cards\n- [How to delete deprecated metadata](how-to-delete-deprecated-metadata), recommended for all orgs upgrading to v22\n\n## Test your store after upgrading\n\nThis 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.\n\nAt a minimum, test every function that is critical to your business:\n\n1. Place a test order end-to-end through checkout and confirm it syncs to Salesforce correctly.\n2. If you use promotions, apply a promo code to a test cart and confirm the discount shows in the cart totals.\n3. Confirm payment processing works for each of your active payment providers. If you process refunds through StoreConnect, test a refund as well.\n4. If you use the StoreConnect POS, complete a test sale and confirm it syncs.\n5. If you use subscriptions, confirm renewals and payment collection work correctly.\n6. Check the Sync Error log in the StoreConnect Console for new sync errors and review your error logs.\n7. Test any custom Flows, automations, and integrations that touch StoreConnect objects.\n\nSee the post-upgrade tasks in [Managing StoreConnect upgrades](managing-storeconnect-upgrades) for the full checklist."}