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.00order_value: Dollar amount. Example: 5000 = $5,000.00- The tool calculates
discount_percentageinternally 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
}
}