A promotion is a list people join. It holds no money-off rule of its own. It names a discount code that already exists (and/or a download link) and hands it to each person who signs up. The code is an ordinary discount, made in Discount Center and checked at checkout like any other: see Discount codes and automatic discounts.
| Discount | Promotion | |
|---|---|---|
| Record | sf_discount | promotion, and a subscriber per person |
| Where | Storefront › Discounts (/discount) | CRM › Promotions (/promotions) |
| What it does | changes the price at checkout | collects sign-ups and gives them the code or download |
| The shopper meets it | the Promo Code box, or automatically | the /join?promotion=<name> page and its emails |
A banner or popup that advertises the offer is a site notice: Site notice: banner, popup, age gate or cookie consent.
The site never lists a promotion's code. GET storefront/discounts/promotions/active leaves out every code a promotion hands out, and codes for groups or named customers (discount.service.ts listPublicPromotions). It is still one code for everyone: whoever has it can use it at checkout. For a code only some people can use, see Discount codes.
Ask first
- What do people get for joining? A discount code (which offer: % or $ off, minimums, dates), a download link, both, or nothing (a plain newsletter, waitlist or alert list).
- Must they confirm their email first (double opt-in)? The code then comes only after they click the link.
- Dates: when sign-ups open and close.
- The emails: the built-in ones, or their own wording.
- Where the link goes: the site, a broadcast, a social post. The person shares it; the AI doesn't.
Steps
1. Storefront › Discounts: the code to hand out
Make the code first, as in Discount codes: typically percent with usageLimitPerCustomer: 1. Activate it on the owner's yes and quote it once.
The promotion only copies the code's text. It doesn't check the code exists, is active or fits the people joining. A subscriber handed a draft, expired or group-limited code is refused at checkout. Don't limit it with customerGroups: new subscribers aren't in any group.
Hands on: the discount's code.
Check: POST storefront/discounts/calculate with a qualifying basket and the code gives the saving.
2. CRM › Promotions: the promotion
call_appengine POST crm/promotions (staff only):
{
"name": "spring-list",
"title": "Join and get 10% off",
"description": "Our news, and 10% off your first order.",
"type": "offer",
"channels": ["email"],
"requireDoubleOptIn": true,
"discountCode": "SPRING10",
"endDate": "2026-05-31T23:59:59.000Z"
}It answers with the saved record. A second promotion with the same name is refused: Promotion spring-list already exists.
| Field | What it does |
|---|---|
name | The promotion's id: letters, digits, -, _, at least 2 characters, unique. It goes in the sign-up link. Can't be changed (PUT drops it). |
title, description | The sign-up page's heading and text, and the emails'. title defaults to name. |
type | newsletter (default), offer, gated_content, waitlist, alert. A label only: nothing behaves differently. |
status | active (default through this call) or inactive. Inactive or out of dates: the page says the offer isn't running and sign-ups are refused. |
channels | email, sms. Not enforced. The sign-up page only ever takes an email. |
requireDoubleOptIn | With an email: the subscriber stays pending until they open the confirmation link, valid 24 hours. The code is sent after that. |
discountCode | The code each subscriber gets. |
downloadUrl | A link each subscriber gets. |
startDate, endDate | When sign-ups are taken. |
notifications | The promotion's own emails (step 4). |
color, icon | Saved; the sign-up page doesn't use them. |
stats | totalSubscribers, activeSubscribers, unsubscribed, incentivesClaimed, kept by the server. |
Change it with PUT crm/promotions/<name> (only the fields sent; name and stats are ignored). Read it with GET crm/promotions/<name>, list with GET crm/promotions (status, type, search, page, pageSize).
On screen. CRM › Promotions (/promotions), tabs Dashboard, Promotions (?tab=promotions), Subscribers; one promotion opens with ?openId=<sk>. The form picks the code from Discount Center's codes. It saves through the generic record save: the name is still checked as unique, but leave Status set, or the promotion has none and takes no sign-ups. The menu on each row has Copy sign-up link, Open sign-up page, Clone and Delete.
Hands on: the promotion's name.
Check: GET crm/promotions/<name>/public (no sign-in, on the site's /api) answers open: true and hasIncentive: true. This is what the page shows; it never contains the code.
3. Website: the sign-up page
The sign-up page is built in. Every site answers <site>/join?promotion=<name>. Nothing to switch on, and no page to make. Without ?promotion= the address is an ordinary page (or a 404). See Built-in pages and templates for what frames it: the store page while Storefront is on, else account-layout.
The page shows the title, the description and "From utm_source, utm_medium and utm_campaign from the link onto the subscriber. After signing up it shows:
- without double opt-in: "Here is your code", the code with Copy code, "Enter it at checkout. We have emailed it to you as well.", the download link if there is one, and Start shopping (the store);
- with double opt-in: "Check your inbox". The confirmation link lands on
<site>/confirm-subscription?token=…, which confirms and then shows the code.
Closed promotions show "This offer has ended.", "This offer has not started yet." or "This offer is not running right now.". A promotion that doesn't exist shows "Promotion
Stop: from here on, every sign-up sends real email (step 4). Show the owner the link and the page. Don't submit the form. The owner shares the link.
The link is <site address>/join?promotion=<name>. Copy sign-up link builds it from the site's own address.
Check: open the link in a browser. The title, description and form show (tested on a local site). Read it, don't sign up.
4. Message Templates: the emails (optional)
Each step of a sign-up can send an email. Which one is sent is decided per trigger:
| Trigger | When | Sent when there is no notification row |
|---|---|---|
subscribed | a new sign-up, or a re-sign-up after unsubscribing | only with double opt-in: the built-in promotion-subscribed, carrying the confirm link |
confirmed | the confirmation link was opened | no |
incentive_sent | the code or download was given | always: the built-in promotion-incentive_sent, with the code and the download |
unsubscribed | they left the promotion | no |
reminder | never fired | — |
With a row for the trigger in notifications, that row decides: { "trigger": "confirmed", "deliveryType": "email", "template": "<message template name>" }, or subject with html / text written in the row. A row with none of those uses the built-in promotion-<trigger>. deliveryType: "sms" texts the subscriber's phone. Send trigger and deliveryType as single words, as here. Write a template with Email and SMS templates with merge fields: the context is data.subscriber, data.promotion, data.incentive.code, data.incentive.url, data.confirmationToken and data.unsubscribeToken.
The built-in emails link to <site>/confirm-subscription?token=… and <site>/unsubscribe?email=…&promotion=<name>&t=<token>, the site's own unsubscribe page, which takes them off this promotion. The t token is signed for that address and promotion, and the unsubscribe call needs it. In a template of your own, build the link the same way, with &t={{urlEncode data.unsubscribeToken}}; a link without it can't unsubscribe anyone (promotion.service.ts unsubscribeToken).
A promotion with a code or download emails it to every new subscriber, at once or after they confirm. There is no switch to stop it, only a different wording (a notification row). Someone who signs up again while still active sees the code on the page again but gets no new email. Someone who left and joins again gets no code email without double opt-in.
Stop: writing these is safe; they send on the next sign-up. Show the owner the wording first.
Check: GET crm/promotions/<name> shows the notifications rows.
5. CRM › Promotions: subscribers and claims
GET crm/promotions/<name>/subscribers (status, page, pageSize), newest first. Each row has email or phone, name, status (pending, active, unsubscribed), source, sourceUrl, the UTM fields, the consent text, and incentive { sent, sentAt, code, claimed, claimedAt, orderId, orderNumber }. On screen: the Subscribers tab.
When a placed order uses the code under the subscriber's email, that subscriber's incentive is marked claimed with the order, and the promotion's stats.incentivesClaimed goes up. A subscriber with only a phone is never marked.
A subscriber is not a customer or a lead. Signing up creates only the subscriber row.
Check: the promotion's stats match the Subscribers tab.
The public calls the page uses
All on the site's /api, no sign-in:
| Call | Answers |
|---|---|
GET crm/promotions/<name>/public | name, title, description, type, channels, requireDoubleOptIn, startDate, endDate, hasIncentive, open, and reason when closed: Promotion is not active, Promotion has not started yet, Promotion has ended. 404 when there's no such promotion. |
POST crm/promotions/<name>/subscribe with { email or phone, name, channel, source, sourceUrl, utmSource, utmMedium, utmCampaign, consentText } | { status, requiresConfirmation, promotion, incentive? }, with incentive: { type: "discount" | "download" | "both", code, url } when it was given. Refusals (400): Email or phone is required, Promotion is not active, Promotion has not started yet, Promotion has ended, Promotion <name> not found. |
GET crm/promotions/confirm/<token> | { status, promotion, incentive: { code } }. 400 Invalid confirmation token, Subscription already confirmed or invalid, Confirmation token has expired. |
POST crm/promotions/<name>/unsubscribe with { email or phone, reason, t } (t from the email's link; token also read) | { status: "unsubscribed", promotion }. 400 This unsubscribe link is not valid. Use the link in the email. without a matching t; 400 Subscriber not found. |
Listing promotions or subscribers, and GET crm/promotions/preferences, need someone signed in to the business: a visitor gets 403 "This needs someone signed in to the business" (tested).
When it's done
Tell the person:
- the promotion's name and title, what joiners get, and whether they confirm first;
- the code it hands out and what that code gives at checkout;
- the sign-up link, and which emails go out on each sign-up;
- that the link is theirs to share.
Open the promotion in CRM › Promotions (/promotions?tab=promotions&openId=<sk>).
What it can't do yet
- The code can be passed on. It is one shared code, so "join to get the code" is a courtesy, not a gate.
- One code for everyone. Every subscriber gets the same
discountCode; no unique codes per person. - The promotion doesn't check its code is active, unexpired or open to new customers.
- The page takes email only.
channelsisn't used, and phone sign-ups need a page of your own posting to the subscribe call. - The confirmation is a plain link. Email scanners that open links can confirm an address.
reminderemails are never sent, andtype,colorandiconchange nothing.- Claims are matched by email only, and an order counts as a claim when it is placed, paid or not.
Don'ts
- Don't submit the sign-up form or call subscribe with a real address to test; it emails the code. Test with the public call and by opening the page.
- Don't hand out a code that is a draft, expired or limited to a customer group.
- Don't promise subscribers a code nobody else can use: it can be passed on.
- Don't share the sign-up link or post it anywhere; the person does.
- Don't delete a promotion people are signed up to without asking; its subscribers stay, orphaned.