What It Is
A trigger billable item is a special type that defines a condition-driven charge. Unlike one-off items (added to invoices) or recurring items (added to subscription plans), trigger items define when and how a charge fires based on a condition being met.
Every trigger item has two core settings: a trigger mode that determines how the condition and amount work, and a capture mode that determines how payment is collected.
The trigger-specific fields include `bi_trigger_mode`, `bi_capture_mode`, `bi_trigger_condition`, `bi_trigger_threshold`, `bi_trigger_floor`, `bi_allow_amount_override`, `bi_max_capture_amount`, and `bi_trigger_description`. These fields only appear when `bi_billing_type` is set to `trigger`.
Why It Matters
The trigger billable item is where you define your billing logic. Instead of writing custom code to decide when to charge, how much, and how to collect payment, you configure it once on the item. Every time the trigger fires, Edge enforces the rules: amount limits, capture mode, condition validation, cooldown windows.
Your billing rules live in your billing system, not scattered across application code. And the API Sample panel means you can copy the exact integration code right from the item detail page.
How It Works
There are four trigger modes, each with different behavior.
Fixed mode locks both amount and threshold at creation. The fire call only needs `billable_item_id` and `billing_customer_id`. Edge checks the condition and charges the preset amount. Example: wallet topup at $200 when balance <= $15.
Variable mode locks the threshold but accepts the amount at fire time via `override_amount`. The charge is capped by `max_capture_amount`. Example: retainer billing at variable hours multiplied by rate.
Event mode has no threshold and fires on demand. The amount can optionally be overridden. Example: milestone billing at $5,000 per deliverable.
Threshold mode locks the amount but accepts a `metric_value` from the caller. Edge evaluates the condition against the provided metric. Example: API overage at $50 when calls >= 10,000.
Capture modes determine how payment is collected. off_session charges the stored payment method immediately — no client interaction needed. client_confirm creates an invoice with a Pay Now link, requiring the client to review and approve the charge.
After saving a trigger item, an API Sample panel appears showing the exact API call to fire the trigger, pre-filled with the `billable_item_id` and the relevant parameters for the selected trigger mode.
Trigger Modes Compared
| Mode | Amount Set By | Threshold | Override Allowed | Best For |
|---|---|---|---|---|
| Fixed | Creator | Required | No | Wallet topup, metered SaaS |
| Variable | Caller at fire time | Required | Yes (amount) | Retainer billing, variable milestones |
| Event | Caller or default | None | Yes (amount + description) | Milestone billing, demand charges |
| Threshold | Creator | Required | No (metric only) | External platforms with own metrics |
Examples
SaaS wallet topup
Fixed mode, off_session capture, condition lte, threshold $15, amount $200. The platform detects a low wallet balance, fires the trigger via the API, and Edge charges $200 to the stored payment method automatically.
Agency milestone billing
Event mode, client_confirm capture, default amount $3,000. When the project manager completes a phase, they fire the trigger from the Edge UI. The client receives an invoice with a Pay Now link to review and approve the charge.
Consulting retainer
Variable mode, off_session capture, condition gte, threshold 20 hours, default $2,000, max capture $15,000. The consulting firm fires the trigger with an override_amount calculated from actual hours worked. Edge validates the amount is within the cap and charges the stored payment method.
