guardrail-sim
byJeff Green

Promotional Limits

Time-based and volume-limited promotions

Promotional Limits

Control promotions with time windows, volume limits, and customer eligibility.

The Scenario

Black Friday promotion:

  • Up to 20% off for qualifying orders
  • Only for orders 100+ units
  • Maintain minimum 15% margin
  • Different tiers for different customer segments

The Policy

import { PolicyEngine } from '@guardrail-sim/policy-engine';
import type { Policy } from '@guardrail-sim/policy-engine';
 
const blackFridayPolicy: Policy = {
  id: 'black-friday-2026',
  name: 'Black Friday 2026 Policy',
  rules: [
    // Maximum promotional discount
    {
      name: 'promo_cap',
      conditions: {
        all: [
          { fact: 'proposed_discount', operator: 'greaterThan', value: 0.20 }
        ]
      },
      event: {
        type: 'violation',
        params: { message: 'Black Friday discount cannot exceed 20%' }
      },
      priority: 1
    },
    // Margin protection
    {
      name: 'margin_floor',
      conditions: {
        all: [
          { fact: 'calculated_margin', operator: 'lessThan', value: 0.15 }
        ]
      },
      event: {
        type: 'violation',
        params: { message: 'Discount would reduce margin below 15%' }
      },
      priority: 2
    },
    // Volume requirement for promotional pricing
    {
      name: 'volume_requirement',
      conditions: {
        all: [
          { fact: 'quantity', operator: 'lessThan', value: 100 },
          { fact: 'proposed_discount', operator: 'greaterThan', value: 0.10 }
        ]
      },
      event: {
        type: 'violation',
        params: { message: 'Promotional pricing requires 100+ unit orders' }
      },
      priority: 3
    },
    // Gold tier bonus
    {
      name: 'gold_tier_limit',
      conditions: {
        all: [
          { fact: 'customer_segment', operator: 'notEqual', value: 'gold' },
          { fact: 'customer_segment', operator: 'notEqual', value: 'platinum' },
          { fact: 'proposed_discount', operator: 'greaterThan', value: 0.15 }
        ]
      },
      event: {
        type: 'violation',
        params: { message: 'Discounts over 15% require Gold or Platinum tier' }
      },
      priority: 4
    }
  ]
};
 
const engine = new PolicyEngine(blackFridayPolicy);

Testing Customer Tiers

// Standard customer, small discount (allowed)
const result1 = await engine.evaluate(
  { order_value: 5000, quantity: 100, product_margin: 0.4, customer_segment: 'silver' },
  0.12
);
// result1.approved: true
 
// Standard customer, large discount (rejected)
const result2 = await engine.evaluate(
  { order_value: 5000, quantity: 100, product_margin: 0.4, customer_segment: 'silver' },
  0.18
);
// result2.approved: false
// result2.violations: [{ rule: 'gold_tier_limit', message: '...' }]
 
// Gold customer, large discount (allowed)
const result3 = await engine.evaluate(
  { order_value: 5000, quantity: 100, product_margin: 0.4, customer_segment: 'gold' },
  0.18
);
// result3.approved: true
 
// Anyone, excessive discount (rejected)
const result4 = await engine.evaluate(
  { order_value: 5000, quantity: 100, product_margin: 0.4, customer_segment: 'platinum' },
  0.25
);
// result4.approved: false
// result4.violations: [{ rule: 'promo_cap', message: '...' }]

Using with MCP

Validate promotional discounts before checkout:

{
  "name": "validate_discount_code",
  "arguments": {
    "code": "BF2026",
    "discount_amount": 100000,
    "order": {
      "order_value": 5000,
      "quantity": 150,
      "product_margin": 0.35
    }
  }
}

UCP Integration

The simulate_checkout_discount tool returns UCP-formatted allocations:

{
  "name": "simulate_checkout_discount",
  "arguments": {
    "codes": ["BF2026"],
    "line_items": [
      { "item": { "id": "SKU-001" }, "quantity": 100, "subtotal": { "amount": 300000, "currency": "USD" } },
      { "item": { "id": "SKU-002" }, "quantity": 50, "subtotal": { "amount": 200000, "currency": "USD" } }
    ],
    "currency": "USD",
    "discount_percentage": 0.15,
    "product_margin": 0.4
  }
}

On this page