Upgrade guide — v20 to v21 — E-commerce

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

Salesforce package changes

Action required: Removed deprecated fields

The following fields were deprecated in earlier releases and have been removed from the StoreConnect package in v20/21. 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

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.

Review: Cart Fulfillment objects

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

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

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: Customer Notes field on Cart__c

Customer_Notes_Long__c (label: Customer Notes) on Cart__c stores notes provided by the customer during checkout and supports up to 10,000 characters.

Review whether this field should be added to your Cart__c page layouts.

Review: Assess record volumes and enable selecti for standard object records

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. Enable record sync.

If you do enable it, note the following:

• When StoreConnect creates a record from the store (a “fromStore” insert), it bypasses opt-in filtering for that initial creation. However, subsequent updates or deletes on that record from Salesforce are subject to opt-in filtering. 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: Advanced promotions objects

Version 21 introduces nine new Salesforce objects to support the Advanced promotions engine. Permissions for all nine objects are already included in the standard StoreConnect permission sets. No manual assignment is needed for the out-of-the-box 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

If you have custom permission sets in your org, review whether those sets should include access to the new objects. See Advanced Promotions for full feature documentation.

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.

Review: New fields on Cart_Item__c

New field	Purpose
Promotion2_Id__c	Links a cart item to the Advanced promotion applied to it
Transaction_Discount__c	Records the discount amount applied to the item via a promotion
Product_Component_Id__c	Links a cart item to its product component record when part of a StoreConnect Bundle

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

Review: New fields on OrderItem

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	Records the payment mode used for a deposit on this line item
Deposit_Percentage__c	Records the deposit percentage applied to this line item

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

Review: Channels field on Shipping_Rate__c

v21 adds a Channels__c multi-select picklist field to Shipping_Rate__c. This field specifies whether a shipping rate applies to the web store, the POS, or both. Available values are web and pos.

The package upgrade automatically backfills all existing Shipping_Rate__c records with web;pos, so existing rates continue to apply to both channels after upgrade. A new validation rule requires Channels__c to be set when creating or updating any Shipping_Rate__c record going forward.

1. After upgrading, confirm that your existing shipping rate records have Channels__c set to web;pos.
2. Review each shipping rate and determine whether it should be restricted to a specific channel. For example, in-store pickup rates may be appropriate for POS only. Web-only promotional rates should exclude POS.
3. When creating new shipping rates, set Channels__c before saving.

See Shipping Rate Object Reference for full field documentation.

Review: Channels field on Tax_Provider__c

v21 adds the same Channels__c field to Tax_Provider__c. The field and validation rule behave identically to the one on Shipping_Rate__c.

The package upgrade automatically backfills all existing tax provider records with web;pos.

1. After upgrading, confirm that your existing tax provider records have Channels__c set.
2. Review whether any tax providers should be scoped to a single channel.
3. When creating new tax providers, set Channels__c before saving.

See Tax Provider Object Reference for full field documentation.

Review: StoreConnect Bundles objects

v21 introduces three new Salesforce objects to support StoreConnect Bundles. Permissions are already 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 pricebook or per anchor product and pricebook combination

If you have custom permission sets, review whether those sets should include access to the new objects.

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 for full setup documentation.

Review: Channels field on Script_Block__c and Style_Block__c

v21 adds a Channels__c multi-select picklist field to Script_Block__c and Style_Block__c. This field scopes a script or style block to specific channels. Available values are web and pos.

When Channels__c is empty, the block loads on all channels. Existing script and style blocks are unaffected after upgrading.

If you have scripts or styles that should not load on the POS, such as third-party chat widgets, analytics tags, or web-only tracking pixels, you can now set Channels__c to web to prevent them from loading in POS sessions.

Review: Voucher activation deadline field

A new Activate_Before_Datetime__c date-time field on Voucher__c allows you to set a deadline by which a voucher must be activated. Vouchers not activated before this date and time cannot be redeemed.

Review whether Activate_Before_Datetime__c should be added to your Voucher__c page layouts and whether any existing vouchers should have an activation deadline set.

Review: New fields on Product2

New field	Purpose
Payment_Capture_Type__c	Controls how payment is captured at checkout for this product. Options are Charge Immediately (default), Preauthorize Only, or Save Payment Method Only
Exclude_From_Price_Reductions__c	Multi-select picklist that prevents specific reduction types from applying to this product. Available values are discounts, promotions, and manual

Review whether any products should use a non-default payment capture type or should be excluded from price reductions. If you are using Advanced Promotions, use Exclude_From_Price_Reductions__c to prevent promotions from applying to specific products.

Review: New fields on PricebookEntry

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	The minimum amount a customer can pay when variable pricing is enabled on this entry
Variable_Pricing_Max_Amount__c	The maximum amount a customer can pay when variable pricing is enabled on this entry
Minimum_Deposit_Amount__c	The minimum deposit amount required when purchasing this entry via the POS
Minimum_Deposit_Percent__c	The minimum deposit percentage required when purchasing this entry via the POS
Minimum_Deposit_Points__c	The minimum deposit points required when purchasing this entry via the POS

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

Liquid template changes

Review: cart.create Liquid action

v21 adds a cart.create Liquid action, which allows templates to programmatically create a cart and associate it with an sc_id. This is useful for custom flows where a cart needs to be created before checkout is initiated.

No changes to existing templates are required. Review this if you maintain custom Liquid templates that manage cart creation.

Review: Custom objects in Liquid

Salesforce custom objects can now be synced to the web store and queried in Liquid templates. This enables data from any synced custom object to be surfaced on store pages without requiring a standard StoreConnect object.

See Custom Objects for documentation on setting up and querying custom objects in Liquid.

Action required: Product JSON-LD template renamed

The product structured data snippet has been renamed from snippets/products/product/json-ld.liquid to snippets/products/product/rich_data_json.liquid. For now, the old filename still works — StoreConnect automatically forwards requests for the old file to the new one behind the scenes. But this forwarding is temporary, so custom themes referencing the old filename should be updated before the next theme deployment.

1. In Site Builder, search your theme files for json-ld.liquid. If found, update the reference to rich_data_json.liquid.
2. If you have not customized this template, no action is needed — StoreConnect manages the structured data output automatically.
3. Update the reference before your next theme deployment to avoid breakage when the forwarding is removed.

See Product rich data snippet for the updated template reference.

Review: Liquid request headers

Liquid templates can now access HTTP request headers. This enables template logic based on headers such as user agent, referrer, or custom headers passed by integrations.

No changes to existing templates are required unless you want to use this capability.