> ## 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.
# Prezzi Localizzati
> Imposta un prezzo fisso per ogni valuta o paese invece di lasciare che siano i tassi di cambio a decidere. Applica prezzi arrotondati e orientati al mercato e conduci promozioni per paese.
## Cosa Sono i Prezzi Localizzati?
Ogni prodotto ha un prezzo base in una valuta base. I Prezzi Localizzati ti permettono di sostituire quel prezzo base con **prezzi fissi che imposti per ogni valuta o per ogni paese**. Attivalo impostando un `pricing_mode` sul prodotto, quindi allega una regola per mercato.
È uno dei tre strumenti indipendenti per la determinazione dei prezzi internazionali, ognuno risolvendo un problema diverso:
| Meccanismo | Cosa fa | Il numero che vede il cliente |
| :------------------------------------------------- | :---------------------------------------------------------------------- | :------------------------------------------------ |
| **Prezzi Localizzati** | Un prezzo fisso che imposti per valuta o paese | Esattamente l'importo che imposti |
| [**Valuta Adattiva**](/features/adaptive-currency) | Converte automaticamente il tuo prezzo base ai tassi di cambio correnti | Prezzo base convertito al tasso di cambio attuale |
| [**Codici sconto**](/features/discount-codes) | Una riduzione percentuale sul prezzo base | Prezzo base meno lo sconto |
Prezzi Localizzati e Valuta Adattiva lavorano insieme. Quando non c'è una regola localizzata che corrisponde, il prodotto torna al suo prezzo base — addebitato direttamente se il cliente è già nella tua valuta base, o convertito tramite Valuta Adattiva se non lo è.
***
## Casi d'Uso
Addebita meno nei mercati sensibili al prezzo senza scontare il tuo mercato domestico. Una regola `by_country` consente a un prodotto base da \$20 di essere venduto per **₹999 in India** — regolato secondo il potere d'acquisto locale, non una conversione diretta dei tassi di cambio. È il modo nativo consigliato per eseguire il PPP.
Una conversione diretta FX di \$19,99 si traduce in un numero scomodo come €18,43. Una regola `by_currency` fissa il prezzo pulito e psicologicamente regolato che i clienti si aspettano — **€9,99**, **¥1000**, **₹499** — esattamente come digitato.
Lanciarsi in un nuovo paese? Aggiungi una regola `by_country` con un prezzo introduttivo, quindi **archiviala** quando la promozione termina per tornare ai prezzi base/adaptivi. Le regole sono archiviate, mai cancellate, quindi mantieni un record chiaro di ciò che era attivo e quando.
Fissa un singolo mercato per corrispondere a un concorrente locale. Una regola `by_country` per **£9,00 nel Regno Unito** mantiene esattamente quel prezzo indipendentemente da come si muove il tasso GBP/USD.
***
## Concetti Chiave
* **Modalità di Prezzo** — Un prodotto è in una sola modalità alla volta, impostata dal suo `pricing_mode`:
* `by_currency`: un prezzo per valuta, indipendentemente dal paese. Tutti coloro che pagano in EUR vedono €9,99.
* `by_country`: un prezzo specifico per un paese (₹999 in India), anche quando diversi paesi condividono una valuta.
* **Importi Fissi, nell'unità più piccola** — L'`amount` di una regola è un intero nell'unità più piccola della valuta, lo stesso di ovunque nell'API: `99900` è ₹999,00, `999` è €9,99. È un prezzo che imposti, mai un valore convertito.
* **Quando non ci sono regole corrispondenti** — Il prodotto mantiene il suo comportamento esistente: i clienti nella tua valuta base pagano direttamente il prezzo base; tutti gli altri ottengono il prezzo convertito tramite [Valuta Adattiva](/features/adaptive-currency).
* **Le commissioni sono inclusive quando c'è una regola corrispondente** — Il cliente paga **esattamente** l'importo che imposti. La commissione FX [Valuta Adattiva](/features/adaptive-currency#choose-who-bears-the-fee) è assorbita da te (trattata come commissioni-inclusive per quella transazione) piuttosto che aggiunta sopra, quindi il prezzo locale dichiarato è sempre il prezzo addebitato.
***
## Imposta nel Cruscotto
Nel tuo Cruscotto del commerciante, vai a **Prodotti** e crea un prodotto (o aprine uno esistente per modificarlo). Imposta il **Prezzo** di base e la valuta come di consueto.
Nella sezione **Prezzi**, seleziona **Prezzi Localizzati**, quindi scegli **Per Paese** o **Per Valuta**.
Fai clic su **Aggiungi Prezzo Paese** o **Aggiungi Prezzo Valuta**, compila il pannello **Prezzi Localizzati** e fai clic su **Aggiungi**. Ogni mercato che aggiungi appare nella tabella delle sostituzioni, dove puoi modificarlo o rimuoverlo in seguito.
Scegli un paese, seleziona la valuta ed inserisci l'importo (ad esempio ₹999 per l'India), quindi fai clic su **Aggiungi**.
Il paese ora appare nella tabella **Sostituzioni per Paese**, dove puoi modificarlo o rimuoverlo.
Scegli una valuta ed inserisci l'importo (ad esempio €9,99 per l'EUR), quindi fai clic su **Aggiungi**.
La valuta ora appare nella tabella **Sostituzioni per Valuta**, dove puoi modificarla o rimuoverla.
Salva con **Aggiungi prodotto**. I prezzi localizzati si applicano immediatamente ai futuri check-out.
Esegui un test di check-out con un paese di fatturazione che ha una regola e conferma che l'importo localizzato appaia.
***
## Gestione tramite API
I Prezzi Localizzati sono completamente disponibili tramite l'API. Prima imposta la modalità di prezzo del prodotto, quindi allega le regole.
### Imposta la modalità di prezzo
Imposta `pricing_mode` quando crei il prodotto (o aggiorni uno esistente). `null` significa solo base, il comportamento esistente.
```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)
}
}
```
### Aggiungi un prezzo localizzato
Allega una regola al prodotto. In modalità `by_country` è richiesta `country_code`; in modalità `by_currency` deve essere omessa.
```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)),
},
)
```
Per un prodotto `by_currency`, ometti `country_code`. Per esempio, una `€9.99` piatta per tutti coloro che pagano in EUR (`currency: 'EUR'`, `amount: 999`).
### Elenca, aggiorna e archivia
Puoi aggiornare solo l'`amount` di una regola; valuta e paese sono fissi una volta creati. L'archiviazione è una cancellazione soft-idempotente, quindi la regola smette di corrispondere ma rimane nel tuo storico.
```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",
)
```
Vedi i punti di accesso completi per i Prezzi Localizzati del Prodotto: crea, elenca, recupera, aggiorna e archivia.
***
## Come si Applica al Checkout
Il prezzo localizzato è risolto per riga del carrello, e solo per i prodotti che hanno un `pricing_mode` impostato. Dodo Payments legge due segnali dalla richiesta: il **paese di fatturazione** del cliente, e un opzionale **`billing_currency`** (quando omesso, una valuta è derivata dal paese di fatturazione).
* **Per Paese**: cerca una regola che corrisponda al paese di fatturazione. Se esiste, al cliente viene addebitato l'importo della regola nella valuta della regola.
* **Per Valuta**: cerca una regola che corrisponda alla valuta del cliente (l'`billing_currency`, o la valuta derivata dal loro paese). Se esiste, al cliente viene addebitato l'importo della regola in quella valuta.
* **Nessuna corrispondenza o nessun `pricing_mode`**: si applica il prezzo base, addebitato direttamente quando la valuta del cliente è uguale a quella base, altrimenti convertito tramite [Valuta Adattiva](/features/adaptive-currency).
Ogni riga del carrello è risolta da sola, quindi puoi localizzare un prodotto e lasciare altri a prezzi base nello stesso check-out. Se una qualsiasi linea corrisponde a una regola localizzata, l'intera transazione è forzata a commissioni-inclusive (vedi [Concetti Chiave](#core-concepts)).
***
## Comportamenti Importanti
| Comportamento | Dettaglio |
| :--------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Importi Pre-tasse** | Un importo localizzato è il prezzo *prima* delle tasse. Per i prodotti tax-exclusive, la tassa è aggiunta sopra al checkout, quindi l'importo localizzato non è il totale finale. Vedi [Prezzi con Tassa Inclusa](/features/tax-inclusive-pricing). |
| **Non per Pay What You Want** | Le regole localizzate non si applicano mai ai prodotti [Pay What You Want](/features/pay-what-you-want), dove il cliente sceglie l'importo. |
| **Per-valuta differente da quello base** | Una regola `by_currency` deve utilizzare una valuta diversa da quella base del prodotto. |
| **Una regola per mercato** | Un prodotto può avere al massimo una regola attiva per valuta (per-valuta) o per paese (per-paese). |
| **Tutti i tipi di prodotto** | Si applica a prodotti una tantum, in abbonamento e basati sull'uso. |
Le modifiche alle regole localizzate non emettono propri webhook. L'importo risolto appare sul pagamento o abbonamento risultante esattamente come qualsiasi altro prezzo.
***
## Migliori Pratiche
* **Mantieni un prezzo base sensato.** È la soluzione di ripiego per ogni mercato senza una regola, convertita tramite Valuta Adattiva.
* **Arrotonda ai prezzi locali di fascino.** L'intero punto di un importo fisso è un numero pulito come ₹999, €9,99 o ¥1000, non un risultato FX.
* **Scegli la modalità giusta per il lavoro.** Usa `by_country` per i prezzi basati sul potere d'acquisto; usa `by_currency` quando un prezzo per zona valutaria è sufficiente.
* **Archivia, non ricrea, per le promozioni.** L'archiviazione di una regola fa tornare il mercato a base/adattivo preservando lo storico; ricrea o ri-prezza più tardi se necessario.
* **Fai attenzione alla linea delle tasse prima di pubblicizzare un totale.** Per i prodotti tax-exclusive il cliente paga l'importo localizzato *più* la tassa, quindi non citarlo come prezzo finale negli annunci.
***
## Correlati
Prezzi localizzati nativi vs. codici sconto basati sulla posizione per PPP.
Conversione FX automatica e gestione delle commissioni su cui si basano i prezzi localizzati.
Controlla se i tuoi prezzi includono le tasse.
Consenti ai clienti di scegliere l'importo. Le regole localizzate non si applicano lì.