Manage Billing and Subscriptions in Perspection

How do you upgrade from the Perspection free trial?

Every new workspace receives a 14-day free trial with full feature access and no credit card required. To upgrade, admins click the trial badge in the sidebar or navigate to Settings > Usage & Billing. Selecting a plan redirects to Stripe Checkout, where payment completes immediately and the subscription activates without delay.

Trial activation

When a workspace is created (see Create Your Workspace), the billing system performs the following:

1. The pricing table mounts and calls POST /v1/billing/{workspaceId}/ensure-trial.

2. The endpoint checks core.tenants for an existing stripe_subscription_id and queries the Stripe API to catch out-of-sync records.

3. If no subscription exists, the endpoint creates a Stripe customer and trial subscription with trial_period_days: 14 and missing_payment_method: cancel.

4. The API writes the subscription ID, subscription_status: trialing, and trial_ends_at to the tenant record.

5. The trial badge activates in the sidebar, displaying "Trial - X days left."

The ensureTrial endpoint is idempotent -- multiple calls return existing trial data without creating duplicates.

Trial badge urgency escalation

The sidebar trial badge adapts visually as the trial progresses:

1. More than 7 days remaining -- Blue primary styling, Sparkles icon.

2. 4 to 7 days remaining -- Amber/warning styling, Clock icon.

3. 3 days or fewer -- Red styling, pulsing Clock icon.

4. Trial expired -- Red styling, AlertCircle icon, text reads "Subscribe."

5. Active paid subscription -- Green styling with filled circle, displays plan name.

Step-by-step upgrade

1. Open billing -- Click the trial badge in the sidebar, or navigate to Settings > Usage & Billing.

2. Select billing interval -- Toggle between "Monthly" and "Yearly." The yearly option shows a "40% off" badge.

3. Choose a plan -- Click "Get started" on the Starter or Growth card. Growth is marked "Recommended."

4. Complete Stripe Checkout -- Perspection calls POST /v1/billing/{workspaceId}/upgrade-from-trial, which cancels the trial immediately and creates a checkout session with immediate charge. The browser redirects to the Stripe-hosted checkout page.

5. Return to Perspection -- After payment, Stripe redirects to /billing/success?session_id={cs_xxx}. The success page fires a Meta Pixel Purchase event and PostHog payment_success event, then redirects to the Home Dashboard.

Only workspace admins can upgrade (requires MANAGE_SUBSCRIPTION permission). Members with the member role can view billing information (VIEW_BILLING permission) but cannot initiate changes.

How do you monitor usage against your Perspection plan quota?

Settings > Usage & Billing displays real-time progress bars for orders processed versus plan quota and active destinations versus the limit. When usage exceeds 75%, the bar changes from blue to yellow (75-89%), orange (90-99%), or red (100%+), with warning badges reading "Warning," "Approaching Limit," or "Quota Exceeded."

Usage metrics

The billing API at GET /v1/billing/{workspaceId}/usage returns:

1. Orders processed -- Current-period order count with a progress bar showing percentage of orders_quota consumed.

2. Destinations active -- Active destination count with a progress bar against the destinations_max limit.

3. Events processed -- Total raw events, shown when the plan defines an events_quota.

4. Billing period -- Current period start and end dates.

5. Next billing date -- The date Stripe processes the next payment.

6. Billing cycle -- Monthly or annual indication.

Color-coded thresholds

When usage exceeds 100%, a red text line appears below the progress bar: "Over by X orders." Perspection also provides a granular quota check at GET /v1/billing/{workspaceId}/quota/{resource} for events, destinations, team_members, ai_credits, or storage.

How do you manage payment methods and invoices in Perspection?

Admins manage payment methods and invoices through the Perspection Settings dialog (cards on file, invoice history with PDF links) and the Stripe Customer Portal (update cards, change billing email, view invoices, cancel subscriptions). The "Manage Billing" button generates a Stripe Customer Portal session URL.

Payment methods

The Usage & Billing section lists all Stripe payment methods on file, showing card brand and last 4 digits (e.g., "Visa 1234"), expiration date, and a "Default" badge on the primary method. The "Manage Payment Methods" button opens the Stripe Customer Portal for adding, removing, or changing cards. The button requires EDIT_BILLING permission and is disabled without an active subscription.

Invoice history

Recent invoices are fetched from the Stripe API via GET /v1/billing/{workspaceId}/invoices. Each row displays the invoice number, a color-coded status badge (green for paid, blue for open, red for void), the creation date and amount, and a "PDF" download button linking to the Stripe-hosted invoice PDF. A "View All Invoices" button opens the full archive in the Stripe Customer Portal.

Stripe Customer Portal actions

Clicking "Manage Billing" generates a portal session and redirects the browser. From the Stripe Customer Portal, admins can:

1. Update credit card -- Add or replace the default payment method.

2. View and download invoices -- Browse the complete archive with PDF links.

3. Change billing email -- Update the receipt email address.

4. Cancel subscription -- Schedule cancellation at period end (full access continues until the period ends).

5. Reactivate subscription -- Undo a scheduled cancellation before the period ends.

Payment failure handling

When payment fails and the subscription enters past_due status, Perspection displays a red alert banner with "Payment Failed" header, grace period countdown, and "Update Payment Method" and "Retry Payment" buttons. Per Stripe best practices, Perspection grants full access during past_due while Stripe retries. Restricted access applies only after all retries fail.

Methodology

All billing features, plan details, and subscription management steps in this guide were verified against the Perspection production dashboard and Stripe billing portal as of February 2026.

"Billing transparency is the single highest-leverage trust signal for a SaaS product. Perspection surfaces usage progress bars directly inside the Settings dialog -- not buried on a separate billing page -- because workspace operators need to see order consumption alongside workspace configuration. The color-coded threshold system (blue to yellow at 75%, orange at 90%, red at 100%) was designed after analyzing support tickets: 68% of billing-related tickets came from customers who exceeded quotas without warning. The Stripe Customer Portal integration offloads PCI compliance entirely -- Perspection never stores, processes, or transmits credit card numbers -- while still providing a seamless billing experience that feels native to the product."

-- Perspection Product Engineering Team

Sources & References

1. Stripe -- Customer Portal, https://stripe.com/docs/customer-management/portal

2. Perspection Pricing Page, https://perspection.app/pricing

3. Perspection Product Guide -- Create Your Workspace, /library/create-your-workspace-guide

4. Perspection Product Guide -- Team & Settings, /library/team-members-workspace-settings-guide