Skip to main content
GET
/
billing
/
subscription
Get Subscription
curl --request GET \
  --url https://api.example.com/billing/subscription
{
  "plan": {},
  "status": {},
  "cancel_at_period_end": true,
  "current_period_end": {},
  "credits_remaining": 123,
  "credits_topup_balance": 123,
  "coupon_credits_balance": 123,
  "has_access": true
}
Returns the team’s current subscription — plan details, Stripe status, and credit balances (monthly, purchased top-ups, coupon). Agents can call this to check whether a team is billable before enqueuing an expensive job. Resolves to the team selected by the authenticated caller’s session. API-key callers are scoped to the team that owns the key.

​
Response

200
{
  "plan": {
    "id": "plan-uuid",
    "slug": "pro",
    "name": "Pro",
    "description": "For growing creators",
    "price_cents": 2900,
    "currency": "usd",
    "monthly_credits": 500,
    "allowed_models": ["fal:nano-banana-pro", "fal:kling-v2.5-pro"],
    "allowed_features": ["influencer", "slides"],
    "is_active": true,
    "sort_order": 20
  },
  "status": "active",
  "cancel_at_period_end": false,
  "current_period_end": "2026-05-21T12:00:00Z",
  "credits_remaining": 342,
  "credits_topup_balance": 1000,
  "coupon_credits_balance": 0,
  "has_access": true
}

​
Fields

​
plan
object | null
The plan row. null when the team has never had a subscription. See List Plans for the full plan shape.
​
status
string | null
Stripe subscription status. One of trialing, active, past_due, canceled, unpaid, incomplete, incomplete_expired, paused.
​
cancel_at_period_end
boolean
true when the subscription will not auto-renew at current_period_end.
​
current_period_end
string | null
ISO-8601 timestamp of the next renewal. Also the date at which monthly credits reset.
​
credits_remaining
integer
Monthly-plan credits left in the current period. Resets on renewal.
​
credits_topup_balance
integer
Purchased top-up credits. Non-expiring. Spent AFTER the monthly balance depletes.
​
coupon_credits_balance
integer
Promotional credits from claimed coupons. Non-expiring.
​
has_access
boolean
Computed: true when status ∈ (active, trialing, past_due) AND current_period_end is in the future. Use this to decide whether a team can generate, not status alone.

​
Example

cURL
curl https://api.supapost.so/billing/subscription \
  -H "Authorization: Bearer YOUR_API_KEY"