Billing-Dev Integration Guide

┌─────────────────────────────────────────────────────────────────────┐
│                        USER / BROWSER                                │
└─────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         do.dev (Main App)                            │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐     │
│  │ Billing Pages   │  │ useBillingDev   │  │ /api/billing-dev│     │
│  │ (UI)            │→ │ (React Hook)    │→ │ (API Route)     │     │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘     │
└─────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼ HTTP API
┌─────────────────────────────────────────────────────────────────────┐
│                    billing-dev (Convex Backend)                      │
│                                                                      │
│  Convex Site URL: https://laudable-chicken-562.convex.site          │
│                                                                      │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐                 │
│  │ /entitlement │ │ /usage/record│ │ /keys/validate│                │
│  │ /entitlement │ │              │ │              │                 │
│  │   /check     │ │              │ │              │                 │
│  └──────────────┘ └──────────────┘ └──────────────┘                 │
│                                                                      │
│  Tables: organizations, products, subscriptions, entitlements,       │
│          usageTypes, usageEvents, dailyUsage, monthlyUsage          │
└─────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼ Webhooks
┌─────────────────────────────────────────────────────────────────────┐
│                            Stripe                                    │
│                                                                      │
│  Products: Pro ($20/mo), Team ($39/mo), Add-ons                     │
│  Metered: API Calls, Emails, Voice Minutes, Storage, AI Tokens      │
└─────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼ HTTP API
┌─────────────────────────────────────────────────────────────────────┐
│                     Subdomain Apps                                   │
│                                                                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐            │
│  │ send.dev │  │ talk.dev │  │ local.dev│  │ doc.dev  │            │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘            │
│                                                                      │
│  Each subdomain calls billing-dev to:                               │
│  1. Check entitlements before allowing access                       │
│  2. Record usage for metered billing                                │
│  3. Validate API keys                                               │
└─────────────────────────────────────────────────────────────────────┘

Billing status comes from billing-dev, NOT from user roles.
Never use hasRole("pro") or hasRole("early-adopter") for billing checks.

// ✅ CORRECT - Use userId from WorkOS auth
const result = await createPortalSession({
  userId: user.id,      // WorkOS user ID
  email: user.email,    // For fallback lookup
  returnUrl,
});

// ❌ WRONG - Don't use orgId for new integrations
const result = await createPortalSession({
  orgId: someOrgId,     // DEPRECATED
  returnUrl,
});

// In API routes and billing code
const planMap: Record<string, string> = {
  "free": "hobby",      // Legacy "free" → "hobby"
  "early_adopter": "pro", // Deprecated tier → "pro"
};

function normalizePlan(plan: string): string {
  return planMap[plan] || plan;
}

// lib/plan-limits.ts
export const PLAN_LIMITS = {
  hobby: {
    dailyLimit: 100,
    monthlyLimit: 1000,
    perMinute: 10,
  },
  pro: {
    dailyLimit: 10000,
    monthlyLimit: 100000,
    perMinute: 60,
  },
  // ... other tiers
} as const;

"use client"
import { useAuth } from "@/lib/use-auth"

export function PricingPage() {
  const { raw } = useAuth()

  // Check both plan and roles for Pro status (belt and suspenders)
  const isPro = raw?.plan === "pro" || raw?.roles?.includes("pro")
  const currentPlan = raw?.plan || "hobby"

  return (
    <div>
      {isPro ? (
        <span>You're on Pro!</span>
      ) : (
        <a href="/dashboard?upgrade=pro">Upgrade to Pro</a>
      )}
    </div>
  )
}

// When subscription changes in Stripe webhook:
// 1. Update billing-dev (automatic via webhook)
// 2. Update WorkOS metadata
await workos.userManagement.updateUser(userId, {
  metadata: {
    plan: newPlan,
    roles: newPlan === "pro" ? ["pro"] : [],
  },
});

INTERNAL_API_SECRET=ed96eaf5aa06964de198b165b2a282a06e1812185f0d6baf0cb5c183a5df074c
STRIPE_SECRET_KEY=sk_test_51JltnDBMKDQ3bUd4...
STRIPE_WEBHOOK_SECRET=whsec_RfM4L7jR2N1qJpAgBLD7rr0jcyTzRAQG
STRIPE_PRICE_PRO=price_1SfLPpBMKDQ3bUd4UfHgE0S8
STRIPE_PRICE_TEAM=price_1SmYeJBMKDQ3bUd42VTtsBp6

BILLING_DEV_URL=https://laudable-chicken-562.convex.site
BILLING_DEV_API_SECRET=ed96eaf5aa06964de198b165b2a282a06e1812185f0d6baf0cb5c183a5df074c

https://laudable-chicken-562.convex.site

Authorization: Bearer ed96eaf5aa06964de198b165b2a282a06e1812185f0d6baf0cb5c183a5df074c

{
  "orgId": "k5780q24xykqptp67wz3v09b0h7ybshy",
  "plan": "pro",
  "credits": 0,
  "limits": {
    "apiCalls": 10000,
    "emails": 5000,
    "storage": 1000,
    "voiceMinutes": 1000,
    "aiTokens": 100000,
    "teamMembers": 1
  },
  "features": ["dashboard", "send.access"],
  "hasOverageAccess": false,
  "planStartedAt": 1704067200000,
  "activeSubscriptions": 1
}

curl -H "Authorization: Bearer $API_SECRET" \
  "https://laudable-chicken-562.convex.site/entitlement?userId=user_01KC4EJ7NRCBH5ZNVS5KCWSHFT&email=user@example.com"

curl -H "Authorization: Bearer $API_SECRET" \
  "https://laudable-chicken-562.convex.site/entitlement?orgId=k5780q24xykqptp67wz3v09b0h7ybshy"

{
  "hasAccess": true,
  "feature": "send.access",
  "plan": "pro"
}

curl -H "Authorization: Bearer $API_SECRET" \
  "https://laudable-chicken-562.convex.site/entitlement/check?orgId=xxx&feature=send.access"

{"status": "ok"}

{
  "orgId": "xxx",
  "usageType": "email_send",
  "quantity": 100,
  "domain": "send"
}

{
  "apiKey": "do_live_xxx",
  "domain": "send"
}

{
  "hasSubscription": true,
  "plan": "pro",
  "status": "active",
  "currentPeriodStart": 1704067200000,
  "currentPeriodEnd": 1706745600000,
  "cancelAtPeriodEnd": false,
  "cancelAt": null
}

curl -H "Authorization: Bearer $API_SECRET" \
  "https://laudable-chicken-562.convex.site/subscription?userId=user_01KC4EJ7NRCBH5ZNVS5KCWSHFT&email=user@example.com"

{
  "userId": "user_01KC4EJ7NRCBH5ZNVS5KCWSHFT",
  "customerEmail": "user@example.com",
  "priceId": "price_1SfLPpBMKDQ3bUd4UfHgE0S8",
  "successUrl": "https://send.dev/dashboard/billing?checkout=success",
  "cancelUrl": "https://send.dev/dashboard/billing?checkout=cancelled",
  "mode": "subscription",
  "metadata": {
    "planId": "pro",
    "source": "send.dev"
  }
}

{
  "sessionId": "cs_test_xxx",
  "url": "https://checkout.stripe.com/xxx"
}

{
  "userId": "user_01KC4EJ7NRCBH5ZNVS5KCWSHFT",
  "email": "user@example.com",
  "returnUrl": "https://send.dev/dashboard/billing/overview"
}

{
  "url": "https://billing.stripe.com/xxx"
}

{
  "userId": "user_01KC4EJ7NRCBH5ZNVS5KCWSHFT",
  "email": "user@example.com",
  "cancelAtPeriodEnd": true
}

{
  "subscriptionId": "sub_xxx",
  "cancelAtPeriodEnd": true,
  "cancelAt": 1706745600000,
  "currentPeriodEnd": 1706745600000
}

// lib/billing-dev-client.ts

const BILLING_DEV_URL = process.env.BILLING_DEV_URL || "https://laudable-chicken-562.convex.site";
const BILLING_DEV_API_SECRET = process.env.BILLING_DEV_API_SECRET;

interface BillingDevResponse<T> {
  success: boolean;
  data?: T;
  error?: string;
}

interface EntitlementResponse {
  orgId: string;
  plan: "hobby" | "pro" | "team" | "enterprise";
  credits: number;
  limits: {
    apiCalls?: number;
    emails?: number;
    storage?: number;
    voiceMinutes?: number;
    aiTokens?: number;
  } | null;
  features: string[];
  hasOverageAccess: boolean;
}

interface SubscriptionResponse {
  hasSubscription: boolean;
  plan: string;
  status?: string;
  currentPeriodEnd?: number;
  currentPeriodStart?: number;
  cancelAtPeriodEnd?: boolean;
  cancelAt?: number | null;
}

interface CheckoutSessionResult {
  sessionId: string;
  url: string;
}

interface PortalSessionResult {
  url: string;
}

function getAuthHeader(): HeadersInit {
  return {
    Authorization: `Bearer ${BILLING_DEV_API_SECRET}`,
    "Content-Type": "application/json",
  };
}

/**
 * Get entitlements for a user
 * @param userId - WorkOS user ID (from user.id) - PRIMARY identifier
 * @param email - User email for fallback lookup
 */
export async function getEntitlementByUserId(
  userId: string,
  email?: string
): Promise<BillingDevResponse<EntitlementResponse>> {
  try {
    const params = new URLSearchParams({ userId });
    if (email) params.append("email", email);

    const response = await fetch(
      `${BILLING_DEV_URL}/entitlement?${params.toString()}`,
      { headers: getAuthHeader(), cache: "no-store" }
    );

    if (!response.ok) {
      const error = await response.json().catch(() => ({ error: "Unknown error" }));
      return { success: false, error: error.error || `HTTP ${response.status}` };
    }

    return { success: true, data: await response.json() };
  } catch (error) {
    return { success: false, error: error instanceof Error ? error.message : "Network error" };
  }
}

/**
 * Get subscription status for a user
 * @param userId - WorkOS user ID (from user.id) - PRIMARY identifier
 * @param email - User email for fallback lookup
 */
export async function getSubscriptionByUserId(
  userId: string,
  email?: string
): Promise<BillingDevResponse<SubscriptionResponse>> {
  try {
    const params = new URLSearchParams({ userId });
    if (email) params.append("email", email);

    const response = await fetch(
      `${BILLING_DEV_URL}/subscription?${params.toString()}`,
      { headers: getAuthHeader(), cache: "no-store" }
    );

    if (!response.ok) {
      const error = await response.json().catch(() => ({ error: "Unknown error" }));
      return { success: false, error: error.error || `HTTP ${response.status}` };
    }

    return { success: true, data: await response.json() };
  } catch (error) {
    return { success: false, error: error instanceof Error ? error.message : "Network error" };
  }
}

/**
 * Create a checkout session for subscription
 * @param userId - WorkOS user ID (from user.id) - PRIMARY identifier
 */
export async function createCheckoutSession(params: {
  userId: string;
  email: string;
  priceId: string;
  successUrl: string;
  cancelUrl: string;
  mode?: "subscription" | "payment";
  metadata?: Record<string, string>;
}): Promise<BillingDevResponse<CheckoutSessionResult>> {
  try {
    const body = {
      userId: params.userId,
      customerEmail: params.email,
      priceId: params.priceId,
      successUrl: params.successUrl,
      cancelUrl: params.cancelUrl,
      mode: params.mode || "subscription",
      metadata: params.metadata,
    };

    const response = await fetch(`${BILLING_DEV_URL}/checkout`, {
      method: "POST",
      headers: getAuthHeader(),
      body: JSON.stringify(body),
    });

    if (!response.ok) {
      const error = await response.json().catch(() => ({ error: "Unknown error" }));
      return { success: false, error: error.error || `HTTP ${response.status}` };
    }

    return { success: true, data: await response.json() };
  } catch (error) {
    return { success: false, error: error instanceof Error ? error.message : "Network error" };
  }
}

/**
 * Create a portal session for managing subscription
 * @param userId - WorkOS user ID (from user.id) - PRIMARY identifier
 * @param email - User email for fallback lookup
 */
export async function createPortalSession(params: {
  userId: string;
  email?: string;
  returnUrl: string;
}): Promise<BillingDevResponse<PortalSessionResult>> {
  try {
    const body = {
      userId: params.userId,
      email: params.email,
      returnUrl: params.returnUrl,
    };

    const response = await fetch(`${BILLING_DEV_URL}/portal`, {
      method: "POST",
      headers: getAuthHeader(),
      body: JSON.stringify(body),
    });

    if (!response.ok) {
      const error = await response.json().catch(() => ({ error: "Unknown error" }));
      return { success: false, error: error.error || `HTTP ${response.status}` };
    }

    return { success: true, data: await response.json() };
  } catch (error) {
    return { success: false, error: error instanceof Error ? error.message : "Network error" };
  }
}

/**
 * Cancel a subscription
 * @param userId - WorkOS user ID (from user.id) - PRIMARY identifier
 * @param email - User email for fallback lookup
 */
export async function cancelSubscription(params: {
  userId: string;
  email?: string;
  cancelAtPeriodEnd?: boolean;
}): Promise<BillingDevResponse<{ subscriptionId: string; cancelAtPeriodEnd: boolean; cancelAt: number | null; currentPeriodEnd: number }>> {
  try {
    const body = {
      userId: params.userId,
      email: params.email,
      cancelAtPeriodEnd: params.cancelAtPeriodEnd ?? true,
    };

    const response = await fetch(`${BILLING_DEV_URL}/cancel`, {
      method: "POST",
      headers: getAuthHeader(),
      body: JSON.stringify(body),
    });

    if (!response.ok) {
      const error = await response.json().catch(() => ({ error: "Unknown error" }));
      return { success: false, error: error.error || `HTTP ${response.status}` };
    }

    return { success: true, data: await response.json() };
  } catch (error) {
    return { success: false, error: error instanceof Error ? error.message : "Network error" };
  }
}

# Billing Dev Service
BILLING_DEV_URL=https://laudable-chicken-562.convex.site
BILLING_DEV_API_SECRET=ed96eaf5aa06964de198b165b2a282a06e1812185f0d6baf0cb5c183a5df074c

// middleware/billing.ts

import { NextRequest, NextResponse } from "next/server";
import { getEntitlementByUserId } from "@/lib/billing-dev-client";

const DOMAIN = "send"; // Change per subdomain: "send", "talk", "local", "doc"
const FEATURE = `${DOMAIN}.access`; // e.g., "send.access"

/**
 * Check if user has billing access to this subdomain
 * @param userId - WorkOS user ID (from user.id)
 * @param email - User email for fallback lookup
 */
export async function checkBillingAccess(
  userId: string,
  email?: string
): Promise<NextResponse | null> {
  const result = await getEntitlementByUserId(userId, email);

  if (!result.success || !result.data) {
    return NextResponse.json(
      {
        error: "billing_error",
        message: "Unable to verify billing status",
      },
      { status: 500 }
    );
  }

  const hasAccess = result.data.features.includes(FEATURE);

  if (!hasAccess) {
    return NextResponse.json(
      {
        error: "subscription_required",
        message: `Upgrade to Pro to access ${DOMAIN}.dev`,
        upgradeUrl: "https://do.dev/pricing",
      },
      { status: 403 }
    );
  }

  return null; // Access granted
}

/**
 * Check usage limits for a user
 * @param userId - WorkOS user ID (from user.id)
 * @param email - User email for fallback lookup
 */
export async function checkUsageLimits(
  userId: string,
  email: string | undefined,
  usageType: string,
  quantity: number = 1
): Promise<{ allowed: boolean; remaining: number; requiresCredits: boolean }> {
  const result = await getEntitlementByUserId(userId, email);

  if (!result.success || !result.data) {
    return { allowed: false, remaining: 0, requiresCredits: false };
  }

  const entitlement = result.data;
  const limit = entitlement.limits?.[usageType as keyof typeof entitlement.limits] || 0;

  // TODO: Get current usage from billing-dev
  const currentUsage = 0; // Placeholder

  const remaining = Math.max(0, limit - currentUsage);
  const wouldExceed = currentUsage + quantity > limit;

  if (wouldExceed) {
    // Check if user can use credits for overage
    if (entitlement.hasOverageAccess && entitlement.credits > 0) {
      return { allowed: true, remaining, requiresCredits: true };
    }
    return { allowed: false, remaining, requiresCredits: false };
  }

  return { allowed: true, remaining, requiresCredits: false };
}

// app/api/emails/send/route.ts (for send.dev)

import { NextRequest, NextResponse } from "next/server";
import { withAuth } from "@workos-inc/authkit-nextjs";
import { checkBillingAccess, checkUsageLimits } from "@/middleware/billing";

export async function POST(request: NextRequest) {
  // Get user from WorkOS auth
  const { user } = await withAuth();

  if (!user) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  // Check billing access using userId (not orgId!)
  const accessDenied = await checkBillingAccess(user.id, user.email);
  if (accessDenied) return accessDenied;

  // Check usage limits
  const { allowed, remaining, requiresCredits } = await checkUsageLimits(
    user.id,
    user.email,
    "emails",
    1 // sending 1 email
  );

  if (!allowed) {
    return NextResponse.json(
      {
        error: "limit_exceeded",
        message: "Email limit exceeded. Add credits to continue.",
        remaining,
      },
      { status: 429 }
    );
  }

  // Perform the action
  const result = await sendEmail(/* ... */);

  // Record usage
  await recordUsage({
    orgId,
    usageType: "email_send",
    quantity: 1,
    domain: "send",
  });

  return NextResponse.json({ success: true, ...result });
}

// components/BillingStatus.tsx

"use client";

import { useEffect, useState } from "react";

interface BillingStatus {
  plan: string;
  features: string[];
  limits: Record<string, number>;
  credits: number;
}

export function BillingStatus({ orgId }: { orgId: string }) {
  const [status, setStatus] = useState<BillingStatus | null>(null);

  useEffect(() => {
    async function fetchStatus() {
      const response = await fetch(`/api/billing/status?orgId=${orgId}`);
      if (response.ok) {
        setStatus(await response.json());
      }
    }
    fetchStatus();
  }, [orgId]);

  if (!status) return null;

  return (
    <div className="p-4 bg-white rounded-lg border">
      <div className="text-sm text-gray-500">Current Plan</div>
      <div className="text-lg font-semibold capitalize">{status.plan}</div>

      {status.plan === "hobby" && (
        <a
          href="https://do.dev/pricing"
          className="mt-2 inline-block text-blue-600 hover:underline"
        >
          Upgrade to Pro
        </a>
      )}
    </div>
  );
}

INTERNAL_API_SECRET=your_internal_api_secret_here
STRIPE_SECRET_KEY=sk_test_your_stripe_secret_key
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here
STRIPE_PRICE_PRO=price_your_pro_price_id
STRIPE_PRICE_TEAM=price_your_team_price_id
WORKOS_CLIENT_ID=client_your_workos_client_id

BILLING_DEV_URL=https://your-deployment.convex.site
BILLING_DEV_API_SECRET=your_billing_api_secret_here

{
  slug: "pro",
  name: "Pro",
  type: "base_plan", // or "addon", "usage"
  stripePriceId: "price_xxx",
  price: 2000, // $20 in cents
  includedLimits: {
    apiCalls: 10000,
    emails: 5000,
    storage: 1000,
    voiceMinutes: 1000,
    aiTokens: 100000,
    teamMembers: 1,
  },
  features: ["dashboard", "send.access", "talk.access", ...],
}

{
  orgId: "xxx",
  feature: "send.access",
  source: "plan", // or "addon", "trial", "manual"
  sourceId: "subscription_id",
  expiresAt: null, // or timestamp for trials
}

// app/pricing/page.tsx
export default function PricingPage() {
  const { raw } = useAuth()
  const isPro = raw?.plan === "pro" || raw?.roles?.includes("pro")
  const currentPlan = raw?.plan || "hobby"

  const tiers = [
    {
      name: "Hobby",
      cta: currentPlan === "hobby" ? "Your Plan" : "Get Started Free",
      isCurrentPlan: currentPlan === "hobby",
    },
    {
      name: "Pro",
      cta: isPro ? "Your Plan" : "Upgrade to Pro",
      isCurrentPlan: isPro,
    },
    // ...
  ]
}

// api/src/routes/keys.ts
function mapToApiKeyTier(tier: string | undefined): ApiKeyTier {
  const tierMap: Record<string, ApiKeyTier> = {
    hobby: "hobby",
    free: "hobby",  // Legacy mapping
    pro: "pro",
    developer: "developer",
    business: "business",
    enterprise: "enterprise",
  };
  return tierMap[tier || "hobby"] || "hobby";
}

// app/api/user/keys/route.ts
const response = await callWorkerApi("/internal/keys", {
  method: "POST",
  body: JSON.stringify({
    name: name.trim(),
    user_id: user.id,
    email: user.email,
    tier: "hobby",  // Default tier for new users
  }),
});

// ✅ CORRECT
const result = await createPortalSession({
  userId: user.id,      // WorkOS user ID from withAuth()
  email: user.email,    // For fallback lookup
  returnUrl: "https://yourapp.dev/dashboard/billing",
});

const { user } = await withAuth();
// user.id is the WorkOS user ID - use this!

# Health check
curl https://laudable-chicken-562.convex.site/health

# Get entitlement (using userId - RECOMMENDED)
curl -H "Authorization: Bearer $API_SECRET" \
  "https://laudable-chicken-562.convex.site/entitlement?userId=user_01KC4EJ7NRCBH5ZNVS5KCWSHFT&email=user@example.com"

# Get subscription status
curl -H "Authorization: Bearer $API_SECRET" \
  "https://laudable-chicken-562.convex.site/subscription?userId=user_01KC4EJ7NRCBH5ZNVS5KCWSHFT&email=user@example.com"

# Create portal session
curl -X POST -H "Authorization: Bearer $API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"userId":"user_01KC4EJ7NRCBH5ZNVS5KCWSHFT","email":"user@example.com","returnUrl":"https://app.dev/billing"}' \
  "https://laudable-chicken-562.convex.site/portal"

cd /Users/tim/code/working/dodotdev/billing-dev

# Deploy
npx convex dev --once

# Run migrations
npx convex run migrations:migratePlanNames

# Seed products
npx convex run products:seedProducts
npx convex run products:seedUsageTypes

# Check env vars
npx convex env list