docs

Campaigns

A campaign is a time-limited price reduction that your shop runs through the SCAYLE Panel. The Storefront Application V3 shows the running campaign in the page ribbon, on product badges, in deal banners, and in the basket, using the name, colors, and schedule you set in the SCAYLE Panel.

A campaign is switched on by time, a promotion by the basket. While a campaign runs, the Storefront API reduces the prices it covers, and the Storefront Application shows one running campaign at a time, the first active one. A promotion applies once the customer meets its rules, such as the items in the basket, and several can run side by side.

Why it matters

When a customer sees a campaign badge on a product card, the same campaign name and colors should appear on the product detail page, in the basket, and in the deals panel. The Storefront Application V3 resolves the running campaign once per request and hands the same value to every page and component, so every surface of that page renders the same campaign.

Try it

Try it: View a campaign

See the campaign ribbon, the banner and badges on the demo shop.

Recording of a campaign in the demo shop

What's included

  • Campaign page prop: campaign is a shared prop typed Campaign | null. It is a once prop (see Shared data) and part of the first server-rendered HTML, so components render it without a loading state.
  • Ribbon: On pages that use the full layout, the ribbon at the top shows the campaign headline, subline, and a countdown to the end date. The ribbon never renders on the basket page. When a campaign is running, it takes the ribbon slot before the first promotion. The countdown is hidden when the campaign sets hideCountdown, and the customer can close the ribbon.
  • Product badges: Product cards and sliders show a campaign badge only when the product's price carries a campaign reduction. The label is the campaign's badgeLabel, or the translation key campaign.deal when it is empty. A highlight (a page promotion or a CMS override) replaces the campaign and promotion badges with at most one badge of its own. The highlight badge can be hidden, so a highlighted product can show no badge at all.
  • Deal banners: The product detail page shows a campaign banner only when the selected price carries a campaign reduction. The basket page shows one only when the basket has a campaign reduction. Both banners use the campaign headline, subline, colors, and countdown, and they link to the campaign link when it is set.
  • Deals slide-in: SFPromotionSlideIn.vue lists the running campaign before the promotions. The header button that opens it counts the campaign as one deal. The count appears once the promotions have loaded, because promotions is a deferred prop, which the server sends after the first render.
  • Basket display: A basket line with a campaign reduction shows the campaign badge on its image. In the basket summary, the Discount row adds the campaign reduction to the promotion total. Expanding the row lists the campaign by headline, or by name when the headline is empty, with its amount in the campaign colors.
  • Price information: The price information modal lists the campaign name and its reduction when the price carries one.
  • Campaign reduction on prices: Product prices and basket prices carry campaignReductionInCents and hasCampaignReduction. The Storefront API sends them as applied reductions in the campaign category, the way Pricing describes for other reductions. The basket cost adds them up as campaignReductionSumInCents.
  • Campaign key on API requests: The SDK passes the running campaign's key as campaignKey to Storefront API requests for products, listings, search, recommendations, the basket, the wishlist, and checkout.
  • Tracking: The ribbon and the deal banners report view_promotion and select_promotion for the campaign, the same way they do for promotions.

What you can change

Configure

  • Campaign schedules, names, discounts, and colors are set entirely in the SCAYLE Panel under Shops ➜ Promotions. No configuration is needed in the Storefront Application V3 code.
  • Set the environment variable STOREFRONT_CACHE_DISABLED=true to turn off the server cache while you check a campaign locally. It disables every cache entry of the application, so keep it out of production.

Theme

  • Set the fallback colors with the --color-campaign and --color-primary tokens in src/client/design-tokens.css. They apply to campaigns whose colors the SCAYLE Panel left empty. Colors set in the SCAYLE Panel win over the tokens.
  • Restyle the ribbon, banners, and badges in src/client/components/deal/ and src/client/components/product/SFBadges.vue. They are your components.

Extend

Constraints and limits

Permanent

  • The Storefront API applies the campaign discount and returns it in the price. The Storefront Application V3 does not calculate it. The campaign prop supplies the labels, colors, link, and schedule. Hiding the campaign components does not remove the discount from a price.
  • Campaign badges, the product detail banner, and the basket banner depend on the price, not only on the campaign. A campaign applies to all products or to selected ones, and a product outside the campaign has hasCampaignReduction set to false. Check that flag in any component you add that shows campaign UI for a product, as SFBadges.vue and SFProductDealBanners.vue do. Without the check, a product outside the campaign carries a campaign badge next to its regular price. The ribbon and the deals slide-in show the campaign whenever it is running.
  • A campaign counts as running only when it has both a start date and an end date and the current time is at or after the start and before the end. A campaign without both dates never reaches the page.

Known limitations

  • A change in the SCAYLE Panel takes up to 5 minutes to reach a full page load, and about 10 for a customer who navigates inside the Storefront Application V3. See Data cache TTLs. A campaign that ends keeps showing, and one that starts stays hidden, until then. The browser keeps its copy of the campaign once prop for the same time again.
  • If your CDN caches the HTML of the routes in cacheableRoutes, a cached page also carries the campaign as of its render. Schedule a campaign to start a few minutes before you promote it, or shorten the lifetimes with Change how long a campaign is cached.
  • When several campaigns are running, the SDK picks the first one in the order the Storefront API lists them. It requests the first page of the campaign list with the API's default order and applies no ranking of its own. SCAYLE allows several price campaigns per shop at once, so overlapping campaigns can produce a pick you did not intend. Run one campaign at a time, or use Choose which campaign wins.
  • When the Storefront API or the cache fails, the SDK logs Failed to fetch the active campaign, treats the shop as having no campaign for that lookup, and continues without a campaign key. It does not cache the failure, so the next lookup retries. Override resolveActiveCampaign to change that behavior.
  • The campaign condition text reaches the page props as conditions, but no component of the Storefront Application V3 shows it. The campaign banners render the headline and subline only.

How it works

Fetching and caching

CampaignsService from @scayle/storefront/services runs once per request, because every caller of the request shares one lookup. The lookup asks the Storefront API for the campaign list and keeps the first campaign whose schedule covers the current time. It stores that raw campaign in the server cache, and CampaignMapperService maps it on every call, see Rules for cached values.

The campaign once prop asks CampaignsService for the active campaign. The service reads the server cache, asks the Storefront API on a miss, and maps the result with CampaignMapperService. The browser reuses the prop until it expires.

The SDK also uses the lookup to supply the campaign key for Storefront API requests, so overriding the lookup changes both the campaign the page shows and the key the API receives. The SDK's own lookup never rejects: on a failure it logs once and returns null.

Mapping

The mapped campaign that reaches the page has this shape: id, key, name, reduction, schedule with from and to, headline, subline, link, hideCountdown, conditions, an optional badgeLabel, and color. The headline falls back to name when the Storefront API sends an empty one.

The SDK's base CampaignMapper produces everything except color. The Storefront Application V3 adds color in src/server/services/mappers/campaign-mapper.ts, because the SDK has no dependency on Vue. The CampaignMapperService there turns the Storefront API's { background, text } colors into backgroundColor and color inline styles. It falls back to var(--color-campaign) and var(--color-primary) when a color is missing or empty, so both values are always non-empty strings.

Shared data

src/server/middleware/sharedData.ts shares the campaign as a once prop. A once prop is a shared prop that the browser keeps between client-side visits, see Props and when they load. The expiry for campaign is the same as the server cache lifetime, counted from the response that carried it. A full page load asks the server again, and so does the first client-side visit after the expiry.

Setup

The Storefront Application V3 reads campaigns without any code or configuration change. You need a shop with products that a campaign can include.

  1. Create a campaign in the SCAYLE Panel and give it a start date, an end date, a discount, and the design fields described under Configuration.
  2. Open a page of your shop. The server cache can hold the previous state, so reload after the delay described under Constraints and limits.

When it worked, the ribbon shows the campaign headline, products in the campaign carry a campaign badge, and the deals button in the header counts the campaign.

Configuration

SCAYLE Panel

A campaign is created and managed in the SCAYLE Panel under Shops ➜ Promotions as a Price Campaign. Create it, set the discount value and schedule, then enable the Campaign Design toggle to fill in the UI fields (headline, badge label, colors, link). If the campaign targets multiple countries, translate the fields on the Translations page after saving.

Storefront Application

Campaigns have no keys in storefront.config.ts. These are the values that shape how long a campaign stays in a cache:

ValueWhere it livesDefault
Server cache lifetime of the running campaignA constant of the SDK. Change it by overriding resolveActiveCampaign.See Data cache TTLs
Browser lifetime of the campaign once propSecond argument of Inertia.once for campaign in src/server/middleware/sharedData.tsThe server cache lifetime

Customization guides

Add a field from the Storefront API to the campaign

You end up with a Storefront API campaign field, such as description, available as campaign.description in every component. The base Campaign carries the top-level fields listed under Mapping. Fields such as description, colorStyle, and customData stay on the raw Storefront API campaign until you map them.

  1. Add the field to the Campaign augmentation in src/shared/types/Promotion.ts, next to color. The module name must be @scayle/storefront/types, the same as the existing block.

    The typecheck now fails in every typed Campaign object, such as createMockCampaign in src/test/mock-data/promotions.ts, the stories, and the tests, because they lack the new required field. CampaignMapperService still compiles, because it spreads the base result, so the field arrives as undefined until step 2.
  2. Return the field from mapCampaign in src/server/services/mappers/campaign-mapper.ts.
  3. Add the field to each of the other Campaign objects the typecheck still reports.
  4. Read the field in a component through usePage().props.campaign.

When it worked, the typecheck passes and campaign.description holds the text from the Storefront API.

Test the campaign mapper

You end up with a test of CampaignMapperService that fails when an override drops a base field or breaks the color mapping. Write one like it for a field you add. A mapper depends only on its context and its input, so it tests without a browser or a Storefront API. @scayle/storefront/test ships the context doubles and createApiCampaign, which returns a Storefront API campaign you can override field by field. Import it from test files only, because it depends on vitest. The application re-exports the context doubles from src/test/utils/context.ts.

The first test catches a hand-built shape that drops a base field, and the second asserts the color mapping. Run the file with pnpm exec vitest run src/server/services/mappers/campaign-mapper.test.ts, and both tests pass. The application's docs/testing-guidelines.md covers its testing rules.

Choose which campaign wins

You end up with a campaign pick that follows your own rule when several campaigns run at once. The example prefers the campaign that started most recently. It also fixes the key the Storefront API requests receive, because the SDK reads both from the same lookup.

  1. Create src/server/services/latest-campaigns-service.ts and override resolveActiveCampaign. isCampaignActive is not exported, so the example repeats its date check.

    Keep the try and catch. The campaign prop in sharedData.ts has no catch of its own, so a rejection would reach the page render. Remove the catch only if you want a Storefront API failure to fail the request.
  2. Register the subclass in src/server/registries.ts and remove CampaignsService from that file's import list when nothing else there uses it. No declare module entry is needed, because every consumer reads only the members of the base class.

When it worked, a shop with two overlapping campaigns shows the one that started last, and its key is the value under campaign.key in the page props.

Change how long a campaign is cached

You end up with a shorter or longer window between a Panel change and the storefront. A shorter window costs more Storefront API calls for the campaign list.

  1. Change the browser lifetime in src/server/middleware/sharedData.ts. Replace the second argument of Inertia.once for campaign.

    Remove CampaignsService from the import of @scayle/storefront/services in that file if nothing else there uses it.
  2. Change the server lifetime by overriding resolveActiveCampaign as in Choose which campaign wins and passing your own number of seconds to getOrSet in place of the constant that example uses.

When it worked, a Panel change reaches a full page load within the new server lifetime, and a client-side visit within the sum of both lifetimes.

Best practices

Read the campaign from the page props in components

Components get the campaign through usePage().props.campaign, as SFProductCard.vue does. A component cannot call the campaign service, and the prop is already the mapped, typed value. Server code that needs the campaign, such as a controller, can call services.campaigns.fetchActiveCampaign(). The call shares the request's lookup, so it adds no second Storefront API request.

Treat the campaign as nullable

Check campaign for null before you read it, such as with v-if="campaign". The prop is null when no campaign is running and when the lookup failed, as Constraints and limits describes.

Use campaign.color without a fallback check

CampaignMapperService returns a non-empty string for backgroundColor and color, either from the SCAYLE Panel or from the theme tokens. Bind campaign.color as an inline style without a fallback. If you rewrite the color mapping, keep a fallback for each value so this stays true.

Keep the base mapping in your mapper override

Keep the ...super.mapCampaign(campaign) spread in CampaignMapperService. A hand-built object that satisfies the compiler can still drop an optional field such as badgeLabel, and no error points at it.

Troubleshooting

A campaign is running in the SCAYLE Panel but the storefront shows regular prices and no campaign

Issue: The campaign has started and the cache window has passed, but no ribbon, badge, or banner shows and the prices have no campaign reduction.

Possible causes: The campaign has no start date or no end date, or the campaign lookup failed. Both are described in Constraints and limits.

Solution:

  1. Open the campaign in the SCAYLE Panel and check that it has both a start date and an end date. Add the missing date and reload after the cache window has passed.
  2. Search the server logs for Failed to fetch the active campaign. A match means the lookup failed, and the next request retries it.

Prevention: Set both dates whenever you create a campaign.

The storefront shows a different campaign than the one I expect

Issue: A ribbon, badge, or banner shows, but its name or colors belong to another campaign.

Possible causes: Several campaigns run at once, and the SDK picked the first one in the order the Storefront API lists them. This is described under Known limitations in Constraints and limits.

Solution:

  1. Open the page source and find the campaign prop. Compare its key with the key of the campaign you expect.
  2. If the keys differ, end the overlapping campaign in the SCAYLE Panel or use Choose which campaign wins.

Prevention: Run one campaign at a time.

Reference

SCAYLE Panel configuration

Storefront API