Manage team subscriptions and browse self-serve plans.
Subscription endpoints require billing:read (view) or billing:write (create, change, cancel, portal). Plan listing is public.
→ Billing API — balance top-ups and saved payment methods
List plans
GET /plans
Returns all active plans (Starter, Pro, Team, Enterprise, and any custom plans). No authentication required.
Use the self_serve field to see which plans support Stripe Checkout signup. The default Starter tier is included for limits reference but is not subscribable — teams without a paid subscription receive Starter entitlements automatically.
In the workspace, browse the same plans at Pricing with a comparison table and monthly/yearly toggle. Logged-in users can start Stripe Checkout from that page; existing subscribers are routed to Settings → Subscription.
Provider price IDs are stripped from the public response.
Response
Array of plan objects:
| Field | Type | Description |
|---|---|---|
id | string | Plan ID (use in subscription requests) |
name | string | Display name |
description | string | Plan description |
price_monthly | int | Monthly price in cents (nullable) |
price_yearly | int | Yearly price in cents (nullable) |
credits_monthly | int64 | Included credits per period (microcents) |
limits | object | Plan limit definitions (maps to entitlement resources) |
self_serve | boolean | Whether users can subscribe via checkout |
Example:
1curl https://api.inference.sh/plans \2 -H "X-API-Version: 2"Get subscription
GET /subscription
Returns the current team's paid subscription, or null when no Stripe subscription is active.
Teams with null still run on the Starter tier: entitlements come from the Starter plan (see GET /entitlements and GET /entitlements/usage). Add credits via Billing or subscribe to Pro or Team for higher limits and included monthly credits.
Requires billing:read.
Response
| Field | Type | Description |
|---|---|---|
plan_id | string | Subscribed plan ID |
plan | object | Embedded PlanDTO when loaded |
interval | string | monthly or yearly |
status | string | trialing, active, past_due, canceled, or paused |
current_period_start | string | ISO timestamp |
current_period_end | string | ISO timestamp |
trial_end | string | ISO timestamp (optional) |
cancel_at_period_end | boolean | Subscription ends at period end if true |
credits_per_period | int64 | Credits granted each period (microcents) |
Stripe subscription IDs are omitted from public responses.
Example:
1curl https://api.inference.sh/subscription \2 -H "Authorization: Bearer inf_your_key" \3 -H "X-API-Version: 2"Create subscription
POST /subscription
Creates a Stripe Checkout session for subscription signup. Requires billing:write.
Body:
| Field | Type | Required | Description |
|---|---|---|---|
plan_id | string | Yes | Plan ID from GET /plans |
interval | string | No | monthly (default) or yearly |
success_url | string | No | Redirect after success (defaults to {origin}/settings/billing/subscription?success=1) |
cancel_url | string | No | Redirect if canceled (defaults to {origin}/settings/billing/subscription) |
Response:
1{2 "url": "https://checkout.stripe.com/..."3}Redirect the user to url to complete signup. After Stripe Checkout, the workspace reads ?success=1 on the subscription settings page, refreshes subscription state, and shows a confirmation toast.
Change plan
PUT /subscription
Upgrade or downgrade the active subscription. Requires billing:write.
Body:
1{2 "plan_id": "plan_pro"3}Returns the updated SubscriptionDTO.
Cancel subscription
DELETE /subscription
Cancel the team's subscription. Requires billing:write.
Body (optional):
1{2 "at_period_end": true3}Defaults to at_period_end: true (cancel at end of billing period). Set false for immediate cancellation.
Resume subscription
POST /subscription/resume
Resume a subscription that was set to cancel at period end. Requires billing:write.
Billing portal
POST /subscription/portal
Creates a Stripe Customer Portal session for managing payment methods and invoices. Requires billing:write.
Body:
| Field | Type | Required | Description |
|---|---|---|---|
return_url | string | Yes | URL to return to after the portal session |
Response:
1{2 "url": "https://billing.stripe.com/..."3}Plan limits
Plan limits define caps enforced at runtime — concurrency, request rate, storage, team seats, triggers, data retention, BYOK, and more. When a limit is exceeded, the API returns 402 (limit_exceeded) or 403 (feature_not_available) with structured error metadata.
Each limit in GET /plans responses includes a label field with a human-readable name (for example concurrent tasks, triggers) and an optional unit field for display formatting (for example mb, days for retention_days). Limits with a zero cap or no label are omitted from workspace plan cards.
Use GET /entitlements/usage (requires authentication) to inspect current usage vs limits. Use GET /entitlements to list entitlement rows without usage counts.
In the workspace, entitlement errors open an upgrade modal that lists higher tiers and marks the recommended plan — the cheapest option that resolves the blocked resource. The subscription settings page also shows live resource usage from GET /entitlements/usage with progress bars (warning at 80%, highlighted at the cap). Manage subscriptions at Settings → Billing → Subscription. See REST overview — Workspace modals.
→ Entitlements API — Get usage
Related
- Billing API — pay-as-you-go balance and top-ups
- REST overview — authentication and API versioning
- Extend pricing — usage-based pricing for published apps