Upgrade guide — v20 to v21 — E-commerce

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

Salesforce package changes

Review: Advanced promotions objects

v21 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 — for example, 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.

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.

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.

Behavior changes

Review: StoreConnect Bundles

v21 introduces StoreConnect Bundles, a native bundle solution for stores that do not use or need Salesforce CPQ. If you are not adopting this feature, no action is needed.

When configuring bundles, the Bundle Only and Bundle Price Strategy fields on a product’s Pricebook Entry control standalone sales eligibility and pricing behaviour. Products with Bundle Only enabled cannot be added to a cart directly — they can only be included as components within a bundle. In the POS, bundle-only products are visible in search and product grids but are blocked from being added to a cart. Bundle configuration is not available at the POS in this release.

See Product Bundles for full setup documentation.

Review: Express checkout for logged-in customers

Logged-in customers can now complete checkout using an express flow that pre-fills their saved address and payment details. This capability is available for CyberSource at launch.

Review whether your store’s checkout templates or custom flows need to be updated to account for this new path.