> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Preços Localizados
> Defina seu próprio preço fixo para cada moeda ou país em vez de deixar as taxas de câmbio decidirem. Cobrar preços arredondados, ajustados ao mercado e realizar promoções por país.
## O que é Preço Localizado?
Todo produto tem um preço base em uma moeda base. O Preço Localizado permite substituir essa base com **preços fixos que você define por moeda ou por país**. Ative-o configurando um `pricing_mode` no produto, e então anexe uma regra por mercado.
É um de três mecanismos independentes para precificação internacional, cada um resolvendo um problema diferente:
| Mecanismo | O que faz | O número que o cliente vê |
| :-------------------------------------------------- | :----------------------------------------------------------------- | :-------------------------------------------- |
| **Preço Localizado** | Um preço fixo que você define por moeda ou país | Exatamente o valor que você definiu |
| [**Moeda Adaptativa**](/features/adaptive-currency) | Converte automaticamente seu preço base em taxas de câmbio ao vivo | Preço base convertido na taxa de câmbio atual |
| [**Códigos de Desconto**](/features/discount-codes) | Uma redução percentual do preço base | Preço base menos o desconto |
Preço Localizado e Moeda Adaptativa funcionam juntos. Quando não há regra localizada correspondente, o produto retorna ao seu preço base — cobrado diretamente se o cliente já estiver na sua moeda base, ou convertido por Moeda Adaptativa se não estiver.
***
## Casos de Uso
Cobrar menos em mercados sensíveis ao preço sem descontar seu mercado doméstico. Uma regra `by_country` permite que um produto base de \$20 seja vendido por **₹999 na Índia** — ajustado ao poder de compra local, não a uma conversão direta de FX. A maneira recomendada e nativa de executar PPP.
Uma conversão ao vivo do FX de \$19.99 resulta em um número estranho como €18.43. Uma regra `by_currency` define o preço limpo e ajustado psicologicamente que os clientes esperam — **€9.99**, **¥1000**, **₹499** — exatamente como digitado.
Lançando em um novo país? Adicione uma regra `by_country` com um preço introdutório, depois **arquive-a** quando a promoção terminar para retornar ao preço base/adaptativo. As regras são arquivadas, nunca excluídas, para que você mantenha um registro limpo do que estava ativo e quando.
Fixe um único mercado para corresponder a um concorrente local. Uma regra `by_country` para **£9.00 no Reino Unido** mantém esse preço exato independentemente de como a taxa GBP/USD se move.
***
## Conceitos Principais
* **Modos de precificação** — Um produto está exatamente em um modo de cada vez, definido pelo seu `pricing_mode`:
* `by_currency`: um preço por moeda, independentemente do país. Todos pagando em EUR veem €9.99.
* `by_country`: um preço específico para um país (₹999 na Índia), mesmo quando vários países compartilham uma moeda.
* **Quantias fixas, na menor unidade** — O `amount` de uma regra é um inteiro na menor unidade da moeda, assim como em qualquer outro lugar na API: `99900` é ₹999.00, `999` é €9.99. É um preço que você define, nunca um valor convertido.
* **Quando nenhuma regra é correspondente** — O produto mantém o comportamento existente: clientes na sua moeda base pagam o preço base diretamente; todos os outros o recebem convertido através da [Moeda Adaptativa](/features/adaptive-currency).
* **As taxas estão inclusas quando uma regra é correspondente** — O cliente paga **exatamente** o valor que você definiu. A taxa de FX da [Moeda Adaptativa](/features/adaptive-currency#choose-who-bears-the-fee) é absorvida por você (tratada como inclusiva para essa transação) em vez de adicionada por cima, para que seu preço local declarado seja sempre o preço cobrado.
***
## Configurar no Painel
No seu Painel do Comerciante, vá para **Produtos** e crie um produto (ou abra um existente para editar). Defina o **Preço** base e a moeda como de costume.
Na seção **Preços**, marque **Preço Localizado**, depois escolha **Por País** ou **Por Moeda**.
Clique em **Adicionar Preço por País** ou **Adicionar Preço por Moeda**, preencha o painel de **Preco Localizado** e clique em **Adicionar**. Cada mercado que você adicionar aparece na tabela de substituições, onde você pode editar ou removê-lo depois.
Escolha um país, selecione a moeda e insira o valor (por exemplo ₹999 para a Índia), depois clique em **Adicionar**.
O país agora aparece na tabela de **Substituições por País**, onde você pode editá-lo ou removê-lo.
Escolha uma moeda e insira o valor (por exemplo €9.99 para EUR), depois clique em **Adicionar**.
A moeda agora aparece na tabela de **Substituições por Moeda**, onde você pode editá-la ou removê-la.
Salvar com **Adicionar produto**. Os preços localizados são aplicados nas futuras finalizações de compra imediatamente.
Execute uma finalização de compra de teste com um país de cobrança que tenha uma regra e confirme que o valor localizado aparece.
***
## Gerenciar via API
O Preço Localizado está totalmente disponível na API. Primeiro, defina o modo de precificação do produto, depois anexe regras.
### Definir o modo de precificação
Defina `pricing_mode` quando você criar o produto (ou atualizar um já existente). `null` significa apenas base, o comportamento existente.
```typescript theme={null} theme={null}
import DodoPayments from 'dodopayments';
const client = new DodoPayments({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
environment: 'test_mode',
});
const product = await client.products.update('pdt_premium_plan', {
pricing_mode: 'by_country',
});
```
```python theme={null} theme={null}
import os
from dodopayments import DodoPayments
client = DodoPayments(
bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
environment="test_mode",
)
product = client.products.update(
"pdt_premium_plan",
pricing_mode="by_country",
)
```
```go theme={null} theme={null}
package main
import (
"context"
"os"
"github.com/dodopayments/dodopayments-go"
"github.com/dodopayments/dodopayments-go/option"
)
func main() {
client := dodopayments.NewClient(
option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
)
_, err := client.Products.Update(
context.TODO(),
"pdt_premium_plan",
dodopayments.ProductUpdateParams{
PricingMode: dodopayments.F(dodopayments.PricingModeByCountry),
},
)
if err != nil {
panic(err)
}
}
```
### Adicionar um preço localizado
Anexe uma regra ao produto. No modo `by_country` o `country_code` é necessário; no modo `by_currency` ele deve ser omitido.
```typescript theme={null} theme={null}
// ₹999.00 for customers in India
const localizedPrice = await client.products.localizedPrices.create('pdt_premium_plan', {
currency: 'INR',
country_code: 'IN',
amount: 99900,
});
```
```python theme={null} theme={null}
# ₹999.00 for customers in India
localized_price = client.products.localized_prices.create(
"pdt_premium_plan",
currency="INR",
country_code="IN",
amount=99900,
)
```
```go theme={null} theme={null}
// ₹999.00 for customers in India
localizedPrice, err := client.Products.LocalizedPrices.New(
context.TODO(),
"pdt_premium_plan",
dodopayments.ProductLocalizedPriceNewParams{
Currency: dodopayments.F(dodopayments.CurrencyInr),
CountryCode: dodopayments.F(dodopayments.CountryCodeIn),
Amount: dodopayments.F(int64(99900)),
},
)
```
Para um produto `by_currency`, omita `country_code`. Por exemplo, um `€9.99` para todos que pagam em EUR (`currency: 'EUR'`, `amount: 999`).
### Listar, atualizar e arquivar
Você pode atualizar apenas o `amount` de uma regra; moeda e país são fixos uma vez criados. O arquivamento é uma exclusão suave idempotente, então a regra para de corresponder, mas permanece em seu histórico.
```typescript theme={null} theme={null}
// List all active rules on a product
const rules = await client.products.localizedPrices.list('pdt_premium_plan');
// Change the amount (e.g. end a promo)
await client.products.localizedPrices.update('lcp_india_price', {
product_id: 'pdt_premium_plan',
amount: 119900,
});
// Archive a rule
await client.products.localizedPrices.archive('lcp_india_price', {
product_id: 'pdt_premium_plan',
});
```
```python theme={null} theme={null}
# List all active rules on a product
rules = client.products.localized_prices.list("pdt_premium_plan")
# Change the amount (e.g. end a promo)
client.products.localized_prices.update(
"lcp_india_price",
product_id="pdt_premium_plan",
amount=119900,
)
# Archive a rule
client.products.localized_prices.archive(
"lcp_india_price",
product_id="pdt_premium_plan",
)
```
```go theme={null} theme={null}
// List all active rules on a product
rules, err := client.Products.LocalizedPrices.List(context.TODO(), "pdt_premium_plan")
// Change the amount (e.g. end a promo)
_, err = client.Products.LocalizedPrices.Update(
context.TODO(),
"pdt_premium_plan",
"lcp_india_price",
dodopayments.ProductLocalizedPriceUpdateParams{
Amount: dodopayments.F(int64(119900)),
},
)
// Archive a rule
err = client.Products.LocalizedPrices.Archive(
context.TODO(),
"pdt_premium_plan",
"lcp_india_price",
)
```
Veja os endpoints completos de Preços Localizados de Produto: criar, listar, recuperar, atualizar e arquivar.
***
## Como se Aplica na Finalização de Compra
O preço localizado é resolvido por linha de carrinho e apenas para produtos que têm um `pricing_mode` definido. A Dodo Payments lê dois sinais do pedido: o **país de cobrança** do cliente e uma **`billing_currency`** opcional (quando omitida, uma moeda é derivada do país de cobrança).
* **Por País**: procura uma regra que corresponda ao país de cobrança. Se existir, o cliente é cobrado o valor da regra na moeda da regra.
* **Por Moeda**: procura uma regra que corresponda à moeda do cliente (o `billing_currency`, ou a moeda derivada do país dele). Se existir, o cliente é cobrado o valor da regra nessa moeda.
* **Nenhuma correspondência, ou nenhum `pricing_mode`**: o preço base se aplica, cobrado diretamente quando a moeda do cliente é igual à moeda base, caso contrário convertido através da [Moeda Adaptativa](/features/adaptive-currency).
Cada linha de carrinho é resolvida por conta própria, então você pode localizar um produto e deixar outros com precificação base na mesma finalização de compra. Se qualquer linha corresponder a uma regra localizada, a transação inteira força taxas inclusas (veja [Conceitos Principais](#core-concepts)).
***
## Comportamentos Importantes
| Comportamento | Detalhe |
| :--------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Quantias antes do imposto** | Um valor localizado é o preço *antes* do imposto. Para produtos sem imposto, o imposto é adicionado por cima na finalização de compra, então o valor localizado não é o total final. Veja [Preço com Impostos Incluídos](/features/tax-inclusive-pricing). |
| **Não para Pague o Quanto Quiser** | Regras localizadas nunca se aplicam a produtos [Pague o Quanto Quiser](/features/pay-what-you-want), onde o cliente escolhe o valor. |
| **Por-moeda difere da base** | Uma regra `by_currency` deve usar uma moeda diferente da moeda base do produto. |
| **Uma regra por mercado** | Um produto pode ter no máximo uma regra ativa por moeda (por-moeda) ou por país (por-país). |
| **Todos os tipos de produto** | Aplica-se a produtos de uso único, assinatura e baseados em uso. |
Mudanças em regras localizadas não emitem seus próprios webhooks. O valor resolvido aparece no pagamento ou assinatura resultante exatamente como qualquer outro preço.
***
## Práticas Recomendadas
* **Mantenha um preço base sensato.** Ele é o fallback para todos os mercados sem uma regra, convertido através da Moeda Adaptativa.
* **Arredonde para custos psicológicos locais.** Todo o ponto de uma quantia fixa é um número limpo como ₹999, €9.99 ou ¥1000, não um resultado de FX.
* **Escolha o modo para o trabalho.** Use `by_country` para precificação baseada no poder de compra; use `by_currency` quando um preço por zona monetária for suficiente.
* **Arquive, não recrie, para promoções.** Arquivar uma regra reverte o mercado para base/adaptativo enquanto preserva o histórico; recrie ou reprecifique mais tarde conforme necessário.
* **Preste atenção na linha de impostos antes de anunciar um total.** Para produtos sem imposto, o cliente paga o valor localizado *mais* imposto, então não o cite como o preço final em anúncios.
***
## Relacionados
Preços localizados nativos vs. códigos de desconto baseados na localização para PPP.
Conversão automática de FX e o tratamento de taxas que a precificação localizada constrói.
Controle se seus preços incluem imposto.
Deixe os clientes escolherem o valor. Regras localizadas não se aplicam lá.