@dodopayments/opencode-plugin 0.6.0 → 0.6.1

package/README.md

@@ -175,6 +175,7 @@ If you prefer the local stdio API server with your own API key instead of the de
 | `dodo-best-practices` | SDK setup, environments, API keys, and the canonical checkout-to-webhook architecture |
 | `framework-adapters` | Official `@dodopayments/*` handlers for Next.js, Express, Hono, Astro, Remix, SvelteKit, Nuxt, Fastify, TanStack, Bun, Convex |
 | `testing-and-go-live` | Test mode, test payment methods, webhook testing, production launch checklist |
+| `dodo-mcp-usage` | When to use the documentation vs API MCP servers, test-mode safety rules, auth, troubleshooting |
 
 **Accepting payments**
 

package/opencode-plugin/README.md

@@ -37,7 +37,7 @@ opencode run "List every skill available to you by name."
 
 ## What you get
 
-Agent skills (auto-loaded when relevant): `dodo-best-practices`, `framework-adapters`, `testing-and-go-live`, `checkout-integration`, `subscription-integration`, `mobile-checkout`, `webhook-integration`, `credit-based-billing`, `usage-based-billing`, `license-keys`, `product-catalog-management`, `discounts-and-promotions`, `localized-pricing`, `customer-management`, `refunds-and-disputes`, `billing-sdk`, `better-auth-integration`.
+Agent skills (auto-loaded when relevant): `dodo-best-practices`, `dodo-mcp-usage`, `framework-adapters`, `testing-and-go-live`, `checkout-integration`, `subscription-integration`, `mobile-checkout`, `webhook-integration`, `credit-based-billing`, `usage-based-billing`, `license-keys`, `product-catalog-management`, `discounts-and-promotions`, `localized-pricing`, `customer-management`, `refunds-and-disputes`, `billing-sdk`, `better-auth-integration`.
 
 Two MCP servers (registered automatically):
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dodopayments/opencode-plugin",
-    "version": "0.6.0",
+    "version": "0.6.1",
     "description": "Dodo Payments agent skills and MCP servers for OpenCode.",
     "type": "module",
     "main": "opencode-plugin/index.js",

package/skills/better-auth-integration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: better-auth-integration
-description: Guide only for applications using @dodopayments/better-auth, covering authenticated customer sync, checkout, portal access, usage ingestion, and verified webhook callbacks.
+description: Dodo Payments plugin for Better Auth (@dodopayments/better-auth) covering customer sync on signup, authenticated checkout, customer portal, usage ingestion, and verified webhooks. Use when an app uses Better Auth and needs the dodopayments, dodopaymentsClient, checkout, portal, usage, or webhooks plugins; for other auth stacks use framework-adapters.
 ---
 
 # Better Auth Integration
@@ -18,9 +18,11 @@ Use `@dodopayments/better-auth` to synchronize Better Auth users with Dodo Payme
 ## Install
 
 ```bash
-npm install @dodopayments/better-auth dodopayments better-auth
+npm install @dodopayments/better-auth dodopayments better-auth zod
 ```
 
+Requires Better Auth 1.4 or a later 1.x release.
+
 The package exports the lowercase server functions `dodopayments`, `checkout`, `portal`, `usage`, and `webhooks`. Its client entry point exports `dodopaymentsClient`.
 
 ## Server setup
@@ -76,6 +78,13 @@ export const auth = betterAuth({
 
 `products` maps an application slug to a Dodo product ID. `authenticatedUsersOnly: true` requires a Better Auth session for checkout. `getCustomerParams` adds application metadata when customer synchronization runs.
 
+The plugin adds a `dodoCustomerId` field to the Better Auth `user` table. After adding the plugin, update your database schema with the [Better Auth CLI](https://www.better-auth.com/docs/concepts/cli):
+
+```bash
+npx auth generate   # generate the ORM schema or SQL migration, then apply it yourself
+npx auth migrate    # or apply it directly (built-in Kysely adapter only)
+```
+
 ## Browser client setup
 
 ```typescript
@@ -170,7 +179,7 @@ if (error) {
 }
 ```
 
-The plugin derives `customer_id` from the authenticated session. `event_id` is the event's idempotency key; reuse it when retrying the same event.
+Both `usage.ingest` and `usage.meters.list` require a signed-in user with a verified email address. The plugin derives `customer_id` from the authenticated session. `event_id` is the event's idempotency key; reuse it when retrying the same event.
 
 ## Webhook endpoint
 

package/skills/billing-sdk/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: billing-sdk
-description: Guide for building billing UI with BillingSDK - the open-source React component library for pricing tables, subscription management, usage meters, invoice history, and customer portal flows wired to Dodo Payments.
+description: BillingSDK, the open-source React and shadcn component library for Dodo Payments billing UI. Use when building pricing tables, pricing pages, account billing pages, usage meters, credit balances, invoice history, or cancel and upgrade UI in React or Next.js, or running @billingsdk/cli init; keep Dodo API calls server-side.
 ---
 
 # BillingSDK
@@ -75,8 +75,10 @@ From the current official registry, grouped by purpose:
 | Payments | `payment-details`, `payment-details-two`, `payment-method-selector`, `payment-card`, `payment-failure` |
 | Promotion and trials | `banner`, `limited-offer-dialog`, `trial-expiry-card` |
 
-`pricing-table-one` is the only block with an officially published prop example, reproduced below. For
-every other block, run `add` and read the generated file's props type.
+Most blocks have a published usage example and props table on their page at
+[billingsdk.com/docs/components](https://billingsdk.com/docs/components) (for example `subscription-management`
+and `billing-settings`); `pricing-table-one` is reproduced below. The generated file's props type is still
+authoritative for the version you installed, so read it after running `add`.
 
 ## Server client
 
@@ -103,44 +105,75 @@ are `https://test.dodopayments.com` and `https://live.dodopayments.com`.
 
 ### 1. Plan catalogue
 
-Keep the product ids and the display copy in one module. The `price` here is a display number rendered by
-the component — the amount actually charged comes from the Dodo product catalogue, and Dodo API amounts
-are always in the smallest currency unit (cents). Treat this file as a mirror of the dashboard and
-reconcile it when you change a price.
+`pricing-table-one` takes BillingSDK's `Plan[]`, not an arbitrary shape. Adding the component generates
+`lib/billingsdk-config.ts`, which exports the `Plan` interface and a sample `plans` array — edit that array
+rather than defining your own type. Prices are display **strings** (`monthlyPrice`, `yearlyPrice`) and
+`features` are objects. The amount actually charged comes from the Dodo product catalogue (always in the
+smallest currency unit), so treat this file as a mirror of the dashboard and reconcile it when you change a
+price.
 
 ```typescript
-// lib/plans.ts
-export type PlanId = 'starter' | 'pro';
-
+// lib/billingsdk-config.ts (generated by `add pricing-table-one`; edit the plans)
 export interface Plan {
-  id: PlanId;
+  id: string;
   title: string;
-  price: number;
-  period: string;
-  features: string[];
-  popular: boolean;
+  description: string;
+  highlight?: boolean;
+  type?: 'monthly' | 'yearly';
+  currency?: string;
+  monthlyPrice: string;
+  yearlyPrice: string;
+  buttonText: string;
+  badge?: string;
+  features: {
+    name: string;
+    icon: string;
+    iconColor?: string;
+  }[];
 }
 
-export const PLANS: readonly Plan[] = [
+export const plans: Plan[] = [
   {
     id: 'starter',
     title: 'Starter',
-    price: 9,
-    period: 'month',
-    features: ['100 requests', 'Basic support', '1 project'],
-    popular: false,
+    description: 'For individuals getting started.',
+    currency: '$',
+    monthlyPrice: '9',
+    yearlyPrice: '90',
+    buttonText: 'Choose Starter',
+    features: [
+      { name: '100 requests', icon: 'check' },
+      { name: 'Basic support', icon: 'check' },
+      { name: '1 project', icon: 'check' },
+    ],
   },
   {
     id: 'pro',
     title: 'Pro',
-    price: 29,
-    period: 'month',
-    features: ['Unlimited requests', 'Priority support', '10 projects'],
-    popular: true,
+    description: 'For teams running in production.',
+    currency: '$',
+    monthlyPrice: '29',
+    yearlyPrice: '290',
+    buttonText: 'Choose Pro',
+    badge: 'Most popular',
+    highlight: true,
+    features: [
+      { name: 'Unlimited requests', icon: 'check' },
+      { name: 'Priority support', icon: 'check' },
+      { name: '10 projects', icon: 'check' },
+    ],
   },
 ];
 ```
 
+The generated file is the contract for your installed version; if its `Plan` differs from the above, follow
+the file. `onPlanSelect` receives only the plan `id`, so the ids here are the slugs the server maps below.
+
+This example sells **monthly plans only**: `yearlyPrice` is required by the `Plan` type and is displayed,
+but the server map below has only monthly products. To sell yearly too, create the yearly products in Dodo,
+track the table's billing-period toggle in your own state (it is not passed to `onPlanSelect`), send it with
+the plan id, and key the server map by plan and period (for example `pro:yearly`).
+
 ### 2. Product id map — server only
 
 Never let the browser choose an arbitrary `product_id`. Map the public plan slug to a `pdt_` id on the
@@ -149,16 +182,16 @@ server and reject anything else.
 ```typescript
 // lib/plan-products.server.ts
 import 'server-only';
-import type { PlanId } from './plans';
 
-const PRODUCT_IDS: Record<PlanId, string> = {
+// Keys must match the `id`s in lib/billingsdk-config.ts.
+const PRODUCT_IDS: Readonly<Record<string, string>> = {
   starter: 'pdt_starter_monthly',
   pro: 'pdt_pro_monthly',
 };
 
 export function productIdForPlan(value: unknown): string | null {
-  if (typeof value !== 'string') return null;
-  return PRODUCT_IDS[value as PlanId] ?? null;
+  if (typeof value !== 'string' || !Object.hasOwn(PRODUCT_IDS, value)) return null;
+  return PRODUCT_IDS[value];
 }
 ```
 
@@ -220,7 +253,7 @@ integrations. Checkout parameters are covered in depth in the `checkout-integrat
 
 import { useState } from 'react';
 import { PricingTableOne } from '@/components/billingsdk/pricing-table-one';
-import { PLANS } from '@/lib/plans';
+import { plans } from '@/lib/billingsdk-config';
 
 export function PricingPlans() {
   const [error, setError] = useState<string | null>(null);
@@ -249,7 +282,7 @@ export function PricingPlans() {
   return (
     <>
       <PricingTableOne
-        plans={PLANS}
+        plans={plans}
         title="Choose your plan"
         description="Select the plan that works best for you"
         onPlanSelect={handlePlanSelect}
@@ -458,14 +491,14 @@ signature verification is covered in the `webhook-integration` skill.
 **Accepting a raw `product_id` from the request body.** A caller can then check out against any product in
 your catalogue, including internal or discounted ones. Map an opaque plan slug to a `pdt_` id server-side.
 
-**Hardcoding prices in the client.** `PLANS[].price` is display text. When you change a price in the Dodo
+**Hardcoding prices in the client.** `plans[].monthlyPrice` / `yearlyPrice` are display text. When you change a price in the Dodo
 dashboard, the checkout charges the new amount while the pricing page keeps advertising the old one.
-Reconcile `lib/plans.ts` with the dashboard as part of any pricing change.
+Reconcile `lib/billingsdk-config.ts` with the dashboard as part of any pricing change.
 
 **`npm install billingsdk`.** The root repository package is private. Install through
 `@billingsdk/cli` or the shadcn registry instead.
 
-**Guessing prop names.** `pricing-table-one` is the only block with a published prop example. Open the
+**Guessing prop names.** Check the block's page on billingsdk.com/docs/components, then open the
 generated file under `components/billingsdk/` and read the exported props type before wiring anything else.
 
 **Using `DODO_PAYMENTS_WEBHOOK_SECRET`.** The SDK reads `DODO_PAYMENTS_WEBHOOK_KEY` for the `webhookKey`

package/skills/checkout-integration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: checkout-integration
-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.
+description: Dodo Payments checkout via hosted Checkout Sessions (client.checkoutSessions.create), static payment links, and overlay or inline checkout for one-time and subscription products. Use when building a pay button, checkout page, trial signup, custom fields, discount codes at checkout, or return_url redirects; use subscription-integration for post-checkout lifecycle.
 ---
 
 # Dodo Payments Checkout Integration
@@ -38,7 +38,7 @@ Dodo Payments offers three ways to collect payment:
 
 **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`.
+**Return URL:** Where the customer lands after payment. Dodo appends `payment_id` (one-time) or `subscription_id` (subscription), `status`, and when available `license_key` and `email`. It is a UI hint only, never proof of payment.
 
 **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.
 
@@ -637,31 +637,27 @@ async function createCheckoutUrl(planId: PlanId, quantity = 1): Promise<string>
   return data.checkoutUrl;
 }
 
-export async function openOverlayCheckout(planId: PlanId): Promise<void> {
-  const checkoutUrl = await createCheckoutUrl(planId);
-
+// Call ONCE when the app loads (e.g. in your root component or entry point),
+// not before every checkout. Pick the display type your page uses.
+export function initCheckout(displayType: 'overlay' | 'inline'): void {
   DodoPayments.Initialize({
     mode: 'test', // or 'live'
-    displayType: 'overlay',
+    displayType,
     onEvent: (event) => {
       console.log('Checkout event:', event);
     }
   });
+}
 
+// Requires initCheckout('overlay') to have run at app load.
+export async function openOverlayCheckout(planId: PlanId): Promise<void> {
+  const checkoutUrl = await createCheckoutUrl(planId);
   DodoPayments.Checkout.open({ checkoutUrl });
 }
 
+// Requires initCheckout('inline') to have run at app load.
 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);
-    }
-  });
-
   DodoPayments.Checkout.open({
     checkoutUrl,
     elementId: 'dodo-inline-checkout'
@@ -685,6 +681,8 @@ No-code shareable links. No server-side API call needed.
 https://checkout.dodopayments.com/buy/{productid}
 ```
 
+In test mode the host is `test.checkout.dodopayments.com` (for example `https://test.checkout.dodopayments.com/buy/{productid}`); a test-mode product does not exist on the live host.
+
 Example:
 ```text
 https://checkout.dodopayments.com/buy/pdt_example
@@ -789,12 +787,20 @@ const session = await client.checkoutSessions.create({
 After payment, the customer is redirected to your `return_url` with query parameters:
 
 ```text
-https://yoursite.com/success?status=success&session_id=cks_123
+# One-time payment
+https://yoursite.com/success?payment_id=pay_xxx&status=succeeded&email=customer%40example.com
+
+# Subscription (with license keys)
+https://yoursite.com/success?subscription_id=sub_xxx&status=active&license_key=LK-001,LK-002&email=customer%40example.com
 ```
 
 Query parameters:
-- `status`: `success` or `failed`
-- `session_id`: Checkout session ID
+- `payment_id` (one-time payments) or `subscription_id` (subscriptions)
+- `status`: `succeeded` (one-time) or `active` (subscription) on success; `failed` if declined; `processing` (or a `requires_*` value) if it settles later; `expired` if the session expired
+- `license_key`: present when the product issues license keys (comma-separated if several)
+- `email`: present when the customer has an email on record
+
+There is no `session_id` parameter. Treat `processing`/missing status as "unknown" and wait for the webhook.
 
 ### Verify Payment Server-Side
 
@@ -818,8 +824,8 @@ Do not use `client.payments.create()` or `client.subscriptions.create()` for new
 **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.
+**4. Using the deprecated `discount_code`**
+Use `discount_codes` (an array). The singular `discount_code` string is deprecated (still accepted for backward compatibility) and cannot be combined with `discount_codes` in the same request.
 
 **5. Amounts in wrong unit**
 All amounts are in the smallest currency unit (cents for USD). $10 is `1000`, not `10`.

package/skills/credit-based-billing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: credit-based-billing
-description: Complete guide for giving customers included, free, prepaid, promotional, or top-up credits using grants, balances, ledger deductions, rollover, expiry, alerts, and overage.
+description: Dodo Payments credit-based billing with credit entitlements, grants, balances, ledger deductions, rollover, expiry, low-balance alerts, and overage. Use when selling prepaid or top-up credit packs, including credits in a plan, deducting AI token or API credits via meters, or granting promo credits; use usage-based-billing for direct per-unit charges.
 ---
 
 # Dodo Payments Credit-Based Billing
@@ -203,7 +203,7 @@ Attach the credit entitlement to the same usage-based product as the meter. The
 | Field | Purpose |
 |---|---|
 | `meter_id` | Meter to aggregate usage. |
-| `free_threshold` | Optional usage excluded before rating. |
+| `free_threshold` | Free usage excluded before rating - applies **only** when the meter bills in money. It is ignored for credit-billed meters: every unit is deducted from the credit balance. |
 | `credit_entitlement_id` | Credit pool consumed by this meter. |
 | `meter_units_per_credit` | Usage units required to deduct one credit; required when `credit_entitlement_id` is set. |
 | `price_per_unit` | Direct per-unit monetary price when using pure usage pricing; decimal string. |
@@ -297,7 +297,7 @@ If the same `idempotency_key` already exists, the API can return `409`. Treat th
 
 ## Deduct credits manually
 
-Use the same method with `entry_type: 'debit'`. Debits consume the oldest grants first (FIFO) and can return `400` when the balance is insufficient.
+Use the same method with `entry_type: 'debit'`. Debits consume the earliest-expiring grants first and can return `400` when the balance is insufficient.
 
 ```typescript
 async function deductJobCredits(
@@ -356,10 +356,9 @@ Persist the Dodo ledger entry ID with internal order, support-case, or job IDs.
 2. Add the meter to the same product.
 3. Enable **Bill usage in Credits** for that meter.
 4. Set `credit_entitlement_id` and `meter_units_per_credit`.
-5. Optionally set `free_threshold`; usage under it is excluded.
-6. Ingest events whose case-sensitive `event_name` matches the meter.
+5. Ingest events whose case-sensitive `event_name` matches the meter.
 
-A background worker processes new usage approximately every minute, aggregates it according to the meter, converts meter units using `meter_units_per_credit`, and consumes the oldest non-expired grants first (FIFO). Multiple meters can consume one shared credit pool at different conversion rates.
+A background worker processes new usage approximately every minute, aggregates it according to the meter, converts meter units using `meter_units_per_credit`, and deducts from non-expired grants with the earliest-expiring grants consumed first. There is no free threshold on a credit-billed meter. Multiple meters can consume one shared credit pool at different conversion rates.
 
 This delay is material: an accepted usage event does not imply that a balance read immediately afterward includes its deduction.
 
@@ -467,7 +466,7 @@ The lifecycle is:
 1. The model returns actual prompt and completion token counts.
 2. The app ingests one uniquely identified `ai.tokens` event.
 3. The meter aggregates the `tokens` metadata value.
-4. The worker converts units into credits and deducts FIFO from non-expired grants.
+4. The worker converts units into credits and deducts from non-expired grants, earliest-expiring first.
 5. Dodo emits `credit.deducted`; when configured threshold conditions are met, it emits `credit.balance_low`.
 6. The app notifies the customer and offers checkout for the attached top-up product.
 
@@ -588,7 +587,7 @@ Return an application-level payment/credit-required response with a top-up or up
 16. **Sending duplicate IDs within one batch.** Duplicate `event_id` values in the same ingestion request reject the entire request. Previously ingested IDs are ignored on retry.
 17. **Inventing a deduplication window.** Current docs require unique event IDs but do not publish a retention duration.
 18. **Getting conversion backward.** `meter_units_per_credit` is usage units required for one credit, and is required when `credit_entitlement_id` is set.
-19. **Ignoring the free threshold.** Usage under `free_threshold` is excluded before credit deduction.
+19. **Expecting a free threshold on credit-billed meters.** `free_threshold` applies only to meters billed in money. When **Bill usage in Credits** is on, every unit deducts credits; model included usage as granted credits instead.
 20. **Supplying one rollover timeframe field.** `rollover_timeframe_count` and `rollover_timeframe_interval` must be supplied together.
 21. **Using the wrong rollover enum case.** Confirmed values are `Day`, `Week`, `Month`, and `Year`.
 22. **Assuming expiry happens before rollover.** Rollover is applied first; only the remainder expires.

package/skills/customer-management/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: customer-management
-description: Guide for managing customer records, saved payment methods, monetary wallets, and hosted customer-portal sessions; subscription lifecycle and custom billing UI are covered separately.
+description: Dodo Payments customer management, covering customer CRUD, saved payment methods, real-money customer wallets and ledger entries, entitlements, and hosted customer portal sessions. Use when linking app users to cus_ IDs, opening a Manage billing portal, listing or deleting payment methods, or crediting wallets; use credit-based-billing for usage credits.
 ---
 
 # Customer Management
@@ -68,19 +68,28 @@ await client.customers.update('cus_abc123', {
 
 ## Customer Portal
 
-Create a time-bound session that redirects customers to a hosted portal. The portal is read-only for most actions; customers can view invoices, cancel subscriptions, change plans, update payment methods, recover on-hold subscriptions, and download license keys.
+Create a time-bound session that redirects customers to a hosted portal. In the portal, customers can view invoices, cancel subscriptions, change plans, update payment methods, recover on-hold subscriptions, and download license keys.
+
+Never call the SDK from the browser: it uses your secret API key. Create the session in a server route and return only the link.
 
 ```typescript
-// Create a portal session
+// Server route: create a portal session
 const session = await client.customers.customerPortal.create('cus_abc123', {
   return_url: 'https://yourapp.com/dashboard',
+  // send_email: true, // optionally also email the link to the customer
 });
 
-// Redirect the customer
-window.location.href = session.link;
+return Response.json({ link: session.link });
 ```
 
-The portal session link expires after a short time. Customers cannot:
+```typescript
+// Browser: redirect the customer
+const res = await fetch('/api/portal', { method: 'POST' });
+const { link } = await res.json();
+window.location.href = link;
+```
+
+The portal session link is valid for 24 hours. Pass `send_email: true` to have Dodo also email the link to the customer. Customers cannot:
 - Create new subscriptions (use checkout for that)
 - Refund themselves
 - Change their email or name (contact support)
@@ -225,23 +234,22 @@ const found = customers.items.find(c => c.email === user.email);
 
 ## Common mistakes
 
-**Creating duplicate customers per checkout.** Each checkout should reuse an existing `customer_id` or create the customer once. Creating a new customer for every transaction fragments your customer data.
+**Creating duplicate customers per checkout.** Passing `customer: { email }` does not create a new customer each time: by default, checkout uses the email to find an existing customer and attaches the session to it. Duplicates come from setting `feature_flags.always_create_new_customer: true`, or from calling `customers.create` before every checkout. Create the customer once (or let the first checkout create it), store its `customer_id`, and pass that on later checkouts.
 
 ```typescript
-// WRONG
+// WRONG: forces a new customer record on every checkout
 const session = await client.checkoutSessions.create({
-  product_cart: [...],
-  customer: { email: user.email }, // Creates a new customer each time
+  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
+  customer: { email: user.email },
+  feature_flags: { always_create_new_customer: true },
 });
 
-// RIGHT
-const customer = await client.customers.create({
-  email: user.email,
-  name: user.name,
-});
+// RIGHT: reuse the stored customer ID, or fall back to email (matched to an existing customer by default)
 const session = await client.checkoutSessions.create({
-  product_cart: [...],
-  customer: { customer_id: customer.customer_id }, // Reuse the customer
+  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
+  customer: user.dodo_customer_id
+    ? { customer_id: user.dodo_customer_id }
+    : { email: user.email },
 });
 ```
 

package/skills/discounts-and-promotions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: discounts-and-promotions
-description: Guide for implementing discount codes and promotional pricing with Dodo Payments, including CRUD operations, eligibility rules, stacking, subscription-cycle limits, and plan-change preservation.
+description: Dodo Payments discount codes and promotional pricing, covering discount CRUD, percentage and flat amounts, eligibility rules, usage limits, stacking via discount_codes, subscription-cycle limits, and preservation on plan changes. Use when creating coupons or promo codes, applying or validating a code at checkout, or debugging a discount that won't apply.
 ---
 
 # Discounts and Promotions
@@ -20,7 +20,7 @@ This skill covers discount codes, coupons, and promotional pricing in Dodo Payme
 
 **Discount types:** Dodo supports both percentage and flat-amount discounts. Percentage amounts are expressed as integers where 1500 means 15% (100 = 1%). Flat amounts are in the smallest currency unit (cents for USD).
 
-**Discount code:** A human-readable string (e.g., `SUMMER2025`) that customers enter at checkout. Codes are case-sensitive.
+**Discount code:** A human-readable string (e.g., `SUMMER2025`) that customers enter at checkout. The API uppercases codes on create (`summer2025` is stored as `SUMMER2025`); codes must be at least 3 characters, and omitting `code` generates a random 16-character uppercase code.
 
 **Eligibility:** Discounts can be restricted to specific products, customers, or date ranges. A discount without restrictions applies to any product and any customer.
 
@@ -119,7 +119,7 @@ await client.discounts.delete('discount_id');
 
 ## Discount types and configuration
 
-**Important:** The feature documentation states that only percentage discounts are currently supported. However, the current OpenAPI schema defines both `flat` and `percentage` types with currency options. Follow the API reference when implementing. If you encounter unexpected behavior with flat discounts, verify with Dodo support whether flat discounts are fully enabled in your account.
+Two types are supported: `percentage` and `flat` (shown as **Amount** in the dashboard). A `flat` discount requires `currency_options` with at least one resolvable default currency; for a `percentage` discount, `currency_options` is optional and caps the discount per currency. A flat deduction is pooled across the whole cart rather than applied per line item.
 
 ### Percentage discounts
 
@@ -177,19 +177,12 @@ const discount = await client.discounts.create({
   customer_eligibility: 'specific',
 });
 
-await fetch(
-  `https://test.dodopayments.com/discounts/${discount.discount_id}/customers`,
-  {
-    method: 'POST',
-    headers: {
-      Authorization: `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`,
-      'Content-Type': 'application/json',
-    },
-    body: JSON.stringify({
-      customer_ids: ['cus_vip_001', 'cus_vip_002'],
-    }),
-  },
-);
+// The SDK has no named method for this endpoint yet. `client.post` reuses the
+// client's auth and base URL (test.dodopayments.com for `test_mode`,
+// live.dodopayments.com for `live_mode`), so nothing is hardcoded.
+await client.post(`/discounts/${discount.discount_id}/customers`, {
+  body: { customer_ids: ['cus_vip_001', 'cus_vip_002'] },
+});
 ```
 
 ### Date range
@@ -236,7 +229,10 @@ const discount = await client.discounts.create({
 
 ### Single code
 
+Never call the SDK from the browser: it uses your secret API key. Create the session in a server route and return only the URL.
+
 ```typescript
+// Server route
 const session = await client.checkoutSessions.create({
   product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
   discount_codes: ['SUMMER2025'],
@@ -244,7 +240,14 @@ const session = await client.checkoutSessions.create({
   return_url: 'https://yoursite.com/return'
 });
 
-window.location.href = session.checkout_url;
+return Response.json({ checkout_url: session.checkout_url });
+```
+
+```typescript
+// Browser
+const res = await fetch('/api/checkout', { method: 'POST' });
+const { checkout_url } = await res.json();
+window.location.href = checkout_url;
 ```
 
 ### Multiple codes (stacking)

package/skills/dodo-best-practices/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dodo-best-practices
-description: Guide for initial Dodo Payments setup, including SDK installation, test and live environments, API keys, and the canonical checkout-to-webhook architecture.
+description: Starting point for any Dodo Payments integration, covering Merchant of Record basics, SDK installation and client setup, test and live environments, API keys, and the canonical checkout-to-webhook flow. Use when starting a new integration, initializing the dodopayments client, choosing an architecture, or unsure which Dodo Payments skill applies.
 ---
 
 # Dodo Payments Integration Guide
@@ -125,8 +125,13 @@ composer require "dodopayments/client:6.19.0"
 ```php
 use Dodopayments\Client;
 
+$apiKey = getenv('DODO_PAYMENTS_API_KEY');
+if ($apiKey === false || $apiKey === '') {
+    throw new RuntimeException('DODO_PAYMENTS_API_KEY is not set');
+}
+
 $client = new Client(
-    bearerToken: getenv('DODO_PAYMENTS_API_KEY') ?: 'My Bearer Token',
+    bearerToken: $apiKey,
     environment: 'test_mode',
 );
 ```
@@ -155,8 +160,12 @@ dodo_payments = Dodopayments::Client.new(
 ```
 
 ```java
-DodoPaymentsClient client = DodoPaymentsOkHttpClient.fromEnv();
-// Reads DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_WEBHOOK_KEY, DODO_PAYMENTS_BASE_URL
+// fromEnv() reads DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_WEBHOOK_KEY, DODO_PAYMENTS_BASE_URL.
+// Without testMode() (or a test DODO_PAYMENTS_BASE_URL) the client targets live mode.
+DodoPaymentsClient client = DodoPaymentsOkHttpClient.builder()
+    .fromEnv()
+    .testMode()
+    .build();
 ```
 
 ### Kotlin
@@ -170,7 +179,11 @@ DodoPaymentsClient client = DodoPaymentsOkHttpClient.fromEnv();
 ```
 
 ```kotlin
-val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv()
+// Without testMode() (or a test DODO_PAYMENTS_BASE_URL) the client targets live mode.
+val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.builder()
+    .fromEnv()
+    .testMode()
+    .build()
 ```
 
 ---