Trigger Modes Explained
How the four trigger modes handle amounts, conditions, and overrides
What It Is
Every trigger billable item has a trigger mode that determines how the charge amount and condition work together.
Fixed locks both the charge amount and threshold at creation. When the trigger fires, Edge checks the condition and charges the pre-set amount. Nothing varies. Simplest mode.
Variable locks the threshold but lets the caller pass the charge amount at fire time via override_amount. The condition still must be met, but the charge depends on what happened (hours worked, materials used).
Event has no threshold. It fires on demand whenever you or your system decides. Amount can optionally be overridden. Pure demand-driven billing.
Threshold locks the charge amount but lets the caller pass the metric value. Edge evaluates the condition using the caller's metric against the item's threshold. For platforms that track their own metrics.
Why It Matters
Choosing the right mode determines control at fire time vs creation time. Fixed is hands-off. Variable and Event give flexibility. Threshold pushes metric evaluation to Edge.
A wallet topup should be Fixed (same amount every time). A retainer bill should be Variable (amount depends on work done). A milestone charge should be Event (no threshold, fire when delivered). An API overage should be Threshold (platform tracks calls, Edge bills).
How It Works
Each mode at fire time:
Fixed: Fire call sends billable_item_id and billing_customer_id only. Edge reads amount and condition from the item. If condition met, charges the pre-set amount. Override parameters rejected.
Variable: Fire call adds override_amount. Edge checks threshold. If met, charges the override amount (capped by bi_max_capture_amount). Requires bi_allow_amount_override = 1.
Event: Fire call optionally includes override_amount and override_description. No condition check. Charges immediately or sends invoice. Most flexible mode.
Threshold: Fire call adds metric_value. Edge evaluates: is metric_value [condition] bi_trigger_threshold? If yes, charges bi_unit_price. Caller tracks the metric, Edge makes the billing decision.
Trigger Modes Compared
| Mode | Set at Creation | Passed at Fire Time | Condition Check | Best For |
|---|---|---|---|---|
| Fixed | Amount + threshold + condition | Nothing (just IDs) | Yes | Wallet topup, metered SaaS |
| Variable | Threshold + condition + max capture | override_amount | Yes | Retainer billing, variable milestones |
| Event | Optional default amount + max capture | Optional amount + description | No | Milestone billing, demand charges |
| Threshold | Amount + threshold + condition | metric_value | Yes (caller's metric) | External platforms with own metrics |
Examples
Fixed — Wallet auto-topup
Item amount=$200, condition=lte, threshold=$15. Balance hits $12. Fire trigger. Edge checks $12 <= $15, charges $200.
Variable — Monthly retainer
Item condition=gte, threshold=1, max_capture=$10,000. Firm logs 47 hours at $150/hr. Fires with override_amount=$7,050. Edge charges $7,050.
Event — Project milestone
Item default $5,000. PM fires with override_description="Phase 2: UI mockups". No condition. Edge sends invoice.
Threshold — API usage
Item amount=$50, condition=gte, threshold=10000. Platform fires with metric_value=10247. Edge evaluates 10,247 >= 10,000 = true, charges $50.
