Billable Item Field Reference
Complete field definitions for all billable item types
This reference documents every field on a billable item record, including the trigger-specific fields that appear when bi_billing_type is set to trigger.
Standard Fields (All Billing Types)
bi_name
string
required
Display name shown on invoices and in the UI
bi_description
text
optional
Detailed description of the product or service
bi_unit_price
decimal
required
Base price per unit. For trigger items, this is the default charge amount
bi_currency
string
required
Three-letter currency code
Default: USD
bi_taxable
boolean
optional
Whether tax applies to this item
Default:
bi_tax_included
boolean
optional
Whether bi_unit_price includes tax
Default:
bi_item_type
enum
optional
virtual or physical. Trigger items are always virtual
Default: virtual
bi_billing_type
enum
required
one-off, recurring, or trigger. Determines which additional fields are available
Default: one-off
bi_payment_channel
enum
required
all, credit-card, invoice, or trigger-api
Default: all
bi_status
boolean
required
Whether the item is active. Inactive items cannot be used in new invoices or enrollments
Default: 1
Trigger-Specific Fields (bi_billing_type = trigger only)
bi_trigger_mode
enum
required
fixed, variable, event, or threshold. Determines how amount and condition interact
bi_capture_mode
enum
required
off_session (charge immediately) or client_confirm (send invoice with Pay Now)
Default: off_session
bi_trigger_condition
enum
required
lte (<=), gte (>=), or eq (=). Required for fixed, variable, and threshold modes
bi_trigger_threshold
decimal
required
The Y value in the condition check. Required for fixed, variable, and threshold modes
bi_trigger_floor
decimal
optional
Hard minimum for threshold, enforced by platform. Cannot exceed bi_trigger_threshold
bi_allow_amount_override
boolean
required
If true, fire endpoint accepts override_amount. Required to be true for variable and event modes
Default:
bi_max_capture_amount
decimal
optional
Upper limit on override_amount. Null means platform default ($500)
bi_trigger_description
string
optional
Human-readable condition description. Auto-generated but editable. Example: When wallet balance <= $15, charge $200
Important: Trigger fields are only validated and saved when bi_billing_type is set to trigger. For one-off and recurring items, these fields are ignored even if present in the API request.
