@dodopayments/opencode-plugin 0.5.1 → 0.6.1

package/skills/license-keys/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: license-keys
-description: Guide for implementing license key management with Dodo Payments - activation, validation, and access control for software products.
+description: Dodo Payments license keys for software products, covering activation, validation, and deactivation via client.licenses, activation limits, expiry, entitlement grants, revocation, and license webhooks. Use when gating a desktop app, CLI, plugin, or SaaS feature behind a license key, enforcing per-seat or per-device limits, or building a license dashboard.
 ---
 
 # Dodo Payments License Keys
@@ -26,8 +26,11 @@ License keys authorize access to your digital products. Use them for software li
    - `validate()` — check if a key is valid
    - `deactivate()` — free an activation slot
 
-2. **`client.licenseKeys.*`** — merchant-side key management (requires API key)
-   - `list()`, `retrieve()`, `create()`, `update()` — manage keys for your customers
+2. **Entitlement grants** — merchant-side reads and revocation (requires API key)
+   - `client.customers.listEntitlementGrants()`, `client.entitlements.grants.list()` — list issued keys (each license-key grant carries a `license_key` object)
+   - `client.entitlements.grants.revoke()` — revoke a key
+   - `client.licenseKeys.create()` — still supported, for **importing** existing keys
+   - `client.licenseKeys.list()` / `retrieve()` / `update()` are **deprecated** (`GET /license_keys`, `GET`/`PATCH /license_keys/{id}`); use the grant endpoints above instead
 
 3. **`client.licenseKeyInstances.*`** — per-device activation instances (requires API key)
    - `list()`, `retrieve()`, `update()` — track active devices per key
@@ -36,7 +39,7 @@ License keys authorize access to your digital products. Use them for software li
 
 **Expiry semantics:**
 - One-time-payment keys honor the entitlement duration.
-- Subscription-issued keys have no independent expiry; validity follows subscription state. On hold disables them temporarily. An immediate cancellation disables them permanently, but when `cancel_at_next_billing_date` is set, keep them active until the subscription reaches the end of its term.
+- Subscription-issued keys have no independent expiry; Dodo drives their validity from subscription state **automatically**: `past_due` leaves them active, `on_hold` and `paused` disable them until the subscription recovers or resumes, `cancelled`/`expired` disable them permanently, and `plan_changed` replaces them. A one-time `refund.succeeded` also disables them. You do not need to disable keys yourself.
 - Imported keys use nullable `expires_at`; null means perpetual.
 
 ---
@@ -48,8 +51,10 @@ License keys authorize access to your digital products. Use them for software li
 ```typescript
 import DodoPayments from 'dodopayments';
 
-// No API key needed for public endpoints
-const client = new DodoPayments();
+// The license endpoints are public and don't check the token, but the SDK
+// constructor requires a value. Never ship your secret API key in client software.
+// Set the environment explicitly: the SDK defaults to live_mode.
+const client = new DodoPayments({ bearerToken: 'public', environment: 'test_mode' });
 
 async function activateLicense(licenseKey: string, deviceName: string) {
   try {
@@ -80,12 +85,15 @@ Response includes `id` (instance ID), `business_id`, `name`, `license_key_id`, `
 ```typescript
 import DodoPayments from 'dodopayments';
 
-const client = new DodoPayments();
+const client = new DodoPayments({ bearerToken: 'public', environment: 'test_mode' }); // public endpoints: placeholder token; use 'live_mode' in production
 
-async function validateLicense(licenseKey: string) {
+async function validateLicense(licenseKey: string, instanceId: string) {
   try {
     const response = await client.licenses.validate({
       license_key: licenseKey,
+      // Also checks that THIS device's activation still exists, so a
+      // deactivated device stops validating even though the key is active.
+      license_key_instance_id: instanceId,
     });
 
     return { valid: response.valid };
@@ -95,14 +103,14 @@ async function validateLicense(licenseKey: string) {
 }
 ```
 
-Optional: pass `license_key_instance_id` to validate a specific instance.
+Without `license_key_instance_id`, validation only checks that the key is `active` and unexpired. Pass the instance ID you stored at activation.
 
 ### Deactivate a license
 
 ```typescript
 import DodoPayments from 'dodopayments';
 
-const client = new DodoPayments();
+const client = new DodoPayments({ bearerToken: 'public', environment: 'test_mode' }); // public endpoints: placeholder token; use 'live_mode' in production
 
 async function deactivateLicense(licenseKey: string, instanceId: string) {
   try {
@@ -122,7 +130,9 @@ async function deactivateLicense(licenseKey: string, instanceId: string) {
 
 ## Merchant-Side Key Management
 
-### List customer license keys
+### List a customer's license keys
+
+`client.licenseKeys.list()`, `retrieve()`, and `update()` are deprecated. Read keys through the entitlement grant endpoints; each license-key grant carries a `license_key` object (`key`, `status`, `expires_at`, `activations_used`, `activations_limit`), which is `null` on a manual-mode grant still `Pending`.
 
 ```typescript
 import DodoPayments from 'dodopayments';
@@ -133,48 +143,39 @@ const client = new DodoPayments({
 });
 
 async function listCustomerKeys(customerId: string) {
-  const keys = await client.licenseKeys.list({
-    customer_id: customerId,
-  });
-
-  return keys.items.map(key => ({
-    id: key.id,
-    key: key.key,
-    status: key.status,
-    expiresAt: key.expires_at,
-    activationsUsed: key.instances_count,
-    activationsLimit: key.activations_limit,
-  }));
+  const keys = [];
+  for await (const grant of client.customers.listEntitlementGrants(customerId, {
+    integration_type: 'license_key',
+    status: 'Delivered',
+  })) {
+    if (!grant.license_key) continue;
+    keys.push({
+      grantId: grant.id,
+      entitlementId: grant.entitlement_id,
+      key: grant.license_key.key,
+      status: grant.license_key.status,
+      expiresAt: grant.license_key.expires_at,
+      activationsUsed: grant.license_key.activations_used,
+      activationsLimit: grant.license_key.activations_limit,
+    });
+  }
+  return keys;
 }
 ```
 
-### Retrieve a single license key
-
-```typescript
-const key = await client.licenseKeys.retrieve('lk_abc123');
-
-console.log({
-  id: key.id,
-  key: key.key,
-  status: key.status,
-  expiresAt: key.expires_at,
-  activationsUsed: key.instances_count,
-  activationsLimit: key.activations_limit,
-});
-```
+To list every key issued for one License Key entitlement, use `client.entitlements.grants.list('ent_...', { status: 'Delivered' })`.
 
-### Update a license key
+### Revoke a license key
 
 ```typescript
-// Disable a key or adjust its activation limit
-await client.licenseKeys.update('lk_abc123', {
-  disabled: true,
-  // or adjust activations_limit
-  activations_limit: 10,
-});
+// Disables the key with revocation_reason: manual. Manually revoked keys are
+// not re-granted on subscription renewal.
+await client.entitlements.grants.revoke('entg_abc123', { id: 'ent_license_key_id' });
 ```
 
-### Create a license key (manual issuance)
+### Import a license key (`POST /license_keys`)
+
+Use this to migrate keys from another system. Imported keys do **not** trigger a customer email; notify the customer yourself. For keys Dodo issues, Dodo emails them.
 
 ```typescript
 const newKey = await client.licenseKeys.create({
@@ -227,12 +228,13 @@ import DodoPayments from 'dodopayments';
 import os from 'os';
 
 const store = new Store();
-const client = new DodoPayments();
+const client = new DodoPayments({ bearerToken: 'public', environment: 'test_mode' }); // public endpoints: placeholder token; use 'live_mode' in production
 
 interface LicenseInfo {
   key: string;
   instanceId: string;
   activatedAt: string;
+  lastValidatedAt?: string; // last time the server confirmed the license (absent on records saved before it was added)
 }
 
 export async function activateLicense(licenseKey: string): Promise<boolean> {
@@ -244,10 +246,12 @@ export async function activateLicense(licenseKey: string): Promise<boolean> {
       name: deviceName,
     });
 
+    const now = new Date().toISOString();
     const licenseInfo: LicenseInfo = {
       key: licenseKey,
       instanceId: response.id,
-      activatedAt: new Date().toISOString(),
+      activatedAt: now,
+      lastValidatedAt: now,
     };
 
     store.set('license', licenseInfo);
@@ -268,16 +272,37 @@ export async function checkLicense(): Promise<boolean> {
   try {
     const response = await client.licenses.validate({
       license_key: license.key,
+      license_key_instance_id: license.instanceId,
     });
 
-    return response.valid;
+    if (!response.valid) {
+      // An explicit "invalid" from the server (revoked key, deactivated
+      // instance) ends the license: drop the cache so a later offline start
+      // cannot fall back to the grace period.
+      store.delete('license');
+      return false;
+    }
+    store.set('license', { ...license, lastValidatedAt: new Date().toISOString() });
+    return true;
   } catch (error) {
-    // If offline, trust local license with a grace period
-    const activatedAt = new Date(license.activatedAt);
-    const daysSinceActivation = (Date.now() - activatedAt.getTime()) / (1000 * 60 * 60 * 24);
+    // Only a connection failure (offline, DNS, timeout) earns the grace period.
+    // Any other API error - a revoked key, a deactivated instance - is a real
+    // answer from the server, so fail closed.
+    if (!(error instanceof DodoPayments.APIConnectionError)) {
+      return false;
+    }
+
+    // Trust the cached result only within a grace period measured from the
+    // LAST SUCCESSFUL validation, not from activation - otherwise a key revoked
+    // yesterday keeps working offline for 30 days after activation, and an old
+    // activation gets no grace at all.
+    // Records saved before lastValidatedAt existed fall back to activatedAt
+    // until their first successful validation.
+    const lastValidated = new Date(license.lastValidatedAt ?? license.activatedAt);
+    const daysSinceValidation = (Date.now() - lastValidated.getTime()) / (1000 * 60 * 60 * 24);
 
     // Allow 30-day offline grace period
-    return daysSinceActivation < 30;
+    return daysSinceValidation < 30;
   }
 }
 
@@ -384,7 +409,7 @@ interface CliStore {
 
 // Typing the store keeps `config.get('license')` strongly typed at every call site.
 const config = new Conf<CliStore>({ projectName: 'your-cli' });
-const client = new DodoPayments();
+const client = new DodoPayments({ bearerToken: 'public', environment: 'test_mode' }); // public endpoints: placeholder token; use 'live_mode' in production
 
 export async function activate(licenseKey: string): Promise<void> {
   const machineId = machineIdSync();
@@ -423,6 +448,7 @@ export async function checkLicense(): Promise<boolean> {
   try {
     const response = await client.licenses.validate({
       license_key: license.key,
+      license_key_instance_id: license.instanceId,
     });
 
     return response.valid;
@@ -508,9 +534,9 @@ program.parse();
 
 ### Handle license key delivery
 
-When a product with licensing enabled is purchased, an `entitlement_grant.delivered` webhook fires with the license key details:
+Dodo generates **and emails** each auto-fulfilled key to the customer (including the entitlement's activation message), and it disables, re-enables, and replaces keys as the subscription changes state. Your webhook only needs to mirror that state for your own records - do not email keys yourself and do not disable keys on cancellation.
 
-Persist a local license-to-subscription association during fulfillment. Cancellation handling must query that association by `subscription_id`; filtering only by customer would also revoke keys for unrelated products or subscriptions.
+When a product with licensing enabled is purchased, an auto-fulfilled key arrives as `entitlement_grant.created` with `status: "Delivered"` and a `license_key` object; no separate `entitlement_grant.delivered` follows. `entitlement_grant.delivered` fires only when a grant moves to `Delivered` later (for example, when you manually fulfill a `Pending` grant, or a revoked grant is restored), so handle both:
 
 ```typescript
 // app/api/webhooks/dodo/route.ts
@@ -520,6 +546,7 @@ import DodoPayments from 'dodopayments';
 const client = new DodoPayments({
   bearerToken: process.env.DODO_PAYMENTS_API_KEY,
   webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
+  environment: process.env.DODO_PAYMENTS_ENVIRONMENT === 'live_mode' ? 'live_mode' : 'test_mode',
 });
 
 export async function POST(req: NextRequest) {
@@ -533,46 +560,19 @@ export async function POST(req: NextRequest) {
       },
     });
 
-    if (event.type === 'entitlement_grant.delivered') {
-      const { customer_id, id, license_key } = event.data;
-
-      // Delivered grants for other entitlement types do not include a license key.
-      if (!license_key) {
-        return NextResponse.json({ received: true });
-      }
-
-      // Store in your database
-      await prisma.license.create({
-        data: {
-          externalId: id,
-          key: license_key.key,
-          customerId: customer_id,
-          expiresAt: license_key.expires_at ? new Date(license_key.expires_at) : null,
-          activationsLimit: license_key.activations_limit,
-          status: 'active',
-        },
-      });
-
-      // Send email with activation instructions
-      await sendLicenseEmail(customer_id, license_key.key);
+    if (
+      (event.type === 'entitlement_grant.created' || event.type === 'entitlement_grant.delivered') &&
+      event.data.status === 'Delivered' &&
+      event.data.license_key // other entitlement types (and Pending manual grants) have no key
+    ) {
+      // Dodo emails the key to the customer itself, so there is no email to send here.
+      await mirrorGrant(event.data, 'active');
     }
 
-    if (event.type === 'subscription.cancelled' || event.type === 'subscription.expired') {
-      const { subscription_id, cancel_at_next_billing_date } = event.data;
-
-      // End-of-period cancellation keeps access active until the term expires.
-      if (event.type === 'subscription.cancelled' && cancel_at_next_billing_date) {
-        return NextResponse.json({ received: true });
-      }
-
-      // Query your persisted license-to-subscription mapping.
-      const licenseKeyIds = await getLicenseKeyIdsForSubscription(subscription_id);
-
-      for (const licenseKeyId of licenseKeyIds) {
-        await client.licenseKeys.update(licenseKeyId, {
-          disabled: true,
-        });
-      }
+    if (event.type === 'entitlement_grant.revoked') {
+      // Dodo already disabled the key (cancellation, expiry, refund, on_hold,
+      // pause, plan change, or manual revoke). Mirror it locally.
+      await mirrorGrant(event.data, 'revoked');
     }
 
     return NextResponse.json({ received: true });
@@ -581,15 +581,58 @@ export async function POST(req: NextRequest) {
     return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
   }
 }
+
+type Grant = DodoPayments.Entitlements.EntitlementGrant;
+
+// Webhooks can arrive out of order and be retried concurrently. Apply a grant
+// only when it is newer than the stored copy (by the grant's own updated_at),
+// using a conditional UPDATE so a stale "delivered" can never overwrite a newer
+// "revoked". If no row exists yet - including a revocation that arrives before
+// the delivery - insert one; the unique externalId keeps concurrent inserts
+// safe, and the loser retries the conditional update so the newest grant wins.
+async function mirrorGrant(grant: Grant, status: 'active' | 'revoked') {
+  const grantUpdatedAt = new Date(grant.updated_at);
+  const fields = {
+    customerId: grant.customer_id,
+    status,
+    grantUpdatedAt,
+    ...(grant.license_key && {
+      key: grant.license_key.key,
+      expiresAt: grant.license_key.expires_at ? new Date(grant.license_key.expires_at) : null,
+      activationsLimit: grant.license_key.activations_limit,
+    }),
+  };
+
+  const applyIfNewer = () =>
+    prisma.license.updateMany({
+      where: { externalId: grant.id, grantUpdatedAt: { lt: grantUpdatedAt } },
+      data: fields,
+    });
+
+  const updated = await applyIfNewer();
+  if (updated.count > 0) return;
+
+  // Either no row yet, or the stored copy is already as new or newer.
+  const inserted = await prisma.license.createMany({
+    data: [{ externalId: grant.id, ...fields }],
+    skipDuplicates: true,
+  });
+  if (inserted.count === 0) {
+    // A concurrent webhook inserted the row first. It may hold an OLDER grant,
+    // so re-run the conditional update; it is a no-op if the row is newer.
+    await applyIfNewer();
+  }
+}
 ```
 
 **Webhook events:**
 
-- `entitlement_grant.delivered` — license key issued (current, recommended)
-- `entitlement_grant.revoked` — license key revoked
+- `entitlement_grant.created` — grant created; `status: "Delivered"` with a `license_key` for auto-fulfilled keys (the primary issuance event), `status: "Pending"` with no key for manual fulfillment
+- `entitlement_grant.delivered` — an existing grant moved to `Delivered` (manual fulfillment, or a revoked grant restored); not sent for auto-fulfilled keys
+- `entitlement_grant.revoked` — license key revoked (Dodo already disabled it; mirror the state, inspect `revocation_reason`)
 - `license_key.created` — legacy event (still fires, but use `entitlement_grant.*` for new integrations)
-- `subscription.cancelled` — disable only this subscription's keys for immediate cancellation
-- `subscription.expired` — disable this subscription's keys when its term ends
+
+Subscription `cancelled`/`expired`/`on_hold`/`paused` events need no license action from you: Dodo disables the keys itself, and `licenses.validate()` reflects it immediately.
 
 ---
 
@@ -675,6 +718,7 @@ store.set('license', {
   key,
   instanceId: response.id,
   activatedAt: new Date().toISOString(),
+  lastValidatedAt: new Date().toISOString(),
 });
 ```
 
@@ -712,5 +756,6 @@ try {
 - [Validate License API](https://docs.dodopayments.com/api-reference/licenses/validate-license)
 - [Deactivate License API](https://docs.dodopayments.com/api-reference/licenses/deactivate-license)
 - [License Key Instances API](https://docs.dodopayments.com/api-reference/licenses/get-license-key-instances)
+- [List Customer Grants API](https://docs.dodopayments.com/api-reference/entitlements/list-customer-grants)
 - [Entitlement Grant Webhooks](https://docs.dodopayments.com/developer-resources/webhooks/intents/entitlement-grant)
 - [Webhook Verification](https://docs.dodopayments.com/developer-resources/webhooks/verification)

package/skills/localized-pricing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: localized-pricing
-description: Guide for implementing localized pricing, adaptive currency, and purchasing power parity with Dodo Payments
+description: Dodo Payments multi-currency pricing, covering fixed localized prices per country or currency, Adaptive Currency live FX conversion at checkout, and purchasing power parity (PPP) percentages. Use when pricing in INR, EUR, or other local currencies, offering regional or PPP discounts, or resolving billing country and currency fallback.
 ---
 
 # Localized Pricing, Adaptive Currency, and PPP
@@ -23,9 +23,9 @@ This skill covers three distinct mechanisms for pricing in multiple countries an
 |---|---|---|---|
 | **Localized Pricing** | Developer sets fixed prices per country/currency | You (via API) | Only when you update them |
 | **Adaptive Currency** | Live FX conversion at checkout time | Dodo (live rates) | Every transaction, based on current rates |
-| **PPP Discounts** | Third-party tools generate discount codes for low-income regions | ParityDeals, Evendeals, or similar | Per tool's schedule |
+| **Purchasing Power Parity (PPP)** | Charges a per-country percentage of the base price | You (business-wide country percentages in the dashboard, per-product opt-in) | Only when you change the percentages |
 
-**Key distinction:** Localized prices are static. Adaptive currency is dynamic. PPP is a discount mechanism, not a pricing mode.
+**Key distinction:** Localized prices are static. Adaptive currency is dynamic. PPP is a native per-country percentage applied to the base price before Adaptive Currency converts it.
 
 ### Localized Pricing
 
@@ -41,9 +41,23 @@ Use adaptive currency when you want to offer checkout in any currency without ma
 
 ### PPP (Purchasing Power Parity)
 
-Third-party services like ParityDeals or Evendeals generate discount codes for customers in low-income countries. These are not a native Dodo API feature. You integrate them by accepting the discount codes they generate and passing them to Dodo at checkout.
+PPP is native ([docs](https://docs.dodopayments.com/features/purchasing-power-parity)). Dodo keeps one business-wide percentage per country (30 to 100, managed in the dashboard only), and the customer pays that share of your list price based on their billing country. Each product opts in with `price.purchasing_power_parity: true` (default `false`).
 
-Use PPP when you want to offer affordability-based discounts without building your own detection logic.
+PPP requires Adaptive Currency: enable it under **Settings → Business** first, or product opt-in is rejected. A matching localized price always wins over PPP, and discount codes apply to the PPP-reduced price.
+
+```typescript
+await client.products.create({
+  name: 'Starter Plan',
+  tax_category: 'saas',
+  price: {
+    type: 'one_time_price',
+    currency: 'USD',
+    price: 2000, // $20.00; a customer in India at 30% pays $6.00
+    discount: 0,
+    purchasing_power_parity: true,
+  },
+});
+```
 
 ## Product pricing mode
 
@@ -125,24 +139,40 @@ Archived prices are soft-deleted. They no longer apply to new checkouts but rema
 
 ## Adaptive Currency at checkout
 
-Enable adaptive currency by passing `billing_currency` to a checkout session. Dodo converts the base product price using live rates.
+Enable Adaptive Currency in the dashboard under **Settings → Business** ([docs](https://docs.dodopayments.com/features/adaptive-currency)). Dodo then converts the base product price at live rates. Passing `billing_currency` and `billing_address.country` on a checkout session only pins the currency you charge in; if you omit them, Adaptive Currency picks the currency and country from the customer's IP address.
 
 ```typescript
-const session = await client.checkoutSessions.create({
-  product_cart: [
-    {
-      product_id: 'pdt_premium_plan',
-      quantity: 1,
-    },
-  ],
-  billing_currency: 'AED', // Customer sees price in AED
-  return_url: 'https://example.com/return',
-});
+// Server route (e.g. POST /api/checkout): create the session and return its URL
+export async function POST() {
+  const session = await client.checkoutSessions.create({
+    product_cart: [
+      {
+        product_id: 'pdt_premium_plan',
+        quantity: 1,
+      },
+    ],
+    billing_currency: 'AED', // Pin the charge currency (requires Adaptive Currency)
+    billing_address: { country: 'AE' },
+    return_url: 'https://example.com/return',
+  });
+
+  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 and redirects:
 
-// Redirect customer to checkout
-window.location.href = session.checkout_url;
+```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;
 ```
 
+**Fees:** Adaptive Currency adds a tiered conversion fee (4% under $500, 3% from $500 to $1,500, 2% above $1,500) on top of the displayed price by default. Turn on **Fees Inclusive** in **Settings → Business** to absorb the fee from your settlement instead. When a localized price matches, the transaction is always treated as fees-inclusive.
+
+**Charm Pricing:** With Adaptive Currency on, [Charm Pricing](https://docs.dodopayments.com/features/charm-pricing) can round the converted price to a clean ending such as 49.99. It requires Adaptive Currency.
+
 Adaptive currency is also available on subscription creation and plan changes. Check the API reference for `billing_currency` support on the specific endpoint you're using.
 
 ## Billing country and currency resolution
@@ -195,7 +225,7 @@ A customer in India using a USD card will match `by_currency: USD` but not `by_c
 
 ### Mistake 3: Forgetting a fallback price
 
-If you set `pricing_mode: by_country` but don't create a localized price for a customer's country, Dodo falls back to the base price in the base currency. This is usually not what you want.
+If you set `pricing_mode: by_country` but don't create a localized price for a customer's country, Dodo falls back to the base price: charged directly if the customer is already in your base currency, or converted through Adaptive Currency when that is enabled ([docs](https://docs.dodopayments.com/features/localized-pricing)). Without Adaptive Currency, that is the base price in the base currency, which is usually not what you want.
 
 Always create localized prices for your target markets before enabling the mode.
 
@@ -205,17 +235,9 @@ You can use both on the same product, but they serve different purposes. Localiz
 
 If you set a localized price for India and also enable adaptive currency, the localized price takes precedence for customers in India.
 
-### Mistake 5: Expecting PPP to be a native Dodo API
-
-PPP discounts are generated by third-party services like ParityDeals or Evendeals. Dodo does not have a built-in PPP API. You integrate PPP by accepting discount codes from these services and passing them to Dodo at checkout.
+### Mistake 5: Reaching for a third-party tool for PPP
 
-```typescript
-const session = await client.checkoutSessions.create({
-  product_cart: [{ product_id: 'pdt_premium_plan', quantity: 1 }],
-  discount_codes: ['PPP_DISCOUNT_CODE_FROM_PARITY_DEALS'],
-  return_url: 'https://example.com/return',
-});
-```
+PPP is native: opt products in with `price.purchasing_power_parity: true` and set country percentages in the dashboard (Adaptive Currency must be on). Third-party tools like ParityDeals are only an alternative if you want their site banners; their codes are passed as ordinary `discount_codes` at checkout.
 
 ### Mistake 6: Not handling missing localized prices in production