@dodopayments/opencode-plugin 0.6.0 → 0.6.1

package/skills/dodo-mcp-usage/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: dodo-mcp-usage
+description: How and when to use the Dodo Payments MCP servers (dodo-knowledge for docs search, dodopayments-api for the live API via Code Mode) safely. Use when looking up current Dodo payloads or event names, or inspecting or changing real products, checkouts, customers, subscriptions, webhooks or refunds.
+---
+
+# Using the Dodo Payments MCP servers
+
+The [Dodo Payments agent plugin](https://github.com/dodopayments/dodo-agent-plugin) ships two MCP servers. They do different jobs, so pick the right one before you call anything.
+
+**Prerequisite:** this skill is useful only when the servers are connected. Installing these skills on their own (for example with `npx skills add`) does **not** connect them. Check your tool list for the Dodo tools; if they are missing, install the agent plugin, which registers both servers, or add them by hand as described under [Authentication](#authentication). Without them, fall back to the other skills and the docs at docs.dodopayments.com.
+
+| Server | URL | Auth | Use it for |
+|--------|-----|------|------------|
+| `dodo-knowledge` | `https://knowledge.dodopayments.com/mcp` | None | Semantic search over Dodo Payments docs, API reference and SDK docs |
+| `dodopayments-api` | `https://mcp.dodopayments.com/mcp` | OAuth in the browser, or a local API key | Reading and changing real resources in your Dodo account |
+
+## When to call which
+
+### Call `dodo-knowledge` first, before writing integration code
+
+Your memory of the Dodo API can be stale. Search the docs whenever you need:
+
+- Request and response shapes (for example checkout session fields, subscription plan change params).
+- Webhook event names and payload fields.
+- SDK method names and which endpoints are deprecated.
+- Base URLs (`https://test.dodopayments.com` for test mode, `https://live.dodopayments.com` for live mode).
+
+Prefer a docs result over what you remember. If the docs and your memory disagree, the docs win. Put the framework or language in the query for sharper results, for example "Next.js webhook handler verify signature".
+
+### Call `dodopayments-api` to act on real data
+
+Use it when the task needs the user's actual account:
+
+- List or create products and prices.
+- Create a checkout session to test a flow end to end.
+- Look up a customer, payment or subscription by ID.
+- Inspect or register webhook endpoints.
+- Issue a refund or cancel a subscription (only after confirmation, see Safety).
+
+Don't use the API server to answer "how does X work" questions. That's what `dodo-knowledge` is for.
+
+## How the API server works: Code Mode
+
+The Dodo Payments MCP server uses **Code Mode**. Instead of one tool per endpoint, it exposes two tools:
+
+1. **Docs search**: query the API and SDK documentation.
+2. **Code execution** (`execute`): write TypeScript against the `dodopayments` SDK. It runs in an isolated sandbox with no network or filesystem access, and whatever the code returns or prints comes back as the tool result.
+
+What this means for you:
+
+- Look at the tool list your client exposes for the exact tool names. Don't invent per-endpoint tool names like `create_product`; they don't exist in Code Mode.
+- The API key is injected server-side. You never pass a key in tool parameters, and you shouldn't try to read one from inside the sandbox.
+- Batch related calls into one script and return only what you need (IDs, statuses, counts), not whole objects. One script with 20 calls beats 20 round trips.
+- Search docs (either server) for the SDK method shape before writing the script, then execute.
+
+Typical read-only flow:
+
+1. Search docs for the method, for example "list subscriptions for a customer".
+2. Run a short `execute` script that calls it and returns a trimmed summary.
+3. Report the result to the user.
+
+## Safety rules
+
+These are non-negotiable when the API server is connected.
+
+1. **Default to test mode.** For the local server, `DODO_PAYMENTS_ENVIRONMENT` defaults to `live_mode` when unset, so set `test_mode` explicitly during development. Use `dodo_test_` keys with test mode and `dodo_live_` keys with live mode.
+2. **Know which mode you're in before any write.** With the local server, it is `DODO_PAYMENTS_ENVIRONMENT`. With the remote OAuth server the mode follows the account the user signed in to and is not visible in the tool configuration, so **always ask the user to confirm test or live mode before the first write in a session**. A read can help you check: for example, if the user gives an ID, retrieving it succeeds only in the mode it was created in.
+3. **Read before write.** Retrieve the resource first, show the user what will change, then act.
+4. **Confirm every live mode write with the user**, naming the exact resource ID and the effect. This is mandatory for:
+   - refunds (full or partial),
+   - subscription cancellations and plan changes,
+   - anything that moves money or affects payouts,
+   - deleting or archiving products and discounts,
+   - changing or deleting webhook endpoints.
+5. **Never print secrets.** Don't echo API keys, webhook signing keys, or full card or bank details into chat, logs, or files. Don't return them from `execute` scripts.
+6. **Don't retry writes blindly.** If a create or refund call errors or times out, read the current state first (list refunds for the payment, fetch the subscription) before trying again, so you don't double-refund or create duplicates.
+7. **Least privilege.** Dodo API keys can be created with a read-only access level. For inspection-only work with the local server, suggest a read-only key.
+
+## Authentication
+
+### Remote server (recommended)
+
+The plugin points at `https://mcp.dodopayments.com/mcp`. The first time a tool is called, the client opens a browser window to sign in to Dodo Payments. Finish sign-in there, then retry the call.
+
+Both servers speak Streamable HTTP, so clients connect to the URL directly (no bridge process). Client setup, if the user is wiring it up by hand:
+
+- **Claude Code**: `claude mcp add --transport http dodopayments-api https://mcp.dodopayments.com/mcp`
+- **Cursor and other `.mcp.json` clients**: `{"mcpServers": {"dodopayments-api": {"type": "http", "url": "https://mcp.dodopayments.com/mcp"}}}`
+- **VS Code** (`.vscode/mcp.json` uses a top-level `servers` key): `{"servers": {"dodopayments-api": {"type": "http", "url": "https://mcp.dodopayments.com/mcp"}}}`
+- **Codex CLI**: `codex mcp add dodopayments-api --url https://mcp.dodopayments.com/mcp`, then `codex mcp login dodopayments-api`
+- **Claude.ai**: Settings, Connectors, Add Custom Connector, paste the URL.
+
+`dodo-knowledge` is configured the same way with `https://knowledge.dodopayments.com/mcp` and needs no sign-in.
+
+For a client that cannot dial Streamable HTTP or run MCP OAuth itself, the `mcp-remote` bridge still works as a fallback: run `npx -y mcp-remote@latest https://mcp.dodopayments.com/mcp` as a stdio server.
+
+### Local stdio server
+
+Run the server on the user's machine with an API key:
+
+```json
+{
+  "mcpServers": {
+    "dodopayments_api": {
+      "command": "npx",
+      "args": ["-y", "dodopayments-mcp@latest"],
+      "env": {
+        "DODO_PAYMENTS_API_KEY": "dodo_test_...",
+        "DODO_PAYMENTS_WEBHOOK_KEY": "your_webhook_key",
+        "DODO_PAYMENTS_ENVIRONMENT": "test_mode"
+      }
+    }
+  }
+}
+```
+
+| Variable | Required | Notes |
+|----------|----------|-------|
+| `DODO_PAYMENTS_API_KEY` | Yes | From the dashboard, Developer, API Keys |
+| `DODO_PAYMENTS_WEBHOOK_KEY` | No | Webhook signing key |
+| `DODO_PAYMENTS_ENVIRONMENT` | No | `test_mode` or `live_mode`; defaults to `live_mode` |
+
+The local `execute` tool needs Deno on `PATH` (Deno 2.8 or earlier for now) and works on macOS and Linux only. On Windows, use WSL2 or the remote server. Docs search still works without Deno.
+
+Tell the user to keep the key in their client config or environment, never in a committed file.
+
+## Troubleshooting
+
+**"Needs authentication" or 401 from the remote server**
+The OAuth sign-in hasn't happened or has expired. Ask the user to complete the browser sign-in and retry. If it keeps failing, sign out and back in from the client's MCP menu (for example `/mcp` in Claude Code, `codex mcp login`), then restart the client. Clients that still use the older `mcp-remote` bridge cache tokens in `~/.mcp-auth`; clearing that folder forces a fresh sign-in.
+
+**Authentication errors with the local server**
+The key and environment don't match. A `dodo_test_` key needs `DODO_PAYMENTS_ENVIRONMENT=test_mode`; a `dodo_live_` key needs `live_mode`. If it still fails, have the user generate a new key in the dashboard.
+
+**Empty lists or "not found" for an ID the user just gave you**
+You're probably in the wrong mode. Test mode and live mode data are fully separate. Confirm which mode the ID came from before concluding it doesn't exist.
+
+**`execute` errors locally but docs search works**
+Deno is missing, too new, or you're on Windows. See the local server notes above.
+
+**Tool execution failures**
+Read the API error in the result; it usually names the bad field. Re-check the method shape with `dodo-knowledge`, then fix the script. You can also have the user reproduce the call with curl against `https://test.dodopayments.com` to rule out the MCP layer.
+
+**Rate limiting (429)**
+Slow down, batch work into fewer scripts, and back off before retrying. Don't loop on writes.
+
+## Related skills
+
+- `checkout-integration`: building checkout sessions in app code.
+- `webhook-integration`: verifying and handling webhook events.
+- `testing-and-go-live`: moving from test mode to live mode safely.
+- `dodo-best-practices`: overall integration guidance.

package/skills/framework-adapters/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: framework-adapters
-description: Guide for mounting official @dodopayments/* checkout, portal, and verified-webhook route handlers in supported web frameworks; use domain skills for payment and lifecycle logic.
+description: Official @dodopayments/* framework adapters that mount Checkout, CustomerPortal, and Webhooks route handlers. Use when integrating Dodo Payments into Next.js, Express, Fastify, Hono, Astro, Remix, SvelteKit, Nuxt, TanStack, Bun, or Convex, such as @dodopayments/nextjs; use domain skills for payment and subscription logic.
 ---
 
 # Framework Adapters
@@ -21,10 +21,12 @@ Dodo publishes `@dodopayments/*` packages that wrap the core SDK with framework-
 
 Each adapter exposes three handler families:
 
-- **Checkout:** static (GET only), dynamic (POST with cart), or session (POST with pre-built session).
+- **Checkout:** static (GET only), dynamic (POST, creates a payment or subscription via the deprecated `POST /payments` / `POST /subscriptions` endpoints - existing integrations only), or session (POST with a checkout session payload - use this for new integrations).
 - **CustomerPortal:** generates a time-bound portal session link.
 - **Webhooks:** verifies webhook signatures and dispatches typed events.
 
+> **Security - CustomerPortal does not authenticate.** Every `CustomerPortal` handler opens the portal for whatever `?customer_id=` it receives. Mounted as-is, any visitor can open any customer's portal by guessing or enumerating IDs. Put the route behind your own authentication and resolve the customer ID **server-side from the signed-in session**; never accept it from the client. The portal examples below do this.
+
 **Export names are not uniform across adapters.** Most export `Checkout` / `CustomerPortal` / `Webhooks`, but two differ, and the return shapes differ as well. Check this table before writing imports:
 
 | Adapter | Checkout export | Portal export | Handler shape |
@@ -34,7 +36,7 @@ Each adapter exposes three handler families:
 | `fastify` | `Checkout` | `CustomerPortal` | returns `{ getHandler, postHandler }` |
 | `sveltekit` | `Checkout` | `CustomerPortal` | returns `{ GET, POST }` / `{ GET }` |
 | `nuxt` | `checkoutHandler` (auto-imported) | `customerPortalHandler` | no import statement |
-| `convex` | `DodoPayments` component | — | `createDodoWebhookHandler` |
+| `convex` | `checkout` (from `dodo.api()`) | `customerPortal` (from `dodo.api()`, uses `identify`) | `createDodoWebhookHandler` |
 
 The adapters handle raw body preservation for webhook verification, environment variable mapping, and framework-specific request/response shapes. Checkout payload design belongs to the `checkout-integration` skill; webhook business logic belongs to `webhook-integration`; portal behavior belongs to `customer-management`.
 
@@ -71,7 +73,7 @@ DODO_PAYMENTS_RETURN_URL=https://yourdomain.com/checkout/success
 NUXT_PRIVATE_BEARER_TOKEN=dodo_test_...
 NUXT_PRIVATE_WEBHOOK_KEY=your-webhook-secret
 NUXT_PRIVATE_ENVIRONMENT=test_mode
-NUXT_PRIVATE_RETURNURL=https://yourdomain.com/checkout/success
+NUXT_PRIVATE_RETURN_URL=https://yourdomain.com/checkout/success
 ```
 
 **Convex** uses dashboard environment variables (not local `.env`):
@@ -108,6 +110,7 @@ Defaulting to `test_mode` is deliberate: a missing or misspelled variable must n
 ```typescript
 // app/api/checkout/route.ts
 import { Checkout } from "@dodopayments/nextjs";
+import { dodoEnvironment } from "@/lib/dodo-env";
 
 export const GET = Checkout({
   bearerToken: process.env.DODO_PAYMENTS_API_KEY,
@@ -128,12 +131,26 @@ export const POST = Checkout({
 
 ```typescript
 // app/api/customer-portal/route.ts
+import { NextRequest } from "next/server";
 import { CustomerPortal } from "@dodopayments/nextjs";
+import { dodoEnvironment } from "@/lib/dodo-env";
+// your auth helper
+import { getSessionUser } from "@/lib/auth";
 
-export const GET = CustomerPortal({
+const portal = CustomerPortal({
   bearerToken: process.env.DODO_PAYMENTS_API_KEY,
   environment: dodoEnvironment,
 });
+
+export async function GET(req: NextRequest) {
+  const user = await getSessionUser(req);
+  if (!user?.dodoCustomerId) return new Response("Unauthorized", { status: 401 });
+
+  // Overwrite any client-supplied ?customer_id= with the signed-in user's ID.
+  const url = new URL(req.url);
+  url.searchParams.set("customer_id", user.dodoCustomerId);
+  return portal(new NextRequest(url, req));
+}
 ```
 
 ### Webhooks
@@ -164,6 +181,8 @@ import { checkoutHandler } from "@dodopayments/express";
 import { dodoEnvironment } from "./lib/dodo-env";
 
 const app = express();
+// Required before the POST route: the session/dynamic handlers read req.body.
+app.use(express.json());
 
 app.get("/api/checkout", checkoutHandler({
   bearerToken: process.env.DODO_PAYMENTS_API_KEY,
@@ -182,13 +201,24 @@ app.post("/api/checkout", checkoutHandler({
 
 ### Customer Portal
 
+The adapter's `CustomerPortal` reads `customer_id` from `req.query`, which you cannot safely rewrite in Express 5. Behind your auth middleware, call the SDK directly with the session's customer ID instead:
+
 ```typescript
-import { CustomerPortal } from "@dodopayments/express";
+import DodoPayments from "dodopayments";
+import { dodoEnvironment } from "./lib/dodo-env";
 
-app.get("/api/customer-portal", CustomerPortal({
+const client = new DodoPayments({
   bearerToken: process.env.DODO_PAYMENTS_API_KEY,
   environment: dodoEnvironment,
-}));
+});
+
+// requireAuth = your session middleware; it must set req.user.
+app.get("/api/customer-portal", requireAuth, async (req, res) => {
+  const customerId = req.user?.dodoCustomerId; // from the session, never from req.query
+  if (!customerId) return res.status(401).send("Unauthorized");
+  const session = await client.customers.customerPortal.create(customerId);
+  res.redirect(session.link);
+});
 ```
 
 ### Webhooks
@@ -196,7 +226,10 @@ app.get("/api/customer-portal", CustomerPortal({
 ```typescript
 import { Webhooks } from "@dodopayments/express";
 
-app.use(express.raw({ type: "application/json" }));
+// The Express handler verifies the signature against the PARSED req.body, so it
+// needs express.json() (skip this line if already registered). Do NOT use express.raw() here - the
+// handler would see a Buffer and reject every request.
+app.use(express.json());
 
 app.post("/api/webhook", Webhooks({
   webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
@@ -269,6 +302,7 @@ fastify.post("/api/webhook", Webhooks({
 ```typescript
 import { Hono } from "hono";
 import { Checkout } from "@dodopayments/hono";
+import { dodoEnvironment } from "./lib/dodo-env";
 
 const app = new Hono();
 
@@ -289,13 +323,24 @@ app.post("/api/checkout", Checkout({
 
 ### Customer Portal
 
+The adapter's `CustomerPortal` reads `c.req.query("customer_id")`. Behind your auth middleware, call the SDK directly with the session's customer ID instead:
+
 ```typescript
-import { CustomerPortal } from "@dodopayments/hono";
+import DodoPayments from "dodopayments";
+import { dodoEnvironment } from "./lib/dodo-env";
 
-app.get("/api/customer-portal", CustomerPortal({
+const client = new DodoPayments({
   bearerToken: process.env.DODO_PAYMENTS_API_KEY,
   environment: dodoEnvironment,
-}));
+});
+
+// Assumes your auth middleware ran first and stored the user on the context.
+app.get("/api/customer-portal", async (c) => {
+  const customerId = c.get("user")?.dodoCustomerId; // from the session, never from the query
+  if (!customerId) return c.text("Unauthorized", 401);
+  const session = await client.customers.customerPortal.create(customerId);
+  return c.redirect(session.link);
+});
 ```
 
 ### Webhooks
@@ -373,6 +418,7 @@ export const POST = Webhooks({
 // app/routes/api.checkout.tsx
 import { Checkout } from "@dodopayments/remix";
 import type { LoaderFunctionArgs, ActionFunctionArgs } from "@remix-run/node";
+import { dodoEnvironment } from "~/lib/dodo-env";
 
 const checkoutHandler = Checkout({
   bearerToken: process.env.DODO_PAYMENTS_API_KEY,
@@ -391,13 +437,24 @@ export const action = ({ request }: ActionFunctionArgs) => checkoutHandler(reque
 // app/routes/api.customer-portal.tsx
 import { CustomerPortal } from "@dodopayments/remix";
 import type { LoaderFunctionArgs } from "@remix-run/node";
+import { dodoEnvironment } from "~/lib/dodo-env";
+// your auth helper
+import { getSessionUser } from "~/lib/auth.server";
 
 const portalHandler = CustomerPortal({
   bearerToken: process.env.DODO_PAYMENTS_API_KEY,
   environment: dodoEnvironment,
 });
 
-export const loader = ({ request }: LoaderFunctionArgs) => portalHandler(request);
+export const loader = async ({ request }: LoaderFunctionArgs) => {
+  const user = await getSessionUser(request);
+  if (!user?.dodoCustomerId) return new Response("Unauthorized", { status: 401 });
+
+  // Overwrite any client-supplied ?customer_id= with the signed-in user's ID.
+  const url = new URL(request.url);
+  url.searchParams.set("customer_id", user.dodoCustomerId);
+  return portalHandler(new Request(url, request));
+};
 ```
 
 ### Webhooks
@@ -428,15 +485,26 @@ export const action = ({ request }: ActionFunctionArgs) =>
 import { Checkout } from "@dodopayments/sveltekit";
 import { DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_RETURN_URL, DODO_PAYMENTS_ENVIRONMENT } from "$env/static/private";
 
-const checkoutHandler = Checkout({
+const dodoEnvironment = DODO_PAYMENTS_ENVIRONMENT === "live_mode" ? "live_mode" : "test_mode";
+
+// Checkout() returns { GET, POST }, not a handler. Export GET from a "static"
+// handler - the GET of a "session"/"dynamic" handler returns 400.
+const staticCheckout = Checkout({
+  bearerToken: DODO_PAYMENTS_API_KEY,
+  returnUrl: DODO_PAYMENTS_RETURN_URL,
+  environment: dodoEnvironment,
+  type: "static",
+});
+
+const sessionCheckout = Checkout({
   bearerToken: DODO_PAYMENTS_API_KEY,
   returnUrl: DODO_PAYMENTS_RETURN_URL,
-  environment: DODO_PAYMENTS_ENVIRONMENT,
+  environment: dodoEnvironment,
   type: "session",
 });
 
-export const GET = checkoutHandler;
-export const POST = checkoutHandler;
+export const GET = staticCheckout.GET;
+export const POST = sessionCheckout.POST;
 ```
 
 ### Webhooks
@@ -469,7 +537,7 @@ export default defineNuxtConfig({
       bearerToken: process.env.NUXT_PRIVATE_BEARER_TOKEN,
       webhookKey: process.env.NUXT_PRIVATE_WEBHOOK_KEY,
       environment: process.env.NUXT_PRIVATE_ENVIRONMENT,
-      returnUrl: process.env.NUXT_PRIVATE_RETURNURL,
+      returnUrl: process.env.NUXT_PRIVATE_RETURN_URL,
     },
   },
 });
@@ -518,7 +586,8 @@ export default Webhooks({
 ```typescript
 // src/routes/api/checkout.ts
 import { Checkout } from "@dodopayments/tanstack";
-import { dodoEnvironment } from "./lib/dodo-env";
+// src/lib/dodo-env.ts
+import { dodoEnvironment } from "../../lib/dodo-env";
 
 export const GET = Checkout({
   bearerToken: process.env.DODO_PAYMENTS_API_KEY,
@@ -545,6 +614,9 @@ TanStack Start's server-route definition API has changed across releases (`creat
 
 ```typescript
 import { Checkout, CustomerPortal } from "@dodopayments/bun";
+import { dodoEnvironment } from "./lib/dodo-env";
+// your auth helper
+import { getSessionUser } from "./lib/auth";
 
 const checkoutHandler = Checkout({
   bearerToken: process.env.DODO_PAYMENTS_API_KEY,
@@ -560,14 +632,18 @@ const portalHandler = CustomerPortal({
 
 Bun.serve({
   port: 3000,
-  fetch(request) {
+  async fetch(request) {
     const url = new URL(request.url);
 
     if (url.pathname === "/api/checkout") {
       return checkoutHandler(request);
     }
     if (url.pathname === "/api/customer-portal" && request.method === "GET") {
-      return portalHandler(request);
+      const user = await getSessionUser(request);
+      if (!user?.dodoCustomerId) return new Response("Unauthorized", { status: 401 });
+      // Overwrite any client-supplied ?customer_id= with the signed-in user's ID.
+      url.searchParams.set("customer_id", user.dodoCustomerId);
+      return portalHandler(new Request(url, request));
     }
 
     return new Response("Not Found", { status: 404 });
@@ -591,20 +667,74 @@ app.use(dodopayments);
 export default app;
 ```
 
-Then use the component in your actions and HTTP routes:
+Run `npx convex dev` once to generate `components.dodopayments`. `identify` needs an app-owned lookup from the signed-in user to their Dodo customer ID. This assumes a `customers` table with `authId` and `dodoCustomerId` fields and a `by_auth_id` index; adapt it to your schema:
+
+```typescript
+// convex/customers.ts
+import { internalQuery } from "./_generated/server";
+import { v } from "convex/values";
+
+export const getByAuthId = internalQuery({
+  args: { authId: v.string() },
+  handler: async (ctx, { authId }) =>
+    ctx.db
+      .query("customers")
+      .withIndex("by_auth_id", (q) => q.eq("authId", authId))
+      .unique(),
+});
+```
+
+Then create a `DodoPayments` client in a local module and export its API methods:
 
 ```typescript
-// convex/checkout.ts
-import { mutation } from "./_generated/server";
-import { components } from "./_generated/server";
-
-export const createCheckoutSession = mutation({
-  args: { customerId: v.string() },
-  handler: async (ctx, args) => {
-    const dodo = components.dodopayments;
-    return dodo.checkout.createSession(ctx, {
-      customerId: args.customerId,
-      // ... checkout params
+// convex/dodo.ts
+import { DodoPayments } from "@dodopayments/convex";
+import { components, internal } from "./_generated/api";
+
+const apiKey = process.env.DODO_PAYMENTS_API_KEY;
+if (!apiKey) throw new Error("DODO_PAYMENTS_API_KEY is not set");
+
+export const dodo = new DodoPayments(components.dodopayments, {
+  // Maps the signed-in Convex user to a Dodo customer; used by customerPortal.
+  identify: async (ctx) => {
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity) return null;
+    const customer = await ctx.runQuery(internal.customers.getByAuthId, {
+      authId: identity.subject,
+    });
+    return customer ? { dodoCustomerId: customer.dodoCustomerId } : null;
+  },
+  apiKey,
+  environment: process.env.DODO_PAYMENTS_ENVIRONMENT === "live_mode" ? "live_mode" : "test_mode",
+});
+
+export const { checkout, customerPortal } = dodo.api();
+```
+
+Call `checkout` from an **action** (mutations cannot make network calls), passing the checkout session fields in `payload`. The client sends a plan slug; the server maps it to a product ID and owns the return URL, so a caller cannot pick an arbitrary product or redirect target:
+
+```typescript
+// convex/payments.ts
+import { action } from "./_generated/server";
+import { v } from "convex/values";
+import { checkout } from "./dodo";
+
+// Public plan slug -> Dodo product ID. Never accept a product_id from the client.
+const PRODUCT_IDS: Readonly<Record<string, string>> = {
+  starter: "pdt_starter_monthly",
+  pro: "pdt_pro_monthly",
+};
+
+export const createCheckout = action({
+  args: { plan: v.string() },
+  handler: async (ctx, { plan }) => {
+    if (!Object.hasOwn(PRODUCT_IDS, plan)) throw new Error(`Unknown plan: ${plan}`);
+    // Returns { checkout_url }
+    return await checkout(ctx, {
+      payload: {
+        product_cart: [{ product_id: PRODUCT_IDS[plan], quantity: 1 }],
+        return_url: process.env.DODO_PAYMENTS_RETURN_URL,
+      },
     });
   },
 });
@@ -618,7 +748,7 @@ Convex only supports session checkout, not static or dynamic modes.
 
 2. **Wrong webhook variable name:** Check whether your adapter uses `DODO_PAYMENTS_WEBHOOK_KEY` or `DODO_PAYMENTS_WEBHOOK_SECRET`. The docs are inconsistent; use the name your adapter actually references.
 
-3. **Forgetting raw body preservation:** Webhook handlers must receive the raw request body, not a re-parsed JSON object. Fastify requires an explicit string body parser; Express needs `express.raw()`; other frameworks handle this automatically. Webhook signature verification is covered in the `webhook-integration` skill.
+3. **Forgetting raw body preservation:** Webhook handlers must receive the raw request body, not a re-parsed JSON object. Fastify requires an explicit string body parser; other frameworks handle this automatically. **Express is the exception:** its `Webhooks` handler verifies against the parsed `req.body`, so register `express.json()` before the route and do not use `express.raw()`, which makes every verification fail. Webhook signature verification is covered in the `webhook-integration` skill.
 
 4. **Mixing framework conventions:** Each framework has its own request/response shape. Don't try to use a Next.js handler in Express or vice versa. Use the adapter for your framework.
 
@@ -626,7 +756,9 @@ Convex only supports session checkout, not static or dynamic modes.
 
 6. **Skipping environment setup:** The adapters won't work without `DODO_PAYMENTS_API_KEY` and `DODO_PAYMENTS_ENVIRONMENT`. Set these before testing.
 
-7. **Using `@dodopayments/core` directly:** The core package is an internal dependency, not a documented public entry point. Use the framework adapter for your stack.
+7. **Exposing CustomerPortal unauthenticated:** The portal handlers trust `?customer_id=` from the request. Resolve the ID from the signed-in session on the server, as in the examples above, or anyone can open any customer's portal.
+
+8. **Using `@dodopayments/core` directly:** The core package is an internal dependency, not a documented public entry point. Use the framework adapter for your stack.
 
 ## Resources