@dodopayments/opencode-plugin 0.5.1 → 0.6.1

package/skills/refunds-and-disputes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: refunds-and-disputes
-description: Guide for issuing refunds, handling disputes and chargebacks, and reconciling customer access with Dodo Payments
+description: Dodo Payments refunds and disputes, covering full and partial refunds, refund statuses, dispute and chargeback lifecycle events, evidence, and revoking or restoring customer access. Use when issuing a refund, handling refund or dispute webhooks, responding to a chargeback, or reconciling entitlements after a payment reversal.
 ---
 
 # Refunds and Disputes
@@ -23,7 +23,7 @@ This skill covers issuing refunds (full and partial), handling the dispute lifec
 
 **Amounts** are always in the smallest currency unit (cents for USD, paise for INR, etc.).
 
-**Access revocation** means removing the customer's ability to use the product or service. On a dispute, you typically revoke access while it's open. Restore it only on `dispute.won`; all other outcomes keep access revoked until you reconcile them separately.
+**Access revocation** means removing the customer's ability to use the product or service. On a dispute, you typically revoke access while it's open. Restore it on `dispute.won` or `dispute.cancelled` (withdrawn, no further action needed); the losing outcomes (`dispute.accepted`, `dispute.lost`, `dispute.expired`) keep access revoked.
 
 ## Refunds
 
@@ -54,7 +54,7 @@ To refund only specific items from a payment, pass the `items` array with each i
 const partialRefund = await client.refunds.create({
   payment_id: 'pay_abc123',
   items: [
-    { item_id: 'item_1', amount: 1000 },
+    { item_id: 'item_1' }, // no amount: the whole item is refunded
     { item_id: 'item_2', amount: 2500 },
   ],
 });
@@ -104,34 +104,63 @@ const client = new DodoPayments({
   webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
 });
 
+type WebhookEvent = ReturnType<typeof client.webhooks.unwrap>;
+
+// Register ONE endpoint for every Dodo event. A second app.post('/webhook')
+// would never run, because the first handler answers every request.
 app.post('/webhook', async (req, res) => {
+  let event: WebhookEvent;
   try {
-    const event = client.webhooks.unwrap(req.body.toString(), {
+    event = client.webhooks.unwrap(req.body.toString(), {
       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,
       },
     });
+  } catch {
+    // Only signature verification failures reach this branch
+    res.status(401).json({ error: 'Invalid signature' });
+    return;
+  }
 
-    if (event.type === 'refund.succeeded') {
-      const refund = event.data;
-      // Refund succeeded; revoke access if needed
-      await revokeCustomerAccess(refund.customer.customer_id);
-      await updateRefundRecord(refund.refund_id, 'succeeded');
-    }
-
-    if (event.type === 'refund.failed') {
-      const refund = event.data;
-      // Refund failed; keep access active, alert support
-      await logRefundFailure(refund.refund_id, refund.reason);
-    }
-
+  try {
+    await handleRefundEvent(event);
+    await handleDisputeEvent(event); // defined under "Handle dispute webhooks"
     res.json({ received: true });
   } catch (error) {
-    res.status(401).json({ error: 'Invalid signature' });
+    // Any non-2xx response makes Dodo retry the delivery
+    console.error('Webhook handler failed:', error);
+    res.status(500).json({ error: 'Webhook handler failed' });
   }
 });
+
+async function handleRefundEvent(event: WebhookEvent) {
+  if (event.type === 'refund.succeeded') {
+    const refund = event.data;
+    if (!refund.is_partial) {
+      // Full refund: nothing in the payment is still paid for
+      await revokeCustomerAccess(refund.customer.customer_id);
+    } else {
+      // Partial refund: keep access to items that are still paid for, and
+      // remove it for any item with nothing left to refund. Reading the line
+      // items covers every case - an omitted amount, an explicit amount equal
+      // to the item price, or several partial refunds that add up to it.
+      const { items } = await client.payments.retrieveLineItems(refund.payment_id);
+      const fullyRefundedItemIds = items
+        .filter((item) => item.refundable_amount === 0)
+        .map((item) => item.items_id);
+      await revokeItemAccess(refund.customer.customer_id, fullyRefundedItemIds);
+    }
+    await updateRefundRecord(refund.refund_id, 'succeeded');
+  }
+
+  if (event.type === 'refund.failed') {
+    const refund = event.data;
+    // Refund failed; keep access active, alert support
+    await logRefundFailure(refund.refund_id, refund.reason);
+  }
+}
 ```
 
 ## Disputes
@@ -159,7 +188,7 @@ A dispute moves through seven events. Each event requires a different action fro
 | `dispute.opened` | Customer initiated a chargeback | Record the dispute; consider revoking access immediately; gather evidence from your logs |
 | `dispute.challenged` | You submitted evidence | Wait for the card network to review |
 | `dispute.accepted` | You accepted (conceded) the dispute; funds go to the cardholder | Keep access revoked; mark the dispute as accepted in your records |
-| `dispute.cancelled` | Customer or system cancelled the dispute | Keep access revoked; reconcile the payment separately |
+| `dispute.cancelled` | The dispute was withdrawn or cancelled | No further action needed; restore access you revoked on `dispute.opened` |
 | `dispute.expired` | Dispute window closed without resolution | Treat as lost; keep access revoked |
 | `dispute.won` | You won the dispute | Funds are retained; restore access; update customer records |
 | `dispute.lost` | You lost the dispute | Funds returned to cardholder; keep access revoked; reconcile your records |
@@ -174,66 +203,56 @@ async function resolveDisputeCustomerId(disputeId: string) {
   return dispute.customer.customer_id;
 }
 
-app.post('/webhook', async (req, res) => {
-  try {
-    const event = client.webhooks.unwrap(req.body.toString(), {
-      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,
-      },
-    });
-
-    if (event.type === 'dispute.opened') {
-      const dispute = event.data;
-      // Record the dispute and revoke access
-      await recordDispute(dispute.dispute_id, dispute.payment_id, dispute.amount);
-      const customerId = await resolveDisputeCustomerId(dispute.dispute_id);
-      await revokeCustomerAccess(customerId);
-      // Gather evidence from your system and submit via dashboard
-      // (no evidence-submission API exists; use the Dodo dashboard)
-    }
-
-    if (event.type === 'dispute.won') {
-      const dispute = event.data;
-      // Funds retained; restore normal state
-      await markDisputeResolved(dispute.dispute_id, 'won');
-      const customerId = await resolveDisputeCustomerId(dispute.dispute_id);
-      await restoreCustomerAccess(customerId);
-    }
+// Called from the single /webhook handler above, after signature verification
+async function handleDisputeEvent(event: WebhookEvent) {
+  if (event.type === 'dispute.opened') {
+    const dispute = event.data;
+    // Record the dispute and revoke access
+    await recordDispute(dispute.dispute_id, dispute.payment_id, dispute.amount);
+    const customerId = await resolveDisputeCustomerId(dispute.dispute_id);
+    await revokeCustomerAccess(customerId);
+    // Gather evidence from your system and submit via dashboard
+    // (no evidence-submission API exists; use the Dodo dashboard)
+  }
 
-    if (event.type === 'dispute.lost') {
-      const dispute = event.data;
-      // Funds returned to cardholder; keep access revoked
-      await markDisputeResolved(dispute.dispute_id, 'lost');
-      // Do NOT restore access
-    }
+  if (event.type === 'dispute.won') {
+    const dispute = event.data;
+    // Funds retained; restore normal state
+    await markDisputeResolved(dispute.dispute_id, 'won');
+    const customerId = await resolveDisputeCustomerId(dispute.dispute_id);
+    await restoreCustomerAccess(customerId);
+  }
 
-    if (event.type === 'dispute.accepted') {
-      const dispute = event.data;
-      // Merchant conceded; funds go to the cardholder and access stays revoked
-      await markDisputeResolved(dispute.dispute_id, 'accepted');
-      // Do NOT restore access
-    }
+  if (event.type === 'dispute.lost') {
+    const dispute = event.data;
+    // Funds returned to cardholder; keep access revoked
+    await markDisputeResolved(dispute.dispute_id, 'lost');
+    // Do NOT restore access
+  }
 
-    if (event.type === 'dispute.cancelled') {
-      const dispute = event.data;
-      // Cancellation is not a win; keep access revoked and reconcile separately
-      await markDisputeResolved(dispute.dispute_id, 'cancelled');
-    }
+  if (event.type === 'dispute.accepted') {
+    const dispute = event.data;
+    // Merchant conceded; funds go to the cardholder and access stays revoked
+    await markDisputeResolved(dispute.dispute_id, 'accepted');
+    // Do NOT restore access
+  }
 
-    res.json({ received: true });
-  } catch (error) {
-    res.status(401).json({ error: 'Invalid signature' });
+  if (event.type === 'dispute.cancelled') {
+    const dispute = event.data;
+    // The dispute was withdrawn; no further action is needed, so undo the
+    // revocation from dispute.opened
+    await markDisputeResolved(dispute.dispute_id, 'cancelled');
+    const customerId = await resolveDisputeCustomerId(dispute.dispute_id);
+    await restoreCustomerAccess(customerId);
   }
-});
+}
 ```
 
 ### Evidence submission
 
 Dodo handles the card-network dispute process as Merchant of Record. You submit evidence through the Dodo dashboard, not via API. No evidence-submission API exists.
 
-When a dispute opens, gather your evidence (order confirmation, delivery proof, customer communication, etc.) and upload it to the dashboard within the dispute window (typically 4 days). The card network reviews your evidence and makes a final decision.
+When a dispute opens, gather your evidence (order confirmation, delivery proof, customer communication, etc.) and upload it to the dashboard within the dispute window (10 days from when the dispute is created). The card network reviews your evidence and makes a final decision.
 
 ## Access revocation pattern
 
@@ -266,7 +285,8 @@ async function handleDisputeLifecycle(
       break;
 
     case 'dispute_cancelled':
-      // Cancellation is not a win; reconcile separately and keep access revoked
+      // Withdrawn; no further action needed, so restore access
+      await restoreCustomerAccess(customerId);
       break;
 
     case 'dispute_expired':
@@ -319,9 +339,9 @@ async function reconcileRefund(refund) {
 
 **Ignoring partial refunds when computing entitlements.** If a customer refunds only one item from a multi-item purchase, their entitlement to the other items remains valid. Track refunds by item, not just by payment.
 
-**Restoring access on any outcome except `dispute.won`.** `dispute.accepted` means you conceded and the cardholder receives the funds. A cancelled dispute is also not a win. Keep access revoked and reconcile separately unless you receive `dispute.won`.
+**Restoring access on a losing outcome.** `dispute.accepted`, `dispute.lost`, and `dispute.expired` resolve (or typically resolve) in the cardholder's favor; keep access revoked. Restore access only on `dispute.won` or `dispute.cancelled` (the dispute was withdrawn and needs no further action).
 
-**Submitting evidence after the dispute window closes.** The card network typically gives you 4 days to respond. Set a calendar reminder and gather evidence immediately when a dispute opens.
+**Submitting evidence after the dispute window closes.** You have 10 days from when the dispute is created to respond. Set a calendar reminder and gather evidence immediately when a dispute opens.
 
 **Assuming Dodo will handle access revocation.** Dodo handles the card-network process; you handle application access. Dodo won't revoke your customer's subscription or file access automatically.
 

package/skills/subscription-integration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: subscription-integration
-description: Guide for managing recurring subscriptions after checkout, including trials, lifecycle states, plan changes, cancellation, failed-payment recovery, proration, mandates, and on-demand charges.
+description: Dodo Payments subscription lifecycle after checkout, covering trials, statuses like active, on_hold, and cancelled, plan upgrades and downgrades, proration, cancellation, failed-payment recovery, mandates, and on-demand charges. Use when managing recurring billing, plan changes, dunning, or off-session charging; use checkout-integration to start the purchase.
 ---
 
 # Dodo Payments Subscription Integration
@@ -19,7 +19,7 @@ Implement recurring billing with trials, plan changes, and on-demand charging. S
 
 ## Core Concepts
 
-**Subscription lifecycle:** The six subscription statuses are `pending`, `active`, `on_hold`, `cancelled`, `failed`, and `expired`. A trialing subscription reports `active`; `subscription.renewed` is an event, not a status. Failed payments can move a subscription to `on_hold` (recoverable) or `failed` (terminal). Cancellation sets it to `cancelled` or schedules it to become `expired` at period end.
+**Subscription lifecycle:** The eight subscription statuses are `pending`, `active`, `past_due`, `on_hold`, `paused`, `cancelled`, `failed`, and `expired`. A trialing subscription reports `active`; `subscription.renewed` is an event, not a status. A failed renewal moves a subscription to `past_due` (only if you configured a grace period; access is kept) or `on_hold` (access revoked); both are recoverable. `paused` is a deliberate freeze by you or the customer. `failed` is terminal and only happens when **initial creation** fails. Cancellation sets it to `cancelled` or schedules it to become `expired` at period end.
 
 **Checkout Sessions:** The recommended path for creating subscriptions. A single-use hosted checkout that collects payment and customer data, then creates the subscription server-side.
 
@@ -89,12 +89,16 @@ const session = await client.checkoutSessions.create({
 | Status | Meaning | Transitions |
 |--------|---------|-----------|
 | `pending` | Creation in progress | → `active`, `failed` |
-| `active` | Actively renewing | → `on_hold`, `cancelled`, `expired` |
-| `on_hold` | Renewal/plan-change payment failed; recoverable | → `active` (payment method updated), `failed` (retries exhausted), `cancelled` |
+| `active` | Actively renewing | → `past_due`, `on_hold`, `paused`, `cancelled`, `expired` |
+| `past_due` | Renewal failed and the grace period is open; customer **keeps** access until `past_due_ends_at` | → `active` (debt settled), `on_hold` or `cancelled` (grace period ends, per your setting) |
+| `on_hold` | Renewal/plan-change payment failed; renewals stopped, access revoked; recoverable | → `active` (payment method updated / retry succeeds), `cancelled` |
+| `paused` | Deliberately paused by you or the customer; billing frozen, access revoked | → `active` (resumed), `cancelled` |
 | `cancelled` | Will not renew | → `expired` (at period end) |
-| `failed` | Initial mandate/payment failed; terminal | (no recovery) |
+| `failed` | Initial mandate/payment failed at creation; terminal. Never reached from `on_hold` or exhausted retries | (no recovery) |
 | `expired` | Subscription term ended | (terminal) |
 
+`past_due` only occurs if you enable a grace period; without one, a failed renewal goes straight to `on_hold`.
+
 **Trial period:** If `trial_period_days` is set, the subscription enters `active` immediately but charges nothing until the trial ends. The first charge occurs on the trial end date.
 
 ---
@@ -108,6 +112,20 @@ const subscription = await client.subscriptions.retrieve('sub_xxxxx');
 console.log(subscription.status, subscription.next_billing_date);
 ```
 
+### Pause and Resume
+
+Pause and resume run through `status` on the update endpoint. Send it on its own: combining `paused`/`active` with any other field is rejected with `422`.
+
+```typescript
+// Pause: renewals stop, access is revoked, next_billing_date shifts by the pause length
+await client.subscriptions.update('sub_xxxxx', { status: 'paused' });
+
+// Resume
+await client.subscriptions.update('sub_xxxxx', { status: 'active' });
+```
+
+Pausing emits `subscription.paused`; resuming emits `subscription.unpaused`. Customer self-service pause in the portal is opt-in (**Settings → Subscriptions → Allow Subscription Pause**).
+
 ### Update Payment Method
 
 When a subscription is `on_hold` due to failed payment, the customer can update their payment method. This automatically charges any outstanding dues.
@@ -162,7 +180,7 @@ await client.subscriptions.changePlan('sub_xxxxx', {
 
 | Mode | Upgrade | Downgrade | Billing date |
 |------|---------|-----------|--------------|
-| `prorated_immediately` | Time-prorated charge | Time-prorated credit | Resets to change date |
+| `prorated_immediately` | Credit for unused time on the old plan, then charge a **full** new cycle (net = full new cycle − unused credit) | Same formula; a credit only remains if the unused credit exceeds the new plan price | Resets to change date |
 | `difference_immediately` | Full new-plan charge | Difference becomes credit | Resets |
 | `full_immediately` | Full new-plan charge | Full new-plan charge, no credit | Resets |
 | `do_not_bill` | No charge | No credit | Preserved |
@@ -172,6 +190,19 @@ await client.subscriptions.changePlan('sub_xxxxx', {
 - `prevent_change`: Keep the old plan if the charge fails.
 - `apply_change`: Apply the new plan even if payment fails (subscription may become `on_hold`).
 
+**Scheduling:** `effective_at` defaults to `'immediately'`. Pass `effective_at: 'next_billing_date'` to schedule the change (typical for downgrades) - nothing is charged now, the customer keeps the current plan until the period ends, and the pending change appears on the subscription as `scheduled_change` (cancel it with `cancelChangePlan`).
+
+```typescript
+await client.subscriptions.changePlan('sub_xxxxx', {
+  product_id: 'pdt_lower_tier',
+  quantity: 1,
+  proration_billing_mode: 'prorated_immediately',
+  effective_at: 'next_billing_date',
+});
+```
+
+**Plan changes are rejected while the subscription is `past_due`.** Settle the renewal debt first.
+
 ### Preview Plan Change
 
 Show the customer a quote before committing:
@@ -319,11 +350,16 @@ For full customer management (creating, updating, listing), see the `customer-ma
 | Event | When | Action |
 |-------|------|--------|
 | `subscription.active` | Subscription becomes active, including a trial start or recovery | Grant access |
+| `subscription.updated` | Any subscription field changes | Sync your stored copy (status, dates, metadata) |
 | `subscription.renewed` | Successful renewal | Log renewal, send receipt |
+| `subscription.past_due` | Renewal failed and the grace period opened (payload has `past_due_ends_at`) | Keep access, prompt for payment before the deadline |
 | `subscription.on_hold` | Renewal/plan-change payment failed | Notify customer, offer recovery |
+| `subscription.paused` | Subscription paused | Revoke access while paused |
+| `subscription.unpaused` | Paused subscription resumed | Restore access |
 | `subscription.plan_changed` | Plan upgraded/downgraded or add-ons changed | Update entitlements |
+| `subscription.update_payment_method` | Payment method updated | Update stored payment details |
 | `subscription.cancelled` | Customer cancels | Schedule access revocation per `cancel_at_next_billing_date` |
-| `subscription.failed` | Initial mandate/payment failed | Notify customer, offer retry or new subscription |
+| `subscription.failed` | Initial creation failed (mandate creation) | Notify customer, offer a new subscription |
 | `subscription.expired` | Subscription term ended | Revoke access |
 
 Webhook signature verification, raw-body handling, durable processing, and idempotency are covered in the `webhook-integration` skill.
@@ -357,6 +393,22 @@ export async function POST(req: NextRequest) {
     case 'subscription.on_hold':
       await notifyPaymentFailed(event.data.customer.customer_id);
       break;
+    case 'subscription.paused':
+    case 'subscription.unpaused': {
+      // Pause and resume can happen in quick succession, and handlers for
+      // different events can finish in any order. Don't trust the event type:
+      // re-read the subscription and apply its CURRENT status, scoped to this
+      // subscription (the customer may hold other active ones). Run this under
+      // a per-subscription lock if your handlers execute concurrently.
+      const current = await client.subscriptions.retrieve(event.data.subscription_id);
+      if (current.status === 'paused') {
+        await suspendSubscriptionAccess(current.subscription_id);
+      } else if (current.status === 'active' || current.status === 'past_due') {
+        // past_due keeps access during the payment grace period
+        await restoreSubscriptionAccess(current.subscription_id);
+      }
+      break;
+    }
     case 'subscription.cancelled':
       if (event.data.cancel_at_next_billing_date) {
         await scheduleAccessRevocation(event.data.subscription_id, new Date(event.data.next_billing_date));
@@ -459,9 +511,9 @@ await client.subscriptions.changePlan('sub_xxxxx', {
 
 This will fail. Always specify a proration mode.
 
-### 5. Confusing `on_hold` with Pause
+### 5. Confusing `on_hold` with `paused`
 
-`on_hold` means payment failed, not that the customer paused. There is no general pause/resume operation. `on_hold` is recoverable only by updating the payment method or waiting for retry.
+`on_hold` is involuntary: a payment failed, and it is recovered by updating the payment method or a successful retry. `paused` is deliberate: you or the customer froze the subscription with `subscriptions.update(id, { status: 'paused' })`, and it is resumed with `{ status: 'active' }`. Handle `subscription.paused`/`subscription.unpaused` separately from `subscription.on_hold`.
 
 ### 6. Not Handling `cancel_at_next_billing_date`
 
@@ -481,6 +533,7 @@ if (data.cancel_at_next_billing_date) {
 
 ## Resources
 
+- [Subscriptions (states, pause, grace period)](https://docs.dodopayments.com/features/subscription)
 - [Subscription Integration Guide](https://docs.dodopayments.com/developer-resources/subscription-integration-guide)
 - [Upgrade & Downgrade Guide](https://docs.dodopayments.com/developer-resources/subscription-upgrade-downgrade)
 - [On-Demand Subscriptions](https://docs.dodopayments.com/developer-resources/ondemand-subscriptions)

package/skills/testing-and-go-live/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: testing-and-go-live
-description: Guide for test-mode payment scenarios, renewal simulation, local webhook delivery tests, test and live catalog migration, and production launch checks.
+description: Dodo Payments test mode and production launch, covering test cards and payment methods, success and decline scenarios, renewal simulation, local webhook testing with the CLI, copying products from test to live, and a go-live checklist. Use when verifying payment flows, switching from test_mode to live_mode, or preparing to launch.
 ---
 
 # Testing and Go-Live
@@ -44,6 +44,8 @@ const client = new DodoPayments({
 ```
 
 ```python
+import os
+
 from dodopayments import DodoPayments
 
 client = DodoPayments(
@@ -67,31 +69,34 @@ Get your test API key from the Dodo dashboard. Test keys are prefixed `dodo_test
 
 ### Card success and decline scenarios
 
-Use these card numbers in test mode. The expiry can be any future date; the CVC can be any three digits.
+Use these card numbers in test mode with expiry **06/32** (or **12/34**) and CVV **123**.
 
 | Scenario | Card Number | Result |
 |---|---|---|
 | Success | `4242 4242 4242 4242` | Payment succeeds |
 | Decline | `4000 0000 0000 0002` | Payment declined |
 | Decline (insufficient funds) | `4000 0000 0000 9995` | Insufficient funds error |
-| Decline (lost card) | `4000 0000 0000 9987` | Lost card error |
+
+Only use cards listed on the [Testing Process](https://docs.dodopayments.com/miscellaneous/testing-process) page; other Stripe-style test numbers (for example "lost card" variants) are not documented for Dodo.
 
 ### Subscription renewal failure
 
 To test subscription renewal failures, use this card:
 
-| Card Number | Behavior |
-|---|---|
-| `4000 0000 0000 0069` | Renewal fails on next billing date |
+| Card Number | Expiry | CVV | Behavior |
+|---|---|---|---|
+| `4000 0000 0000 0341` | 12/34 | 123 | Declined at the subscription's next charge (renewal, upgrade, or downgrade) |
+
+Create the subscription with a success card first, then switch its payment method to this card in the Customer Portal.
 
 ### UPI (India)
 
-Test UPI success and failure with these VPAs:
+Test UPI success and failure with these VPAs. The billing country must be `IN` and the currency `INR` (non-Indian merchants also need Adaptive Currency enabled):
 
 | VPA | Result |
 |---|---|
-| `success@okhdfcbank` | Payment succeeds |
-| `failure@okhdfcbank` | Payment fails |
+| `success@upi` | Payment succeeds |
+| `failure@upi` | Payment fails |
 
 ### BNPL, wallets, and regional methods
 
@@ -162,7 +167,9 @@ dodo wh trigger payment.success http://localhost:3000/webhook
 
 Sends a realistic mock payload for a chosen event. It runs offline and works even while logged out — which is the tell for the part that matters: **these payloads are unsigned.** `unwrap()` rejects them because there is no valid signature to verify.
 
-Use `unsafeUnwrap()` for triggered events only, and never on an endpoint that also receives real traffic. Event names are `<category>.<event>`, for example `payment.success`, `subscription.active`, or `dispute.opened`.
+Use `unsafeUnwrap()` for triggered events only, and never on an endpoint that also receives real traffic. Trigger names are `<category>.<event>`, for example `payment.success`, `subscription.active`, or `dispute.opened`.
+
+**Trigger names are not always the payload `type`.** `payment.success` delivers `type: "payment.succeeded"`, `refund.success` delivers `refund.succeeded`, and `licence.created` delivers `license_key.created`. Switch on the payload types in your handler; a `case 'payment.success'` never matches.
 
 As with `listen`, both arguments are required in direct mode; `/wh trigger` inside the TUI opens a wizard instead.
 
@@ -184,19 +191,19 @@ Products are environment-specific. You cannot reuse a test product ID in product
 
 **Programmatic approach:**
 
-Fetch the product from test mode, extract its configuration, and create it in live mode:
+Fetch the product from test mode, extract its configuration, and create it in live mode. API keys are per mode — a test key does not authenticate against live mode and vice versa — so this needs two distinct keys:
 
 ```typescript
 // In test mode
 const testClient = new DodoPayments({
-  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
+  bearerToken: process.env.DODO_PAYMENTS_TEST_API_KEY,
   environment: 'test_mode',
 });
 const testProduct = await testClient.products.retrieve('pdt_test_123');
 
 // In live mode
 const liveClient = new DodoPayments({
-  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
+  bearerToken: process.env.DODO_PAYMENTS_LIVE_API_KEY,
   environment: 'live_mode',
 });
 const liveProduct = await liveClient.products.create({
@@ -331,5 +338,5 @@ Test keys (prefixed `dodo_test_`) only work with `https://test.dodopayments.com`
 
 - [Testing Process](https://docs.dodopayments.com/miscellaneous/testing-process)
 - [Test vs. Live Mode](https://docs.dodopayments.com/miscellaneous/test-mode-vs-live-mode)
-- [Webhook Integration](https://docs.dodopayments.com/developer-resources/webhooks/intents/introduction)
-- [Dodo CLI](https://docs.dodopayments.com/developer-resources/cli)
+- [Webhook Integration](https://docs.dodopayments.com/developer-resources/webhooks)
+- [Dodo CLI](https://docs.dodopayments.com/developer-resources/sdks/cli)

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

@@ -1,6 +1,6 @@
 ---
 name: usage-based-billing
-description: Guide for charging directly per measured API call, token, storage unit, or other consumption using meters, stable usage events, aggregation, free thresholds, and metered subscriptions.
+description: Dodo Payments usage-based billing that charges per measured unit, covering meters, usage event ingestion by event_name, aggregation, free thresholds, price_per_unit, and metered subscriptions. Use when billing per API call, AI token, storage, or bandwidth, sending usage events, or adding metered pricing to a plan; use credit-based-billing for prepaid credit pools.
 ---
 
 # Dodo Payments Usage-Based Billing
@@ -181,7 +181,7 @@ async function trackBatchUsage(
     customerId: string;
     eventName: string;
     occurredAt: string;
-    metadata: Record<string, string>;
+    metadata: Record<string, string | number | boolean>;
   }>
 ) {
   const formattedEvents = events.map((event) => ({
@@ -301,10 +301,11 @@ async function callAI(
       customer_id: customerId,
       event_name: 'ai.tokens',
       timestamp: completedAt,
+      // Aggregated properties (Sum/Max/Last) must be numbers, not strings.
       metadata: {
-        tokens: response.usage.total_tokens.toString(),
-        prompt_tokens: response.usage.prompt_tokens.toString(),
-        completion_tokens: response.usage.completion_tokens.toString(),
+        tokens: response.usage.total_tokens,
+        prompt_tokens: response.usage.prompt_tokens,
+        completion_tokens: response.usage.completion_tokens,
         model: 'gpt-4',
       }
     }]
@@ -331,9 +332,10 @@ async function updateStorageUsage(
       customer_id: customerId,
       event_name: 'storage.snapshot',
       timestamp: capturedAt,
+      // Numeric values: a string property does not aggregate.
       metadata: {
-        bytes: bytesUsed.toString(),
-        gb: (bytesUsed / 1024 / 1024 / 1024).toFixed(2),
+        bytes: bytesUsed,
+        gb: Number((bytesUsed / 1024 / 1024 / 1024).toFixed(2)),
       }
     }]
   });
@@ -355,15 +357,16 @@ await updateStorageUsage(
 ### Retrieve Usage History
 
 ```typescript
-const usage = await client.subscriptions.retrieveUsageHistory(
-  'sub_abc123',
-  { page_size: 100 }
-);
-
-console.log(usage.items); // Array of billing-period usage records
+// Auto-paginates across ALL billing periods; narrow with start_date/end_date/meter_id.
+for await (const period of client.subscriptions.retrieveUsageHistory('sub_abc123', {
+  start_date: '2025-01-01T00:00:00Z',
+  page_size: 20,
+})) {
+  console.log(period); // one record per billing period, with per-meter usage
+}
 ```
 
-This returns aggregated usage per meter for the subscription's current billing period.
+This is paginated usage history organized by billing period, across the subscription's lifetime - not just the current period. Filter with `start_date`, `end_date`, and `meter_id`, and iterate pages (or `for await`) rather than reading only the first page.
 
 ---
 
@@ -378,7 +381,7 @@ To link a meter to credits:
 3. On the meter, enable **Bill usage in Credits**.
 4. Set `credit_entitlement_id` and `meter_units_per_credit` (e.g., 1,000 tokens = 1 credit).
 
-Usage under the free threshold is excluded. Approximately every minute, a background worker aggregates new usage, converts it using the meter-to-credit ratio, and consumes the oldest non-expired credit grants (FIFO). When credits run out, configured overage behavior applies.
+The free threshold does **not** apply to credit-billed meters: every unit counts toward credit deduction (it only applies when the meter bills in money). Approximately every minute, a background worker aggregates new usage, converts it using the meter-to-credit ratio, and deducts from non-expired grants, earliest-expiring grants consumed first. When credits run out, configured overage behavior applies.
 
 ---