{"title":"Upgrade guide — v20 to v21","slug":"upgrade-guide-v20-to-v21","url":"https://support.storeconnect.com/articles/upgrade-guide-v20-to-v21","url_markdown":"https://support.storeconnect.com/articles/upgrade-guide-v20-to-v21.md","subtitle":null,"summary":"A plain-English overview of what changed in v21, including Advanced promotions, StoreConnect Bundles, multi-channel shipping and tax, and multi-gateway refunds, with links to detailed upgrade steps.","type":"Release_Notes","video_url":"","keywords":null,"last_modified":"2026-08-21T07:12:35+0000","body_markdown":"v21 is a significant release with major updates across promotions, POS, and payments, and introduces StoreConnect Bundles as a new feature. This guide gives you a plain-English overview of what has changed, followed by detailed upgrade steps in each subsection.\n\nView the full [Version 21 release notes](version-21-release-notes) for feature details and breaking changes.\n\n## Advanced promotions\n\nStoreConnect v21 introduces a new Advanced promotions engine with a dedicated Salesforce data model. Nine new objects support the full promotion lifecycle: `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`. The engine supports promo codes, auto-applied promotions, free product rewards, and free shipping rewards. Permissions for all nine objects are included in the standard StoreConnect permission sets.\n\n## StoreConnect Bundles\n\nv21 introduces StoreConnect Bundles, a native bundle solution for stores that do not use or need Salesforce CPQ. Products can be flagged as bundle-only via their pricebook entry, preventing them from being added to a cart directly and reserving them for use as bundle components only.\n\n## Multi-channel shipping and tax\n\nShipping rates and tax providers can now be scoped to specific channels. The new `Channels__c` field on `Shipping_Rate__c` and `Tax_Provider__c` specifies whether the rate or provider applies to the web store, the POS, or both. Existing records are automatically backfilled with both channels during the package upgrade.\n\n## Multi-gateway refunds\n\nRefund support has been extended to a wider range of payment gateways, including Adyen, ZippayAu, Windcave, Tyro, PayWay, and CyberSource. These gateways previously required refunds to be processed outside StoreConnect.\n\n## eWay integration rewrite\n\nThe eWay integration has been rewritten in v21, adding 3DS2 support, subscription payments, wallet payments (Apple Pay and Google Pay), and express checkout. The new integration requires the Payment Provider **API Mode** field to contain exactly the lowercase value `production` for live payments. If your store uses eWay, review the Payments section of this guide before upgrading — an incorrect API Mode value will stop card payments after the upgrade.\n\n## POS improvements\n\nv21 includes a major overhaul of the POS sync system. Sync now uses cursor-based pagination, improving reliability and removing the previous 72-hour window limitation on order retrieval. A new `Register_Shift_Id__c` field on `Payment__c` links payments to POS register shifts for end-of-shift reconciliation. New `outlet` and `register` Liquid drops are available in POS templates.\n\n## Custom objects in Liquid\n\nSalesforce custom objects can now be synced to the web store and queried using Liquid templates, enabling data from any synced custom object to be surfaced on store pages.\n\n## Voucher enhancements\n\nVouchers now support an activation deadline via the new `Activate_Before_Datetime__c` field on `Voucher__c`. Voucher audit logging has been added, and asset linking is now supported.\n\n## Subscription improvements\n\nNew delinquency tracking fields on `Subscription__c` provide visibility into subscriptions that have missed payment cycles. eWay v2 subscriptions now support 3DS token rotation.\n\n## ZippayAu\n\nThe legacy Zippay v1 API integration has been replaced with ZippayAu. If your store uses Zippay, review the Payments section of this guide before upgrading.\n\n## Account security\n\nv21 strengthens account security for web storefronts. New customer accounts created at checkout must confirm their email before they can log in, and password changes now require the current password. Customer sessions now time out after a period of inactivity and after a maximum session length, customer accounts lock after repeated failed login attempts, and login and password reset forms no longer reveal whether an email address has an account. All of the timeout and lockout behavior ships with safe defaults and can be tuned with store variables. See the E-commerce section of this guide, and [Store security settings](store-security-settings).\n\n## Deprecated metadata cleanup\n\nv21 removes several fields that are no longer used by StoreConnect. After upgrading, these fields remain in your org until you manually delete them. Running the cleanup is recommended to keep your org tidy and avoid confusion with unused fields appearing in Salesforce.\n\n\u003e **Warning: Deleting deprecated metadata permanently removes the fields and all data stored in them.** Review each field below before proceeding. If any field still holds data you rely on, export or migrate it first — this action cannot be undone.\n\nThe following fields are removed in v21:\n\n**`s_c__Store__c`**\n- `s_c__Pay_By_Account_Enabled__c` — Controlled whether Pay By Account was enabled on the store. If your store has used this feature, confirm it is no longer needed before deleting.\n\n**`s_c__Outlet_Stock_Location__c`**\n- `s_c__Priority__c` — Previously used to set a priority order for outlet stock locations. If you have assigned priorities, note your current values before proceeding — they will be permanently lost.\n\n**`s_c__Pos_Layout__c`**\n- `s_c__Grid_Columns__c` — Previously defined the number of columns in a POS layout grid. POS layout grid configuration has been redesigned in v21.\n- `s_c__Grid_Rows__c` — Previously defined the number of rows in a POS layout grid. POS layout grid configuration has been redesigned in v21.\n\n**`s_c__Trait_Category__c`**\n- `s_c__Display_As_Filter_Top_Level__c` — Controlled whether a trait category appeared as a top-level filter. If you have trait categories configured this way, note your current setup before deleting.\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 — v20 to v21 — E-commerce](upgrade-guide-v20-to-v21-ecommerce) — applies to all stores\n- [Upgrade guide — v20 to v21 — POS](upgrade-guide-v20-to-v21-pos) — POS users only\n- [Upgrade guide — v20 to v21 — Subscriptions and vouchers](upgrade-guide-v20-to-v21-subscriptions) — subscription and voucher users only\n- [Upgrade guide — v20 to v21 — Payments](upgrade-guide-v20-to-v21-payments) — if adopting a new gateway or if you use Zippay or eWay\n- [How to delete deprecated metadata](how-to-delete-deprecated-metadata) — recommended for all orgs upgrading to v21\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. Confirm payment processing works for each of your active payment providers. If you process refunds through StoreConnect, test a refund as well.\n3. If you use the StoreConnect POS, complete a test sale and confirm it syncs.\n4. If you use subscriptions, confirm renewals and payment collection work correctly.\n5. Check the Sync Error log in the StoreConnect Console for new sync errors and review your error logs.\n6. 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."}