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 automatically deactivates the radar and sends a webhook notification.

---

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 (automatic deactivation with webhook notification)
• 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.

Radar failure due to insufficient balance/funds - When a radar fails because the user doesn't have enough funds to renew the monthly subscription.

JSON

{
  "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": "insufficient_funds",
    "refund_amount_usd": 0,
    "message": "Your radar was deactivated due to insufficient funds. Please add more credits to reactivate."
  }
}

Missing Prerequisites - When a radar fails because required data sources aren't available:

JSON

{
  "event_id": "41991828-ed31-4bd9-98d2-44b2763f9f35",
  "event_type": "radar_failure",
  "record_id": null,
  "discovered_at": "2025-03-20T08:30:00Z",
  "data": {
    "radar_id": "c70813b3-7e87-4ca7-90fd-8c64574d911b",
    "radar_type": "job_openings",
    "domain": "example.com",
    "next_charge_at": null,
    "custom_fields": {
      "priority": "high",
      "account_id": "0011U00000TFV7MQAX"
    }
  },
  "content": {
    "failure_reason": "missing_prerequisites",
    "refund_amount_usd": 5.00,
    "message": "Radar creation failed because the domain does not have required social media accounts. Credits have 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	Radar deactivated due to insufficient balance for recurring billing	Add credits to account to reactivate radar

Refund & Notification Timing

• Setup failure refunds are typically processed within 24 hours of failure detection. You receive a radar_failure webhook with refund_amount_usd.
• Insufficient funds notifications are sent immediately when a radar is deactivated during recurring billing (no refund - credits weren't charged).

---

Best Practices for Developers

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