Balance and Pricing

• Monthly Subscription Billing
• Update-Based Billing

​

Overview

​

Pricing Models

​

Monthly Subscription

• Charge at creation — balance is deducted when the radar is first created.
• Recurring charge — deducted automatically every 30 days while the radar is active. next_charge_at in the API response shows the next billing date.
• Refund on setup failure — if the radar fails during initial setup (missing prerequisites, source inaccessible), the creation charge is automatically reversed and you receive a radar_failure webhook with refund_amount_usd > 0.
• User cancellation — radar transitions to inactive. For monthly subscription, service can continue until the current billing period ends.

​

Update-Based

• No charge at creation — next_charge_at is null. Nothing is deducted when the radar is set up.
• Charged per update found — balance is deducted each time TAMradar finds and approves a new update for your radar (a new hire, job change, funding round, etc.).
• No refund on setup failure — if the radar fails during setup, you receive a radar_failure webhook with refund_amount_usd: 0 (nothing was charged, so nothing to refund).
• Auto-reactivation on top-up — if a radar was deactivated due to insufficient funds, it automatically reactivates when a new payment is added to your account. No manual action needed.

​

Radar States

• radar_status (active / inactive)
• radar_failure payload fields: code, message, and refund_amount_usd

​

Monitoring Balance Events

​

Webhook Notifications

{
  "update_id": "550e8400-e29b-41d4-a716-446655440000",
  "update_type": "radar_failure",
  "record_id": null,
  "discovered_at": "2025-03-20T14:10:38Z",
  "completed_at": "2025-03-20T14:10:38Z",
  "data": {
    "radar_id": "54e32291-25a4-459f-8bd6-4f79489ea931",
    "radar_type": "company_new_hires",
    "domain": "example.com",
    "next_charge_at": null,
    "custom_fields": {}
  },
  "status": "error",
  "code": 402,
  "message": "Your radar was deactivated due to insufficient funds. Please add more credits to reactivate.",
  "errors": [{ "field": "radar", "reason": "insufficient_funds" }],
  "refund_amount_usd": 0,
  "timestamp": "2025-03-20T14:10:38Z",
  "error_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "update_id": "41991828-ed31-4bd9-98d2-44b2763f9f35",
  "update_type": "radar_failure",
  "record_id": null,
  "discovered_at": "2025-03-20T08:30:00Z",
  "completed_at": "2025-03-20T08:30:00Z",
  "data": {
    "radar_id": "c70813b3-7e87-4ca7-90fd-8c64574d911b",
    "radar_type": "industry_job_openings",
    "domain": null,
    "next_charge_at": null,
    "custom_fields": {}
  },
  "status": "error",
  "code": 400,
  "message": "Radar creation failed: missing prerequisites.",
  "errors": [{ "field": "radar", "reason": "missing_prerequisites" }],
  "refund_amount_usd": 0.10,
  "timestamp": "2025-03-20T08:30:00Z",
  "error_id": "41991828-ed31-4bd9-98d2-44b2763f9f35"
}

{
  "update_id": "72bc9a00-1234-4abc-b000-aabbccddeeff",
  "update_type": "radar_failure",
  "record_id": null,
  "discovered_at": "2025-03-21T10:00:00Z",
  "completed_at": "2025-03-21T10:00:00Z",
  "data": {
    "radar_id": "a1b2c3d4-0000-0000-0000-000000000001",
    "radar_type": "contact_job_changes",
    "domain": "example.com",
    "next_charge_at": null,
    "custom_fields": {}
  },
  "status": "error",
  "code": 400,
  "message": "Radar creation failed: missing prerequisites.",
  "errors": [{ "field": "radar", "reason": "missing_prerequisites" }],
  "refund_amount_usd": 0,
  "timestamp": "2025-03-21T10:00:00Z",
  "error_id": "72bc9a00-1234-4abc-b000-aabbccddeeff"
}

​

Failure Reasons

​

Bulk Endpoint — Async Outcomes

• the affected item ends in a failure state during async processing
• the failure appears in:
  • GET /v1/radars/bulk/:bulk_id item results, and
  • webhook delivery (radar_failure for item-level failures, plus final bulk_completed)

​

Best Practices

1. Monitor balance — poll GET /v1/account for balance_remaining_usd and alert before it hits zero.
2. Handle radar_failure webhooks — persist code, message, and refund_amount_usd for reconciliation.
3. Update-based: top up proactively — radars auto-reactivate on top-up, but there’s a gap while they’re inactive. Schedule automatic top-ups to avoid missed updates.
4. Monthly subscription: budget for renewals — check next_charge_at on your active radars and ensure balance covers the next 30 days.
5. Bulk retries are workflow-based — top up balance, then resubmit the failed items from your async bulk status/webhook outcomes.