> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Localize prices

Improve conversion rates by offering customers prices in local currencies. Let Paddle automatically convert amounts, and set country specific pricing for key markets.

---

Paddle supports [over 200 countries and territories](https://developer.paddle.com/concepts/sell/supported-countries-locales.md) and [30 currencies](https://developer.paddle.com/concepts/sell/supported-currencies.md), with no extra setup or engineering effort required. You can localize prices to build customer confidence and improve payment acceptance.

Localized pricing in Paddle lets you do things like:

- Automatically convert prices to local currencies.
- Offer US Dollar pricing in non-US markets.
- Set different prices for different countries or regions that share a currency.
- Price according to willingness-to-pay and purchasing power.

{% callout type="note" %}
Paddle automatically handles conversion into your balance currency for you, meaning you see the amount you earned in your preferred currency no matter what currency customers pay in.
{% /callout %}

## How it works

[Complete products in Paddle](https://developer.paddle.com/build/products/create-products-prices.md) are made up of a product entity and related price entities. [Price entities](https://developer.paddle.com/api-reference/prices/overview.md) describe how much and how often a product is charged.

When you create a price, you can set how much it costs and its currency. This is called the base price.

You can charge all customers your base price, or you can localize your prices using:

- [**Automatic currency conversion**](#background-automatic-conversion)  
  Let Paddle automatically convert your prices into the local currency for a customer at checkout.
- [**Country specific pricing**](#background-price-overrides)  
  Override base prices with custom prices and currencies for countries that you choose.

Automatic currency conversion and country specific pricing work together — you don't have to pick one or the other, you can use both. If you like, you can just charge your base prices, turning off price localization altogether.

### Automatic currency conversion

Paddle can automatically convert prices into local currencies for customers at checkout. For example, your base price can be in US Dollar (`USD`), but customers can pay in Pound Sterling (`GBP`), Brazilian Real (`BRL`), or Indian Rupee (`INR`) depending on their location.

Offering local currencies is recommended because:

- It builds trust by helping customers understand exactly what they're paying.
- It means customers don't incur FX fees from their bank when making a payment.
- Local banks are more likely to approve payments in the local currency.

You can turn on automatic currency conversion for all supported currencies, or choose the currencies that you want to enable it for.

### Country specific pricing

While offering prices in local currencies is important, you can further boost conversion by tailoring prices to local market conditions. For example, 100 `USD` buys you less in the United Kingdom and more in India than it does in the United States.

Use country specific pricing in Paddle to manually override base prices with custom prices for countries that you choose. It lets you price according to purchasing power and willingness-to-pay, meaning:

- You can maximize revenue in markets where willingness-to-pay is higher, charging more than your base price.
- You can increase your volume of sales by expanding into emerging markets, pricing according to purchasing power.

For example:

|                                   | United States | United Kingdom       | Brazil               | India                 |
|-----------------------------------|---------------|----------------------|----------------------|-----------------------|
| **Automatic currency conversion** | `100 USD`     | `79 GBP`             | `478 BRL`            | `8200 INR`            |
| **Price overrides**               | `100 USD`     | `90 GBP` [`115 USD`] | `52 USD` [`248 BRL`] | `2320 INR` [`28 USD`] |

{% callout type="info" %}
These figures are illustrative. They may not be exactly what you see at checkout.
{% /callout %}

As well as setting the unit price, you can set the currency too. This is useful for countries like Brazil, where `USD` is often preferred to `BRL`.

You can create country specific prices when creating prices in Paddle. They're called price overrides in the API.

### Customer experience

Paddle automatically shows the correct prices for a customer at [checkout](https://developer.paddle.com/concepts/sell/self-serve-checkout.md). When opening a checkout, Paddle uses geolocation to estimate where a customer is buying from. If a customer changes the preselected country, Paddle gets localized prices for the country they selected.

Paddle shows localized prices in this order:

1. Country specific price and currency (price override) for the customer country
2. Automatically converted price in the local currency for the customer country
3. Base price in base currency

When [building a pricing page](https://developer.paddle.com/build/checkout/build-pricing-page.md), you can pass an IP address or location information to return localized prices.

## Before you begin

Country specific prices (price overrides) are set against prices in Paddle, so you'll need to [create products and prices](https://developer.paddle.com/build/products/create-products-prices.md) first. You can add country specific prices when creating a price initially, or update prices to add them later.

## Turn on automatic currency conversion

{% instruction-steps %}

1. Go to **Paddle** > **Business account** > **Currencies**.
2. Use the checkboxes to select currencies that you want Paddle to automatically convert, or check **Select all**.
3. Click {% mock-button %}Save when you're done.
{% /instruction-steps %}

{% /dashboard-instructions %}

## Add price overrides to a price

You can add price overrides to a price when [creating](https://developer.paddle.com/build/products/create-products-prices.md) or updating it.

We recommend creating price overrides using the Paddle dashboard.

{% tabs sync="interaction-preference" %}
{% tab-item title="Dashboard" %}

{% instruction-steps %}

1. Go to **Paddle** > **Catalog** > **Products**, then click the product you want to create a price override for in the list.
2. Find the price you want to create a price override for in the list click, then click  and choose {% mock-button icon="carbon:edit" %}Edit from the menu
3. Under the country specific prices section, enter details for the countries you want to create price overrides for.
4. Click Save when you're done.

{% /instruction-steps %}

{% /dashboard-instructions %}

{% /tab-item %}

{% tab-item title="API" %}

Send a `PATCH` request to the `/prices/{price_id}` endpoint to update a price to include price overrides.

In your request, include an array of `unit_price_overrides`. For each override, include `country_codes` (array of country codes) and `unit_price` (`amount` and `currency_code`).

If creating a new price, include other required fields too, see [Create products and prices](https://developer.paddle.com/build/products/create-products-prices.md).

{% accordion %}
{% accordion-item title="Create price overrides for countries that share a currency" %}

The euro (`EUR`) is shared across 20 countries. Some countries are willing to pay more, while other countries have less purchasing power.

This example adds price overrides for some countries that use the euro:

- Luxembourg (`LU`) and Ireland (`IE`) have a price override set at 40 `EUR`
- Germany (`DE`), France (`FR`), and the Netherlands (`NL`) have a price override set at 35 `EUR`
- All other countries paying in `EUR` fall back to the base price of 30 `EUR`

If successful, Paddle responds with a copy of the updated price entity.

{% api-example method="PATCH" path="/prices/{price_id}" href="/api-reference/prices/update-price" %}

```json
{
  "unit_price_overrides": [
    {
      "country_codes": ["LU", "IE"],
      "unit_price": {
        "amount": "4000",
        "currency_code": "EUR"
      }
    },
    {
      "country_codes": ["DE", "FR", "NL"],
      "unit_price": {
        "amount": "3500",
        "currency_code": "EUR"
      }
    }
  ],
  "unit_price": {
    "amount": "3000",
    "currency_code": "EUR"
  }
}
```

```json
{
  "data": {
    "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
    "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
    "name": "Monthly (per seat)",
    "description": "Monthly (per seat)",
    "billing_cycle": {
      "interval": "month",
      "frequency": 1
    },
    "trial_period": null,
    "tax_mode": "account_setting",
    "unit_price": {
      "amount": "3000",
      "currency_code": "EUR"
    },
    "unit_price_overrides": [
      {
        "country_codes": ["LU", "IE"],
        "unit_price": {
          "amount": "4000",
          "currency_code": "EUR"
        }
      },
      {
        "country_codes": ["DE", "FR", "NL"],
        "unit_price": {
          "amount": "3500",
          "currency_code": "EUR"
        }
      }
    ],
    "custom_data": null,
    "status": "active",
    "quantity": {
      "minimum": 10,
      "maximum": 100
    }
  },
  "meta": {
    "request_id": "794f9da4-0b87-45f2-b234-2b6b1842d8a1"
  }
}
```

{% /api-example %}

{% /accordion-item %}
{% accordion-item title="Create a price override for a country where USD is preferred" %}

Customers in some countries may prefer to pay in `USD`, rather than their local currency.

This example adds a price override for Brazil, where some customers prefer to use US Dollar online.

- Brazil (`BR`) has a price override set at 52 `USD`
- All other countries paying in `USD` fall back to the base price of 100 `USD`

If successful, Paddle responds with a copy of the updated price entity.

{% api-example method="PATCH" path="/prices/{price_id}" href="/api-reference/prices/update-price" %}

```json
{
  "unit_price_overrides": [
    {
      "country_codes": ["BR"],
      "unit_price": {
        "amount": "5200",
        "currency_code": "USD"
      }
    }
  ],
  "unit_price": {
    "amount": "10000",
    "currency_code": "USD"
  }
}
```

```json
{
  "data": {
    "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
    "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
    "name": "Monthly (per seat)",
    "description": "Monthly (per seat)",
    "billing_cycle": {
      "interval": "month",
      "frequency": 1
    },
    "trial_period": null,
    "tax_mode": "account_setting",
    "unit_price": {
      "amount": "10000",
      "currency_code": "USD"
    },
    "unit_price_overrides": [
      {
        "country_codes": ["GB"],
        "unit_price": {
          "amount": "9000",
          "currency_code": "GBP"
        }
      },
      {
        "country_codes": ["IN"],
        "unit_price": {
          "amount": "2320",
          "currency_code": "INR"
        }
      }
    ],
    "custom_data": null,
    "status": "active",
    "quantity": {
      "minimum": 10,
      "maximum": 999
    }
  },
  "meta": {
    "request_id": "9c47ab84-dc59-4d9c-bada-c0e3aacd5231"
  }
}
```

{% /api-example %}

{% /accordion-item %}
{% accordion-item title="Create price overrides for purchasing parity" %}

This example adds price overrides for countries based on their purchasing power. Pricing for purchasing power lets you increase the amount customers pay in countries where willingness-to-pay is higher, and offer accessible pricing in emerging markets.

- United Kingdom (`GB`) has a price override set at 90 `GBP` [115 `USD`]
- India (`IN`) has a price override set at 2320 `INR` [28 `USD`]
- All other countries paying in `USD` fall back to the base price of 100 `USD`

If successful, Paddle responds with a copy of the updated price entity.

{% api-example method="PATCH" path="/prices/{price_id}" href="/api-reference/prices/update-price" %}

```json
{
  "unit_price_overrides": [
    {
      "country_codes": ["GB"],
      "unit_price": {
        "amount": "9000",
        "currency_code": "GBP"
      }
    },
    {
      "country_codes": ["IN"],
      "unit_price": {
        "amount": "2320",
        "currency_code": "INR"
      }
    }
  ],
  "unit_price": {
    "amount": "10000",
    "currency_code": "USD"
  }
}
```

```json
{
  "data": {
    "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
    "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
    "name": "Monthly (per seat)",
    "description": "Monthly (per seat)",
    "billing_cycle": {
      "interval": "month",
      "frequency": 1
    },
    "trial_period": null,
    "tax_mode": "account_setting",
    "unit_price": {
      "amount": "3000",
      "currency_code": "USD"
    },
    "unit_price_overrides": [
      {
        "country_codes": ["GB"],
        "unit_price": {
          "amount": "9000",
          "currency_code": "GBP"
        }
      },
      {
        "country_codes": ["IN"],
        "unit_price": {
          "amount": "2320",
          "currency_code": "INR"
        }
      }
    ],
    "custom_data": {
      "features": {
        "crm": true,
        "data_retention": false,
        "reports": true
      }
    },
    "status": "active",
    "quantity": {
      "minimum": 10,
      "maximum": 999
    }
  },
  "meta": {
    "request_id": "cb4bd3ee-42e6-4380-a400-20f8215b9fe4"
  }
}
```

{% /api-example %}

{% /accordion-item %}
{% /accordion %}

{% /tab-item %}
{% /tabs %}

## Update price overrides

{% tabs sync="interaction-preference" %}
{% tab-item title="Dashboard" %}

You can update price overrides when editing a price in the Paddle dashboard, [as in the previous section](#create-price-overrides).

{% /tab-item %}

{% tab-item title="API" %}

Send a `PATCH` request to the `/prices/{price_id}` endpoint to update price overrides against a price.

When updating price overrides, send the complete list you want to keep — including existing overrides. If you omit a price override, it's removed from the price. Get existing overrides first:

{% api-endpoint method="GET" path="/prices/{price_id}" href="/api-reference/prices/get-price" /%}

Extract price overrides you want to keep, then build your request with the complete `unit_price_overrides` array.

For each override, include `country_codes` and `unit_price` (`amount` and `currency_code`). To learn more, see [Work with lists](https://developer.paddle.com/api-reference/about/lists.md).

{% api-endpoint method="PATCH" path="/prices/{price_id}" href="/api-reference/prices/update-price" /%}

{% /tab-item %}
{% /tabs %}

## Remove price overrides

{% tabs sync="interaction-preference" %}
{% tab-item title="Dashboard" %}

{% callout type="info" %}
Removing price overrides is only available using the API.
{% /callout %}

{% /tab-item %}

{% tab-item title="API" %}

Send a `PATCH` request to the `/prices/{price_id}` endpoint to update a price to remove price overrides.

Set `unit_price_overrides` to an empty array in your request to remove all price overrides.

{% api-example method="PATCH" path="/prices/{price_id}" href="/api-reference/prices/update-price" %}
```json
{
  "unit_price_overrides": []
}
```
```json
{
  "data": {
    "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
    "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
    "name": "Monthly (per seat)",
    "description": "Monthly (per seat)",
    "billing_cycle": {
      "interval": "month",
      "frequency": 1
    },
    "trial_period": null,
    "tax_mode": "account_setting",
    "unit_price": {
      "amount": "3000",
      "currency_code": "USD"
    },
    "unit_price_overrides": [],
    "custom_data": null,
    "status": "active",
    "quantity": {
      "minimum": 10,
      "maximum": 999
    }
  },
  "meta": {
    "request_id": "d48a99a8-5a2a-4efd-a48f-ce655e746f8f"
  }
}
```
{% /api-example %}

{% /tab-item %}
{% /tabs %}