Balance System Explained

Overview

The TAMradar balance system manages all billing for your radars in real USD. This document explains how balance is deducted, when refunds occur, and how to handle balance-related webhooks in your application.

How Balance Works

Cost per Radar – Each radar type has a customer-specific USD price.
Billing Cycle
- Initial charge – Deducted when the radar is first created.
- Recurring charge – Deducted automatically every 30 days while the radar is active.
Automatic Management – If your balance cannot cover a charge, TAMradar pauses the radar and returns an INSUFFICIENT_FUNDS error.

Radar Lifecycle & Balance Impact

Radar States

Radars switch between two billing-relevant states:

State	Billing Behaviour
`active`	Deducts USD balance on creation and every 30 days
`inactive`	No balance deducted

Reasons for Inactive State

Manual deactivation by the user
Insufficient balance
Setup / configuration issues
Missing prerequisites (e.g., no public data to track)

Balance Refunds

A full refund is automatically applied when:

A radar fails during initial setup
Required prerequisites (social accounts, RSS feeds, etc.) are missing
Configuration issues prevent normal operation

Monitoring Balance Events

Webhook Notifications

Your application receives webhook events whenever balance is affected.

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "radar_failure",
  "record_id": null, 
  "discovered_at": "2025-03-20T14:10:38Z",
  "data": {
    "radar_id": "54e32291-25a4-459f-8bd6-4f79489ea931",
		"radar_type": "new_hires",
    "domain": "example.com",
    "next_charge_at": null,
    "custom_fields": {
      "department": "engineering"
    }
  },
  "content": {
    "failure_reason": "setup_failure",
    "refund_amount_usd": 0.15,
    "message": "Radar creation failed during setup. Balance has been refunded."
  }
}

Understanding Failure Reasons

Failure Reason	Description	Action Needed
`missing_prerequisites`	Required accounts or data sources not found	Verify the company has public profiles that can be monitored
`setup_failure`	Generic failure during radar creation/initialisation	Contact support for assistance
`insufficient_funds`	User has insufficient balance for radar creation	Add credits to account and retry

Refund Timing

Refunds are typically processed within 24 hours of failure detection. When processed, you receive a radar_failure webhook with refund_amount_usd.

Best Practices for Developers

Monitor balance – Alert your team when balance_remaining_usd (from GET /v1/account) drops below your comfort threshold.
Handle webhooks – Process and persist radar status / refund events for reconciliation.
Graceful degradation – Design your UI and workflows to handle INSUFFICIENT_FUNDS and paused radars.
Retain webhook data – Store webhook payloads for auditing and troubleshooting.
Top-up proactively – Schedule automatic top-ups or budget approvals so radars never pause unexpectedly.