Skip to main content
WorldMonitor uses Dodo Payments for PRO subscriptions and Convex as the source-of-truth for entitlements. These edge endpoints are thin auth proxies — they validate the Clerk JWT, then forward to Convex HTTP actions via RELAY_SHARED_SECRET.

​
Checkout

​
POST /api/create-checkout

Creates a Dodo checkout session and returns the hosted-checkout URL.
  • Auth: Clerk bearer (required)
  • Body:
  • Response: { "checkoutUrl": "https://checkout.dodopayments.com/..." }
  • Idempotency: optional Idempotency-Key supported for 10 minutes after a successful response. Retrying the same key with an identical body replays the original checkout response instead of creating another checkout attempt.
  • returnUrl is validated against an allowlist on the Convex side.

​
POST /api/customer-portal

Creates a Dodo customer-portal session for an existing subscriber (update card, cancel, view invoices).
  • Auth: Clerk bearer + active entitlement
  • Response: { "portalUrl": "..." }
  • Idempotency: optional Idempotency-Key supported. Retrying the same key replays the original portal response instead of creating another portal attempt.

​
GET /api/customer-portal

The link target for payment-failure emails. Each request mints a fresh Dodo customer-portal session and redirects the browser to it.
  • Auth: ?t= portal token from a payment-failure email, or a Clerk bearer. The token expires 8 days after the email is sent. It mints a session only while the account still has a subscription on hold.
  • Response: 302 to the Dodo portal session. Any failure, including an expired token or a rate limit, redirects to https://www.worldmonitor.app/dashboard?billing=portal, which opens the billing portal once the user is signed in. The route ignores next and redirect query parameters.
  • Rate limit: per IP, plus a separate cap per portal token.

​
Product catalog

​
GET /api/product-catalog

Returns the tier view-model used by the /pro pricing page. Cached in Redis under product-catalog:v3 for 1 hour; on cache miss, fetches live prices from Dodo Payments and falls back to the generated FALLBACK_PRICES in _product-catalog.generated.js if Dodo is unreachable. Response carries an X-Product-Catalog-Source header so probes can tell cache hits from live fetches. Response (tiers ordered free, pro, pro_business, api_starter, api_business, enterprise):
The example above is truncated to the pricing-page view. The full payload also carries product (catalog identity), currency, plans (the per-plan entitlement records, including annual variants), and capabilities alongside tiers. Notes:
  • Price fields are flat on the tier. Paid tiers always expose monthlyPrice / monthlyProductId, and add annualPrice / annualProductId only when an annual variant exists. Free uses price: 0, period: "forever"; Enterprise uses price: null.
  • highlightFeatures is an optional array of license/commercial-use callouts, rendered separately from features on the pricing page. Tiers without a callout omit the field.
  • Prices are dollars (Dodo returns cents; the handler divides by 100). Currency is implicit USD for the published catalog.

​
DELETE /api/product-catalog

Purges the cached catalog. Requires Authorization: Bearer $RELAY_SHARED_SECRET. Internal.

​
Referrals

​
GET /api/referral/me

Returns the caller’s deterministic referral code (an 8-char HMAC of the Clerk userId, stable for the life of the account) and a pre-built share URL. Clerk bearer required. The handler also fires a best-effort ctx.waitUntil Convex binding so future /pro?ref=<code> signups can attribute — this never blocks the response.
Errors:
  • 401 UNAUTHENTICATED — missing or invalid Clerk JWT.
  • 503 service_unavailable — BRIEF_URL_SIGNING_SECRET not configured (the referral-code HMAC reuses that secret).
No referrals count or rewardMonths is returned today — Dodo’s affonso_referral attribution doesn’t yet flow into Convex, and exposing only the waitlist-side count would mislead. affonso_referral is the vendor-contracted metadata key Dodo forwards to Affonso’s referral-tracking webhook. The key name is load-bearing — renaming it (to wm_referral, ref, etc.) silently breaks Dodo→Affonso attribution. See convex/payments/checkout.ts and convex/payments/subscriptionHelpers.ts for the writer/reader call sites.

​
Waitlist

​
POST /api/leads/v1/register-interest

Captures an email into the Convex waitlist table. Turnstile-verified (desktop sources bypass), rate-limited per IP. Part of LeadsService; see Platform endpoints for the request shape.