Skip to content
Help Center Guide · Plans & Usage
2 min readVerified 2026-11-16

Plan Changes & Cancellation

Upgrade or downgrade fixed-capacity tiers immediately, switch billing intervals, and manage subscription cancellations without data surprise.

In This Guide

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

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
SUBSCRIPTION TRANSITION & PRORATION STATE MACHINE
STAGE 01 STEP 1: PRORATION PREVIEW
POST/api/v1/billing/subscription/preview (request payload)
Computes Unused Time Credit on Current Plan vs. Remaining Time on Target Plan
Validates Current activePasses Against Target Tier Capacity Ceiling
STAGE 02 STEP 2: IDEMPOTENT EXECUTION
Mid-Cycle Upgrade / Interval Switch
Immediate Capacity Unlock
Validates expectedAmountDueToday to prevent price drift
Tier Downgrade
Scheduled at currentPeriodEnd
Revocable via `/scheduled-change
/cancel` Before Renewal
POST/api/v1/billing/subscription/change (request payload)
STAGE 03 STEP 3: PERIOD-END CANCELLATION & RESUME
POST/api/v1/billing/subscription/cancel (CANCEL_AT_PERIOD_END / Cancel)
POST/api/v1/billing/subscription/resume (Restores Auto-Renewal Anytime)

Important: You can only downgrade to a smaller tier if your workspace's current activePasses count is at or below the target plan's capacity limit. If your active passes exceed the target tier, /preview and /change return a structured capacity blocker indicating how many active passes must be reduced first.

Subscription Transition Endpoints (Billing API)

EndpointHTTP VerbOperational Behavior
/api/v1/billing/subscription/previewPOSTEvaluates request payload ({ planId, promotionCode? }) and calculates exact proration, tax, and capacity eligibility without mutating state.
/api/v1/billing/subscription/changePOSTExecutes request payload ({ planId, idempotencyKey, promotionCode?, paymentMethodId?, expectedAmountDueToday?, intent? }).
/api/v1/billing/subscription/scheduled-change/cancelPOSTRevokes a pending period-end downgrade so the workspace stays on its current tier.
/api/v1/billing/subscription/cancelPOSTSchedules subscription cancellation at period end (request payload: { reason?, feedback? }).
/api/v1/billing/subscription/resumePOSTReverses 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):

HTTP
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)

JSON
{
  "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:

HTTP
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
}
JSON
{
  "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:

HTTP
POST /api/v1/billing/subscription/scheduled-change/cancel HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
JSON
{
  "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:

HTTP
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."
}
JSON
{
  "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.

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.