Vanilo 6.0 Released.See what's new
WARNING! You're browsing the documentation of the upcoming version of Vanilo. It may contain unreleased features and changes, or even features that will not be present in the next release as described here. The latest stable version is 6.x
On this page
Components Promotions
5 min read

Promotions

Promotions are a powerful feature in Vanilo Cloud that allows you to create various types of discounts and special offers for shoppers.

Core Concepts

A promotion consists of:

  • Basic properties (name, description, validity period, etc.)
  • Rules that determine in what conditions the promotion applies
  • Actions that define what the promotion does
  • Coupon codes (optional) that can be used to activate the promotion

Promotion Properties

$promotion = Promotion::create([
    'name' => 'Summer Sale',
    'description' => 'Special summer discount',
    'priority' => 1,
    'is_exclusive' => false,
    'usage_limit' => 100,
    'usage_count' => 0,
    'is_coupon_based' => false,
    'starts_at' => '2025-06-01 00:00:00',
    'ends_at' => '2025-08-31 23:59:59',
    'applies_to_discounted' => true
]);

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 starts_at is set)
  • It hasn't expired (if ends_at is set)
  • It hasn't reached its usage limit (if usage_limit is set)

If neither start date, end date and usage limit is set, the promotion is considered valid indefinitely.

Rules

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

To add rules to a promotion, use the addRule method:

$promotion->addRule('cart_quantity', ['count' => 3]);
$promotion->addRule('cart_minimum_value', ['amount' => 100]);

The first parameter is the rule type, and the second is the rule configuration.

The rule type can be either the ID or the class name of a registered rule type.

Cart Quantity Rule Type

This rule checks if the cart contains a minimum number of items, like "Buy 3 or more items".

The configuration is as follows:

{
    "count": 3
}

The above configuration means "Buy 3 or more items to qualify", where count is the minimum number of items required in the cart.

Cart Minimum Value Rule

This rule checks if the cart total reaches a minimum amount.

Configuration example: "Spend $100 or more to qualify":

{
    "amount": 100
}

Actions

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

To add actions to a promotion, use the addAction method:

$promotion->addAction('cart_fixed_discount', ['amount' => 10]);
$promotion->addAction('cart_percentage_discount', ['percentage' => 20]);

The first parameter is the action type, and the second is the action configuration.

The action type can be either the ID or the class name of a registered action type.

Cart Fixed Discount

Applies a fixed amount discount to the entire cart (items only, excluding shipping fees).

Sample configuration, "$10 off your order":

{
   "amount": 10
}
  • amount: Fixed discount amount to apply
  • Example: "$10 off your order"

Cart Percentage Discount

Applies a percentage discount to the cart, like "20% off your order".

It takes a single configuration property, the percentage, which is the discount percentage to apply.

Example "20% off your order":

{
    "percentage": 20
}

Staggered Discount

Applies different discounts on individual cart items, based on the quantity of each line item.

The configuration takes a single thresholds property, which is an object mapping cart quantity thresholds to discount percentages.

Example "Buy 10 get 5% off, 20 to get 7% off; 30 get 10% off":

{
   "thresholds": {
      "10": 5,
      "20": 7,
      "30": 10
   }
}

Coupons

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

$coupon = Coupon::create([
    'code' => 'SUMMER2025',
    'promotion_id' => $promotion->id,
    'usage_limit' => 50,
    'per_customer_usage_limit' => 1,
    'usage_count' => 0,
    'expires_at' => '2025-08-31 23:59:59'
]);

It is possible to directly look up a promotion based on the coupon code:

$promotion = Promotion::findByCouponCode('SUMMER2025');

Coupon Properties

  • Code: The unique code customers enter
  • Usage Limit: Maximum number of times the coupon can be used
  • Per Customer Limit: Maximum number of times a single 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

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

Extending the System

Adding New Rule Types

  1. Create a new rule class implementing PromotionRuleType interface
  2. Register the rule type in your application's AppServiceProvider class.
class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        PromotionRuleTypes::register('new_rule_type', NewRuleType::class);
    }
}

Adding New Action Types

  1. Create a new action class implementing PromotionActionType interface
  2. Register the action type in your application's AppServiceProvider class.
class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        PromotionActionTypes::register('new_action_type', NewActionType::class);
    }
}
Next in Components Translations