Skip to content

Configuration reference ​

The plugin configuration is under Extensions → My extensions → Unlock Bar → Configure. Every setting can be set for all sales channels or for one. The tables below are generated from the plugin's config.xml; the descriptions are the help texts shown next to each field. How to use them: Change where the bar shows and how it looks.

The configuration page also shows three parts that are not settings: a header card with the plan in effect and a link to the ladder, a live preview in the Look card, and, without Pro, a lock row with a Get Pro button.

Display ​

SettingTypeDefaultDescription
showInOffcanvas — Show in the off-canvas cartbooltrueThe cart that slides in after adding a product. Off only hides the bar; rewards still apply.
showOnCartPage — Show on the cart pagebooltrueOff only hides the bar; rewards still apply.
showOnConfirmPage — Show on the checkout confirm pagebooltrueThe last step before ordering. Off only hides the bar; rewards still apply.
showAllUnlockedMessage — Show the "everything unlocked" messagebooltrueConfirms in words what was unlocked once no goal is left. Off shows the bar alone.
thresholdRounding — Round converted thresholds up tosingle-select1For sales channels in another currency. The rounded value is the real threshold. Options: 0 (No rounding), 1 (Whole currency unit (63.84 → 64)), 5 (5 currency units (63.84 → 65)), 10 (10 currency units (63.84 → 70)).

Look ​

SettingTypeDefaultDescription
preset — Presetsingle-selectnativeMinimal, Bold and Steps require Unlock Bar Pro; without Pro the bar uses Native. Options: native (Native (follows the theme)), minimal (Minimal: thin line, dot markers (Pro)), bold (Bold: thick pill, large photos (Pro)), steps (Steps: numbered stepper (Pro)).
fillColor — Fill colourcolorpicker—Empty = theme primary colour.
trackColor — Track colourcolorpicker—Empty = theme border colour.

Look: fine controls (Pro) ​

SettingTypeDefaultDescription
cornerRadius — Corner radius (px)int—Bar, fill and markers. 0 to 999 px; 999 = fully round. Empty = the preset's.
barHeight — Bar height (px)int—2 to 24 px. Empty = the preset's.
markerStyle — Marker stylesingle-selectautoWhat each milestone marker on the bar shows. Preset default: Native and Bold show the gift photo, Minimal a dot, Steps a number. Options: auto (Preset default), photo (Gift photo), icon (Icon), dot (Dot), number (Number).
textColor — Text colourcolorpicker—Empty = theme text colour.
unlockedColor — "Unlocked" colourcolorpicker—Empty = theme success colour.
celebration — Unlock celebrationsingle-selectoffPlays once when a milestone unlocks while the shopper watches. Left out for shoppers who reduce motion. Options: off (Off), pulse (Pulse), confetti (Confetti).

Milestone fields ​

Milestones are edited under Marketing → Unlock Bar, not in the plugin configuration.

FieldApplies toNotes
ActiveallInactive milestones are kept but not shown and grant nothing.
RewardallFree shipping or Gift.
ThresholdallGreater than 0. Global ladder: default currency. Sales-channel ladder: the channel's currency.
TitleallTranslatable. Empty shows "Free shipping" or the gift's product name. A free-shipping title is also the promotion's name in the cart and order.
DescriptionallTranslatable. Shown in the gift's popover.
Gift optionsgiftProducts or variants, not parent products. The first is the default. More than one needs Pro.
Show only to (Rule Builder)allPro. Empty means everyone. One free-shipping milestone per rule.
IconallReplaces the marker image (truck icon or gift photo). Uploads go to the "Unlock Bar Media" folder.

Plans ​

CapabilityFreePro
Free-shipping milestonesone per "Show only to" ruleone per "Show only to" rule
Gift milestones1 (the lowest threshold that applies)unlimited
Gift options per milestonethe default optionunlimited
Show only to (Rule Builder)rules already set are kept✓
Presets, fine controls, unlock celebrationsaved, not applied✓

Details: Get Unlock Bar Pro.

Permissions ​

In Settings → Users & permissions, Unlock Bar adds the role Unlock Bar under Marketing:

RoleAllows
Vieweropen the Unlock Bar page and read the ladder, including the products, rules, promotions and shipping methods it shows
Editorcreate, change and delete milestones and gift options, upload icons and create rules inline (includes Viewer)

The plugin configuration itself is governed by Shopware's own permission for plugin settings.

Storefront snippets ​

The bar's texts are storefront snippets under the key ssdUnlockBar (English and German included). Edit them under Settings → Snippets.

Developer interfaces ​

InterfaceName
Store API cart extensionunlockBarProgress
Store API routesPOST /store-api/ssd-unlock-bar/gift/{milestoneId}/choose, POST /store-api/ssd-unlock-bar/gift/{milestoneId}/add-back
JavaScript eventUnlockBar/milestoneUnlocked on document.$emitter
Rule Builder conditionssdCpbMilestoneUnlocked
Entitiesssd_cpb_milestone, ssd_cpb_gift_option

Details: Adapt the bar in a theme or a headless storefront.

Your Vision. Signed, Sealed, Delivered.