@dodopayments/opencode-plugin 0.5.1 → 0.6.1

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()
 ```
 
 ---

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.