Quickstart

@creem_io/convex connects your Convex backend to Creem. Webhooks keep billing state synced into your Convex database. Pre-built React and Svelte widgets handle checkout, plan switching, and cancellation. This page gets you to a working two-plan pricing page. Before you start, you need an existing Convex project with npx convex dev running, and auth configured so ctx.auth.getUserIdentity() returns your signed-in user. Without auth, the pricing page renders - but only in its public, logged-out state, and checkout stays unavailable.

Integrating with an AI agent, or migrating from another billing provider? Point it at the Integration Guide. That page holds the whole setup sequence in order, with validation steps. Agents can fetch it as raw markdown:

https://docs.creem.io/code/sdks/convex/integration.md

Backend

Install

npm install @creem_io/convex convex creem

convex/convex.config.ts

import { defineApp } from "convex/server";
import creem from "@creem_io/convex/convex.config";

const app = defineApp();
app.use(creem);

export default app;

Set secrets

npx convex env set CREEM_API_KEY <your_creem_api_key>
npx convex env set CREEM_WEBHOOK_SECRET <your_creem_webhook_signing_secret>
npx convex env set CREEM_SERVER test

Both keys live in the Developers section of your dashboard. Toggle Test Mode to get test keys. Set CREEM_SERVER=prod (or omit it) when you go live.

Export the billing API

The resolve callback maps your authenticated session to a billing entity. Replace it with your real auth logic:

convex/billing.ts

import { Creem, type ApiResolver } from "@creem_io/convex";
import { components } from "./_generated/api";
import { internalAction } from "./_generated/server";

export const creem = new Creem(components.creem);

// Return `null` for an unauthenticated caller. That is what keeps public
// pricing pages working. Anything thrown here counts as a real failure.
const resolve: ApiResolver = async (ctx) => {
  const identity = await ctx.auth.getUserIdentity();
  if (!identity) return null;
  return {
    userId: identity.subject,
    email: identity.email!,
    entityId: identity.subject, // for org billing, return the org ID
  };
};

const { uiModel, checkouts, subscriptions, customers } = creem.api({ resolve });

export { uiModel };
export const checkoutsCreate = checkouts.create;
export const subscriptionsUpdate = subscriptions.update;
export const subscriptionsCancel = subscriptions.cancel;
export const subscriptionsResume = subscriptions.resume;
export const customersPortalUrl = customers.portalUrl;

export const syncBillingProducts = internalAction({
  args: {},
  handler: async (ctx) => {
    await creem.syncProducts(ctx);
  },
});

Keep these export names. connectCreemApi on the frontend maps them onto the widget API for you.

convex/http.ts

import { httpRouter } from "convex/server";
import { creem } from "./billing";

const http = httpRouter();
creem.registerRoutes(http);
export default http;

In your Creem dashboard, set the webhook endpoint to your Convex site URL plus /creem/events:

https://<your-deployment>.convex.site/creem/events

Create two products

This quickstart renders a Basic and a Premium plan, so create one Creem product for each.

CLI
Dashboard

Install the CLI, then sign in with the same test key you set in step 3:

creem login --api-key creem_test_YOUR_KEY

creem products create \
  --name "Basic" \
  --description "For small teams" \
  --price 1900 \
  --currency USD \
  --billing-type recurring \
  --billing-period every-month

creem products create \
  --name "Premium" \
  --description "For growing teams" \
  --price 4900 \
  --currency USD \
  --billing-type recurring \
  --billing-period every-month

Each command prints the new prod_... ID. creem products list shows them again later.

Put both IDs in your frontend env file. They are public values that the browser needs in order to start checkout:

.env.local

VITE_CREEM_SUB_BASIC_MONTHLY=prod_...
VITE_CREEM_SUB_PREMIUM_MONTHLY=prod_...

Use whichever public prefix your framework expects: VITE_* for Vite, NEXT_PUBLIC_* for Next.js, PUBLIC_* for SvelteKit. Your Creem API key is not a public value and stays in Convex env, as set above.

Sync products

Pull the product metadata (names, prices, descriptions) into Convex so the widgets can render it:

npx convex run billing:syncBillingProducts

Billing state now syncs into Convex automatically. The backend is done.

Frontend

Install UI dependencies

The widgets are built on Ark UI headless primitives. Add the adapter for your framework to your existing app:

React
Svelte

npm install @ark-ui/react

npm install convex-svelte @ark-ui/svelte

Set up Tailwind and import styles

The widgets require Tailwind CSS v4. If your project doesn’t have it yet, follow the Tailwind framework guide. The steps differ per framework.Then add the component styles to your CSS entry point, after the Tailwind import:

@import "tailwindcss";
@import "@creem_io/convex/styles";

Define your plans

Map stable plan IDs to your Creem product IDs:

React
Svelte

src/billingCatalog.ts

import { defineBillingCatalog } from "@creem_io/convex/react";

export const billingCatalog = defineBillingCatalog({
  version: "1",
  plans: [
    {
      planId: "basic",
      category: "paid",
      billingType: "recurring",
      creemProductIds: {
        "every-month": import.meta.env.VITE_CREEM_SUB_BASIC_MONTHLY,
      },
    },
    {
      planId: "premium",
      category: "paid",
      billingType: "recurring",
      recommended: true,
      creemProductIds: {
        "every-month": import.meta.env.VITE_CREEM_SUB_PREMIUM_MONTHLY,
      },
    },
  ],
} as const);

src/billingCatalog.ts

import { defineBillingCatalog } from "@creem_io/convex/svelte";

export const billingCatalog = defineBillingCatalog({
  version: "1",
  plans: [
    {
      planId: "basic",
      category: "paid",
      billingType: "recurring",
      creemProductIds: {
        "every-month": import.meta.env.VITE_CREEM_SUB_BASIC_MONTHLY,
      },
    },
    {
      planId: "premium",
      category: "paid",
      billingType: "recurring",
      recommended: true,
      creemProductIds: {
        "every-month": import.meta.env.VITE_CREEM_SUB_PREMIUM_MONTHLY,
      },
    },
  ],
} as const);

defineBillingCatalog is the same framework-agnostic function in both entry points. It is re-exported from /react and /svelte so that browser code never has to import the server entry.Titles, descriptions, and prices come from the synced Creem product data.

Render the pricing page

Wrap your billing UI once in CreemConvexProvider. The widgets read everything from it:

React
Svelte

src/PricingPage.tsx

import {
  CreemConvexProvider,
  Subscription,
  BillingPortal,
  connectCreemApi,
  plansOf,
} from "@creem_io/convex/react";
import { api } from "../convex/_generated/api";
import { billingCatalog } from "./billingCatalog";

// Maps the exports from convex/billing.ts onto the widget API.
const connectedApi = connectCreemApi(api.billing);

export function PricingPage() {
  return (
    <CreemConvexProvider api={connectedApi} catalog={billingCatalog}>
      <Subscription.Root plans={plansOf(billingCatalog, ["basic", "premium"])} />
      <BillingPortal />
    </CreemConvexProvider>
  );
}

src/routes/+page.svelte

<script lang="ts">
  import { setupConvex } from "convex-svelte";
  import {
    CreemConvexProvider,
    Subscription,
    BillingPortal,
    connectCreemApi,
    plansOf,
  } from "@creem_io/convex/svelte";
  import { api } from "../convex/_generated/api.js";
  import { billingCatalog } from "./billingCatalog";

  setupConvex(import.meta.env.VITE_CONVEX_URL);

  // Maps the exports from convex/billing.ts onto the widget API.
  const connectedApi = connectCreemApi(api.billing);
</script>

<CreemConvexProvider api={connectedApi} catalog={billingCatalog}>
  <Subscription.Root plans={plansOf(billingCatalog, ["basic", "premium"])} />
  <BillingPortal />
</CreemConvexProvider>

You now have a pricing page with live prices and working checkout. It shows a “Current plan” badge, and handles plan switching, cancel, and resume. Convex keeps all of it in sync. Try it with a test card.

Next steps

Subscriptions

Billing cycles, trials, unit-based pricing, and scheduled changes

One-Time Products & Credits

Owned products, consumables, credit packs, and upgrade paths

Entitlements & Account UI

Feature gating, usage limits, billing history, and payment recovery

Advanced

Custom auth/RBAC, entity model, webhook middleware, and migration

Get Started

AI

Features

Code

Integrations

Community

Merchant of Record

For Customers

Backend

Frontend

Next steps

Subscriptions

One-Time Products & Credits

Entitlements & Account UI

Advanced

​Backend

​Frontend

​Next steps

Subscriptions

One-Time Products & Credits

Entitlements & Account UI

Advanced

Backend

Frontend

Next steps