Promotions

Overview

Promotions are a powerful feature in the Vanilo E-commerce Platform that allows you to create various types of discounts and special offers for your shoppers.

The module offers a flexible system that is regulated by two main types of directives:

  • Promotion Rules: Conditions that determine when a promotion should be applied
  • Promotion Actions: The actual effects or benefits that are applied when the rules are met

Promotions can be created either manually in the Admin panel or programatically using the REST API

Promotions in Vanilo Admin

Core Concepts

A promotion consists of:

  • Basic properties (name, description, validity period, etc.)
  • Rules that determine when the promotion applies
  • Actions that define what the promotion does: effects or benefits that are applied
  • Optional coupon codes for activating a promotion

Promotion Properties

Each promotion has the following configurable properties:

  • Name: The display name of the promotion
  • Description: Detailed explanation of the promotion
  • Priority: Determines which promotion takes precedence when multiple promotions apply (higher number = higher priority)
  • Exclusive: When enabled, this promotion will be the only one applied to an order
  • Usage Limit: Maximum number of times the promotion can be used (optional)
  • Coupon Based: Whether the promotion requires a coupon code
  • Start Date: When the promotion becomes active (optional)
  • End Date: When the promotion expires (optional)
  • Applies to Discounted Items: Whether the promotion can be applied to items already on sale

Validity

A promotion is considered valid when:

  • It has started (if a start date is set)
  • It hasn't expired (if an end date is set)
  • It hasn't reached its usage limit (if a limit is set)

Rules

Rules determine in which conditions a promotion applies. Each rule must pass for the promotion to be eligible. Multiple rules can be combined, and all must be satisfied.

Cart Quantity Rule

Checks if the cart contains a minimum number of items.

Example: "Buy 3 or more items"

Configuration:

{
    "count": 3
}
  • count: The minimum number of items required in the cart

Cart Minimum Value Rule

Checks if the cart total reaches a minimum amount.

Example: "Spend $100 or more"

Configuration:

{
    "amount": 100
}
  • amount: The minimum cart total value required to qualify for the promotion

Actions

Actions define what happens when a promotion is applied. Multiple actions can be added to a single promotion.

Cart Fixed Discount

Applies a fixed amount discount to the entire cart.

Example: "$10 off your order"

Configuration:

{
    "amount": 10
}
  • amount: Fixed discount amount to apply

Cart Percentage Discount

Applies a percentage discount to the cart.

Example: "20% off your order"

Configuration:

{
    "percentage": 20
}
  • percentage: Discount percentage to apply

Staggered Discount

Applies different discounts to line items, based on cart quantity thresholds

Example: "Buy 10 get 5% off, buy 20 get 7% off, buy 50 get 10% off"

Configuration:

{
    "discount": {
        "10": 5,
        "20": 7,
        "50": 10
    }
}
  • discount: Object mapping cart item quantity value thresholds to discount percentages

The above configuration means:

When the ordered quantity is

  • 0-9 items: no discount;
  • 10-19 items: 5% discount;
  • 20-49 items: 7% discount;
  • 50+ items: 10% discount

is applied.

Coupons

Coupons are optional codes that can be associated with promotions. They provide additional control over promotion usage.

Promotion Coupons in Vanilo Admin Panel

Coupon Properties

  • Code: The unique code customers enter at the checkout.
  • Usage Limit: Maximum number of times the coupon can be used.
  • Per Customer Limit: Maximum number of times a single authenticated customer can use the coupon.
  • Expiration Date: When the coupon becomes invalid.

Using Coupons

Customers can enter coupon codes during checkout. The system will:

  1. Validate the coupon code
  2. Check if the promotion is still valid
  3. Verify all rules are satisfied
  4. Apply the promotion's actions if eligible

Best Practices

Priority Management
  • Use higher priority numbers for more important promotions
  • Set exclusive promotions carefully to avoid conflicts
Usage Limits
  • Set appropriate usage limits to control promotion costs
  • Consider per-customer limits for personalized offers
Validity Periods
  • Set clear start and end dates for time-sensitive promotions
  • Monitor usage to adjust limits if needed
Rule Combinations
  • Combine rules to create targeted promotions
  • Test rule combinations to ensure they work as intended
Action Stacking
  • Be mindful of how multiple actions interact
  • Consider the order of operations when combining different types of discounts