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.2 }],
      },
      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.1 },
        ],
      },
      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.

Note on units:

  • discount_amount: Integer in minor currency units (cents). Example: 100000 = $1,000.00
  • order_value: Dollar amount. Example: 5000 = $5,000.00
  • The tool calculates discount_percentage internally as: discount_amount / (order_value * 100)

In this example, 100000 / (5000 * 100) = 0.20 (20% discount):

{
  "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