Credits & Subscription API

Retrieve user credit totals, plan types, and trigger automated subscription renewal checks.

1. Get Credit Balance

Retrieve the aggregated credit balance (monthly subscription + Pay As You Go), current tier plan, and subscription expiration date.

Endpoint

GET /api/v1/user/credits

Request Headers

Authorization: Bearer sona_sk_your_api_key_here

Response (200 OK)

{
  "credits": 105000,
  "payg_credits": 3000,
  "plan": "pro",
  "expiresAt": "2026-07-10T12:00:00.000Z"
}

• credits: Total available credit balance (sum of subscription, payg, and free credits).
• payg_credits: The portion of credits purchased via Pay As You Go packs.
• plan: The active plan tier name (free, pro, or max).
• expiresAt: ISO date timestamp when the current subscription tier expires. Null if not subscribed.

2. Check Subscription Renewal

Trigger a verification check against active subscriptions. If a user's subscription expiration date has passed, the server automatically demotes the account to the free tier and resets their credits to the free baseline allowance.

Endpoint

POST /api/v1/user/subscription/check-renewal

Request Headers

Authorization: Bearer sona_sk_your_api_key_here

Response (200 OK)

{
  "action": "subscription_expired_reset_to_free",
  "credits": 10000,
  "plan": "free",
  "expiresAt": null
}

• action: The billing migration action executed during the check:
  • "none": Subscription is active, or the user is already on the free tier.
  • "subscription_expired_reset_to_free": Expiration time was exceeded, user has been demoted, and credits reset to the free allocation (10,000).
• credits: Up-to-date total credits post-evaluation.
• plan: Current plan tier name.
• expiresAt: Current expiration timestamp.