Localized Pricing

Localized Pricing, Adaptive Currency, and PPP

This skill covers three distinct mechanisms for pricing in multiple countries and currencies. Developers often confuse them. This skill disambiguates them, shows how to implement each, and explains their interactions with plan changes, proration, and tax.

When to use this skill

• You need to set fixed prices for specific countries or currencies.
• You want to offer live foreign-exchange conversion at checkout.
• You're considering purchasing power parity discounts for emerging markets.
• You're unsure whether to use localized pricing or adaptive currency.
• You need to handle billing-country and currency resolution, fallback behavior, or plan changes with localized prices.

Core concepts

Three mechanisms, three purposes

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

Set fixed prices for specific countries and currencies. Once created, a localized price does not change unless you update it. It does not track exchange rates.

Use localized pricing when you want predictable, region-specific pricing that you control.

Adaptive Currency

Enable live foreign-exchange conversion at checkout. The customer sees their local currency, and Dodo converts the base price using current rates.

Use adaptive currency when you want to offer checkout in any currency without manually setting prices for each one.

PPP (Purchasing Power Parity)

PPP is native (docs). 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).

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.

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

Every product has a pricing_mode that determines how prices are resolved:

• by_country: Dodo looks up a localized price by the customer's billing country.
• by_currency: Dodo looks up a localized price by the customer's billing currency.

Set the mode once per product via client.products.update(...). You cannot mix modes on the same product.

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
});

// Set pricing mode to by_country
await client.products.update('pdt_premium_plan', {
  pricing_mode: 'by_country',
});

// Or by_currency
await client.products.update('pdt_premium_plan', {
  pricing_mode: 'by_currency',
});

Localized Pricing CRUD

Localized prices are nested under products. All amounts are in the smallest currency unit (cents for USD, paise for INR).

Create a localized price

// ₹999.00 for customers in India
const localizedPrice = await client.products.localizedPrices.create('pdt_premium_plan', {
  currency: 'INR',
  country_code: 'IN',
  amount: 99900, // 999.00 in paise
});

List localized prices for a product

const prices = await client.products.localizedPrices.list('pdt_premium_plan');
console.log(prices);

Retrieve a specific localized price

const price = await client.products.localizedPrices.retrieve('lp_abc123', {
  product_id: 'pdt_premium_plan',
});
console.log(price.amount, price.currency, price.country_code);

Update a localized price

await client.products.localizedPrices.update('lp_abc123', {
  product_id: 'pdt_premium_plan',
  amount: 109900, // Update to ₹1099.00
});

Archive a localized price

await client.products.localizedPrices.archive('lp_abc123', {
  product_id: 'pdt_premium_plan',
});

Archived prices are soft-deleted. They no longer apply to new checkouts but remain in your history.

Adaptive Currency at checkout

Enable Adaptive Currency in the dashboard under Settings → Business (docs). 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.

// 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:

// 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 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

Dodo resolves the customer's billing country and currency in this order:

1. Explicit billing_address.country or billing_currency passed to checkout.
2. Customer's stored address (if the customer exists in Dodo).
3. IP geolocation (if available).
4. Fallback to your product's base price and currency.

If no localized price exists for the resolved country or currency, Dodo falls back to the base price. This fallback is automatic and does not raise an error.