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.saveenforces 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.checkCodedecides 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 aPromoCodeResult(APPLIED,ALREADY_APPLIED,NOT_FOUND,EXPIRED,NOT_YET_ACTIVE,USED_UP,ALREADY_USED,CONDITIONS_NOT_MET,BLANK);USED_UPandALREADY_USEDcome from the usage limits below.PromoCodeService(abovePromotionService, because repricing runs the pipeline that calls it) records the stored code onOrder.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.getCodePromotionsre-finds the promotions fromOrder.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)PromoCodeServiceanswersTOO_MANY_ATTEMPTSwithout looking the code up. Only an order with something in the basket can try a code. - A new basket starts that count again, so
PromoCodeRateLimiteralso counts wrong codes per shopper address: after 10 in 15 minutes (badger.promotions.code-guessing.failures-per-address) the address getsTOO_MANY_ATTEMPTSon 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_REQUIREDinstead. The promo box (fragment/promoCode, which has the site key fromPromoCodeView.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 theX-Recaptcha-Tokenheader (on/basket/promoand 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.disabledswitches a promotion off without touching its dates;PromotionServiceImpl.promotionAppliesskips 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 throughPromotionService(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/managePromotionstools. They go throughPromotionService, so they get the same validation, catalogue scoping, unique codes anddisabledswitch as the admin screen.managePromotionstakes the offer asdiscountPercent,discountAmount(shop currency, e.g.5.00) and/orfreeDelivery, and an optionalminimumSpend; a create without an offer is refused (it used to save a promotion that did nothing).disabledswitches one off or on. Onupdateonly the offer fields passed change: a newdiscountPercentordiscountAmountreplaces the discount and leaves free delivery alone, andfreeDeliverytrue adds free delivery, false removes it.freeDeliveryOptionslimits 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. PassingfreeDeliverytrue again withoutfreeDeliveryOptionskeeps the options it had.getreturnsfreeDeliveryOptions: 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 indeliveryOptionCodes(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:maxUsesandmaxUsesPerCustomer(0 removes a limit),combinable(false: never combined with other promotions), andexcludedSkus,excludedCollections(seoNames) andexcludedProductTypes(each replaces the old list;[]clears it), andsubscriberSkusfor subscribers only (["any"]for any active subscription, SKUs for particular ones,[]removes the rule). Itsassign/unassignactions take acustomerIdfrom thecustomerstool and go throughPromotionAssignmentService, which refuses a customer of another site.promotions getreports 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 frompromotions.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 byvalidate(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 (setDisabledvalidates, and the admin list's Enable opens the draft instead). Assigning customers changes onlyassignedUserIds, atomically (PromotionService.setAssigned), andsavekeeps the storedassignedUserIdsrather than the caller's, so neither can overwrite the other. - Services.
PromotionServiceowns the promotions, pricing,checkCodeandrecordUses;PromotionRedemptionServiceowns the uses (recording, limits, giving back) and never looks promotions up, so pricing can depend on it;PromoCodeServicehandles code entry;PromotionAssignmentServicehandles assigning customers, andforCustomergathers 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=customersends assign and remove back to the customer). The oldUser.pendingPromotions/consumedPromotionsandPromotionConsumedEvent, which nothing wrote or listened for, are gone. - Usage limits.
maxTotalRedemptionscaps uses overall (e.g. "first 100 customers") andmaxRedemptionsPerUsercaps uses per customer. A use is aPromotionRedemptionrecord, written at checkout bySetOrderToSubmitted(PromotionService.recordUses, thenPromotionRedemptionService.recordRedemption) for each promotion that discounted the order: how it was applied (code onOrder.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
overLimitfor the merchant. - Giving uses back.
ReleasePromotionUsesProcessorruns incancelOrderandrefundOrder. When the order is cancelled, or everything taken has been refunded, it setsreleasedAton 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, andcheckCodeanswersNOT_ASSIGNED. One with none is open to all. A promotion can also exclude SKUs (productSkuIdorvariantSkuId), collections or product types, and excluded lines don't count towards its minimum spend (DiscountApportionmentService.eligibleLineItems); thepromotion-configsite settings (Settings > Checkout > Promotions) exclude them shop-wide, by default donations and gift cards (donationProduct,virtualGiftCard,physicalGiftCard,giftCardTopUp).canStackWithOtherPromotions=falsemakes 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.
ActiveSubscriptionCriteriais a condition like minimum spend: it holds when the shopper's account has a subscription in Stripe'sactivestatus (SubscriptionService.findActiveByOwner), to one of itssubscriptionSkus(matched against the subscription'sproductSkuId, orskuIdon 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.searchUsersvia?customer=, then assign one by id;/edit/{id}/customers/assignand/unassign) and a Uses panel (the count and the latest 20PromotionRedemptionrecords). 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.mdin 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
SocialLinksextension 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>);SocialProfilesbuilds the links andStorefrontChromeInterceptorputs them on every page associalProfiles.- 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.
ShareNetworkbuilds 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
socialLinksto the blog's post stereotype (e.g. itsmainSection) to give every post share buttons. - Other pages show the shop's accounts unless the block's Force Share Buttons is on.
- Which networks the share buttons offer is the Share buttons setting (Settings → Store →
Social sharing, key
- Share kit — every page and blog post has a Share tab (
ShareKitService) with a social summary (page attributesocialSummary), 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 —
OpenGraphExtensionemitsog:*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) andDiscussionExtension(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 keynav.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
statisticsandsiteTraffictools 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 theanalyticsslot. 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.