Preços Localizados

​

O que é Preço Localizado?

​

Casos de Uso

​

Conceitos Principais

• Modos de preço — Um produto está em exatamente um modo por vez, definido pelo seu pricing_mode:
  • by_currency: um preço por moeda, independentemente do país. Todos que pagarem em EUR verão €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.
• Valores fixos, na menor unidade — O amount de uma regra é um número inteiro na menor unidade da moeda, assim como em todo o restante da API: 99900 é ₹999.00, 999 é €9.99. É um preço definido por você, nunca um valor convertido.
• Uma regra correspondente tem prioridade sobre o preço automático — Quando uma regra de preço localizado se aplica a uma linha, Paridade do Poder de Compra e Precificação Charm são ignoradas para essa linha. O cliente paga o valor definido por você, sem alterações.
• Quando nenhuma regra corresponde — O produto mantém seu comportamento atual: clientes na sua moeda-base pagam diretamente o preço-base; todos os demais recebem o valor convertido por meio de Adaptive Currency.
• As tarifas são inclusas quando uma regra corresponde — O cliente paga exatamente o valor definido por você. A tarifa de câmbio da Adaptive Currency é absorvida por você (tratada como inclusa nas tarifas para essa transação), em vez de ser adicionada ao valor, portanto o preço local informado é sempre o preço cobrado.

​

Configurar no Painel

1

Open the product form

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.

2

Enable Localized Pricing and choose a mode

Na seção Preços, marque Preço Localizado, depois escolha Por País ou Por Moeda.

3

Add a price for each market

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.

• By Country
• By Currency

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.

4

Save the product

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

​

Definir o modo de precificação

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',
});

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",
)

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

// ₹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 for customers in India
localized_price = client.products.localized_prices.create(
    "pdt_premium_plan",
    currency="INR",
    country_code="IN",
    amount=99900,
)

// ₹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)),
	},
)

​

Listar, atualizar e arquivar

// 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',
});

# 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",
)

// 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",
)

​

Como se Aplica na Finalização de Compra

• 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.

​

Como isso se aplica a alterações no plano de assinatura

• Por país: aplica-se uma regra correspondente ao país de cobrança da assinatura. Se a moeda da regra for diferente da moeda em que a assinatura é cobrada, o valor da regra será convertido pelas taxas de câmbio em tempo real — a regra é aplicada, não ignorada.
• Por moeda: aplica-se uma regra correspondente à moeda em que o cliente é cobrado, e o cliente paga exatamente o valor definido pela regra.
• Sem correspondência ou sem um pricing_mode: aplica-se o preço base do novo plano, convertido por meio de Adaptive Currency quando necessário — o mesmo fallback do checkout.

• As prévias são exatas. Preview Change Plan retorna o mesmo valor localizado cobrado pela alteração real.
• As renovações mantêm o preço localizado. Após a alteração, o novo plano é renovado pelo seu valor localizado — e continua com as taxas incluídas — exatamente como uma assinatura criada com esse preço.
• O rateio usa valores reais. Em um upgrade, o crédito pelo tempo não utilizado é baseado no que o cliente realmente pagou pelo plano antigo, enquanto o novo plano é precificado pela sua regra localizada.
• As alterações agendadas bloqueiam o preço no momento do agendamento. Uma alteração agendada para o final do período de cobrança cobra o valor calculado no momento do agendamento, mesmo que você edite a regra nesse intervalo.
• A moeda de cobrança nunca muda. Uma alteração de plano nunca muda a moeda em que uma assinatura é liquidada; uma regra em outra moeda é convertida por câmbio para a moeda da assinatura.
• Os complementos não são localizados. Os preços dos complementos no novo plano sempre usam sua precificação base.

​

Comportamentos importantes

​

Práticas recomendadas

• Mantenha um preço-base razoável. Ele é o fallback para todos os mercados sem uma regra, convertido por meio da Adaptive Currency.
• Digite valores simples. O objetivo de um valor fixo é ter um preço organizado, como ₹999, €9.99 ou ¥1000, e não um resultado de câmbio. Para arredondamento automático em todas as moedas, consulte Precificação Charm.
• Escolha o modo adequado à finalidade. Use by_country para preços baseados no poder de compra; use by_currency quando um preço por zona monetária for suficiente.
• Arquive em vez de recriar para promoções. Arquivar uma regra faz o mercado voltar ao preço-base/adaptativo e preserva o histórico; recrie ou altere o preço posteriormente conforme necessário.
• Verifique o campo de impostos antes de anunciar um total. Para produtos sem impostos inclusos, o cliente paga o valor localizado mais os impostos; portanto, não o informe como preço final nos anúncios.

​

Relacionados