Overview
Passinstance provides a deterministic, idempotent subscription transition engine (Billing API at /api/v1/billing/subscription/* and Settings -> Billing /settings/billing/overview, plus hosted Checkout/Portal sessions at POST /api/v1/billing/checkout/session and /portal) that lets you preview exact down-to-the-minute proration credits before confirming a plan change, execute instant upgrades, schedule or revoke period-end downgrades, and cancel or resume subscriptions with zero downtime to live passes.
Plan Transition & Proration Lifecycle
Important: You can only downgrade to a smaller tier if your workspace's current
activePassescount is at or below the target plan's capacity limit. If your active passes exceed the target tier,/previewand/changereturn a structured capacity blocker indicating how many active passes must be reduced first.
Subscription Transition Endpoints (Billing API)
| Endpoint | HTTP Verb | Operational Behavior |
|---|---|---|
/api/v1/billing/subscription/preview | POST | Evaluates request payload ({ planId, promotionCode? }) and calculates exact proration, tax, and capacity eligibility without mutating state. |
/api/v1/billing/subscription/change | POST | Executes request payload ({ planId, idempotencyKey, promotionCode?, paymentMethodId?, expectedAmountDueToday?, intent? }). |
/api/v1/billing/subscription/scheduled-change/cancel | POST | Revokes a pending period-end downgrade so the workspace stays on its current tier. |
/api/v1/billing/subscription/cancel | POST | Schedules subscription cancellation at period end (request payload: { reason?, feedback? }). |
/api/v1/billing/subscription/resume | POST | Reverses a pending cancellation before currentPeriodEnd arrives, preserving continuous renewal. |
API Walkthrough: Previewing & Executing Plan Changes
1. Preview Proration Before Changing Plans
Always call POST /api/v1/billing/subscription/preview with the target planId (retrieved from GET /api/v1/billing/plans):
POST /api/v1/billing/subscription/preview HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"planId": "scale_10k_monthly",
"promotionCode": "SCALEUP15"
}
Response Payload (200 OK)
{
"eligible": true,
"transitionType": "IMMEDIATE_UPGRADE",
"currentPlan": { "planId": "growth_monthly", "activePassLimit": 2000 },
"targetPlan": { "planId": "scale_10k_monthly", "activePassLimit": 10000 },
"proration": {
"currency": "EUR",
"unusedCreditCents": -6000,
"proratedNewPlanCents": 20000,
"discountCents": -2100,
"subtotalCents": 11900,
"taxCents": 2261,
"totalDueNowCents": 14161,
"nextRenewalAmountCents": 40000,
"nextRenewalDate": "2026-12-01T00:00:00.000Z"
},
"blockers": []
}
2. Execute Idempotent Plan Upgrade or Downgrade
Pass planId and a unique idempotencyKey (plus optional expectedAmountDueToday guard matching the preview) to POST /api/v1/billing/subscription/change:
POST /api/v1/billing/subscription/change HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"planId": "scale_10k_monthly",
"idempotencyKey": "chg_20261116_scale10k",
"promotionCode": "SCALEUP15",
"expectedAmountDueToday": 141.61
}
{
"subscriptionId": "sub_019331b2-7e10-7a44-9b00-112233445566",
"status": "ACTIVE",
"planId": "scale_10k_monthly",
"effectiveActivePassLimit": 10000,
"appliedImmediately": true,
"invoiceId": "inv_01933220-5a11-7e00-9c44-887766554433"
}
3. Revoke a Scheduled Downgrade (scheduled-change/cancel)
If a downgrade was scheduled to take effect at the end of the billing period, you can cancel that pending transition at any time before currentPeriodEnd:
POST /api/v1/billing/subscription/scheduled-change/cancel HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
{
"subscriptionId": "sub_019331b2-7e10-7a44-9b00-112233445566",
"scheduledChangeCanceled": true,
"activePlanKey": "scale_10k"
}
4. Schedule Period-End Cancellation & Resume
When cancelling via POST /api/v1/billing/subscription/cancel, your workspace retains full paid capacity until the already-paid period expires:
POST /api/v1/billing/subscription/cancel HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"reason": "SEASONAL_EVENT_ENDED",
"feedback": "Our annual festival concluded; we will return next summer."
}
{
"subscriptionId": "sub_019331b2-7e10-7a44-9b00-112233445566",
"status": "ACTIVE",
"cancelAtPeriodEnd": true,
"accessValidUntil": "2026-12-01T00:00:00.000Z"
}
To reverse the cancellation before 2026-12-01T00:00:00.000Z, call POST /api/v1/billing/subscription/resume, which resets cancelAtPeriodEnd: false immediately.
Related Documentation
-
Compare plan tiers in Pricing & Subscription Plans.
-
Download prorated PDF invoices in Invoices & Billing History.
-
Manage saved credit cards and payment instruments in Payment Methods.
