Entitlements & Account UI

Feature gating, usage limits, billing snapshot, billing history, payment recovery, and the customer portal in the Creem Convex component.

Gating features on billing state, evaluating usage limits, and the account-level widgets. The state model itself is explained in Concepts.

Where this code goes, and what it assumes

Examples on this page are fragments. They render inside the provider you mounted in the Quickstart:

<CreemConvexProvider api={connectedApi} catalog={billingCatalog}>
  <!-- examples from this page go here -->
</CreemConvexProvider>

If something below does not work, one of these is usually missing. Each links straight to the step that sets it up.

• Component registered — app.use(creem) in convex/convex.config.ts
• Secrets set — CREEM_API_KEY and CREEM_WEBHOOK_SECRET in Convex env
• Billing API exported — convex/billing.ts calling creem.api({ resolve })
• Webhook registered — creem.registerRoutes(http) in convex/http.ts
• Products created — one Creem product per plan and billing cycle
• Products synced — npx convex run billing:syncBillingProducts
• Styles imported — @creem_io/convex/styles after the Tailwind import
• Catalog defined — billingCatalog mapping plan IDs to product IDs
• Provider mounted — <CreemConvexProvider> around your billing UI

Gating UI with BillingGate

BillingGate conditionally renders based on which billing actions are available in the snapshot (checkout, portal, cancel, reactivate):

React

Account page

<BillingGate
  snapshot={snapshot}
  requiredActions="portal"
  fallback={<p>Upgrade to access the billing portal.</p>}
>
  <p>You have portal access.</p>
</BillingGate>

Svelte

<BillingGate snapshot={snapshot} requiredActions="portal">
  {#snippet children()}
    <p>You have portal access.</p>
  {/snippet}
  {#snippet fallback()}
    <p>Upgrade to access the billing portal.</p>
  {/snippet}
</BillingGate>

Usage limits

Catalog plans can carry limits (arbitrary numeric keys like projects or aiMessages). evaluateUsageLimits compares your app’s usage counters against the active plan’s limits:

import { evaluateUsageLimits } from "@creem_io/convex/react"; // or /svelte

const usageLimits = evaluateUsageLimits({
  catalog: billingCatalog,
  planId: activePlanId,
  usage: {
    projects: 3,
    aiMessages: 72,
  },
});

The library evaluates the limits. Your app owns the actual usage counters and decides where they live.

UI gates are user experience, not security. Protected backend actions must check billing state server-side. Read the snapshot inside your Convex function before doing the work.

UI permissions

BillingPermissions controls which widget buttons are enabled. Use it for role-based UI, such as letting only org admins manage billing. Set it once at the provider:

Account page

<CreemConvexProvider
  api={billingApi}
  permissions={{
    canCheckout: isAdmin,
    canChangeSubscription: isAdmin,
    canCancelSubscription: isAdmin,
    canResumeSubscription: isAdmin,
    canUpdateUnits: isAdmin,
    canAccessPortal: isAdmin,
    canManageBillingEmail: isAdmin,
  }}
>
  ...
</CreemConvexProvider>

Disabled permissions render greyed-out buttons. This is cosmetic gating only. Enforce the real rules in your Convex functions, as described in Advanced → Custom auth and RBAC.

Account widgets

Billing portal

Opens the Creem customer portal, which is where payment methods, billing details, and invoice documents live. It hides itself when the entity has no Creem customer record yet, since customers are created on first checkout:

Account page

<BillingPortal />
<BillingPortal>Manage billing & invoices</BillingPortal>

Requires customers.portalUrl in the connected API.

Billing email

The Creem customer portal does not let a customer change the email address invoices and receipts go to. <BillingEmail> does: it shows the address Creem currently uses, and saves a new one through Creem’s customer API.

Account page

<BillingEmail />

Like the portal button, it renders nothing until the entity has a Creem customer, and nothing when canManageBillingEmail is false. It reloads when the billing entity changes. Each request also carries the entity the form shows, and the generated actions refuse it when your resolver now returns a different one, so switching organizations in another tab never saves one organization’s address into another. A failed load offers a retry button.

Requires customers.billingEmail and customers.updateBillingEmail in the connected API. Export customersBillingEmail and customersUpdateBillingEmail from convex/billing.ts and connectCreemApi wires them:

convex/billing.ts

export const customersBillingEmail = customers.billingEmail;
export const customersUpdateBillingEmail = customers.updateBillingEmail;

The generated actions let any caller your resolve accepts change the entity’s billing email. If only billing admins may do that, write your own action with customersUpdateBillingEmailArgs, keep the expectedEntityId check, and check the role before calling creem.customers.updateBillingEmail, as in Advanced → Custom auth and RBAC.

Creem rejects an address that another customer of your store already uses. The widget then shows its generic save error. When the same person checked out for several of your billing entities, those entities share one Creem customer; the widget then refuses the change and says the address is shared, because it is also the other entities’ billing address.

<BillingEmail /> is the ready-made layout. For your own markup, compose the parts inside <BillingEmail.Root>; the root keeps the state and wires the label, description, and error to the input:

Account page

<BillingEmail.Root className="rounded-xl border p-6">
  <BillingEmail.Label />
  <div className="flex gap-2">
    <BillingEmail.Input className="flex-1" />
    <BillingEmail.Save>Update</BillingEmail.Save>
  </div>
  <BillingEmail.Status />
  <BillingEmail.Error />
  <BillingEmail.Retry />
</BillingEmail.Root>

Svelte uses the same names: <BillingEmail.Root>, <BillingEmail.Input />, and so on. See the reference for every part.

Billing history

Paginated transaction history, backed by Creem’s transaction search. This renders transaction rows, not invoice documents:

Account page

<BillingHistory pageSize={5} />

Requires transactions.search in the connected API. Export transactionsSearch from convex/billing.ts and connectCreemApi wires it automatically.

Portal-only today. Payment methods, billing details, and invoice documents are handled by Creem’s hosted portal, which <BillingPortal> opens for the customer. Prefer them embedded in your own UI as Widgets? Vote for payment method, billing preference, and invoice APIs.

Payment recovery

When a subscription is past due or a payment failed, surface it and route the user to the portal to fix their payment method:

Account page

<PaymentRecoveryBanner snapshot={snapshot} />
<PaymentRecoveryButton />

The banner derives its state from snapshot.paymentRecoveryState (or accepts an explicit state). The button reads customers.portalUrl from the provider like every other connected widget, and renders nothing when no portal action is wired.

Checkout success

Show a confirmation banner when the user returns from checkout. Creem’s query parameters are parsed for you:

Account page

<CheckoutSuccessSummary />

React additionally exports a useCheckoutSuccessParams() hook returning the parsed params.

Status banners

Presentational components for specific states, fed from the snapshot:

Component	Shows
ScheduledChangeBanner	Scheduled cancellation or pending period-end update, with undo/resume
TrialLimitBanner	Trial expiration notice
PaymentWarningBanner	Pending, refunded, or partially refunded payment warning

Server-side entitlement checks

The same snapshot powers backend enforcement:

convex/projects.ts

export const createProject = mutation({
  args: { name: v.string() },
  handler: async (ctx, args) => {
    const user = await requireUser(ctx);
    const snapshot = await creem.getBillingSnapshot(ctx, {
      entityId: user.orgId ?? user._id,
    });
    // `access` only contains entitlements that are currently valid, so the
    // presence of a subscription item is the check. Do not add
    // `a.status === "active"`: that would deny users on a trial or in the
    // `past_due` dunning grace period, who should still have access.
    const hasPaidAccess = snapshot.access.some((a) => a.kind === "subscription");
    const projectCount = await countProjects(ctx, user.orgId ?? user._id);
    if (!hasPaidAccess && projectCount >= FREE_PROJECT_LIMIT) {
      throw new ConvexError("Upgrade to create more projects");
    }
    // ...create the project
  },
});

Widget gates keep the UI honest. This check is what actually protects the feature.

Checking a single subscription

When you gate on subscriptions.getCurrent rather than the snapshot, test the status - never the mere existence of a subscription. A returned subscription may be unpaid or paused, in which case it must not grant access:

import { isActiveSubscriptionStatus } from "@creem_io/convex";

const subscription = await creem.subscriptions.getCurrent(ctx, { entityId });
const hasAccess = isActiveSubscriptionStatus(subscription?.status);

isActiveSubscriptionStatus treats active, trialing, scheduled_cancel, and past_due as entitling. past_due is a payment-retry window rather than a loss of access - surface it with PaymentRecoveryBanner instead of cutting the user off.