Credits & Plan API

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

1. Get Credit Balance

Retrieve the aggregated credit balance (plan credits + Pay As You Go), current tier plan, and plan 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 plan, 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 plan's credits expire — the 30-day validity of a web purchase, or the Android subscription period. Null on the free plan.

2. Check Plan Renewal / Expiry

Trigger a verification check against the active plan. If the plan's expiration date has passed (the 30-day validity of a web purchase, or an Android subscription period), 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": The plan is active, or the user is already on the free tier.
  • "subscription_expired_reset_to_free": Plan expiry 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.