Promotions & Campaigns

Overview

The Promotions & Campaigns features allow you to offer discounts and special deals to customers based on predefined conditions. These features are designed to enhance user engagement, increase conversion rates, and encourage higher average order values by automatically applying discounts or offering free gifts when certain criteria are met.

Deals (the collective term for Promotions and Campaigns) are integrated throughout the SCAYLE Storefront experience—including the Product Listing Page (PLP), Product Detail Page (PDP), Basket, and Order Summary—ensuring users are continuously informed about active offers.

Key Features

• Flexible Condition Setup: Supports diverse conditions based on product quantity, total order value, or specific product combinations and attributes.
• Comprehensive Configuration: Full support for configuration via the SCAYLE Panel or API, empowering both developers and marketing teams to align deals with business goals.
• Automatic Application: Eligible deals are automatically applied when their conditions are met (for promotions) or to eligible products (for campaigns).
• Built-in UI Components: A suite of components like badges, ribbons, and banners clearly communicates deals across the shop.
• Prioritization Logic: Ensures the most relevant offer is always displayed when multiple deals apply. Campaigns have priority over promotions in certain components (e.g., Ribbon, order of cards in overview, order of badges and banners).
• Fallback Logic: If custom data is not set, default UI behavior ensures deals are still fully functional, maintaining a consistent fallback display.

Understanding Promotions & Campaigns

What are Promotions?

Promotions are discounts or special offers that are applied automatically once their specific conditions—such as minimum order value (MOV), product combinations, or item quantity—are met. They are typically linked via a shared product attributeId and include additional configuration options through a nested customData object.

What are Campaigns?

Campaigns, on the other hand, are not condition-dependent and apply automatically to eligible products. They are structured differently from Promotions, with their customizable fields located at the top level of the campaign object, rather than being nested inside a customData object.

Promotions vs. Campaigns: Key Differences

Although Promotions and Campaigns are managed separately within the SCAYLE ecosystem, users experience them uniformly as "Deals" in the Storefront Application. The following table highlights their key distinctions:

Configuring Your Deals (SCAYLE Panel & API)

Supported SCAYLE Panel Deal Types

The Storefront Application supports the following deal types, configurable in the SCAYLE Panel:

• Advanced Discount
• Automated Discount
• Item Discount
• Buy X Get Y
• Flash Sales
• Promotion Code
• Price Campaigns
• Tiered Discount

Promotions and Campaigns API

Promotions and campaigns can be created and updated through:

• The SCAYLE Panel
• The Promotion API endpoint /v1/promotions
• The Campaign API endpoint /v1/campaigns

For technical details and payload structure, refer to the Developer Guide or contact your SCAYLE representative.

Data Structure

Promotion Data

Each promotion can include a customData object within its payload, allowing fine-grained customization. This object supports advanced UI configurations, such as custom colors, countdown display, sublines, condition descriptions, and links. You can read more about customData fields and their usage in our Configuration Guideline.

Here’s the expected TypeScript declaration:

ts

Copy

Campaign Data

Campaigns share most of the same attributes as Promotions, but they are structured differently. In Campaigns, these attributes are placed at the top level of the object, rather than being nested inside a customData object as in Promotions.

typescript

Copy

Linking Deals to Products

Linking Promotions to Products

To connect a promotion to a product, both must share a common identifier—promotion attributeId. You can learn how to configure this attributeId in the Configuration Guideline.

Once the promotion attribute is enabled on the product, you can retrieve the ID like this:

ts

Copy

This ID must match promotion.customData.product.attributeId. If the promotion attribute is missing from a product, the promotion components won’t appear on PLP or PDP—but will still be displayed in the Basket, as basket items always include promotion data.

Linking Campaigns to Products

The price property of a product indicates whether a campaign has been applied. This property can be accessed from basket items, product variants, or the product itself. It doesn't require any additional configuration, e.g. by using attributes in SCAYLE Panel.

Within price, the appliedReductions array lists all applied reductions on the product. Each reduction includes a category field. If one of the reductions has the category campaign, it means the product is part of a Campaign deal.

Copy

const price = computed(() => { if (basketItem.value) { return basketItem.value.price.unit as Price } else if (activeVariant.value) { return activeVariant.value.price } return product.value?.priceRange?.min as Price }) const hasCampaignReduction = (price?: Price) => { return price?.appliedReductions.find( (reduction) => reduction.category === 'campaign', ) }

How Deals are Applied (Basket Logic)

Applying Promotions

When a basket is updated, promotions are not automatically applied. The useApplyPromotions composable must be used after a product is added, removed, or updated in the basket to trigger promotion recalculation.

Copy

• Internal Logic: The useApplyPromotions composable will take the first promotion from basket.applicablePromotions with an itemId and apply it to the first basket item without a promotion whose key matches the itemId. This process repeats until no more promotions can be applied.

Applying Campaigns

Campaigns do not require manual application. They are automatically applied and reflected in product price data. The price.appliedReductions array contains all discounts, and if one has a category of "campaign," it means a campaign deal is active on that product.

Important Considerations for Applying Campaigns & Promotions

• Single Deal Per Item: A product can have at most one promotion and one campaign applied at the same time. If multiple promotions are eligible, the one with the highest priority (the lowest numerical value) will be applied.
• Campaigns Limit: Campaigns are currently limited to one active campaign per shop.
• Item-Level Deals: SCAYLE currently does not support order-level deals. All discounts are applied at the item level.

UI Components: How Deals are Communicated

Deals are communicated via dedicated UI components throughout the user journey. These components have fallback designs when no custom data is provided.

Deals Overview (Flyout)

Located under the “Deals” navigation icon, this flyout shows all active promotions and campaigns. Each deal is displayed as a card with its name, countdown timer, optional progress bar for MOV/tiered discounts, conditions, and a link to eligible products. Campaigns will be displayed first in the overview, followed by Promotions sorted by highest priority. If no deals are active, users are informed that they can check back later.

Behavior

• Default: Displays deal name with default colors.
• Customized: Displays a custom message (headline/subline), conditions (condition) and colors from the deal's data. Cards become clickable if a link is provided.

Ribbon

Displayed globally across all pages (except the Basket page and Checkout funnel), the Ribbon highlights the most important deal. If a campaign is active, it will be shown first. If no campaign is set, the highest-priority promotion will be displayed.

Prioritization Customization

If it's not desired to always show the campaign first, the first condition in the following snippet, found in the default.vue layout, can be removed or moved. This will prevent campaigns from being prioritized over promotions in the display logic.

typescript

Copy

Behavior

• Default: Uses default colors and includes only the deal name.
• Customized: Displays a custom message (headline/subline) and colors from the deal's data. The ribbon becomes clickable if a link is provided.

Banner

The banner appears on PDPs and, for MOV/tiered discounts, in the Basket. It provides a real-time, unified view of progress toward a deal. While similar in appearance to the overview card, the banner does not include full deal conditions.

• On PDP: The banner is always displayed for campaigns. For promotions, it's shown on the PDP under two conditions:
  • The product has a promotion attribute with a value that matches the attributeId specified in the promotion's customData.
  • Alternatively, the promotion banner is displayed only when a specific product variant (e.g., size) that is already in the basket is selected on the PDP.
• On Basket: Only the MOV promotion banner is displayed, providing real-time feedback on progress toward a discount. A single, unified component is used to display both MOV promotions and Tiered Discounts.

Behavior

• Default: Uses default colors and includes only the deal name.
• Customized: Uses colors from promotion/campaign data, displays custom headlines/sublines, and becomes clickable if a link is provided.

MOV Promotion Banner Variants Based on Progress

The banner dynamically updates its copy and progress bar depending on the promotion state:

• The required amount hasn’t been met (a single MOV threshold or the first tier in a tiered discount): Shows how much more the user needs to spend to unlock the benefit.
  • Unlock your next deal! Spend {remaining_amount} more to activate this offer.

  

• The required amount has been met:
  • First Tier / MOV reached: Confirms that the deal is unlocked and highlights the benefit achieved. It also encourages further shopping for more savings.
    • Nice work! You've unlocked a deal and saved {savings_amount}. Keep shopping to unlock even more.

    

  • Last Tier or Final MOV reached: Confirms the highest benefit has been unlocked.
    • Great job! You’ve unlocked the full deal and saved {savings_amount}.

    

• MOV reached, but no eligible promotion product in cart: Informs the user they need to add a specific promotion product.
  • Almost there! You’ve met the minimum spend—now just add eligible products to your cart to enjoy the offer.

  

Badge

The badge is a small visual label displayed on product cards to indicate an ongoing deal. It is shown on PLPs and Basket product cards. If both a campaign and a promotion are applied to the same product, two badges are displayed.

Behavior

• Default: Uses default colors and displays a generic label.
• Customized: Uses custom colors and a custom label from the deal's data.

Discount

Deal discounts are shown alongside price details to reflect savings. These appear on both the PDP and in the Basket.

• For Campaigns: The discount is always visible.
• For Promotions (On PDP): The discount is displayed on the PDP under two conditions:
  • The product has a promotion attribute with a value that matches the attributeId specified in the promotion's customData.
  • Alternatively, the promotion discount is displayed only when a specific product variant (e.g., size) that is already in the basket is selected on the PDP.
• For Promotions (On Basket): The discount is always shown.

Behavior

• Default: Uses default colors.
• Customized: Uses custom colors from the promotion/campaign data.

Deals Price Summary (Discounts)

Located in the Basket's price breakdown area, the Deals Price Summary shows the total savings from all active promotions and campaigns. It uses an accordion layout to show overall savings when collapsed and a breakdown of savings by individual deals when expanded.

Behavior

• Default: Uses default colors and displays the deal name.
• Customized: Displays custom colors and the custom name from the deal's data.

Gift Collection

The Gift Collection component is used exclusively for Buy X, Get Y promotion types. It showcases eligible gift items and is shown on both the PDP and the Basket.

• On PDP: The collection is displayed on the PDP under two conditions:
  • The product has a promotion attribute with a value that matches the attributeId specified in the promotion's customData.
  • A product variant is already in the basket.
• On Basket: The collection appears above the product list. If a user adds a gift product while all promotion conditions are satisfied:
  • The product is labeled as "free".
  • A discount is applied automatically.

If a qualifying promotion product is removed from the basket, the gift product will convert into a regular, paid item.

Behavior

• Default: Uses default promotion colors.
• Customized: Uses custom colors from the promotion's customData.

Sold-Out Variants of Free Products

Sold-out variants remain visible on the PDP and Basket to ensure users are informed of all available options.

• These variants are not filtered out or hidden.
• If all variants of a product are sold out, the product is labeled as “sold-out.”

Promotion Codes

The Promotion Codes section allows users to enter, apply, and manage discount codes directly on the Basket page, providing greater control and immediate feedback. This section is placed below the "Go to Checkout" button.

• Input & Submission: Users can enter a code into a dedicated field and submit via the “Plus” button or by pressing Enter.
• Validation:
  • Success: The input clears, a success notification appears, and the code displays as a chip (e.g., SUMMER20 [X]). Long codes are truncated with an ellipsis.
  • Error: The input clears, and an error notification is shown.
• Multiple Codes: Users can enter multiple valid codes, each shown as a separate chip.
• Removal: Codes can be removed via the "X" on the chip. On failure, an error notification appears.

Configuring Your Deals

To explore all available options for configuring your promotions and campaigns—including setup steps, custom data fields, and product linking—please refer to our Configuration Guide.