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
| Setting | Type | Default | Description |
|---|---|---|---|
showInOffcanvas — Show in the off-canvas cart | bool | true | The cart that slides in after adding a product. Off only hides the bar; rewards still apply. |
showOnCartPage — Show on the cart page | bool | true | Off only hides the bar; rewards still apply. |
showOnConfirmPage — Show on the checkout confirm page | bool | true | The last step before ordering. Off only hides the bar; rewards still apply. |
showAllUnlockedMessage — Show the "everything unlocked" message | bool | true | Confirms in words what was unlocked once no goal is left. Off shows the bar alone. |
thresholdRounding — Round converted thresholds up to | single-select | 1 | For 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
| Setting | Type | Default | Description |
|---|---|---|---|
preset — Preset | single-select | native | Minimal, 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 colour | colorpicker | — | Empty = theme primary colour. |
trackColor — Track colour | colorpicker | — | Empty = theme border colour. |
Look: fine controls (Pro)
| Setting | Type | Default | Description |
|---|---|---|---|
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 style | single-select | auto | What 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 colour | colorpicker | — | Empty = theme text colour. |
unlockedColor — "Unlocked" colour | colorpicker | — | Empty = theme success colour. |
celebration — Unlock celebration | single-select | off | Plays 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.
| Field | Applies to | Notes |
|---|---|---|
| Active | all | Inactive milestones are kept but not shown and grant nothing. |
| Reward | all | Free shipping or Gift. |
| Threshold | all | Greater than 0. Global ladder: default currency. Sales-channel ladder: the channel's currency. |
| Title | all | Translatable. 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. |
| Description | all | Translatable. Shown in the gift's popover. |
| Gift options | gift | Products or variants, not parent products. The first is the default. More than one needs Pro. |
| Show only to (Rule Builder) | all | Pro. Empty means everyone. One free-shipping milestone per rule. |
| Icon | all | Replaces the marker image (truck icon or gift photo). Uploads go to the "Unlock Bar Media" folder. |
Plans
| Capability | Free | Pro |
|---|---|---|
| Free-shipping milestones | one per "Show only to" rule | one per "Show only to" rule |
| Gift milestones | 1 (the lowest threshold that applies) | unlimited |
| Gift options per milestone | the default option | unlimited |
| Show only to (Rule Builder) | rules already set are kept | ✓ |
| Presets, fine controls, unlock celebration | saved, not applied | ✓ |
Details: Get Unlock Bar Pro.
Permissions
In Settings → Users & permissions, Unlock Bar adds the role Unlock Bar under Marketing:
| Role | Allows |
|---|---|
| Viewer | open the Unlock Bar page and read the ladder, including the products, rules, promotions and shipping methods it shows |
| Editor | create, 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
| Interface | Name |
|---|---|
| Store API cart extension | unlockBarProgress |
| Store API routes | POST /store-api/ssd-unlock-bar/gift/{milestoneId}/choose, POST /store-api/ssd-unlock-bar/gift/{milestoneId}/add-back |
| JavaScript event | UnlockBar/milestoneUnlocked on document.$emitter |
| Rule Builder condition | ssdCpbMilestoneUnlocked |
| Entities | ssd_cpb_milestone, ssd_cpb_gift_option |
