Subscriptions

A Subscription is the record that links a tenant to a plan. It tracks billing periods, payment status, trial dates, and seat counts. Every status change is recorded to an immutable event log.

Subscription Statuses

Status	Description
`pending`	Created but not yet activated (awaiting payment confirmation)
`trial`	In a free trial period
`active`	Paid and active
`past_due`	Payment failed — grace period
`pending_cancel`	Cancellation requested; access continues until `currentPeriodEnd`
`canceled`	Canceled. For manual billing subscriptions, this is set immediately on cancellation; for recurring subscriptions, it is set at period end.
`expired`	Trial or subscription ended without renewal

Status Transitions

Transitions are triggered by Stripe webhook events or explicit API calls:

Event / Action	Transition
`checkout.session.completed`	`pending` → `active` or `trial`
`customer.subscription.updated`	`trial` → `active`
`invoice.payment_failed`	`active` → `past_due`
`customer.subscription.deleted`	any → `canceled`
`POST /subscriptions/{id}/cancel` (recurring)	`active` / `trial` / `past_due` → `pending_cancel`
`POST /subscriptions/{id}/cancel` (manual billing)	`active` / `trial` / `past_due` → `canceled`

Subscription Fields

{
  "id": "sub_crovver_abc123",
  "status": "active",
  "tenantId": "ten_xyz",
  "planId": "plan_pro",
  "trialEndsAt": null,
  "currentPeriodStart": "2025-01-01T00:00:00Z",
  "currentPeriodEnd": "2025-02-01T00:00:00Z",
  "canceledAt": null,
  "capacityUnits": 15,
  "usedCapacity": 12,
  "providerSubscriptionId": "sub_stripe_...",
  "providerCustomerId": "cus_stripe_..."
}

Event Sourcing

Every subscription status change is written to subscription_events. This gives you a complete audit trail:

{
  "event_type": "subscription.activated",
  "previous_status": "trial",
  "new_status": "active",
  "occurred_at": "2025-02-01T00:00:00Z",
  "metadata": {
    "stripe_event_id": "evt_...",
    "invoice_id": "in_..."
  }
}

Checking Subscription Status

Use the React SDK hook on the frontend:

import { useSubscription } from 'crovver-react';

function Dashboard() {
  const { isActive, plan, subscription } = useSubscription();

  if (!isActive) return <UpgradePrompt />;

  return <App trialEndsAt={subscription?.trialEndsAt} />;
}

Or query the API from your backend:

GET /api/public/subscriptions/status?publicKey=pk_live_...&tenantId=workspace_123

Overview

Core Concepts

Authentication

SDKs

Guides

Subscription Statuses

Status Transitions

Subscription Fields

Event Sourcing

Checking Subscription Status

​Subscription Statuses

​Status Transitions

​Subscription Fields

​Event Sourcing

​Checking Subscription Status

Subscription Statuses

Status Transitions

Subscription Fields

Event Sourcing

Checking Subscription Status