> ## 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.
# Checkout con Prezzi Dinamici e Paga Quanto Vuoi
> Crea link di checkout flessibili con prezzi variabili utilizzando un singolo prodotto. Abilita Paga Quanto Vuoi per consentire ai clienti di scegliere il proprio prezzo o impostare importi dinamici programmaticamente.
**La pricing dinamica** ti consente di offrire prezzi variabili per i tuoi prodotti senza dover creare più voci di prodotto. Abilitando **Paga Quanto Vuoi (PWYW)** su un singolo prodotto, puoi impostare limiti di prezzo minimi e massimi, quindi passare importi dinamici quando crei i link per le sessioni di checkout.
Questo approccio è ideale quando hai bisogno di:
* **Prezzi variabili** senza gestire più prodotti
* **Prezzi guidati dai clienti** in cui gli acquirenti scelgono il loro importo
* **Controllo dei prezzi programmatico** in cui imposti l'importo dinamicamente tramite API
* **Modelli di prezzo flessibili** per prodotti digitali, donazioni o lanci sperimentali
Pay What You Want è disponibile solo per i prodotti **Single Payment** (pagamento una tantum). Non può essere utilizzato con prodotti in abbonamento.
## Come Funziona
Con Paga Quanto Vuoi abilitato, puoi:
1. **Definisci i limiti di prezzo**: Imposta un prezzo minimo (obbligatorio) e opzionalmente un prezzo massimo
2. **Trasmetti importi dinamici**: Includi un campo `amount` nel carrello del prodotto quando crei le sessioni di checkout
3. **Lascia scegliere i clienti**: Se non viene fornito alcun importo, i clienti possono inserire il proprio prezzo (nei limiti da te impostati)
Quando passi un campo `amount` nel carrello del prodotto, quell’importo viene utilizzato per il checkout. Se ometti il campo `amount`, i clienti possono scegliere il proprio prezzo durante il checkout (rispettando i limiti minimo/massimo impostati).
## Passo 1: Crea un Prodotto con Paga Quanto Vuoi
Per prima cosa, crea un prodotto una tantum nel tuo dashboard di Dodo Payments e abilita la pricing Paga Quanto Vuoi.
Vai su **Products** nella dashboard di Dodo Payments e clicca su **Add Product**.
Compila le informazioni richieste del prodotto:
* **Product Name**: nome visualizzato per il prodotto
* **Product Description**: descrizione chiara di ciò che i clienti stanno acquistando
* **Product Image**: carica un’immagine (PNG/JPG/WebP, fino a 3 MB)
* **Tax Category**: seleziona la categoria fiscale appropriata
Seleziona **Pricing Type** come **Single Payment** (pagamento una tantum).
Nella sezione **Pricing**, attiva l’interruttore **Pay What You Want**.
Inserisci il **Prezzo Minimo** che i clienti devono pagare. Questo è obbligatorio e garantisce un livello minimo di entrate.
**Esempio**: se il tuo minimo è \$5.00, inserisci `5.00` (o `500` centesimi).
Opzionalmente, imposta un **Prezzo Massimo** per limitare l’importo che i clienti possono pagare.
Opzionalmente, inserisci un **Prezzo Suggerito** che verrà mostrato per orientare i clienti. Questo aiuta a definire le aspettative e può migliorare il valore medio dell’ordine.
Clicca su **Add Product** per salvare. Prendi nota dell’ID prodotto (ad esempio `pdt_123abc456def`) da utilizzare nelle sessioni di checkout.
Puoi trovare l’ID del prodotto nella dashboard sotto **Products** → **View Details**, oppure utilizzando la [List Products API](/api-reference/products/get-products).
## Passo 2: Crea Sessioni di Checkout con Prezzi Dinamici
Una volta che il tuo prodotto è configurato con Pay What You Want, puoi creare sessioni di checkout con importi dinamici. Il campo `amount` nel carrello del prodotto ti consente di impostare il prezzo in modo programmatico per ogni sessione di checkout.
### Comprendere il Campo Importo
Quando crei una sessione di checkout, puoi includere un campo `amount` in ciascun elemento del carrello del prodotto:
* **Se viene fornito `amount`**: il checkout utilizza questo importo esatto (deve rientrare nei limiti minimo/massimo)
* **Se `amount` viene omesso**: i clienti possono inserire il proprio prezzo durante il checkout (nei limiti da te impostati)
Il campo `amount` è applicabile solo ai prodotti Pay What You Want. Per i prodotti normali, questo campo viene ignorato.
### Esempi di Codice
```typescript TypeScript theme={null}
import DodoPayments from 'dodopayments';
// Initialize the Dodo Payments client
const client = new DodoPayments({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
});
async function createDynamicPricingCheckout(
productId: string,
amountInCents: number,
returnUrl: string
) {
try {
const session = await client.checkoutSessions.create({
product_cart: [
{
product_id: productId,
quantity: 1,
// Dynamic amount in cents (e.g., 1500 = $15.00)
amount: amountInCents
}
],
return_url: returnUrl,
// Optional: Pre-fill customer information
customer: {
email: 'customer@example.com',
name: 'John Doe'
},
// Optional: Add metadata for tracking
metadata: {
order_id: 'order_123',
pricing_tier: 'custom'
}
});
console.log('Checkout URL:', session.checkout_url);
console.log('Session ID:', session.session_id);
return session;
} catch (error) {
console.error('Failed to create checkout session:', error);
throw error;
}
}
// Example: Create checkout with $25.00 (2500 cents)
const session = await createDynamicPricingCheckout(
'prod_123abc456def',
2500, // $25.00 in cents
'https://yoursite.com/checkout/success'
);
// Example: Create checkout with $10.00 (1000 cents)
const session2 = await createDynamicPricingCheckout(
'prod_123abc456def',
1000, // $10.00 in cents
'https://yoursite.com/checkout/success'
);
```
```python Python theme={null}
import os
from dodopayments import DodoPayments
# Initialize the Dodo Payments client
client = DodoPayments(
bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
)
def create_dynamic_pricing_checkout(
product_id: str,
amount_in_cents: int,
return_url: str
):
"""
Create a checkout session with dynamic pricing.
Args:
product_id: The product ID with Pay What You Want enabled
amount_in_cents: The amount in cents (e.g., 2500 for $25.00)
return_url: URL to redirect after payment completion
Returns:
Session object with checkout_url and session_id
"""
try:
session = client.checkout_sessions.create(
product_cart=[
{
"product_id": product_id,
"quantity": 1,
# Dynamic amount in cents (e.g., 1500 = $15.00)
"amount": amount_in_cents
}
],
return_url=return_url,
# Optional: Pre-fill customer information
customer={
"email": "customer@example.com",
"name": "John Doe"
},
# Optional: Add metadata for tracking
metadata={
"order_id": "order_123",
"pricing_tier": "custom"
}
)
print(f"Checkout URL: {session.checkout_url}")
print(f"Session ID: {session.session_id}")
return session
except Exception as error:
print(f"Failed to create checkout session: {error}")
raise error
# Example: Create checkout with $25.00 (2500 cents)
session = create_dynamic_pricing_checkout(
"prod_123abc456def",
2500, # $25.00 in cents
"https://yoursite.com/checkout/success"
)
# Example: Create checkout with $10.00 (1000 cents)
session2 = create_dynamic_pricing_checkout(
"prod_123abc456def",
1000, # $10.00 in cents
"https://yoursite.com/checkout/success"
)
```
**Formato dell’importo**: il campo `amount` deve essere nella denominazione più bassa della valuta. Per USD, ciò significa i centesimi (es. \$25.00 = `2500`). Per altre valute, usa l’unità più piccola (es. paise per INR).
## Passo 3: Consenti ai Clienti di Scegliere il Loro Prezzo
Se desideri che i clienti scelgano il proprio prezzo durante il checkout, ometti semplicemente il campo `amount` dal carrello del prodotto. La pagina di checkout mostrerà un campo di input in cui i clienti potranno inserire qualsiasi importo compreso tra il minimo e il massimo da te impostati.
```typescript TypeScript theme={null}
async function createCustomerChoiceCheckout(
productId: string,
returnUrl: string
) {
try {
const session = await client.checkoutSessions.create({
product_cart: [
{
product_id: productId,
quantity: 1
// No amount field - customer will choose their price
}
],
return_url: returnUrl,
customer: {
email: 'customer@example.com',
name: 'John Doe'
}
});
return session;
} catch (error) {
console.error('Failed to create checkout session:', error);
throw error;
}
}
```
```python Python theme={null}
def create_customer_choice_checkout(
product_id: str,
return_url: str
):
"""
Create a checkout session where customers choose their own price.
"""
try:
session = client.checkout_sessions.create(
product_cart=[
{
"product_id": product_id,
"quantity": 1
# No amount field - customer will choose their price
}
],
return_url=return_url,
customer={
"email": "customer@example.com",
"name": "John Doe"
}
)
return session
except Exception as error:
print(f"Failed to create checkout session: {error}")
raise error
```
## Casi d'Uso Comuni
### Caso d'Uso 1: Prezzi a Livelli Basati sul Tipo di Utente
Offri prezzi diversi a diversi segmenti di clienti utilizzando lo stesso prodotto:
```typescript theme={null}
// Student discount: $10.00
const studentSession = await createDynamicPricingCheckout(
'prod_123abc456def',
1000, // $10.00
'https://yoursite.com/success'
);
// Regular price: $25.00
const regularSession = await createDynamicPricingCheckout(
'prod_123abc456def',
2500, // $25.00
'https://yoursite.com/success'
);
// Premium price: $50.00
const premiumSession = await createDynamicPricingCheckout(
'prod_123abc456def',
5000, // $50.00
'https://yoursite.com/success'
);
```
### Caso d'Uso 2: Prezzi Dinamici Basati sulla Quantità
Regola il prezzo in base alla quantità acquistata:
```typescript theme={null}
async function createQuantityBasedCheckout(
productId: string,
quantity: number
) {
// Base price: $20.00 per unit
// Discount: 10% for 2+ items, 20% for 5+ items
const basePrice = 2000; // $20.00 in cents
let discount = 0;
if (quantity >= 5) {
discount = 0.20; // 20% off
} else if (quantity >= 2) {
discount = 0.10; // 10% off
}
const totalAmount = Math.round(basePrice * quantity * (1 - discount));
const session = await client.checkoutSessions.create({
product_cart: [
{
product_id: productId,
quantity: quantity,
amount: totalAmount
}
],
return_url: 'https://yoursite.com/success'
});
return session;
}
```
### Caso d'Uso 3: Prezzi Basati sul Tempo o Promozionali
Applica prezzi promozionali durante periodi specifici:
```typescript theme={null}
async function createPromotionalCheckout(productId: string) {
const isPromoActive = checkIfPromotionActive(); // Your logic
const regularPrice = 3000; // $30.00
const promoPrice = 2000; // $20.00
const amount = isPromoActive ? promoPrice : regularPrice;
const session = await client.checkoutSessions.create({
product_cart: [
{
product_id: productId,
quantity: 1,
amount: amount
}
],
return_url: 'https://yoursite.com/success',
metadata: {
pricing_type: isPromoActive ? 'promotional' : 'regular'
}
});
return session;
}
```
## Migliori Pratiche
Scegli un prezzo minimo che copra i tuoi costi, mantenendo comunque l’offerta accessibile. Usa un prezzo suggerito per orientare le aspettative dei clienti.
Verifica sempre che gli importi dinamici rientrino nei limiti minimo e massimo del prodotto prima di creare le sessioni di checkout.
Usa i metadata per tracciare il motivo per cui sono stati scelti importi specifici (es. `pricing_tier`, `discount_code`, `user_segment`).
Assicurati che la tua applicazione gestisca in modo appropriato i casi in cui gli importi superano i limiti massimi o sono inferiori ai minimi.
## Validazione e Gestione degli Errori
Valida sempre gli importi rispetto alle impostazioni minime e massime del tuo prodotto:
```typescript TypeScript theme={null}
async function createValidatedCheckout(
productId: string,
amountInCents: number,
minAmount: number,
maxAmount: number | null
) {
// Validate minimum
if (amountInCents < minAmount) {
throw new Error(
`Amount ${amountInCents} is below minimum ${minAmount}`
);
}
// Validate maximum (if set)
if (maxAmount !== null && amountInCents > maxAmount) {
throw new Error(
`Amount ${amountInCents} exceeds maximum ${maxAmount}`
);
}
// Create checkout session
return await client.checkoutSessions.create({
product_cart: [
{
product_id: productId,
quantity: 1,
amount: amountInCents
}
],
return_url: 'https://yoursite.com/success'
});
}
```
```python Python theme={null}
def create_validated_checkout(
product_id: str,
amount_in_cents: int,
min_amount: int,
max_amount: int | None
):
"""
Create a checkout session with amount validation.
"""
# Validate minimum
if amount_in_cents < min_amount:
raise ValueError(
f"Amount {amount_in_cents} is below minimum {min_amount}"
)
# Validate maximum (if set)
if max_amount is not None and amount_in_cents > max_amount:
raise ValueError(
f"Amount {amount_in_cents} exceeds maximum {max_amount}"
)
# Create checkout session
return client.checkout_sessions.create(
product_cart=[
{
"product_id": product_id,
"quantity": 1,
"amount": amount_in_cents
}
],
return_url="https://yoursite.com/success"
)
```
## Riferimento API
Scopri di più sul modello di pricing Pay What You Want e sulle sue potenzialità.
Esplora funzionalità avanzate delle sessioni di checkout e opzioni di personalizzazione.
## Risoluzione dei Problemi
Se il tuo campo `amount` viene ignorato, verifica che:
* Il prodotto abbia **Pay What You Want** attivato nella dashboard
* Il prodotto sia un **Single Payment** (pagamento una tantum), non un abbonamento
* L’importo sia nel formato corretto (denominazione più bassa della valuta, es. centesimi per USD)
L’API rifiuterà le sessioni di checkout in cui l’importo viola i limiti di prezzo del prodotto. Verifica sempre gli importi prima di creare le sessioni di checkout oppure lascia che i clienti scelgano il proprio prezzo omettendo il campo `amount`.
Se i clienti non vedono il campo per inserire il prezzo, assicurati di aver omesso il campo `amount` dal carrello del prodotto. Quando è fornito `amount`, il checkout utilizza quell’importo esatto.