Skip to content

Marketing Tools

What the platform provides for promotions, SEO, email, social and analytics. Anything not listed here (see Not built) needs a third-party tool.

Promotions

A promotion (Promotion, applied in the pricing pipeline by PromotionsApplier / PromotionServiceImpl) has a start and end date, a priority, a list of criteria and a list of actions. With matchAllCriteria every criterion must match; otherwise any one is enough.

Criteria Matches when
MinimumSpendCriteria The basket total before discounts reaches a minimum spend
MultipleItemCriteria The basket has at least N of a given SKU
ItemInCollectionCriteria The basket has items from the given collections (all or any). A line whose product has been deleted counts for nothing
Action Effect
OrderDiscountAction A percentage or fixed amount off the order, apportioned across the lines. Stacked discounts never take a line or the delivery below zero: BasePricer gives each only what's left and records that as its amount
FreeShippingAction Delivery free
  • Global promotions (globalPromotion=true) apply automatically to every qualifying basket within their dates. Applied promotions show on the basket lines and on the admin order view.
  • Each promotion carries a promotionCode. It is also the promotion's identity, so a code must be non-blank and unique within the catalogue, ignoring case (PromotionService.save enforces both, stores it in capitals, and makes one from the name when it is blank).
  • Shoppers enter codes in the basket and at checkout (see Basket and Checkout Pages). PromotionService.checkCode decides whether a code may go on an order now (found ignoring case and spaces, switched on, needs a code, inside its dates, conditions met) and returns a PromoCodeResult (APPLIED, ALREADY_APPLIED, NOT_FOUND, EXPIRED, NOT_YET_ACTIVE, USED_UP, ALREADY_USED, CONDITIONS_NOT_MET, BLANK); USED_UP and ALREADY_USED come from the usage limits below. PromoCodeService (above PromotionService, because repricing runs the pipeline that calls it) records the stored code on Order.promotionCodes, reprices, and takes codes off again. The code lives on the order, not only on a discount source, because every reprice clears all discounts first and rebuilds them: PromotionServiceImpl.getCodePromotions re-finds the promotions from Order.promotionCodes, in one query. A discount left over from a code the shopper removed cannot bring the promotion back (a non-automatic promotion counts only while its code is on the order), and a code whose promotion was deleted, switched off or has ended is dropped on the next reprice. A code whose conditions stop being met (the shopper removes an item) stays on the order but takes nothing off, and the basket says so. An automatic promotion's reference code is not a code shoppers can enter: it reads as not found, so entering codes can't be used to discover hidden promotions.
  • A wrong code costs an attempt: after 8 refusals in 15 minutes on one order (orderProperties.promoCodeFailedAttempts) PromoCodeService answers TOO_MANY_ATTEMPTS without looking the code up. Only an order with something in the basket can try a code.
  • A new basket starts that count again, so PromoCodeRateLimiter also counts wrong codes per shopper address: after 10 in 15 minutes (badger.promotions.code-guessing.failures-per-address) the address gets TOO_MANY_ATTEMPTS on any basket until the window ends. Only wrong codes count. The counts are fixed windows in Redis shared by every node; the key holds a hash of the address, which is never logged; if Redis is down codes are checked as normal. The basket box, its no-JavaScript form and the checkout session patch all pass the address (request.getRemoteAddr()).
  • It also counts a shop's wrong codes per hour. The 100th in an hour (badger.promotions.code-guessing.shop-warning-per-hour), such as a guessing run spread over many addresses, or a proxy address standing in for many shoppers, logs one warning naming the site, for us to look into. The shop isn't alerted: the limits and reCAPTCHA are already dealing with it, and there's nothing for the shop to do.
  • On a shop with reCAPTCHA set up (the site key and secret under Security and access), a throttled shopper gets CAPTCHA_REQUIRED instead. The promo box (fragment/promoCode, which has the site key from PromoCodeView.recaptchaSiteKey) loads Google's script then, runs an invisible reCAPTCHA, the same kind as the shop's sign-in, and sends the code again with the response in the X-Recaptcha-Token header (on /basket/promo and the checkout session patch alike). A response Google accepts clears the order's and the address's counts, and the code is checked as normal; the shop's hourly count is kept. A guessing script has to pass a challenge every 8 tries. Without JavaScript the shopper just sees the message and waits.
  • Promotion.disabled switches a promotion off without touching its dates; PromotionServiceImpl.promotionApplies skips a disabled one. A promotion that never ends stores its end date as the year 3000 (PromotionStatus.OPEN_ENDED), because the pricing queries need a non-null end date.
  • Admin screen: Catalogue > Promotions (/admin/catalogue/promotions, PromotionAdminController, MERCHANDISER, ADMIN, SUPERADMIN), described in the admin guide. It goes through PromotionService (findForAdminList, findById, validate, save, delete, setDisabled), which scopes everything to the site's catalogue. The edit page offers one action (order discount, or free delivery on any or only the ticked delivery options) and at most one each of the three criteria; a promotion with rules beyond that opens with them read-only (PromotionFormMapper.rulesEditable).
  • Promotions can also be created through the MCP promotions / managePromotions tools. They go through PromotionService, so they get the same validation, catalogue scoping, unique codes and disabled switch as the admin screen. managePromotions takes the offer as discountPercent, discountAmount (shop currency, e.g. 5.00) and/or freeDelivery, and an optional minimumSpend; a create without an offer is refused (it used to save a promotion that did nothing). disabled switches one off or on. On update only the offer fields passed change: a new discountPercent or discountAmount replaces the discount and leaves free delivery alone, and freeDelivery true adds free delivery, false removes it. freeDeliveryOptions limits free delivery to those delivery option codes (and gives free delivery); [] makes it cover every option again. A code the shop has no delivery option for is refused, naming the shop's codes. Passing freeDelivery true again without freeDeliveryOptions keeps the options it had. get returns freeDeliveryOptions: null without free delivery, [] for every option.
  • Free delivery on chosen options. A free-delivery promotion (FreeShippingAction) covers every delivery option unless it names some in deliveryOptionCodes (free Standard delivery, Priority at its own price). It stores codes rather than ids, because a code stays the same when a site is copied. On any other option it takes nothing off and doesn't count as applied, so it neither blocks other promotions nor records a use. A code whose option was deleted or renamed matches nothing; the edit page lists it as "No longer exists" with a warning.
  • Free delivery at checkout. The unified checkout shows each delivery option a free-delivery promotion covers as Free, with its own price struck through, and the rest at their price (PromotionService.freeDeliveryFor: the chosen option from its price, the others from whether a free-delivery promotion's conditions are met and it covers them). The same tool sets the limits and exclusions the admin screen has: maxUses and maxUsesPerCustomer (0 removes a limit), combinable (false: never combined with other promotions), and excludedSkus, excludedCollections (seoNames) and excludedProductTypes (each replaces the old list; [] clears it), and subscriberSkus for subscribers only (["any"] for any active subscription, SKUs for particular ones, [] removes the rule). Its assign / unassign actions take a customerId from the customers tool and go through PromotionAssignmentService, which refuses a customer of another site. promotions get reports those settings, the number of uses (from the redemption records) and how many customers it is assigned to, but not who they are. Promotions can also be imported with their full rules from promotions.json (System → Initialisation) or a site transfer.
  • One save path. The admin screen and the MCP tools both go through PromotionService, so every write is scoped to the site's catalogue and checked by validate (unique code, dates in order, a valid offer and criteria, limits of at least 1). A promotion with no offer can only be saved switched off, as a draft to finish in the admin, and switching a draft on is refused (setDisabled validates, and the admin list's Enable opens the draft instead). Assigning customers changes only assignedUserIds, atomically (PromotionService.setAssigned), and save keeps the stored assignedUserIds rather than the caller's, so neither can overwrite the other.
  • Services. PromotionService owns the promotions, pricing, checkCode and recordUses; PromotionRedemptionService owns the uses (recording, limits, giving back) and never looks promotions up, so pricing can depend on it; PromoCodeService handles code entry; PromotionAssignmentService handles assigning customers, and forCustomer gathers a customer's assigned promotions, what can still be assigned and their latest uses for the Promotions card on their admin page (assign from there posts to /admin/catalogue/promotions/customers/assign; from=customer sends assign and remove back to the customer). The old User.pendingPromotions / consumedPromotions and PromotionConsumedEvent, which nothing wrote or listened for, are gone.
  • Usage limits. maxTotalRedemptions caps uses overall (e.g. "first 100 customers") and maxRedemptionsPerUser caps uses per customer. A use is a PromotionRedemption record, written at checkout by SetOrderToSubmitted (PromotionService.recordUses, then PromotionRedemptionService.recordRedemption) for each promotion that discounted the order: how it was applied (code on Order.promotionCodes, assigned or automatic), the code used and the discount across the lines and delivery. A unique (order, promotion) index makes a resubmitted order a no-op. The count is the records not given back; nothing is stored on the promotion, so saving it can't overwrite the count. A promotion whose limit is used up stops discounting baskets and its code is refused (USED_UP / ALREADY_USED), but an order placed with it keeps it when re-priced.
  • Checkout never changes the price. Payment is authorised for the basket total before the order is submitted, so recording uses only counts them. When checkouts race for the last use, the later ones (by record id, which sorts by time) keep the discount the shopper saw and paid for and are flagged overLimit for the merchant.
  • Giving uses back. ReleasePromotionUsesProcessor runs in cancelOrder and refundOrder. When the order is cancelled, or everything taken has been refunded, it sets releasedAt on the order's records, so the uses count again for other shoppers. A partial refund (some lines returned) keeps the use.
  • Assignment and exclusions. A promotion can be assigned to particular customers (assignedUserIds; pricing looks them up on every reprice, so switching the promotion off or editing it takes effect at once). One with customers assigned is theirs alone (PromotionServiceImpl.availableTo): pricing skips it for anyone else, automatic or by code, and checkCode answers NOT_ASSIGNED. One with none is open to all. A promotion can also exclude SKUs (productSkuId or variantSkuId), collections or product types, and excluded lines don't count towards its minimum spend (DiscountApportionmentService.eligibleLineItems); the promotion-config site settings (Settings > Checkout > Promotions) exclude them shop-wide, by default donations and gift cards (donationProduct, virtualGiftCard, physicalGiftCard, giftCardTopUp). canStackWithOtherPromotions=false makes a promotion exclusive, once it has actually discounted something: the apportionment methods return whether any line was discounted, so an exclusive promotion whose lines are all excluded doesn't block the rest. The basket's code box marks a code Not applying unless it took something off (or gives free delivery and no delivery is chosen yet).
  • Subscribers only. ActiveSubscriptionCriteria is a condition like minimum spend: it holds when the shopper's account has a subscription in Stripe's active status (SubscriptionService.findActiveByOwner), to one of its subscriptionSkus (matched against the subscription's productSkuId, or skuId on older records) or to anything when the list is empty. Trials, past_due, paused subscriptions and one being bought in the same basket don't count, and a shopper who isn't signed in never matches. It is looked up on every reprice, so a lapsed subscription stops the discount on the next basket change. SKUs travel unchanged in a site transfer, so the rule needs no remapping.
  • The admin edit page sets the limits, stacking and exclusions with the rest of the promotion, and has a Customers panel (search accounts with UserService.searchUsers via ?customer=, then assign one by id; /edit/{id}/customers/assign and /unassign) and a Uses panel (the count and the latest 20 PromotionRedemption records). The list shows each promotion's uses.
  • The separate Badger Pricing service has its own, richer promotion engine. It is not called from here; see docs/implementation-plan/promotions-admin-and-pricing.md in the repository for the decision on whether and how to integrate.

SEO

Feature How
Clean URLs /product/{seoName}, /collection/{seoName}, /p/{seoName}; the seoName is entered in admin
Meta tags Meta title, description and keywords on the product, collection and page edit screens. Without a meta title the page title is built from the item's name; see Page titles. The meta description falls back to the item's own description; see Meta descriptions
Canonical URLs Optional canonical path per product, collection and page; product pages always get /product/{seoName}
Sitemap Generated on a schedule by the worker (SiteMapGenerator) from pages, category pages (/c/**: the primary merchandising tree's visible nodes that have products, leaving out hidden subtrees, nodes marked exclude from sitemap and nodes with a canonical override), collections and products (each can be excluded) and uploaded to the site's file storage at {siteId}/sitemaps/{domain}/sitemap.xml. The domain is in the path because environments can share a bucket and site ids (the demo dmrt site was overwriting production's sitemap). The storefront serves it itself at /sitemap.xml on the site's own domain (SitemapService, cached per pod for five minutes) rather than redirecting to the storage host, because search engines only accept a sitemap for URLs on its own host. robots.txt gains a Sitemap: https://{domain}/sitemap.xml line unless the site's own robots.txt already names a sitemap. Entries carry lastmod only when the item has a last-modified date, and priority/changefreq only when set on the item (siteMapPriority, siteMapFrequency attributes)
Redirects redirectionRules site config (old->new, optional ->302; 301 by default), edited in Settings → Store and storefront → SEO and redirects
robots.txt Per-site robots.txt config key, with a platform default, served as UTF-8 plain text. Edit it in Settings → Configuration, which shows it (and any value containing line breaks) in a multi-line box. Values saved before that, through the old single-line box, lost their line breaks; RobotsTxt.normalise puts one back before each directive when serving, so crawlers read one rule per line
Noindex Site search (/search) and filtered, sorted or searched category URLs are noindex, follow (see Catalogue SEO). Login, registration, password reset, demo login and order-placed pages (every storefront page that writes its own <head>; NoIndexTest checks them all) carry <meta name="robots" content="noindex">. So do checkout pages (/checkout/{orderId}) and any page holding the basket: an extension whose keepsPageOutOfSearch() is true (Full Basket, Basket Actions) gets BadgerExtension.NO_INDEX in its model, the page controller sets noIndex for the theme head, and the sitemap leaves the page out (ExtensionService.keepsPageOutOfSearch). robots.txt only stops crawling; a disallowed URL can still be indexed from links, and a crawler that can't fetch a page never sees its noindex
Structured data WebSite / Organization JSON-LD, BlogPosting on blog posts, and breadcrumbs; see SEO Structured Data

Email

All email is transactional, sent through Mailtrap and queued to the worker; see Transactional Email. Templates are fixed; subjects, sender, BCC, on/off switches and branding (logo, colours, font, footer) are per-site settings, with a test send.

The Email Capture extension (emailCaptureExtension) is a small sign-up tab that slides up from the bottom of the page (Nova themes) after the visitor has browsed for a while (default 20 seconds) and stopped scrolling, and opens into a form when clicked. It collects a name and email address and records the visitor's consent to receive marketing email, so a sign-up is a real, auditable subscription rather than just details on a user record.

  • What is recorded. The address becomes a contact on your shop, with a consent record showing the topic, when it was given, that it came from the sign-up tab, and the exact wording shown ("We'll email you news and offers. You can unsubscribe at any time."). Change the wording with a Site Text override of emailCapture.consentNote. A link to your privacy notice appears under the note once you have set the Privacy notice URL.
  • Which list. The Newsletter list (topic key) setting on the extension chooses the list visitors join. The default, general, is "News and offers". If the list is archived or does not exist the tab hides itself.
  • Double opt-in. With Confirm newsletter sign-ups by email on (the default), the visitor is told to check their inbox and is only subscribed when they click the link in the confirmation email. That email is sent at most once per address per 24 hours, and the link works for 7 days. With it off, the visitor is subscribed straight away.
  • Hidden once subscribed. For a signed-in visitor who already receives the list, the tab does not appear.
  • Bots. The form has a hidden field that people never see. A sign-up that fills it in is discarded without a trace.

Every marketing email carries an unsubscribe link, which opens a page at /messaging/unsubscribe/... with a button. The page works without signing in, shows the shop and the list but never the email address, and changes nothing until the button is pressed (so mail scanners that open links cannot unsubscribe anyone). The shopper can stop this list or all emails from the shop. Mail apps that offer their own "unsubscribe" button use the same link as a one-click request. The confirmation link opens /messaging/confirm/.... These links never contain the email address, and they only work on the shop that sent them. An unsubscribe link never expires.

The tab still raises the UserInformationAddedEvent, so anything listening for it keeps working. It does not sync with an external newsletter service. Sending news and offers to the people who subscribed is Email campaigns, from the shop's own verified sending domain.

Page titles

Every theme's <title> comes from PageTitles (called from each theme's fragment/head as @pageTitles.title(title, pageName, siteContext)):

Case Title
A Meta Tag Title is set in admin Used exactly as written
No meta title The item's name, then \| and the site name: Donate \| Derby Mountain Rescue Team
The name already contains the site name The name alone
Adding the site name would go past 60 characters The name alone, since search engines cut titles off around there
No name at all The site name

From page 2 onwards, a paginated listing (?p= on collections, search and merchandising pages; ?bp= on blog lists) adds – Page N after the name, so the pages don't all share one title: Callouts – Page 3 \| Derby Mountain Rescue Team. With a meta title it goes on the end. The wording is the seo.title.page-number message (Page {0}; Dutch Pagina {0}).

Meta descriptions

The <meta name="description"> tag, og:description and the content-search description all come from the same place:

Item Source
Product Meta Tag Description (attributes.metaDesc) on the variant, then the product, else the product's description (og:description falls back to the mini description)
Collection Meta Tag Description (attributes.metaDesc) on the collection edit screen, else the collection's description
Page (including blog posts) Meta Tag Description (attributes.metaDesc) on the page edit screen, else the page's description
Merchandising node The node's SEO meta description, else its description

A blank Meta Tag Description counts as unset. Descriptions are written in the rich-text editor, so whichever source wins is turned into plain text by MetaDescription.from: tags are stripped, entities decoded, whitespace collapsed, and the result is cut to 160 characters at a word boundary. An empty editor (<p><br></p>) yields nothing, and the tag is left out rather than published empty.

Every theme (Nova and the themes on it) resolves pages and collections through AttributeContainer.metaDescriptionOr(fallback), products through DProduct.metaDescription() and merchandising nodes through MerchandisingNode.metaDescription(), so the rule lives in one place.

Social

  • Share buttons and social links — the SocialLinks extension shows share buttons on product pages and blog posts, and links to the shop's accounts on other pages and in the footer. Accounts are set in Settings → Site identity as a profile URL (linked as it is) or a bare handle (linked after the network's address, e.g. linkedin.com/company/<handle>); SocialProfiles builds the links and StorefrontChromeInterceptor puts them on every page as socialProfiles.
    • Which networks the share buttons offer is the Share buttons setting (Settings → Store → Social sharing, key share-networks): any of Facebook, LinkedIn, WhatsApp, Bluesky, Threads, Pinterest, X and email. The default is Facebook, X, WhatsApp and email. A copy-link button, and the device's own share menu where there is one, are always shown.
    • Each button opens the network's "share this" screen with the page's address and title filled in. ShareNetwork builds and encodes the links, so a title with & or # in it, or an address with a query string, arrives intact.
    • Blog posts only show the buttons where the extension is placed: add socialLinks to the blog's post stereotype (e.g. its mainSection) to give every post share buttons.
    • Other pages show the shop's accounts unless the block's Force Share Buttons is on.
  • Share kit — every page and blog post has a Share tab (ShareKitService) with a social summary (page attribute socialSummary), the masthead picture and, per network, the text to post, the first comment and a UTM-tagged link, ready to copy. Facebook, LinkedIn, Threads and X put the link in the first comment (they down-rank posts with links), Bluesky in the post, Instagram in the bio. It posts nothing itself; see Sharing on social media.
  • Open Graph — OpenGraphExtension emits og:* tags, plus price, availability and rating on products, with special handling for blog posts and fundraisers.
  • Social login — customers can sign in with Google or Apple.
  • Likes and comments — LikeExtension (product likes) and DiscussionExtension (Disqus comments, needs a Disqus site id).

Merchandising extensions

  • Trending products — ranked by recent page views (TrendingProducts).
  • Featured product — FeaturedProductExtension.
  • Recently viewed — the visitor's browsing history (RecentlyViewedProductsExtension).
  • Related products — "You may also like" on every product page by default, read from each product's stored list of related products, which a background job generates from shared collections and taxonomy category; a new product shows nothing until its list is generated (RelatedProducts; see Extension System).
  • Frequently bought together — add a set of products to the basket in one click (ProductBundleExtension; no bundle discount).
  • Announcement bar — the Storefront setting Announcement (storefront-announcement, falling back to the Site Text key nav.banner.message); see Site Customization.
  • Gift cards — see Gift Cards.
  • Blog RSS — /rss/{blogName}.

Analytics

  • Admin dashboard (/admin/home) with page-view graphs, and Reports (/admin/reports): sales summary, year-over-year, top products, MRR, Gift Aid and item-level, with CSV download.
  • Search-term tracking (search-term-tracking-enabled), feeding top and zero-result searches.
  • MCP statistics and siteTraffic tools expose the same figures to agents.
  • Google Analytics (GA4 measurement id, or the older analytics.js with ecommerce transactions) and Hotjar extensions. They only load once the visitor accepts analytics cookies on the built-in cookie banner.
  • Crisp live chat (crispChatExtension): adds the Crisp chat widget. Paste the Crisp website ID from your Crisp account (a UUID) into Settings > Cookie consent > Crisp Website ID (crisp-website-id), then add the extension to a site-wide stereotype in the analytics slot. Chats are answered in Crisp, which can post each conversation to a Slack thread through its own Slack integration. Like Google Analytics and Hotjar it loads nothing until the visitor accepts cookies, and setting an ID brings up the cookie banner.

Not built

No shopper-entered coupon codes, unique/bulk code generation, usage limits, tiered or bundle pricing, or customer-segment targeting. No abandoned-cart or other triggered emails, and no newsletter-service integration. (Marketing emails to subscribers are email campaigns, with delivery counts and, when tracking is on, open and click rates.) No product reviews, shopping/social catalogue feeds or social feed embeds. No loyalty points, referrals, VIP tiers or birthday rewards. No SEO analysis tool.