@dodopayments/opencode-plugin 0.3.2 → 0.4.0

package/skills/checkout-integration/SKILL.md

@@ -1,140 +1,287 @@
 ---
 name: checkout-integration
-description: Guide for creating checkout sessions and payment flows with Dodo Payments - one-time, subscriptions, and overlay checkout.
+description: Guide for starting hosted Checkout Sessions, payment links, and overlay or inline checkout for one-time and recurring products; use subscription-integration for post-checkout lifecycle management.
 ---
 
 # Dodo Payments Checkout Integration
 
-**Reference: [docs.dodopayments.com/developer-resources/integration-guide](https://docs.dodopayments.com/developer-resources/integration-guide)**
+Use `client.checkoutSessions.create(...)` to build hosted checkout pages or overlay checkout modals. This is the recommended path for all new payment integrations.
 
-Create seamless payment experiences with hosted checkout pages or overlay checkout modals.
+## When to use this skill
+
+- Build a one-time payment checkout flow
+- Create a subscription checkout with optional trial
+- Embed checkout in an overlay or inline modal
+- Collect customer billing info and custom fields at checkout
+- Apply discount codes or handle currency selection
+- Redirect customers after payment completes
 
 ---
 
 ## Checkout Methods
 
-| Method | Best For | Integration |
-|--------|----------|-------------|
-| **Hosted Checkout** | Simple integration, full-page redirect | Server-side SDK |
-| **Overlay Checkout** | Seamless UX, stays on your site | JavaScript SDK |
-| **Payment Links** | No-code, shareable links | Dashboard |
+Dodo Payments offers three ways to collect payment:
+
+| Method | Best For | Setup |
+|--------|----------|-------|
+| **Checkout Sessions** (recommended) | Most integrations; full control | Server-side SDK call |
+| **Static Payment Links** | No-code sharing; reusable URLs | Dashboard or direct URL |
+| **Overlay/Inline Checkout** | Checkout stays on your site | Client-side SDK |
+
+**Legacy:** Dynamic Payment Links created via `POST /payments` or `POST /subscriptions` are deprecated. Use Checkout Sessions instead.
 
 ---
 
-## Hosted Checkout
+## Core Concepts
+
+**Amounts in smallest currency unit:** All prices are in cents (or equivalent). A $10 USD charge is `1000`.
+
+**Checkout Session:** A single-use session that generates a hosted checkout URL. Expires after 24 hours (or 15 minutes if `confirm=true`).
+
+**Return URL:** Where the customer lands after payment. Query parameters include `status=success` and `session_id`.
+
+**Entitlement on webhook:** The browser redirect is not the source of truth. Always verify payment via webhook before granting access. See `webhook-integration` skill for verification.
+
+---
 
-### Basic Implementation
+## Create a Checkout Session
+
+### Basic One-Time Payment
 
 ```typescript
 import DodoPayments from 'dodopayments';
 
 const client = new DodoPayments({
   bearerToken: process.env.DODO_PAYMENTS_API_KEY,
+  environment: 'test_mode', // or 'live_mode'
 });
 
-// Create checkout session
 const session = await client.checkoutSessions.create({
   product_cart: [
-    { product_id: 'prod_xxxxx', quantity: 1 }
+    { product_id: 'pdt_example', quantity: 1 }
   ],
   customer: {
     email: 'customer@example.com',
-    name: 'John Doe',
+    name: 'Jane Doe'
   },
-  return_url: 'https://yoursite.com/checkout/success',
+  return_url: 'https://yoursite.com/checkout/success'
 });
 
-// Redirect customer to checkout
-// session.checkout_url
+console.log('Redirect to:', session.checkout_url);
 ```
 
+Response fields:
+- `session_id`: Unique checkout session ID
+- `checkout_url`: Hosted checkout URL (redirect customer here). Nullable when `confirm=true`
+- `client_secret`: Present only if `confirm=true`
+- `publishable_key`: Present only if `confirm=true`. Pair it with `client_secret` for the inline SDK flow
+- `payment_id`: Present only if `confirm=true`
+
+`publishable_key` is a per-session value returned for confirm-mode inline checkout. It is not a Stripe-style
+publishable *API key* — Dodo issues no such credential, and every API key is secret and server-side only.
+
 ### With Multiple Products
 
 ```typescript
 const session = await client.checkoutSessions.create({
   product_cart: [
-    { product_id: 'prod_item_1', quantity: 2 },
-    { product_id: 'prod_item_2', quantity: 1 },
+    { product_id: 'pdt_item_1', quantity: 2 },
+    { product_id: 'pdt_item_2', quantity: 1 }
+  ],
+  customer: { email: 'customer@example.com' },
+  return_url: 'https://yoursite.com/success'
+});
+```
+
+### With Existing Customer
+
+```typescript
+const session = await client.checkoutSessions.create({
+  product_cart: [
+    { product_id: 'pdt_example', quantity: 1 }
+  ],
+  customer: { customer_id: 'cus_existing_id' },
+  return_url: 'https://yoursite.com/success'
+});
+```
+
+### With Billing Address and Tax ID
+
+```typescript
+const session = await client.checkoutSessions.create({
+  product_cart: [
+    { product_id: 'pdt_example', quantity: 1 }
   ],
   customer: {
     email: 'customer@example.com',
+    name: 'Jane Doe'
   },
-  return_url: 'https://yoursite.com/success',
+  billing_address: {
+    country: 'US',
+    street: '123 Main St',
+    city: 'San Francisco',
+    state: 'CA',
+    zipcode: '94105'
+  },
+  tax_id: 'VAT123456789',
+  customer_business_name: 'Acme Corp',
+  return_url: 'https://yoursite.com/success'
 });
 ```
 
-### With Customer ID (Existing Customer)
+### With Discount Codes
 
 ```typescript
 const session = await client.checkoutSessions.create({
   product_cart: [
-    { product_id: 'prod_xxxxx', quantity: 1 }
+    { product_id: 'pdt_example', quantity: 1 }
   ],
-  customer_id: 'cust_existing_customer',
-  return_url: 'https://yoursite.com/success',
+  customer: { email: 'customer@example.com' },
+  discount_codes: ['PROMO10', 'WELCOME5'], // max 20, ordered
+  feature_flags: {
+    allow_discount_code: true
+  },
+  return_url: 'https://yoursite.com/success'
 });
 ```
 
-### With Metadata
+### With Subscription and Trial
 
 ```typescript
 const session = await client.checkoutSessions.create({
   product_cart: [
-    { product_id: 'prod_xxxxx', quantity: 1 }
+    { product_id: 'pdt_monthly_subscription', quantity: 1 }
   ],
-  customer: {
-    email: 'customer@example.com',
+  subscription_data: {
+    trial_period_days: 14
   },
+  customer: { email: 'subscriber@example.com' },
+  return_url: 'https://yoursite.com/success'
+});
+```
+
+### With Custom Fields
+
+```typescript
+const session = await client.checkoutSessions.create({
+  product_cart: [
+    { product_id: 'pdt_example', quantity: 1 }
+  ],
+  customer: { email: 'customer@example.com' },
+  custom_fields: [
+    {
+      key: 'company_size',
+      label: 'Company Size',
+      field_type: 'dropdown',
+      options: ['1-10', '11-50', '51-200', '200+'],
+      required: true
+    },
+    {
+      key: 'use_case',
+      label: 'Primary Use Case',
+      field_type: 'text',
+      placeholder: 'e.g., analytics, reporting',
+      required: false
+    }
+  ],
+  return_url: 'https://yoursite.com/success'
+});
+```
+
+### With Metadata
+
+```typescript
+const session = await client.checkoutSessions.create({
+  product_cart: [
+    { product_id: 'pdt_example', quantity: 1 }
+  ],
+  customer: { email: 'customer@example.com' },
   metadata: {
     order_id: 'order_12345',
     referral_code: 'FRIEND20',
-    user_id: 'internal_user_id',
+    campaign: 'summer_sale'
   },
-  return_url: 'https://yoursite.com/success',
+  return_url: 'https://yoursite.com/success'
 });
 ```
 
 ---
 
-## Next.js Implementation
+## Next.js App Router
 
 ### API Route
 
 ```typescript
 // app/api/checkout/route.ts
-import { NextRequest, NextResponse } from 'next/server';
+import { NextResponse } from 'next/server';
 import DodoPayments from 'dodopayments';
+import { getCurrentUser } from '@/lib/auth';
 
 const client = new DodoPayments({
   bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
+  environment: process.env.NODE_ENV === 'production' ? 'live_mode' : 'test_mode'
 });
 
-export async function POST(req: NextRequest) {
+type PlanId = 'starter' | 'pro';
+
+const PRODUCT_IDS: Record<PlanId, string> = {
+  starter: 'pdt_starter_monthly',
+  pro: 'pdt_pro_monthly'
+};
+
+function productIdForPlan(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  return PRODUCT_IDS[value as PlanId] ?? null;
+}
+
+export async function POST(request: Request) {
+  const user = await getCurrentUser();
+  if (!user) {
+    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
+  }
+
+  let body: unknown;
   try {
-    const { productId, quantity = 1, email, name, metadata } = await req.json();
+    body = await request.json();
+  } catch {
+    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
+  }
 
-    if (!productId || !email) {
-      return NextResponse.json(
-        { error: 'Missing required fields' },
-        { status: 400 }
-      );
-    }
+  if (!body || typeof body !== 'object') {
+    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
+  }
+
+  const input = body as { planId?: unknown; quantity?: unknown };
+  const productId = productIdForPlan(input.planId);
+  const quantity = input.quantity ?? 1;
 
+  if (!productId) {
+    return NextResponse.json({ error: 'Unknown plan' }, { status: 400 });
+  }
+
+  if (!Number.isInteger(quantity) || (quantity as number) < 1) {
+    return NextResponse.json(
+      { error: 'Quantity must be a positive integer' },
+      { status: 400 }
+    );
+  }
+
+  try {
     const session = await client.checkoutSessions.create({
-      product_cart: [{ product_id: productId, quantity }],
-      customer: { email, name },
-      metadata,
-      return_url: `${process.env.NEXT_PUBLIC_APP_URL}/checkout/success`,
+      product_cart: [{ product_id: productId, quantity: quantity as number }],
+      customer: { email: user.email, name: user.name },
+      metadata: { app_user_id: user.id },
+      return_url: `${process.env.NEXT_PUBLIC_APP_URL}/checkout/success`
     });
 
-    return NextResponse.json({ 
+    return NextResponse.json({
       checkoutUrl: session.checkout_url,
-      sessionId: session.checkout_session_id,
+      sessionId: session.session_id
     });
-  } catch (error: any) {
+  } catch (error) {
     console.error('Checkout error:', error);
     return NextResponse.json(
-      { error: error.message || 'Failed to create checkout' },
+      { error: 'Failed to create checkout' },
       { status: 500 }
     );
   }
@@ -150,32 +297,30 @@ export async function POST(req: NextRequest) {
 import { useState } from 'react';
 
 interface CheckoutButtonProps {
-  productId: string;
-  email: string;
-  name?: string;
+  planId: 'starter' | 'pro';
+  quantity?: number;
   children: React.ReactNode;
 }
 
-export function CheckoutButton({ productId, email, name, children }: CheckoutButtonProps) {
+export function CheckoutButton({ planId, quantity = 1, children }: CheckoutButtonProps) {
   const [loading, setLoading] = useState(false);
 
   const handleCheckout = async () => {
     setLoading(true);
-    
     try {
       const response = await fetch('/api/checkout', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ productId, email, name }),
+        body: JSON.stringify({ planId, quantity })
       });
 
-      const data = await response.json();
-      
-      if (data.checkoutUrl) {
-        window.location.href = data.checkoutUrl;
-      } else {
-        throw new Error(data.error || 'Failed to create checkout');
+      if (!response.ok) {
+        throw new Error('Failed to create checkout');
       }
+
+      const data = (await response.json()) as { checkoutUrl?: string };
+      if (!data.checkoutUrl) throw new Error('Checkout URL was not returned');
+      window.location.href = data.checkoutUrl;
     } catch (error) {
       console.error('Checkout error:', error);
       alert('Failed to start checkout. Please try again.');
@@ -201,9 +346,9 @@ import { Suspense } from 'react';
 function SuccessContent() {
   return (
     <div className="text-center py-20">
-      <h1 className="text-3xl font-bold">Payment Successful!</h1>
+      <h1 className="text-3xl font-bold">Payment Successful</h1>
       <p className="mt-4 text-gray-600">
-        Thank you for your purchase. You will receive a confirmation email shortly.
+        Thank you for your purchase. Check your email for a confirmation.
       </p>
       <a href="/" className="mt-8 inline-block text-blue-600 hover:underline">
         Return to Home
@@ -223,148 +368,99 @@ export default function SuccessPage() {
 
 ---
 
-## Overlay Checkout
-
-Embed checkout directly on your page without redirects.
-
-### Installation
-
-```bash
-npm install @dodopayments/checkout
-```
-
-### Basic Usage
+## Express.js
 
 ```typescript
-import { DodoCheckout } from '@dodopayments/checkout';
+import express from 'express';
+import DodoPayments from 'dodopayments';
+import { getCurrentUser } from './auth';
+import { fulfillOneTimePurchase, grantSubscriptionAccess } from './entitlements';
 
-// Initialize
-const checkout = new DodoCheckout({
-  apiKey: 'your_publishable_key',
-  environment: 'live', // or 'test'
-});
+const app = express();
 
-// Open overlay
-checkout.open({
-  productId: 'prod_xxxxx',
-  customer: {
-    email: 'customer@example.com',
-  },
-  onSuccess: (result) => {
-    console.log('Payment successful:', result);
-    // Handle success
-  },
-  onClose: () => {
-    console.log('Checkout closed');
-  },
+const client = new DodoPayments({
+  bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
+  environment: process.env.NODE_ENV === 'production' ? 'live_mode' : 'test_mode'
 });
-```
 
-### React Component
+// Mount the webhook before express.json() so verification receives signed bytes.
+app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
+  try {
+    const event = client.webhooks.unwrap(req.body.toString('utf8'), {
+      headers: {
+        'webhook-id': req.headers['webhook-id'] as string,
+        'webhook-signature': req.headers['webhook-signature'] as string,
+        'webhook-timestamp': req.headers['webhook-timestamp'] as string
+      }
+    });
 
-```typescript
-// components/OverlayCheckout.tsx
-'use client';
+    if (event.type === 'payment.succeeded') {
+      // This branch fulfills one-time purchases only.
+      await fulfillOneTimePurchase(event.data.customer.customer_id);
+    } else if (event.type === 'subscription.active') {
+      // Subscription access starts only after this verified event.
+      await grantSubscriptionAccess(event.data);
+    }
 
-import { useEffect, useRef } from 'react';
-import { DodoCheckout } from '@dodopayments/checkout';
+    res.json({ received: true });
+  } catch (error) {
+    console.error('Webhook verification failed:', error);
+    res.status(401).json({ error: 'Invalid signature' });
+  }
+});
 
-interface OverlayCheckoutProps {
-  productId: string;
-  email: string;
-  onSuccess?: (result: any) => void;
-  children: React.ReactNode;
-}
+app.use(express.json());
 
-export function OverlayCheckout({ 
-  productId, 
-  email, 
-  onSuccess,
-  children 
-}: OverlayCheckoutProps) {
-  const checkoutRef = useRef<DodoCheckout | null>(null);
-
-  useEffect(() => {
-    checkoutRef.current = new DodoCheckout({
-      apiKey: process.env.NEXT_PUBLIC_DODO_PUBLISHABLE_KEY!,
-      environment: process.env.NODE_ENV === 'production' ? 'live' : 'test',
-    });
+type PlanId = 'starter' | 'pro';
 
-    return () => {
-      checkoutRef.current?.close();
-    };
-  }, []);
-
-  const handleClick = () => {
-    checkoutRef.current?.open({
-      productId,
-      customer: { email },
-      onSuccess: (result) => {
-        onSuccess?.(result);
-        // Optionally redirect
-        window.location.href = '/checkout/success';
-      },
-      onClose: () => {
-        console.log('Checkout closed');
-      },
-    });
-  };
+const PRODUCT_IDS: Record<PlanId, string> = {
+  starter: 'pdt_starter_monthly',
+  pro: 'pdt_pro_monthly'
+};
 
-  return (
-    <button onClick={handleClick}>
-      {children}
-    </button>
-  );
+function productIdForPlan(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  return PRODUCT_IDS[value as PlanId] ?? null;
 }
-```
-
-### Customization
 
-```typescript
-checkout.open({
-  productId: 'prod_xxxxx',
-  customer: { email: 'customer@example.com' },
-  theme: {
-    primaryColor: '#0066FF',
-    backgroundColor: '#FFFFFF',
-    fontFamily: 'Inter, sans-serif',
-  },
-  locale: 'en',
-});
-```
-
----
-
-## Express.js Implementation
+app.post('/api/checkout', async (req, res) => {
+  const user = await getCurrentUser(req);
+  if (!user) {
+    res.status(401).json({ error: 'Not authenticated' });
+    return;
+  }
 
-```typescript
-import express from 'express';
-import DodoPayments from 'dodopayments';
+  const { planId, quantity = 1 } = req.body as {
+    planId?: unknown;
+    quantity?: unknown;
+  };
+  const productId = productIdForPlan(planId);
 
-const app = express();
-app.use(express.json());
+  if (!productId) {
+    res.status(400).json({ error: 'Unknown plan' });
+    return;
+  }
 
-const client = new DodoPayments({
-  bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
-});
+  if (!Number.isInteger(quantity) || (quantity as number) < 1) {
+    res.status(400).json({ error: 'Quantity must be a positive integer' });
+    return;
+  }
 
-app.post('/api/create-checkout', async (req, res) => {
   try {
-    const { productId, email, name, quantity = 1 } = req.body;
-
     const session = await client.checkoutSessions.create({
-      product_cart: [{ product_id: productId, quantity }],
-      customer: { email, name },
-      return_url: `${process.env.APP_URL}/success`,
+      product_cart: [{ product_id: productId, quantity: quantity as number }],
+      customer: { email: user.email, name: user.name },
+      metadata: { app_user_id: user.id },
+      return_url: `${process.env.APP_URL}/success`
     });
 
     res.json({ checkoutUrl: session.checkout_url });
-  } catch (error: any) {
-    res.status(500).json({ error: error.message });
+  } catch (error) {
+    console.error('Checkout error:', error);
+    res.status(500).json({ error: 'Failed to create checkout' });
   }
 });
 
-// Success page route
 app.get('/success', (req, res) => {
   res.send('Payment successful!');
 });
@@ -372,228 +468,383 @@ app.get('/success', (req, res) => {
 
 ---
 
-## Python Implementation
-
-### FastAPI
+## Python (FastAPI)
 
 ```python
-from fastapi import FastAPI, HTTPException
-from pydantic import BaseModel
-from dodopayments import DodoPayments
+import logging
 import os
+from typing import Annotated, Literal
+
+from dodopayments import DodoPayments
+from fastapi import Depends, FastAPI, HTTPException
+from pydantic import BaseModel, Field
+
+from app.auth import User, get_current_user
 
 app = FastAPI()
-client = DodoPayments(bearer_token=os.environ["DODO_PAYMENTS_API_KEY"])
+logger = logging.getLogger(__name__)
+client = DodoPayments(
+    bearer_token=os.environ["DODO_PAYMENTS_API_KEY"],
+    environment="test_mode"
+)
+
+PRODUCT_IDS = {
+    "starter": "pdt_starter_monthly",
+    "pro": "pdt_pro_monthly",
+}
 
 class CheckoutRequest(BaseModel):
-    product_id: str
-    email: str
-    name: str = None
-    quantity: int = 1
+    plan_id: Literal["starter", "pro"]
+    quantity: int = Field(default=1, gt=0)
 
 @app.post("/api/checkout")
-async def create_checkout(request: CheckoutRequest):
+async def create_checkout(
+    request: CheckoutRequest,
+    user: Annotated[User, Depends(get_current_user)],
+):
     try:
         session = client.checkout_sessions.create(
             product_cart=[{
-                "product_id": request.product_id,
+                "product_id": PRODUCT_IDS[request.plan_id],
                 "quantity": request.quantity
             }],
             customer={
-                "email": request.email,
-                "name": request.name
+                "email": user.email,
+                "name": user.name
             },
+            metadata={"app_user_id": user.id},
             return_url=f"{os.environ['APP_URL']}/success"
         )
-        
         return {"checkout_url": session.checkout_url}
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e))
+    except Exception as error:
+        logger.exception("Checkout session creation failed")
+        raise HTTPException(status_code=500, detail="Failed to create checkout") from error
 ```
 
-### Flask
+---
 
-```python
-from flask import Flask, request, jsonify
-from dodopayments import DodoPayments
-import os
+## Overlay Checkout
+
+Use the `dodopayments-checkout` package for overlay or inline checkout that stays on your site.
+
+### Installation
 
-app = Flask(__name__)
-client = DodoPayments(bearer_token=os.environ["DODO_PAYMENTS_API_KEY"])
-
-@app.route('/api/checkout', methods=['POST'])
-def create_checkout():
-    data = request.json
-    
-    session = client.checkout_sessions.create(
-        product_cart=[{
-            "product_id": data['product_id'],
-            "quantity": data.get('quantity', 1)
-        }],
-        customer={
-            "email": data['email'],
-            "name": data.get('name')
-        },
-        return_url=f"{os.environ['APP_URL']}/success"
-    )
-    
-    return jsonify({"checkout_url": session.checkout_url})
+```bash
+npm install dodopayments-checkout
 ```
 
----
+### Server Route
+
+Create the Checkout Session on the server. The browser sends a public plan slug, while the server derives
+the customer from the authenticated user and maps the slug to an allowlisted product id.
 
-## Go Implementation
+```typescript
+// app/api/overlay-checkout/route.ts
+import { NextResponse } from 'next/server';
+import DodoPayments from 'dodopayments';
+import { getCurrentUser } from '@/lib/auth';
+
+const client = new DodoPayments({
+  bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
+  environment: process.env.NODE_ENV === 'production' ? 'live_mode' : 'test_mode'
+});
 
-```go
-package main
+type PlanId = 'starter' | 'pro';
 
-import (
-    "encoding/json"
-    "net/http"
-    "os"
-    
-    "github.com/dodopayments/dodopayments-go"
-)
+const PRODUCT_IDS: Record<PlanId, string> = {
+  starter: 'pdt_starter_monthly',
+  pro: 'pdt_pro_monthly'
+};
 
-var client = dodopayments.NewClient(
-    option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
-)
+export async function POST(request: Request) {
+  const user = await getCurrentUser();
+  if (!user) {
+    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
+  }
 
-type CheckoutRequest struct {
-    ProductID string `json:"product_id"`
-    Email     string `json:"email"`
-    Name      string `json:"name"`
-    Quantity  int    `json:"quantity"`
+  let body: unknown;
+  try {
+    body = await request.json();
+  } catch {
+    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
+  }
+
+  if (!body || typeof body !== 'object') {
+    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
+  }
+
+  const { planId, quantity = 1 } = body as {
+    planId?: unknown;
+    quantity?: unknown;
+  };
+  const productId = typeof planId === 'string'
+    ? PRODUCT_IDS[planId as PlanId]
+    : undefined;
+
+  if (!productId) {
+    return NextResponse.json({ error: 'Unknown plan' }, { status: 400 });
+  }
+
+  if (!Number.isInteger(quantity) || (quantity as number) < 1) {
+    return NextResponse.json(
+      { error: 'Quantity must be a positive integer' },
+      { status: 400 }
+    );
+  }
+
+  try {
+    const session = await client.checkoutSessions.create({
+      product_cart: [{ product_id: productId, quantity: quantity as number }],
+      customer: { email: user.email, name: user.name },
+      metadata: { app_user_id: user.id },
+      return_url: `${process.env.NEXT_PUBLIC_APP_URL}/checkout/success`
+    });
+
+    if (!session.checkout_url) {
+      return NextResponse.json({ error: 'Checkout URL was not returned' }, { status: 502 });
+    }
+
+    return NextResponse.json({ checkoutUrl: session.checkout_url });
+  } catch (error) {
+    console.error('Overlay checkout error:', error);
+    return NextResponse.json({ error: 'Failed to create checkout' }, { status: 500 });
+  }
+}
+```
+
+### Browser Overlay and Inline Modes
+
+Browser code calls the server route and receives only the checkout URL. The Dodo Payments API bearer token
+stays in the server route and is never sent to the browser.
+
+```typescript
+// lib/open-checkout.ts
+import { DodoPayments } from 'dodopayments-checkout';
+
+type PlanId = 'starter' | 'pro';
+
+async function createCheckoutUrl(planId: PlanId, quantity = 1): Promise<string> {
+  const response = await fetch('/api/overlay-checkout', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ planId, quantity })
+  });
+
+  if (!response.ok) throw new Error('Failed to create checkout');
+
+  const data = (await response.json()) as { checkoutUrl?: string };
+  if (!data.checkoutUrl) throw new Error('Checkout URL was not returned');
+  return data.checkoutUrl;
 }
 
-func createCheckout(w http.ResponseWriter, r *http.Request) {
-    var req CheckoutRequest
-    json.NewDecoder(r.Body).Decode(&req)
-    
-    if req.Quantity == 0 {
-        req.Quantity = 1
+export async function openOverlayCheckout(planId: PlanId): Promise<void> {
+  const checkoutUrl = await createCheckoutUrl(planId);
+
+  DodoPayments.Initialize({
+    mode: 'test', // or 'live'
+    displayType: 'overlay',
+    onEvent: (event) => {
+      console.log('Checkout event:', event);
     }
-    
-    session, err := client.CheckoutSessions.Create(r.Context(), &dodopayments.CheckoutSessionCreateParams{
-        ProductCart: []dodopayments.CartItem{
-            {ProductID: req.ProductID, Quantity: req.Quantity},
-        },
-        Customer: &dodopayments.Customer{
-            Email: req.Email,
-            Name:  req.Name,
-        },
-        ReturnURL: os.Getenv("APP_URL") + "/success",
-    })
-    
-    if err != nil {
-        http.Error(w, err.Error(), http.StatusInternalServerError)
-        return
+  });
+
+  DodoPayments.Checkout.open({ checkoutUrl });
+}
+
+export async function openInlineCheckout(planId: PlanId): Promise<void> {
+  const checkoutUrl = await createCheckoutUrl(planId);
+
+  DodoPayments.Initialize({
+    mode: 'test', // or 'live'
+    displayType: 'inline',
+    onEvent: (event) => {
+      console.log('Checkout event:', event);
     }
-    
-    json.NewEncoder(w).Encode(map[string]string{
-        "checkout_url": session.CheckoutURL,
-    })
+  });
+
+  DodoPayments.Checkout.open({
+    checkoutUrl,
+    elementId: 'dodo-inline-checkout'
+  });
 }
 ```
 
+```html
+<div id="dodo-inline-checkout"></div>
+```
+
 ---
 
-## Handling Success
+## Static Payment Links
 
-### Query Parameters
-The return URL receives these query parameters:
-- `status=success` - Payment completed
-- `session_id` - Checkout session ID
+No-code shareable links. No server-side API call needed.
 
-### Verify Payment Server-Side
-Don't rely solely on the redirect. Always verify via webhook:
+### Basic Format
 
-```typescript
-// Webhook handler confirms payment
-app.post('/webhook', async (req, res) => {
-  const event = req.body;
-  
-  if (event.type === 'payment.succeeded') {
-    // This is the source of truth
-    await fulfillOrder(event.data);
-  }
-  
-  res.json({ received: true });
-});
+```text
+https://checkout.dodopayments.com/buy/{productid}
+```
+
+Example:
+```text
+https://checkout.dodopayments.com/buy/pdt_example
+```
+
+### With Query Parameters
+
+```text
+https://checkout.dodopayments.com/buy/pdt_example?quantity=2&email=customer@example.com&redirect_url=https%3A%2F%2Fyoursite.com%2Fsuccess
 ```
 
+Supported parameters:
+- `quantity`: Item quantity
+- `redirect_url`: Success redirect URL
+- `email`: Prefill customer email
+- `fullName`, `firstName`, `lastName`: Prefill name
+- `country`, `city`, `state`, `zipCode`, `addressLine`: Prefill address
+- `paymentCurrency`: Force currency
+- `metadata_*`: Custom metadata (e.g., `metadata_orderId=123`)
+
 ---
 
-## Advanced Options
+## Retrieve and Preview Sessions
+
+### Retrieve Session Status
 
-### Prefill Customer Info
 ```typescript
-const session = await client.checkoutSessions.create({
-  product_cart: [{ product_id: 'prod_xxxxx', quantity: 1 }],
-  customer: {
-    email: 'customer@example.com',
-    name: 'John Doe',
-    phone: '+1234567890',
-    address: {
-      line1: '123 Main St',
-      city: 'San Francisco',
-      state: 'CA',
-      postal_code: '94105',
-      country: 'US',
-    },
-  },
-  return_url: 'https://yoursite.com/success',
+const status = await client.checkoutSessions.retrieve('cks_session_id');
+
+console.log(status.id);
+console.log(status.payment_status);
+```
+
+### Preview Session (without creating)
+
+```typescript
+const preview = await client.checkoutSessions.preview({
+  product_cart: [
+    { product_id: 'pdt_example', quantity: 1 }
+  ],
+  customer: { email: 'customer@example.com' },
+  billing_currency: 'EUR'
 });
+
+console.log('Preview total:', preview.current_breakup.total_amount);
 ```
 
-### Custom Success/Cancel URLs
+---
+
+## Customization
+
+### Theme and Appearance
+
 ```typescript
 const session = await client.checkoutSessions.create({
-  product_cart: [{ product_id: 'prod_xxxxx', quantity: 1 }],
+  product_cart: [{ product_id: 'pdt_example', quantity: 1 }],
   customer: { email: 'customer@example.com' },
-  return_url: 'https://yoursite.com/checkout/success?session_id={CHECKOUT_SESSION_ID}',
+  customization: {
+    theme: 'dark', // 'light', 'dark', or 'system'
+    force_language: 'en',
+    show_order_details: true,
+    theme_config: {
+      font_size: 'md',
+      font_weight: 'normal',
+      radius: '8px',
+      pay_button_text: 'Complete Purchase',
+      light: {
+        bg_primary: '#ffffff',
+        text_primary: '#000000',
+        button_primary: '#0066ff'
+      }
+    }
+  },
+  return_url: 'https://yoursite.com/success'
 });
 ```
 
-### Subscription with Trial
+### Feature Flags
+
 ```typescript
 const session = await client.checkoutSessions.create({
-  product_cart: [{ product_id: 'prod_subscription', quantity: 1 }],
-  subscription_data: {
-    trial_period_days: 14,
-  },
+  product_cart: [{ product_id: 'pdt_example', quantity: 1 }],
   customer: { email: 'customer@example.com' },
-  return_url: 'https://yoursite.com/success',
+  feature_flags: {
+    allow_discount_code: true,
+    allow_currency_selection: true,
+    allow_customer_editing_email: true,
+    allow_phone_number_collection: true,
+    require_phone_number: false,
+    allow_tax_id: true
+  },
+  return_url: 'https://yoursite.com/success'
 });
 ```
 
 ---
 
-## Error Handling
+## Post-Payment Flow
 
-```typescript
-try {
-  const session = await client.checkoutSessions.create({...});
-} catch (error: any) {
-  if (error.status === 400) {
-    // Invalid parameters
-    console.error('Invalid request:', error.message);
-  } else if (error.status === 401) {
-    // Invalid API key
-    console.error('Authentication failed');
-  } else if (error.status === 404) {
-    // Product not found
-    console.error('Product not found');
-  } else {
-    console.error('Checkout error:', error);
-  }
-}
+### Return URL Handling
+
+After payment, the customer is redirected to your `return_url` with query parameters:
+
+```text
+https://yoursite.com/success?status=success&session_id=cks_123
 ```
 
+Query parameters:
+- `status`: `success` or `failed`
+- `session_id`: Checkout session ID
+
+### Verify Payment Server-Side
+
+Do not trust the browser redirect. Use the Express webhook route above: it receives the raw signed body
+before `express.json()`, fulfills one-time purchases on verified `payment.succeeded` using
+`event.data.customer.customer_id`, and grants subscription access only on verified `subscription.active`.
+
+Webhook signature verification is covered in the `webhook-integration` skill.
+
+---
+
+## Common Mistakes
+
+**1. Granting access from the return URL**
+The return URL redirect is not proof of payment. Never grant access or fulfill an order from its query
+parameters; wait for a verified webhook event.
+
+**2. Using deprecated APIs**
+Do not use `client.payments.create()` or `client.subscriptions.create()` for new integrations. Both are deprecated. Use `client.checkoutSessions.create()`.
+
+**3. Forgetting the `environment` flag**
+The default is `live_mode`. Always set `environment: 'test_mode'` during development to avoid charging real cards.
+
+**4. Assuming only one discount-code form is valid**
+Both `discount_code` (a string) and `discount_codes` (an array) are valid Checkout Session parameters.
+
+**5. Amounts in wrong unit**
+All amounts are in the smallest currency unit (cents for USD). $10 is `1000`, not `10`.
+
+**6. Reusing checkout URLs**
+Checkout URLs are single-use. Create a new session for each checkout attempt.
+
+**7. Ignoring `confirm=true` behavior**
+When `confirm=true`, the session is finalized immediately and the checkout URL expires in 15 minutes instead of 24 hours. Use only when you have all required customer data.
+
+**8. Forgetting raw body for webhooks**
+Webhook signature verification requires the raw request body, not a re-serialized JSON object. Mount the
+webhook route with `express.raw({ type: 'application/json' })` before `express.json()`.
+
+**9. Trusting a client-supplied product id**
+Do not accept an arbitrary `pdt_` id from the browser. Authenticate the user, accept a public plan slug,
+map it to an allowlisted product id on the server, and reject quantities that are not positive integers.
+
 ---
 
 ## Resources
 
-- [Integration Guide](https://docs.dodopayments.com/developer-resources/integration-guide)
+- [Checkout Sessions Integration Guide](https://docs.dodopayments.com/developer-resources/integration-guide)
+- [Checkout Sessions API Reference](https://docs.dodopayments.com/api-reference/checkout-sessions/create)
 - [Overlay Checkout](https://docs.dodopayments.com/developer-resources/overlay-checkout)
-- [API Reference](https://docs.dodopayments.com/api-reference/checkout-sessions)
+- [Inline Checkout](https://docs.dodopayments.com/developer-resources/inline-checkout)
+- [Static Payment Links](https://docs.dodopayments.com/developer-resources/integration-guide)
+- [Webhook Integration](https://docs.dodopayments.com/developer-resources/webhooks)