Documentation

Everything you need to go live with Verve

Verve is a complete storefront marketing platform — build cart drawers, promo popups, product-page upsells and targeted campaigns from one place. Here is how it fits together, and how to get live in three steps.

What is Verve?Verve is a complete storefront marketing platform — not just a cart app. Build cart drawers, promo popups, product page upsells, collection banners, and targeted campaigns, all from one place.
Architecture: Templates > Zones > Components
Template (e.g. "Summer Sale")
├── Zone: Cart Drawer (overlay)
│   ├── Header
│   ├── Announcements
│   ├── Items
│   ├── Rewards Bar
│   ├── Upsell Slider
│   ├── Totals
│   └── Checkout Buttons
├── Zone: Promo Popup (overlay)
│   └── Custom Content
└── Zone: Add-to-Cart Bar (on-page)
    └── Add to Cart
Quick-StartRecommended
1Open the Zone Gallery from the sidebar.
2Pick a preset (e.g. Cart Drawer, Exit Intent, Announcement Bar).
3Customize the components and publish.
What are Templates?Top-level containers that group zones. Each template can be enabled/disabled independently, has its own scheduling, and provides isolated settings.
When to Use TemplatesCampaigns — Time-limited promotions (Black Friday, Summer Sale).
Grouping Zones — Organize related zones together.
Isolated Settings — Keep separate design/translation configs per template.
ManagementScheduling — Start/end dates with timezone support.
Import/Export — Share template configs between stores.
Duplicate — Clone an existing template.
Reset — Restore to default state.
Multi-Market: 4-Level Fallback
LevelCountryLocalePriority1SpecificSpecificHighest2SpecificInitialHigh3InitialSpecificMedium4InitialInitialLowest (default)
What are Zones?Rendering areas that control where and how content appears on your storefront. Each zone is placed on the page using a mounting method and contains one or more components.
Zone Types
On Page
Renders inline in the page flow. Injected into existing page structure via CSS selector or HTML placeholder.
Overlay
Renders above the page as drawer, modal, slidedown, or slideup. Opened via triggers (icon click, exit intent, scroll, etc.).
3 Mounting MethodsTheme Editor — Drag & drop the Verve app block in the Shopify Theme Editor.
HTML Placeholder — Add <div id="v1-zone-ID"></div> anywhere in your theme.
CSS Selector — Target any existing element (e.g. .product-form) to inject the zone.
4 Placement Modes
ModeDescriptionVisualizationappendInside target, at end[target [...zone]]prependInside target, at start[target [zone...]]beforeBefore target element[zone] [target]afterAfter target element[target] [zone]
Page FiltersAll pages — Zone shows everywhere.
URL pattern — Glob matching (e.g. /collections/*).
Specific pages — Exact URL list.
5 Overlay Styles
StyleDescriptiondrawerSlides in from the rightdrawer-leftSlides in from the leftmodalCentered popup with backdropslidedownDrops down from the topslideupSlides up from the bottom
Overlay Settings
minWidth — Minimum overlay widthmaxWidth — Maximum overlay widthzIndex — Stack orderoverlayColor — Backdrop color/opacitycloseOnOverlay — Close on backdrop clickcloseOnEsc — Close on Escape key
Column Layouts (1–4)
1 Column:  |  Full Width  |
2 Columns: | Left | Right |
3 Columns: | A | B | C |
4 Columns: | A | B | C | D |
Each column can hold its own set of components. Column widths are configurable.
Shadow DOM vs Light DOMShadow DOM (default) — Isolates zone styles from the theme. Prevents style conflicts in both directions.
Light DOM — Zone renders directly in the page. Theme styles apply. Required for custom code that needs page-level access.
Zone-Level Custom CodeCSS — Custom styles scoped to the zone.
JavaScript — Custom scripts running in zone context.
HTML Before — Raw HTML injected before zone content.
HTML After — Raw HTML injected after zone content.
Container DesignPadding, Background, Border, and Shadow — configurable per zone to match your theme.
What are Zone Items?Each zone can hold multiple items. Use multiple items for carousel/marquee display or multivariate testing. Each item has its own components, schedule, and container design.
3 Multi-Item Display Modes
ModeDescriptionstackedAll items visible at once, stacked verticallycarouselOne item at a time, navigable with arrows/dotsmarqueeContinuous horizontal scroll animation
Navigation OptionsDots, Arrows, Autoplay, and Pause on Hover — all configurable per zone when using carousel or marquee mode.
Per-Item SettingsSchedule — Show/hide items by date range.
Container Design — Independent padding, background, border, shadow.
Column Layout — Each item can have a different column count.
Empty State — Behavior when all components in an item are hidden.
Cart Icon ClickOpens on cart icon click. Auto-detects common cart icons or targets a custom CSS selector.
Auto-Open on Add to CartOpens automatically when a product is added to cart. Intercepts form submissions and fetch requests.
Exit IntentDetects when the cursor moves toward the browser close button. Configurable sensitivity and delay. Fires once per session by default.
Scroll TriggerOpens when the user scrolls past a percentage threshold (e.g. 50%) or a pixel offset.
Timing TriggerOpens after a configurable delay (e.g. 5 seconds after page load).
Custom TriggerOpens via JavaScript API: window.__v1CartSuite.open(zoneId). Full programmatic control.
Sticky Cart IconFloating cart icon fixed to the viewport corner. Shows item count badge. Configurable position, size, and colors.
Cart BubbleAnimated bubble notification that appears after add-to-cart. Shows product thumbnail and quick actions.
What are Components?Components are the building blocks inside zones. Each component has its own schema with design, settings, and translation fields. Add components from the Component Gallery, then configure per instance.
Cart Essentials
Header & Close ButtonCart title with item count. Customizable text,styling,and close button. Shows "Your Cart (3)" with optional close icon.
ItemsLine items with product image,title,variant info,quantity selector. Supports variant switching,subscription plan changes,inventory display,and item removal.
TotalsPrice summary with subtotal,discounts,taxes,shipping estimate,and total. Multiple display modes and compare-at prices available.
Checkout ButtonsPrimary checkout and secondary continue shopping button. Supports dynamic checkout buttons (Shop Pay,Apple Pay,etc.) and terms acceptance.
Empty CartMessage and optional content when cart is empty. Can show recommended products or continue shopping link.
Promotions
RewardsProgress bar for free shipping,percentage discounts,or free gifts. Multiple thresholds with different reward types. Celebration animations when reached.
Discount FieldInput field for discount/promo codes. Shows success/error status and removal of applied codes.
AnnouncementsPromotional banners and messages with types (success,warning,info,critical). Scheduling,links,and countdown timers available. Multiple rotating announcements.
Trust & Info
BenefitsTrust badges and USPs (free shipping,secure checkout,money-back guarantee). Various icon styles and configurable items. Stack,inline,or slider layout.
Payment IconsAccepted payment method icons (Visa,Mastercard,PayPal,Klarna,etc.). Auto-detection from shop or manual selection.
Legal CheckboxTerms,privacy,and return links. Checkbox acceptance for checkout available. Configurable link texts.
Delivery TimeEstimated delivery time with countdown. Supports cut-off times and weekday exclusions (weekends). Dynamic calculation.
Upselling
Upsell & Product SliderProduct recommendations carousel or grid with 4 source modes:manual selection,automatic recommendations (AI-similar or complementary),manual + automatic combined,or automatic with manual fallback. Quick-add to cart.
Single ProductHorizontal single-product showcase with large image and variant dropdown.
Product CarouselMulti-product carousel with styled cards and outside arrows.
Compact Card CarouselHorizontal compact cards for cart drawers with icon button.
Gift WrapGift wrapping option with optional message field. Adds gift wrap product to cart with configurable price.
Shipping ProtectionShipping insurance option. Integration with protection providers or custom pricing.
Custom Content
Store PoliciesStacked policy cards with icons.
Trust BadgesHorizontal trust badges in a row.
Promo RotatorAuto-rotating promos with countdown and discount code.
Tips SliderSwipeable tips with dots and arrows.
Feature CarouselScrollable feature cards with responsive breakpoints.
Info GridResponsive grid of info cards.
Discount CodesColorful discount code badges in a row.
Marquee StripContinuously scrolling trust messages.
Icon + Stacked TextIcon with stacked text lines and truncation.
Images & Slideshow
ImageSingle image with rounded corners.
Image SlideshowAuto-playing image carousel with dots and arrows.
Image CarouselMulti-image carousel with responsive breakpoints.
Image + ContentSide-by-side image and text layout.
Content + ImageSide-by-side text and image layout.
Hero Image SliderFull-width auto-playing hero slider with text overlay.
Utilities
Order NotesCustomer order note text field. Configurable placeholder and character limit. For special requests or instructions.
Add to CartFixed add-to-cart bar on product pages. Shows product image,price,variant selector,and add button when main button scrolls out of viewport.
Custom CodeCustom HTML,CSS,JavaScript,and external script loader. Full control for advanced customizations,tracking pixels,GTM,or unique UI elements. JavaScript and external scripts run in the global page scope — disable Shadow DOM on the zone for full page access. Combine with the Cart Event Bus (15 events) to fire dataLayer events on cart interactions.
Loading SpinnerLoading indicator shown during cart initialization. Customizable spinner style,size,and colors for a smooth loading experience.
Component InstancesEach component added to a zone is an instance. Instances can be reordered, duplicated, or removed. Instance overrides let you customize per country/locale without affecting other markets.
8 Block Types
TypeDescriptionTextRich text with formatting, font size, color, weight, and alignment.LinkClickable link with custom URL, text, and styling.DiscountAuto-applied or copyable discount code badge.CountdownTimer counting down to a target date/time.Delivery DateDynamic estimated delivery date with cut-off calculation.MediaImage or icon with configurable size and alignment.VariableDynamic value placeholder (cart total, item count, etc.).Line BreakVisual separator between blocks.
Multi-Column LayoutsBlocks can be arranged in 1–4 columns within a component. Each column is independently configurable with its own blocks and alignment.
Test Lifecycle
Draft→Running→Paused→Completed
Weight DistributionAssign traffic weights to each zone item variant (e.g. 50/50, 70/30). Visitors are randomly assigned to a variant and see it consistently for the duration of the test.
KPIsconversion_rate — Percentage of sessions that proceed to checkout.
aov — Average order value across sessions.
Device VisibilityShow or hide on Mobile, Tablet, and Desktop independently.
Scheduling (4 Levels)Template, Zone, Zone Item, and Component — each level can have its own start/end date. All four must be active for content to show.
Query Parameter TargetingTarget visitors arriving with specific URL parameters (e.g. ?utm_source=facebook). Useful for campaign-specific experiences.
Targeting Modesshow — Only show when rules match.
hide — Show by default, hide when rules match.
Rule LogicCombine rules with AND (all must match) or OR (any must match). Match types: exact, contains, regex.
Persistencenone — Re-evaluate on every page load.
session — Remember state for the browser session.
permanent — Remember state across sessions (localStorage).
Available Events
EventFired Whencart:readyCart suite initializedcart:item_addedItem added to cartcart:item_removedItem removed from cartcart:item_updatedItem quantity or variant changedcart:openedCart overlay openedcart:closedCart overlay closedcheckout:startedCheckout button clickeddiscount:appliedDiscount code applieddiscount:removedDiscount code removedgiftwrap:toggledGift wrap toggled on/offshippingprotection:toggledShipping protection toggledordernotes:savedOrder notes savedupsell:addedUpsell product added to cartreward:unlockedReward threshold reachedreward:lostCart dropped below reward threshold
Usage
// Subscribe to events
window.__v1CartSuite.on('cart:item_added', (data) => {
  console.log('Added:', data);
  dataLayer.push({ event: 'add_to_cart', ...data });
});

// One-time listener
window.__v1CartSuite.once('cart:ready', () => {
  console.log('Cart suite is ready');
});

// Unsubscribe
const handler = (data) => { /* ... */ };
window.__v1CartSuite.on('cart:opened', handler);
window.__v1CartSuite.off('cart:opened', handler);
3 Subscription Methodson(event, handler) — Subscribe to all future emissions.
off(event, handler) — Unsubscribe a specific handler.
once(event, handler) — Subscribe for a single emission, then auto-unsubscribe.
Available Methods
MethodDescriptiongetCart()Returns the current cart objectadd(items)Add one or more items to the cartchange(updates)Update quantity or properties of existing itemsupdateNote(note)Set the cart notesetAttributes(attrs)Set cart attributes (key-value pairs)setDiscounts(codes)Apply discount codes to the cart
Usage
const cart = window.__v1CartSuite;

// Get current cart
const currentCart = cart.getCart();

// Add items
await cart.add([
  { id: 12345678, quantity: 1 },
  { id: 87654321, quantity: 2, properties: { _gift: 'true' } }
]);

// Update quantity
await cart.change({ id: 12345678, quantity: 3 });

// Set note and attributes
await cart.updateNote('Please gift wrap');
await cart.setAttributes({ gift_note: 'Happy Birthday!' });

// Apply discounts
await cart.setDiscounts(['SAVE10', 'FREESHIP']);
Available Variables
VariableValue{cart.total}Cart total (after discounts){cart.subtotal}Cart subtotal (before discounts){cart.discount}Total discount amount{cart.item_count}Number of items in cart{cart.shipping}Estimated shipping cost{cart.remaining}Amount remaining to next reward threshold{cart.discounts}List of applied discount codes{amount}Context-specific amount (e.g. reward threshold){item.price}Line item price{item.compare_price}Line item compare-at price{item.title}Line item product title
Practical Examples"You're {cart.remaining} away from free shipping!"
"Your cart ({cart.item_count} items):{cart.total}"
"Save {cart.discount} with code {cart.discounts}"
"Spend {amount} more to unlock your reward"
3 Display Modes
ModeDescriptionstackedAll items visible,stacked vertically.carouselMultiple visible items with horizontal scroll and navigation.marqueeContinuous horizontal scroll animation,looping infinitely.

Get in Touch

Questions or feedback? We'd love to hear from you.