Fire Trigger

The core Edge billing primitive — charge a customer when a condition is met

POST /public/edge/fire

Fires a trigger charge against a billing customer for a specific trigger billable item. Validates the enrollment, checks idempotency (60s cooldown), and branches to off_session (immediate charge) or client_confirm (invoice creation). Returns the charge result with status, amount, and gateway reference.

Requires a valid `api_key` in the JSON request body

Parameters

Name	In	Type	Required	Description
`api_key`	body	`string`	Yes	Your Zyntro API key
`org_id`	body	`string`	Yes	Your organization UUID
`brand_id`	body	`string`	Yes	Your brand ID
`billable_item_id`	body	`string`	Yes	The trigger billable item to fire
`billing_customer_id`	body	`string`	Yes	The billing customer to charge
`override_amount`	body	`float`	No	Custom charge amount. Only accepted when the billable item has `bi_allow_amount_override = 1`. Capped by `bi_max_capture_amount`.
`override_description`	body	`string`	No	Custom charge description. Used with variable and event trigger modes.
`metric_value`	body	`float`	No	Current metric value for threshold mode. Edge evaluates this against the item's `bi_trigger_threshold` using the configured condition operator.

Code Samples

bash

curl -X POST https://app.zyntrohq.com/apis/public/edge/fire.php \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_api_key",
    "org_id": "org_xxx",
    "brand_id": "1",
    "billable_item_id": "bi_xxx",
    "billing_customer_id": "bc_xxx"
  }'

Response

200 Charge captured (off_session success)

json

{
    "data": {
        "amount": 200,
        "status": "captured",
        "gateway": "stripe",
        "success": true,
        "currency": "USD",
        "charge_id": "sc_xxx",
        "invoice_id": "inv_xxx",
        "captured_at": "2026-03-30T10:22:00Z",
        "gateway_ref": "pi_xxx"
    },
    "status": "success"
}

200 Pending client action (client_confirm)

json

{
    "data": {
        "amount": 1500,
        "status": "pending_client_action",
        "success": true,
        "charge_id": "sc_xxx",
        "invoice_id": "inv_xxx",
        "pay_now_sent_to": "[email protected]"
    },
    "status": "success"
}

200 Charge failed

json

{
    "data": {
        "status": "failed",
        "success": false,
        "charge_id": "sc_xxx",
        "decline_code": "insufficient_funds",
        "failure_reason": "Your card has insufficient funds.",
        "enrollment_status": "active",
        "consecutive_failures": 1
    },
    "status": "success"
}

Important: Idempotency: If the same `billing_customer_id` + `billable_item_id` fires within the cooldown window (default 60 seconds) and the previous charge is pending or succeeded, Edge returns the existing result instead of creating a new charge.

Errors

Code	Message	Resolution
`MISSING_PARAMS`	Required fields not provided	Include api_key, org_id, brand_id, billable_item_id, and billing_customer_id in the request body.
`INVALID_API_KEY`	Invalid API key	Check your API key is correct and your account is active.
`INACTIVE_ENROLLMENT`	No active enrollment for this customer and item	Enroll the billing customer in the trigger item first via /public/edge/enroll.
`COOLDOWN_ACTIVE`	Duplicate fire within cooldown window	Wait for the cooldown period (default 60s) or the previous charge to complete.

4 min read Updated Apr 4, 2026

Navigation

Fire Trigger

Parameters

Code Samples

Response

Errors