@dodopayments/opencode-plugin 0.6.0 → 0.6.2

package/skills/mobile-checkout/references/react-native.md

@@ -0,0 +1,100 @@
+# Mobile In-App Checkout: React Native (Turbo Module)
+
+
+### Installation
+
+```bash
+npm install @dodopayments/react-native-checkout
+```
+
+For Expo projects, add the plugin to `app.json`:
+
+```json
+{
+  "expo": {
+    "scheme": "myapp",
+    "plugins": [
+      [
+        "@dodopayments/react-native-checkout",
+        { "scheme": "myappcheckout" }
+      ]
+    ]
+  }
+}
+```
+
+The plugin registers a custom URL scheme (`myappcheckout://`) that the checkout flow uses to return to your app.
+
+### Setup
+
+Register the URL listener at app startup:
+
+```typescript
+import { Linking } from 'react-native';
+import { DodoCheckout } from '@dodopayments/react-native-checkout';
+
+// Required for iOS return-URL handling
+Linking.addEventListener('url', ({ url }) => DodoCheckout.handleOpenURL(url));
+```
+
+### Starting checkout
+
+```typescript
+const result = await DodoCheckout.start({
+  checkoutUrl: 'https://checkout.dodopayments.com/...',  // from your backend
+  returnUrl: 'myappcheckout://checkout/return',          // must match registered scheme
+  onEvent: (e) => console.log(e.type),                   // optional event logging
+});
+
+switch (result.status) {
+  case 'succeeded':
+    // Payment succeeded. Verify server-side before granting access.
+    await verifyPaymentOnBackend(result.paymentId);
+    showSuccess();
+    break;
+  case 'failed':
+    // Payment failed. Show error to user.
+    showFailure();
+    break;
+  case 'cancelled':
+    // Sheet closed before the return URL arrived: the outcome is UNKNOWN and the
+    // payment may have succeeded. Do not show a failure - reconcile instead.
+    await reconcileAbandonedSession();
+    break;
+  case 'pending':
+    // Settles later (status=processing / requires_*), or status was missing.
+    await reconcileAbandonedSession();
+    break;
+  case 'expired':
+    // Checkout session expired. Prompt user to start a new checkout.
+    showExpired();
+    break;
+}
+```
+
+### Abandoned session recovery
+
+The SDK keeps a record of the session until checkout ends with `succeeded`, `failed`, or `expired`. The record survives an app kill and **stays after a `cancelled` or `pending` result**. Check it on the next launch and after every `cancelled`/`pending`:
+
+```typescript
+import { DodoCheckout } from '@dodopayments/react-native-checkout';
+
+async function reconcileAbandonedSession() {
+  const abandoned = await DodoCheckout.getAbandonedSession();
+  if (!abandoned) return;
+
+  // Your backend calls GET /checkouts/{abandoned.sessionId} and returns payment_status.
+  const outcome = await fetchCheckoutOutcome(abandoned.sessionId);
+  if (outcome === 'succeeded' || outcome === 'failed' || outcome === 'expired') {
+    showOutcome(outcome);
+    // Clear only once the outcome is final; until then treat it as pending, not failed.
+    await DodoCheckout.clearAbandonedSession();
+  } else {
+    showPending();
+  }
+}
+```
+
+### Android minSdk requirement
+
+React Native checkout requires Android minSdk 24 or higher. Note: the general mobile documentation mentions minSdk 23, but React Native specifically requires 24.

package/skills/product-catalog-management/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: product-catalog-management
-description: Guide for creating and managing products, pricing, add-ons, product collections, images, and digital product delivery
+description: Dodo Payments product catalog management, covering products with one_time_price, recurring_price, or usage_based_price, add-ons, product collections, product images, and digital file delivery. Use when creating or updating products, plans, or prices, building a storefront, uploading images, attaching downloadable files, or debugging a failed product update.
 ---
 
 # Product Catalog Management
@@ -13,7 +13,7 @@ This skill covers the full product lifecycle: creating products with pricing mod
 - You're building a product collection or storefront.
 - You need to upload product images or deliver digital files to customers.
 - You're managing add-ons or product variants.
-- You need to understand why a product update failed or why pricing can't be changed.
+- You need to understand why a product update failed or how to change a product's pricing.
 
 ## Core concepts
 
@@ -36,7 +36,7 @@ Pricing is nested inside the product object. There is no separate top-level Pric
 
 **Lifecycle:** Products support `list`, `retrieve`, `update`, and `archive`/`unarchive`. There is no delete endpoint. Archived products remain in your history but don't appear in new checkouts.
 
-**Images:** Presigned upload URLs expire after 60 seconds. Download the URL immediately after requesting it.
+**Images:** Presigned upload URLs expire after 60 seconds. Upload to the URL immediately after requesting it.
 
 **Digital delivery:** Entitlements grant customers access to files. Download URLs expire after roughly 15 minutes.
 
@@ -129,7 +129,9 @@ const product = await client.products.retrieve('pdt_pro_bundle');
 
 ## Updating a product
 
-You can update the name, description, and metadata. You cannot change the pricing model or price of a live product. Create a new product instead.
+`PATCH /products/{id}` (`client.products.update`) accepts the name, description, and metadata, and also `price`, `tax_category`, and `pricing_mode`. Every field is optional; omitted fields stay unchanged.
+
+Two limits apply. The **pricing model is immutable**: you can edit the amount, but you cannot turn a one-time product into a subscription or usage-based one (or back) - create a new product instead. And a price edit only changes what **new** customers pay: existing subscriptions keep the price they were created with, so move them explicitly with Change Plan (`client.subscriptions.changePlan(...)`).
 
 ```typescript
 await client.products.update('pdt_pro_bundle', {
@@ -226,14 +228,25 @@ await client.productCollections.groups.create(collection.id, {
   ],
 });
 
-// Checkout with a collection
-const session = await client.checkoutSessions.create({
-  product_collection_id: collection.id,
-  product_cart: [], // Required: pass an empty array for collection checkout
-  return_url: 'https://yoursite.com/return',
-});
+// Server route (e.g. POST /api/checkout): create the checkout session and return its URL
+export async function POST() {
+  const session = await client.checkoutSessions.create({
+    product_collection_id: collection.id,
+    product_cart: [], // Required: pass an empty array for collection checkout
+    return_url: 'https://yoursite.com/return',
+  });
 
-window.location.href = session.checkout_url;
+  return Response.json({ checkout_url: session.checkout_url });
+}
+```
+
+Never call the SDK or expose the API key in browser code. The browser only receives the URL from your server route and redirects:
+
+```typescript
+// Browser
+const res = await fetch('/api/checkout', { method: 'POST' });
+const { checkout_url } = (await res.json()) as { checkout_url: string };
+window.location.href = checkout_url;
 ```
 
 ## Digital product delivery
@@ -241,6 +254,9 @@ window.location.href = session.checkout_url;
 Entitlements grant customers access to downloadable files. Create an entitlement, upload files, and generate download links.
 
 ```typescript
+// openAsBlob requires Node.js 20 or later
+import { openAsBlob } from 'node:fs';
+
 // Create an entitlement
 const entitlement = await client.entitlements.create({
   name: 'Pro Bundle Files',
@@ -250,10 +266,15 @@ const entitlement = await client.entitlements.create({
   },
 });
 
-// Upload and attach a file; the response identifies the attached file
-const { file_id } = await client.entitlements.files.upload(entitlement.id);
+// Upload and attach a file as multipart/form-data (append `filename` before `file`)
+const form = new FormData();
+form.append('filename', 'pro-bundle.zip');
+form.append('file', await openAsBlob('./pro-bundle.zip'), 'pro-bundle.zip');
+const { file_id } = await client.entitlements.files.upload(entitlement.id, { body: form });
 
-// Attach the entitlement to a product
+// Attach the entitlement to a product.
+// `entitlements` REPLACES every entitlement already attached to the product:
+// include all of them, send [] to remove all, or omit the field to leave them unchanged.
 await client.products.update('pdt_pro_bundle', {
   entitlements: [{ entitlement_id: entitlement.id }],
 });
@@ -290,7 +311,9 @@ For country or currency-specific pricing, use the `localized-pricing` skill. Do
 
 **Expecting a delete endpoint:** Products don't have a delete method. Archive them instead. Archived products remain in your history for reconciliation.
 
-**Trying to change the pricing model:** Once a product is created with `one_time_price`, you can't change it to `recurring_price`. Create a new product and migrate customers to it.
+**Trying to change the pricing model:** You cannot switch a product between one-time, subscription, and usage-based pricing (for example `one_time_price` to `recurring_price`). Create a new product with the model you need.
+
+**Expecting a price edit to reprice existing subscribers:** `client.products.update(...)` changes the amount for new customers only. Existing subscriptions renew at the price they were created with; move them with `client.subscriptions.changePlan(...)`.
 
 **Hardcoding prices in the client:** Always fetch the product catalog from the API. Prices change, and your client code will become stale. Read `client.products.retrieve(id)` to get the current price.
 
@@ -300,7 +323,7 @@ For country or currency-specific pricing, use the `localized-pricing` skill. Do
 
 **Passing a non-empty product_cart for collection checkout:** Collection checkout requires `product_cart: []`. The collection itself defines what's in the cart.
 
-**Confusing purchasing_power_parity with localized pricing:** The OpenAPI schema includes a `purchasing_power_parity` field in examples, but it's marked unavailable. Use the `localized-pricing` skill for country and currency pricing instead.
+**Confusing purchasing_power_parity with localized pricing:** PPP is native. Set `price.purchasing_power_parity: true` to charge a business-wide, per-country percentage of the price (default `false`). It requires Adaptive Currency to be enabled, and a matching localized price always wins over PPP. See the `localized-pricing` skill.
 
 ## Resources
 

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:
@@ -316,64 +347,11 @@ For full customer management (creating, updating, listing), see the `customer-ma
 
 ## Webhook Events
 
-| Event | When | Action |
-|-------|------|--------|
-| `subscription.active` | Subscription becomes active, including a trial start or recovery | Grant access |
-| `subscription.renewed` | Successful renewal | Log renewal, send receipt |
-| `subscription.on_hold` | Renewal/plan-change payment failed | Notify customer, offer recovery |
-| `subscription.plan_changed` | Plan upgraded/downgraded or add-ons changed | Update entitlements |
-| `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.expired` | Subscription term ended | Revoke access |
-
-Webhook signature verification, raw-body handling, durable processing, and idempotency are covered in the `webhook-integration` skill.
+Full guide: [references/webhook-events.md](references/webhook-events.md).
 
-### Example Handler
+Covers:
 
-```typescript
-import { NextRequest, NextResponse } from 'next/server';
-
-export async function POST(req: NextRequest) {
-  const raw = await req.text();
-  const headers = Object.fromEntries(req.headers.entries());
-  const event = await client.webhooks.unwrap(raw, { headers });
-  const webhookId = req.headers.get('webhook-id');
-
-  if (!webhookId) {
-    return NextResponse.json({ error: 'Missing webhook-id' }, { status: 400 });
-  }
-
-  // Implement this as an atomic insert backed by a UNIQUE constraint.
-  // Keep the claim and entitlement changes in the same database transaction.
-  const claimed = await claimWebhookId(webhookId);
-  if (!claimed) {
-    return NextResponse.json({ received: true });
-  }
-
-  switch (event.type) {
-    case 'subscription.active':
-      await grantAccess(event.data.customer.customer_id, event.data.product_id);
-      break;
-    case 'subscription.on_hold':
-      await notifyPaymentFailed(event.data.customer.customer_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));
-      } else {
-        await revokeAccessImmediately(event.data.subscription_id);
-      }
-      break;
-    case 'subscription.expired':
-      await revokeAccess(event.data.customer.customer_id);
-      break;
-  }
-
-  return NextResponse.json({ received: true });
-}
-```
-
----
+- Example Handler
 
 ## Credit Entitlements
 
@@ -459,9 +437,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 +459,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)