Skip to content
Log in

Upgrade guide — v20 to v21 — E-commerce

On this page

This section applies to all stores. Make sure you review every subsection.

The guide assumes you are on the latest v20 website release. Changes that already shipped in v20 patch releases are not repeated here.

Each heading starts with a label. Action required means you must do something, or the heading tells you in its first sentence who must. Review means check whether the change affects your implementation. If a subsection only applies when you use a feature or have customized a template, it says so in the first sentence, so you can skip it when it does not apply to you.

Before you upgrade

Use this list to find the subsections that need your attention:

Salesforce package changes

Action required: Removed deprecated fields

The following fields were deprecated in earlier releases and are no longer in the StoreConnect package. If you have Flows, Process Builder processes, validation rules, reports, page layouts, or integrations referencing any of these fields, update them to use the replacement fields before upgrading.

Object Removed field Replacement field
Order Customer_Notes__c Customer_Notes_Long__c
Order Shipping_Cost__c Sum of Shipment__c.Cost__c or Shipment__c.Charge__c
Order Total_Taxes__c Total_Tax_Amount__c
Discount__c Ending_Date__c Expires_At__c
Discount__c Starting_Date__c Starts_At__c
Shipment__c Order_Item_Id__c Order_Id__c
Shipment__c Status__c State__c
Shipping_Rate__c Unit_Cost__c Unit_Cost_Amount__c
Stock_Location__c Click_And_Collect_Allowed__c Online_Fulfillment_Options__c
Stock_Location__c Fulfill_Online_Orders__c Online_Fulfillment_Options__c
Article_Category__c Slug__c Path__c
Product_Category__c Slug__c Path__c
Media__c Embed_Video_Url__c Url__c
Media__c File__c Url__c
Media__c Large_Image__c Url__c, with sizes requested through the image filters
Media__c Medium_Image__c Url__c, with sizes requested through the image filters
Media__c Original_Image__c Url__c
Media__c Thumbnail_Image__c Image_Preview__c

These fields have also been removed from the standard StoreConnect permission sets. Before removing access from any custom permission sets or cleaning up any references, confirm the field is not used for purposes outside of StoreConnect, for example in custom Flows, integrations, or reporting that your org relies on independently. If a field has custom uses, assess whether those uses should be migrated to the replacement field before removing access.

  1. Search your Flows, Process Builder processes, and validation rules for references to the removed fields. For each reference found, determine whether it serves a StoreConnect purpose (update to the replacement field) or a custom org purpose (assess whether to migrate or retain separately).
  2. Search your reports, dashboards, and list views for any that include these fields. Update or retire them as appropriate.
  3. Review your page layouts and remove any removed fields.
  4. Review custom permission sets that granted access to these fields. Remove the access only once you have confirmed the field is no longer needed for any purpose in your org.
  5. After the package upgrade, delete the fields from your org by deploying the cleanup zip in How to delete deprecated metadata. The fields stay in your org until you do.

Action required: Add the new picklist values after the package upgrade

A package upgrade does not add new picklist values to fields that already exist in your org. Four fields gained values during this release and StoreConnect relies on them, so a missing value stops a provider from being selected or rejects a sync.

Object Field New values Why it matters
Payment_Provider__c Provider__c AdyenAch, Afterpay, AuthorizeNetAch, CyberSource, EwayV2, Flywire, Latitude, TouchNet, Tyro, WestpacOnlinePay, Windcave Needed to configure those payment providers
Payment__c Status__c partial_capture Written when part of a pre-authorized payment is captured
Shipment__c Fulfillment_Type__c reserved Written for reserved product fulfillments
Shipping_Provider__c Provider__c Custom Needed to configure a custom shipping provider
  1. After the package upgrade, open the StoreConnect Console, select Setup, then Manage picklist values.
  2. For each object and field listed, select Apply new values.
  3. Repeat until the Console reports that every picklist is up to date.

The full procedure is in Managing StoreConnect upgrades.

Action required: Adjust stock through Change Quantity and Set Quantity

This applies only if you have Flows, Apex, or integrations that write Count On Hand or Available To Sell on Stock_Level__c directly. The Stock Level record page now shows those two values as read-only formula fields, Count_On_Hand_Formula__c and Available_To_Sell_Formula__c, and StoreConnect maintains the underlying fields itself. Stock is adjusted through Change_Quantity__c, which adds or subtracts units, or Set_Quantity__c, which sets an absolute count.

  1. Search your Flows, Process Builder processes, Apex, and integrations for writes to Count_On_Hand__c or Available_To_Sell__c.
  2. Change each one to write Change_Quantity__c or Set_Quantity__c instead.
  3. Make manual adjustments in Salesforce through the Change Qty or Set Qty field on the Stock Level record.

See Stock Level Object Reference.

Action required: Password change now requires the current password

Changing a password now requires the user to enter and confirm their current password, which is validated server-side before the change is accepted. Stores using the standard account template get this automatically.

If you have customized snippets/account/profile or snippets/account/credentials, the password-change form fails silently until you add the current-password field: the submission cannot satisfy the new requirement, and no error is shown.

If you have not customized these snippets, no action is needed.

  1. In Site Builder, open your customized snippets/account/credentials (or snippets/account/profile if your override includes the password form).
  2. Inside the {% unless current_store.sso_login? %} block, add the current-password field directly before the existing new-password field. Copy the field from the current base template so the markup matches the release.

Password-change events now also notify the account holder by email.

Action required: New-account checkout now requires email confirmation

When a new customer sets a password during checkout, StoreConnect now emails them a confirmation link and, by default, requires them to confirm their email before they can log in to their account. Previously, new accounts had a one-hour grace period before confirmation was enforced. That grace period is now 0 by default. You can restore a grace period, including the previous one-hour behavior, with the logins.unconfirmed_access_minutes store variable. See Store security settings.

If you have customized snippets/account/checkout/set_password, update it to display a “check your email to confirm your account” message after the form submits, rather than surfacing a password error.

If you have not customized this snippet, no action is needed.

  1. In Site Builder, open your customized snippets/account/checkout/set_password.
  2. After submission, show the email-confirmation message in place of the previous password-error handling.

Review: New account security defaults

StoreConnect now applies several account security protections to web storefront sessions. These apply automatically with safe defaults, so no action is required, but you should be aware of the new behavior. Each one can be tuned using store variables. See Store security settings for the full list of variables and defaults.

  • Session timeouts. Customer sessions expire after 30 minutes of inactivity, and after 60 minutes from login regardless of activity. When a session expires, the customer is logged out. Configure with session.inactivity_timeout_minutes and session.absolute_timeout_minutes. These apply to web sessions only. POS sessions are not affected.
  • Account lockout. A customer account locks after 5 consecutive failed login attempts, and unlocks automatically after 15 minutes. Configure with passwords.lockout.failed_attempts_threshold and passwords.lockout.max_duration_minutes. A password reset clears the lockout immediately.
  • Password reset links expire. A reset link expires after 6 hours by default, set per store with passwords.reset.within_minutes. A customer who follows an expired or already-used link is returned to the password reset form with a message and can request a new link.
  • User enumeration protection. Login and password reset forms return identical messages whether or not an email address exists in the system. This protection is always on and cannot be configured.
  • Contact timestamps. Invitation_Accepted_At__c and Password_Reset_At__c are new on Contact, and Last Login Date is recorded when a customer sets a password by accepting an invitation or resetting it.
  • Content Security Policy. The base theme emits a Content Security Policy header in report-only mode. Set the content_security_policy_type store variable to enforce to block violations, and content_security_policy to supply your own policy.

If you have customized your login, password reset, or account templates, review them to confirm the generic messaging and the lockout and session behavior display correctly for your customers.

Review: Advanced promotions objects

Nine new Salesforce objects support the Advanced promotions engine. Permissions for all nine objects are included in the standard StoreConnect permission sets.

Object Purpose
Promotion2__c Core promotion record
Condition__c Conditions that must be met for a promotion to apply
Reward__c Reward definition: discount, free product, or free shipping
Cart_Promotion2__c Links an applied promotion to a cart
Promotion2_Condition__c Junction between a promotion and its conditions
Promotion2_Product_Scope__c Scopes a promotion to specific products
Promotion2_Usage__c Tracks how many times a promotion has been used
Reward_Usage__c Tracks reward usage per order
Order_Item_Reward__c Links a reward to a specific order item

The existing promotions engine keeps working; the two run side by side and no migration is needed. Exclude_From_Price_Reductions__c on Product and Price Book Entry keeps a product out of promotions, discounts, or manual price reductions.

  1. If you use only the standard StoreConnect permission sets, no action is needed.
  2. If you have custom permission sets, navigate to Setup > Permission Sets, open each custom set, and assess whether access to the new promotion objects is appropriate for that set’s audience.

See Advanced promotions and Exclude products from price reductions.

Review: StoreConnect Bundles objects

Three new Salesforce objects support StoreConnect Bundles. Permissions are included in the standard Administrator, Sync, and Order Manager permission sets.

Object Purpose
Product_Component__c Defines a product as a component within a bundle, including quantity constraints and pricing
Component_Group__c Groups components together so customers can choose between options within a bundle
Component_Pricing__c Overrides component pricing per price book or per anchor product and price book combination

Price Book Entry gains Bundle_Only__c, which keeps a product out of the catalog except as a bundle component, and Bundle_Price_Strategy__c, which sets how a bundle is priced when the entry’s product is the anchor.

  1. If you use only the standard StoreConnect permission sets, no action is needed.
  2. If you have custom permission sets, navigate to Setup > Permission Sets, open each custom set, and assess whether access to Product_Component__c, Component_Group__c, and Component_Pricing__c is appropriate for that set’s audience.

See Product bundles.

Review: Payment Method and Payment Installment objects

Payment_Method__c stores a saved card for a contact: the gateway token, brand, last four digits, expiry, and lookups to the contact and provider. It is created at checkout when a customer saves a card or a subscription is created, and Payment__c.Payment_Method_Id__c and Subscription__c.Payment_Method_Id__c link to it. Payment_Installment__c records each partial capture of a pre-authorized payment. Both objects are included in the Administrator, Order Manager, and Sync permission sets.

Review whether either object should appear as a related list on your Contact or Payment page layouts. See Payment Method Object Reference and Payment Installment Object Reference.

Review: New fields on Payment

New field Purpose
Linked_Payment_Id__c Links a refund payment to its original payment
Reason__c The reason for the payment action, such as a refund reason
Origin__c How the payment was created, such as web checkout or the payment link
Payment_Method_Id__c The saved payment method used
Preauth_Amount_To_Capture__c The amount to capture from a pre-authorized payment
Salesforce_User_Id__c The Salesforce user who initiated a payment action from Salesforce

These fields are populated by StoreConnect. Review whether any should be added to your Payment page layouts.

Review: Cart Fulfillment objects

Two new Salesforce objects represent the fulfillment state of a cart. Permissions for both objects are included in the Administrator, Order Manager, and Sync permission sets.

Object Purpose
Cart_Fulfillment__c The fulfillment plan for a cart, including shipping address, provider, rate, and status
Cart_Fulfillment_Item__c An individual item within a cart fulfillment

Order_Items_Taxes__c gains Fulfillment_Item_Id__c, which ties a tax row to one fulfillment item when an order line ships to more than one tax zone.

Review whether these objects should be added to your page layouts or included in custom permission sets. If you have Flows or automation that work with cart data, assess whether cart fulfillment records should be incorporated.

Review: Discount fields on Cart, Cart Item, and Discount

Cart__c and Cart_Item__c gain Discount_Mode__c, Discount_Amount__c, and Discount_Percentage__c, which record how a cart-wide or line discount was applied. Discount__c gains Outlet_Scope__c, which limits a discount to specific outlets, stores, or store groups; blank means all. These are populated by StoreConnect, or set on the Discount record page for outlet scoping.

Review: New fields on Cart Item

New field Purpose
Promotion2_Id__c Links a cart item to the Advanced promotion applied to it
Transaction_Discount__c The share of an order-level discount applied to the item
Product_Component_Id__c Links a cart item to its product component when part of a StoreConnect Bundle
Deposit_Payment_Mode__c, Deposit_Percentage__c How a deposit is taken for the line, and the percentage
Pending_Status__c The status of a background process on the item

Review whether any of these fields should be added to your Cart Item page layouts.

Review: New fields on Order Product

New field Purpose
Product_Component_Id__c Links an order item to its product component when part of a StoreConnect Bundle
Deposit_Payment_Mode__c, Deposit_Percentage__c How a deposit was taken for the line, and the percentage

Review whether any of these fields should be added to your Order Product page layouts.

Review: Ship-to fields on Shipment

Shipment__c gains a ship-to address of its own: Shipping_Street__c, Shipping_City__c, Shipping_State__c, Shipping_State_Code__c, Shipping_Postal_Code__c, Shipping_Country__c, Shipping_Country_Code__c, Shipping_Recipient_Name__c, Ship_To_Contact_Id__c, and Ship_To_Account_Id__c. Review whether your Shipment page layouts and warehouse reports should use them instead of the order’s address.

Review: Customer Notes field on Cart

Customer_Notes_Long__c (label: Customer Notes) on Cart__c stores notes provided by the customer during checkout, up to 10,000 characters. Review whether this field should be added to your Cart page layouts.

Review: Channels on shipping rates, tax providers, and other records

Channels__c is a new multi-select picklist with the values web and pos on six objects. On Shipping_Rate__c and Tax_Provider__c the package upgrade backfills every existing record with web;pos, so existing rates and providers keep applying to both channels, and a validation rule requires the field on every new record. On Payment_Provider__c, Shipping_Provider__c, Script_Block__c, and Style_Block__c a blank value means every channel, so existing records are unchanged.

  1. After upgrading, confirm that your shipping rate and tax provider records have Channels__c set to web;pos.
  2. Review whether any rate, provider, script, or style should be limited to one channel. For example, a chat widget or web-only tracking pixel should be web.
  3. When creating new shipping rates or tax providers, set Channels__c before saving.

See Shipping Rate Object Reference and Tax Provider Object Reference.

Review: New fields on Product

New field Purpose
Payment_Capture_Type__c How payment is captured at checkout for this product: Charge Immediately (default), Preauthorize Only, or Save Payment Method Only
Exclude_From_Price_Reductions__c Keeps the product out of the selected reduction types: discounts, promotions, and manual
Subscription_Plan_Change_Mode__c How proration is handled when a customer changes subscription plan. See the Subscriptions section
Voucher_Requires__c, Voucher_Uses_Assets__c What a voucher product requires at activation, and whether its vouchers are backed by asset records. See the Subscriptions and vouchers section

Review whether any products should use a non-default payment capture type or should be excluded from price reductions.

Review: New fields on Price Book Entry

New field Purpose
Exclude_From_Price_Reductions__c Per-entry override for price reduction exclusions. When blank, inherits the value from the product
Variable_Pricing_Min_Amount__c, Variable_Pricing_Max_Amount__c The range a customer can enter when variable pricing is enabled on this entry
Bundle_Only__c, Bundle_Price_Strategy__c See the StoreConnect Bundles item above

The tax_method picklist on Price Book Entry gains an Inherit value, which falls back to the store’s tax method. Review whether any of these fields should be added to your Price Book Entry page layouts.

Review: Media Manager objects

Console_Folder__c and Console_Favorite__c support the new Media Manager in the Salesforce console: folders, including nested folders, and per-user favorites. Media__c gains Console_Folder_Id__c, Width__c, and Height__c. Permissions are included in the Administrator, Content Manager, Order Manager, and Sync permission sets. No action is needed. See About the media manager.

Review: Custom object sync with Flows and automatic route mappings

A new invocable action, StoreConnect: Sync Record Changes, lets a record-triggered Flow sync any custom object to the store, and Custom_Data_Mapping__c gains an Indexed__c checkbox for fields that should be indexed. Route mappings are now created automatically whenever the path or slug of a product, page, article, article category, or product category changes in Salesforce. If you maintained redirects by hand after a slug change, that process can be retired. See Sync custom objects using Flows.

Review: Per-record sync opt-in

If you have large volumes of records in your system, you can now select which records get included in the StoreConnect sync process for any standard object. This is designed for organizations with large volumes of records, such as millions of accounts, where only a subset of records are relevant to StoreConnect and need to sync.

Once you opt in and enable this feature, only records you explicitly select for sync will sync; all others are ignored. See Enable record sync.

If you do enable it, note the following:

  • When StoreConnect creates a record from the store, it bypasses opt-in filtering for that initial creation. Subsequent updates or deletes on that record from Salesforce are subject to opt-in filtering, so set StoreConnect_Sync__c to enable_sync automatically on store-created records using a default field value, Flow, or trigger. Otherwise those records may stop syncing after creation.
  • Opt-in filtering applies across all sync paths: trigger-based sync, batch jobs, poll processing, and manual invocable sync actions.
  • Custom objects are not affected by this mechanism.

Review: Redesigned Salesforce console

The StoreConnect console is redesigned around a setup wizard, and gains a Schema Explorer, a Manage picklist values tool, and an Open in Website Builder button on Content Change records. No action is needed beyond the picklist step above.

Liquid template changes

Action required: Changed base-theme templates

This applies only if your theme overrides any of the templates below. The base theme changed in these places. An override is a complete copy, so it does not pick up the new behavior and in some cases blocks a feature. Compare each override you have against the new base version and merge the change.

The biggest structural change is that the mini-cart, the cart page, the checkout payment step, the checkout vouchers section, and the order summary are now components that reload on their own: snippets/header/dropdown/cart became components/cart-menu, snippets/cart/cart became components/cart, snippets/checkout/vouchers became components/checkout/vouchers, and pages/cart.js was removed.

Base template What changed If you do not merge
layouts/theme Renders the new snippets/content_security_policy_header snippet No Content Security Policy header, so the CSP store variables have no effect
snippets/header Renders components/cart-menu instead of the removed snippets/header/dropdown/cart The mini-cart does not refresh after an add to cart or a voucher change
pages/cart Renders components/cart instead of the removed snippets/cart/cart, and pages/cart.js is gone The cart page does not refresh without a full reload
pages/checkout Renders components/checkout/payment_information/page and components/checkout/vouchers instead of the removed vouchers snippet Vouchers and the payment step do not refresh when a voucher is applied
snippets/checkout/payment_information/select_and_payment, show_wallets_only, additional_info, page, new submit_button and payment_error, and every payment_providers/*_form The shared submit button, error display, and element ids are extracted into snippets the provider forms now share An overridden provider form keeps working with its old markup but misses the shared error handling. Test each gateway you use
snippets/checkout/promo_code Applies and shows Advanced promotion codes beside the existing promotion code Advanced promotion codes cannot be entered
snippets/shared/cart_items/item, shared/cart_items/pricing, shared/order_total, orders/order_summary Advanced promotion discounts, cart and line discounts, and deposits in the totals Promotion and deposit lines are missing from carts and summaries
snippets/account/credentials, snippets/account/profile The current-password field, and a list of the customer’s saved carts See the Action required items above. Customers cannot switch between saved carts
snippets/account/register/form Field markup and placeholders Minor display differences
pages/account, snippets/account/subscriptions/index, new account/subscriptions/subscriptions, orders/subscriptions, account/carts, account/profile/carts Subscriptions list rendering, the Pay Owing flow, and saved carts Customers cannot pay an owing renewal or choose a saved cart
snippets/orders/order Shows an order’s subscriptions, the wallet type on a payment, and the capture history of a pre-authorized payment Those details are missing from order pages
pages/product, snippets/products/card, products/card/buttons, products/product/add_to_cart, new products/product/bundle/* and bundles/nested_configurator StoreConnect Bundles: the configurator, component groups, pricing, and the add-to-cart flow Bundles cannot be configured or added to the cart
snippets/shared/variable_pricing_picker Enforces the minimum and maximum variable price from the price book entry The limits are not enforced in the browser
snippets/products/product/images Renders product videos in an iframe Videos do not play
snippets/products/product/booking, new booking_detail The booking selector is rebuilt Bookings cannot be made from an overridden product page
pages/voucher The voucher page is rebuilt around voucher status and PIN Voucher balance and status do not show correctly
snippets/flash The notice container is always rendered so scripts can show notices Notices raised by scripts, such as a voucher result, do not appear
blocks/slideshow The slider class is renamed from Slider to SC-Slider Custom CSS targeting .Slider stops applying
snippets/custom_forms/questions/boolean Shows validation errors on checkbox questions A required checkbox fails without a visible error
snippets/menu/menu_item, menu/child_item Menu item markup Minor display differences
pages/additional_payment Deposit and custom amount entry on the payment link page Customers cannot pay a custom amount or deposit on the payment link
pages/product_category Blank checks on introduction and information content Minor display differences

New templates you may want to copy into your theme if you customize these areas: pages/page.json, page.xml, page.csv, page.md, page.text and the matching pages/article.* templates for alternative formats, and layouts/theme.xml for XML responses.

  1. In Site Builder, list the templates your theme overrides and compare the list with the table above.
  2. For each match, open the base version of the template, copy the changed section into your override, and keep your own customizations.
  3. After the upgrade, place a test order through checkout with each of your payment providers, apply a promotion, and open the account area as a signed-in customer.

Review: Removed translation keys

This applies only if your theme or translations reference one of these keys. The keys were removed from the default translations and now render as a missing translation.

Removed key Replacement
checkout.gateways.form.notices.processing None. The processing notice is rendered by the shared submit button
checkout.gateways.pay_with_zip None. ZippayAu renders its own button
checkout.payment.provider_misconfigured None
checkout.vouchers.remove None. The vouchers component has its own translations
salesforce_payments.errors.fix_data_in_sf None
sc.auth.passwords.invalid_token None. Expired reset links redirect to the password reset form with their own message
sc.checkout.accounts.create.notices.you_can_now_sign_in None. New accounts are asked to confirm their email instead
sc.checkout.payment.finalize_order.notices.order_processing_text None
shipments.errors.provider_not_enabled, shipments.errors.not_ready_to_ship, shipments.errors.provider_shipment_id_is_shipping_rate, shipments.errors.invalid_shipment None. Shipment errors are reported through the shipping provider logs

Review: Components

Components are a new type of theme template that can load or refresh a section of a page independently, without a full page reload. The base theme uses them for the cart, the mini-cart, the checkout payment step, vouchers, and the order summary, and you can use them in your own templates to defer a slow section or refresh one part of a page.

No changes to existing templates are required beyond the table above. See Liquid theme components.

Review: New Liquid capabilities

No changes to existing templates are required. Review these if you maintain custom templates:

  • A cart.clone controller action, and cart.select accepts an sc_id as well as an sfid.
  • cart.custom_data and cart_item.custom_data, and order_item.unit_price, order_item.price_excl_tax, and order.sub_total_excl_tax.
  • {% liquid_query %} can query custom objects, order results, and use pattern-matching and comparison operators.
  • Pages and articles can be served in alternative formats, such as /articles/feed.xml or /pages/data.json, from pages/page.* and pages/article.* templates.
  • Theme files larger than 131,072 characters are stored as sequential chunks, and the controllers/ directory is included when a theme is imported or exported.

Behavior changes

Review: Optional features controlled by store variables

These are off until you set the variable. No action is needed to keep current behavior.

Store variable What it enables
stealth_mode Hides the store from search engines and external services: crawlers are blocked, the sitemap is disabled, and the Google Merchant feed is suppressed, while customers can still shop. See Stealth mode
content_security_policy_type, content_security_policy Switches the Content Security Policy header from report-only to enforce, and replaces the default policy
The Google Tag Manager gateway variables Route Google Tag Manager scripts and measurement hits through the store’s own domain. See Google Tag Manager

See Store variables for the full list.

Review: Storefront behavior changes

  • Saved carts. A signed-in customer’s cart is restored when they sign back in after a session expires, and a customer with several saved carts chooses which one to resume from a list in the account area.
  • Deposits at web checkout. Checkout respects the deposit mode on cart items and shows a deposit and total-due breakdown; the balance is collected through the payment link.
  • Reorder copies custom form answers. Reorder Now carries custom product form answers from the original order into the new cart.
  • Tax-exempt accounts. An account marked tax exempt, and a guest using an email tied to one, is not charged tax at checkout. See Configure tax exempt customers.
  • Featured products on category pages, multiple active delivery windows, and a Contact created automatically on first SAML sign-in are available without configuration.
  • Shipping providers. Shippit and a custom HTTP shipping provider are new provider types, and Easyship is a new tracking provider. See Shippit shipping provider and Custom shipping provider.

Was this article helpful?

Was this article helpful?