Billing events - Timely.ai

These events let you proactively monitor the workspace’s financial status — receive alerts before credits run out, be notified of plan changes, and track the trial cycle without having to check the dashboard manually.

Event list

Event	When it fires
`credit.low`	The credit balance falls below the configured alert threshold
`credit.depleted`	Credits reach zero — the workspace loses the ability to process messages
`plan.changed`	The workspace plan is changed (upgrade, downgrade, or cancellation)
`trial.expiring`	The trial period is 3 days from ending
`trial.expired`	The trial ended without converting to a paid plan

`credit.low`

When it fires

The workspace credit balance falls below the alert threshold configured in Settings → Billing. By default, the alert is triggered when less than 20% of the current cycle’s credits remain.

Payload

{
  "event": "credit.low",
  "event_id": "evt_01HX9A1K9MFQR4YZDNV7P9WCE",
  "timestamp": "2026-04-19T18:00:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "credits_remaining": 1850,
    "credits_total": 10000,
    "credits_used": 8150,
    "usage_percentage": 81.5,
    "alert_threshold_percentage": 80,
    "estimated_depletion_at": "2026-04-21T12:00:00Z",
    "billing_period_end": "2026-04-30T23:59:59Z",
    "plan_id": "plan_pro",
    "plan_name": "Pro"
  }
}

Key fields

Field	Type	Description
`credits_remaining`	integer	Credits still available
`credits_total`	integer	Total credits for the cycle
`credits_used`	integer	Credits consumed so far
`usage_percentage`	number	Usage percentage (0–100)
`alert_threshold_percentage`	number	Configured threshold that triggered the alert
`estimated_depletion_at`	string \| null	Estimated time when credits will reach zero, based on average consumption
`billing_period_end`	string	End date of the current billing period
`plan_id`	string	Current plan ID

Usage example

Use credit.low to trigger an automatic alert in Slack or WhatsApp for the billing manager before service is interrupted. The estimated_depletion_at field helps prioritize urgency.

`credit.depleted`

When it fires

The credit balance reaches zero. When this happens, the workspace enters restricted mode: the AI agent stops responding to new messages until credits are added or the billing cycle renews.

Payload

{
  "event": "credit.depleted",
  "event_id": "evt_01HX9B3M2PGTS6YADOV8Q1XDF",
  "timestamp": "2026-04-21T14:35:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "credits_remaining": 0,
    "credits_total": 10000,
    "credits_used": 10000,
    "billing_period_end": "2026-04-30T23:59:59Z",
    "plan_id": "plan_pro",
    "plan_name": "Pro",
    "service_status": "restricted",
    "depleted_at": "2026-04-21T14:35:00Z"
  }
}

Key fields

Field	Type	Description
`credits_remaining`	integer	Always `0` in this event
`service_status`	enum	`restricted` — the AI agent is paused
`depleted_at`	string	ISO 8601 timestamp of depletion

Usage example

credit.depleted is critical. When triggered, the AI agent stops responding — contacts may be left without support. Set up an automation that adds credits automatically or immediately notifies the person responsible for billing.

`plan.changed`

When it fires

The workspace plan is changed: upgrade to a higher plan, downgrade to a lower one, migration between same-tier plans, or subscription cancellation. Includes both the previous and new plans.

Payload

{
  "event": "plan.changed",
  "event_id": "evt_01HX9C5P4RHTW7ZBEPV9S2YEG",
  "timestamp": "2026-04-19T11:00:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "previous_plan_id": "plan_starter",
    "previous_plan_name": "Starter",
    "new_plan_id": "plan_pro",
    "new_plan_name": "Pro",
    "change_type": "upgrade",
    "effective_at": "2026-04-19T11:00:00Z",
    "billing_period_end": "2026-05-19T23:59:59Z",
    "changed_by": "usr_321"
  }
}

Key fields

Field	Type	Description
`previous_plan_id`	string	Previous plan ID
`previous_plan_name`	string	Previous plan name
`new_plan_id`	string	New plan ID
`new_plan_name`	string	New plan name
`change_type`	enum	`upgrade`, `downgrade`, `canceled`, `reactivated`
`effective_at`	string	When the change took effect
`changed_by`	string \| null	ID of the user who made the change

Usage example

Use plan.changed with change_type: "canceled" to trigger a retention flow — send a follow-up message or offer support before the customer fully stops using the platform.

`trial.expiring`

When it fires

The workspace’s trial period is 3 days from expiration and has not yet converted to a paid plan. This event fires only once per trial cycle.

Payload

{
  "event": "trial.expiring",
  "event_id": "evt_01HX9D7Q5SJUW8ZCFQWA3ZFH",
  "timestamp": "2026-04-17T09:00:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "trial_end_at": "2026-04-20T23:59:59Z",
    "days_remaining": 3,
    "plan_id": "plan_trial",
    "conversations_used": 142,
    "messages_used": 1834,
    "contacts_total": 87,
    "upgrade_url": "https://app.timelyai.com.br/billing/upgrade"
  }
}

Key fields

Field	Type	Description
`trial_end_at`	string	Trial expiration date/time
`days_remaining`	integer	Days remaining until the trial ends
`conversations_used`	integer	Total conversations opened during the trial
`messages_used`	integer	Total messages exchanged during the trial
`contacts_total`	integer	Total contacts in the workspace
`upgrade_url`	string	Direct link to the upgrade page

`trial.expired`

When it fires

The trial period ended without the workspace subscribing to a paid plan. After this date, the workspace enters read-only mode — no AI agents respond and new channels cannot be connected.

Payload

{
  "event": "trial.expired",
  "event_id": "evt_01HX9E9R6TKXV9ADGRXB4AGI",
  "timestamp": "2026-04-21T00:00:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "trial_end_at": "2026-04-20T23:59:59Z",
    "plan_id": "plan_trial",
    "service_status": "read_only",
    "conversations_used": 198,
    "messages_used": 2540,
    "contacts_total": 115,
    "upgrade_url": "https://app.timelyai.com.br/billing/upgrade",
    "expired_at": "2026-04-21T00:00:00Z"
  }
}

Key fields

Field	Type	Description
`service_status`	enum	`read_only` — the workspace is locked for operations
`conversations_used`	integer	Total conversations opened during the trial
`messages_used`	integer	Total messages during the trial
`expired_at`	string	ISO 8601 timestamp of expiration
`upgrade_url`	string	Direct link to the upgrade page

Usage example

If you are a Timely.ai partner or reseller managing multiple workspaces, use trial.expiring and trial.expired to automate conversion follow-ups. The conversations_used and messages_used fields show customer engagement during the trial — great data for personalizing your outreach.

Billing events are only sent to webhooks that have credit.*, plan.*, or trial.* events in their subscription list. Make sure to include those categories when creating the webhook if you want to receive these notifications.

​Event list

​credit.low

​When it fires

​Payload

​Key fields

​Usage example

​credit.depleted

​When it fires

​Payload

​Key fields

​Usage example

​plan.changed

​When it fires

​Payload

​Key fields

​Usage example

​trial.expiring

​When it fires

​Payload

​Key fields

​trial.expired

​When it fires

​Payload

​Key fields

​Usage example

Event list

`credit.low`

When it fires

Payload

Key fields

Usage example

`credit.depleted`

When it fires

Payload

Key fields

Usage example

`plan.changed`

When it fires

Payload

Key fields

Usage example

`trial.expiring`

When it fires

Payload

Key fields

`trial.expired`

When it fires

Payload

Key fields

Usage example