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

# Sconti

> Crea codici promozionali per aumentare le conversioni, gestire campagne e premiare i clienti con sconti percentuali sugli acquisti una tantum e in abbonamento.

<Frame>
  <img src="https://mintcdn.com/dodopayments/mOQO5ej_lx0yH9p-/images/discount-codes/discount-code-cover.png?fit=max&auto=format&n=mOQO5ej_lx0yH9p-&q=85&s=57f1a644801ddc5efc506b50541eaaba" alt="Copertina panoramica dei codici sconto" style={{ maxHeight: '500px', width: 'auto' }} width="1200" height="630" data-path="images/discount-codes/discount-code-cover.png" />
</Frame>

I codici sconto ti permettono di eseguire promozioni mirate e incentivi. Crea sconti basati su percentuali, imposta limiti e scadenze, limitali a prodotti specifici e applicali senza problemi al checkout.

<CardGroup cols={2}>
  <Card title="Checkout Sessions" icon="cart-shopping" href="/developer-resources/checkout-session">
    Applica uno o più codici impilati durante il checkout ospitato con `discount_codes` e controlli UI.
  </Card>

  <Card title="Validate Discount" icon="code" href="/api-reference/discounts/validate-discount">
    Verifica se uno sconto è valido tramite il suo ID.
  </Card>

  <Card title="Get Discount by Code" icon="tag" href="/api-reference/discounts/get-discount-by-code">
    Cerca e convalida uno sconto usando il suo nome di codice (es. "SAVE20").
  </Card>

  <Card title="Create Discount (API)" icon="code" href="/api-reference/discounts/create-discount">
    Crea programmaticamente nuovi codici sconto.
  </Card>

  <Card title="List & Update Discounts" icon="code" href="/api-reference/discounts/list-discounts">
    Sfoglia e gestisci gli sconti esistenti; aggiorna o elimina secondo necessità.
  </Card>

  <Card title="Plan Change Discounts" icon="arrows-rotate" href="/api-reference/subscriptions/change-plan">
    Applica i codici sconto quando si aggiornano o si modificano i piani di abbonamento.
  </Card>
</CardGroup>

## Cosa sono i codici sconto?

I codici sconto sono token promozionali che riducono i totali degli ordini al checkout. Sono ideali per:

* **Campagne stagionali**: Black Friday, lanci di prodotti o anniversari
* **Offerte di acquisizione**: Incentivi per il primo acquisto o premi di referenza
* **Retention**: Premi di riconquista o fedeltà per i clienti esistenti
* **Offerte B2B**: Prezzi contrattati o negoziati tramite codici privati

## Vantaggi principali

* **Sconti flessibili**: Sconti basati su percentuali
* **Codici cumulabili**: Applica fino a 20 codici per checkout, pagamento o abbonamento — combina campagne (ad esempio `WELCOME10` + `BLACKFRIDAY20`) senza creare codici su misura
* **Controllo mirato**: Limita per prodotto e cicli di abbonamento
* **Gestione della campagna**: Date di scadenza e limiti di utilizzo
* **Checkout senza interruzioni**: Campo UI e supporto API tramite sessioni di checkout

## Creazione di codici sconto

Crea codici sconto nel tuo dashboard di Dodo Payments, quindi applicali nel checkout ospitato o tramite API.

### Configurazione del dashboard

* **Nome dello sconto** (obbligatorio): Nome visualizzato internamente e nel cruscotto
* **Codice** (obbligatorio): La stringa che i clienti inseriscono al checkout
* **Tipo e importo** (obbligatorio): Imposta un valore percentuale (attualmente sono supportati solo sconti basati su percentuali), o genera un codice casuale utilizzando il pulsante fornito
* **Data di scadenza** (opzionale): Data dopo la quale il codice diventa invalido
* **Limite di utilizzo** (opzionale): Numero massimo di riscatti totali tra tutti i clienti
* **Restrizione del prodotto** (opzionale): Limita l'applicabilità a prodotti selezionati
* **Limite del ciclo di abbonamento** (opzionale): Numero di cicli di fatturazione a cui si applica lo sconto
* **Metadata** (opzionale): Allegare coppie chiave-valore personalizzate per tracciamento interno o integrazioni

<Tip>
  Usa i limiti dei cicli per prezzi introduttivi sugli abbonamenti (ad es., "50% di sconto per 3 mesi").
</Tip>

## Esperienza di checkout

1. Gli acquirenti inseriscono il codice nel campo del checkout.
2. Gli sconti idonei vengono applicati e i totali si aggiornano immediatamente.

<Info>
  Nelle Sessioni di Checkout, passa `discount_codes` (un array) per pre-applicare uno o più codici, e imposta `feature_flags.allow_discount_code` per mostrare il campo di input. I codici vengono applicati nell'ordine dell'array, fino a un massimo di 20.
</Info>

## Impilamento dei Codici Sconto

Le sessioni di checkout, i pagamenti e gli abbonamenti accettano fino a **20 codici impilati** tramite l'array `discount_codes` (massimo 20 voci). I codici vengono applicati **nell'ordine dell'array**, quindi il primo codice idoneo riduce per primo il prezzo base, il codice successivo riduce il prezzo già scontato e così via. L'insieme completo degli sconti applicati viene restituito nella risposta sotto `discount_ids` (su pagamenti/abbonamenti) e `discounts` (dettaglio più ricco per sconto, inclusa posizione e cicli di abbonamento rimanenti).

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'prod_abc', quantity: 1 }],
  discount_codes: ['WELCOME10', 'BLACKFRIDAY20'], // applied in this order
  customer: { email: 'user@example.com' },
  return_url: 'https://yoursite.com/return'
});
```

<Info>
  Il campo singolare `discount_code` è **deprecato** ma ancora pienamente supportato per la compatibilità con le versioni precedenti — le integrazioni esistenti continuano a funzionare senza modifiche. Non può essere combinato con `discount_codes` nella stessa richiesta. Raccomandiamo di migrare a `discount_codes` (la forma array) quando conveniente, anche per singoli codici, per sfruttare l'impilamento e la forma di risposta più ricca.
</Info>

## Gestione API

<AccordionGroup>
  <Accordion title="Create discounts">
    Crea codici sconto programmaticamente con tipo e importo.

    <Card title="API Reference" icon="code" href="/api-reference/discounts/create-discount">
      Visualizza l'API per creare sconti.
    </Card>
  </Accordion>

  <Accordion title="List and retrieve">
    Elenca tutti gli sconti o recupera i dettagli per gestione e revisione.

    <Card title="API Reference" icon="code" href="/api-reference/discounts/list-discounts">
      Sfoglia le API di elenco e recupero.
    </Card>
  </Accordion>

  <Accordion title="Get discount by code">
    Cerca uno sconto usando il suo codice leggibile dall'uomo (es. "SAVE20") invece dell'ID interno.

    <Card title="API Reference" icon="code" href="/api-reference/discounts/get-discount-by-code">
      Recupera lo sconto tramite il nome del codice.
    </Card>
  </Accordion>

  <Accordion title="Update discounts">
    Modifica la configurazione dello sconto come importo, scadenza o restrizioni.

    <Card title="API Reference" icon="code" href="/api-reference/discounts/update-discount">
      Scopri come aggiornare i dettagli degli sconti.
    </Card>
  </Accordion>

  <Accordion title="Validate discounts">
    Verifica se uno sconto è valido e applicabile prima di applicarlo.

    <Card title="API Reference" icon="code" href="/api-reference/discounts/validate-discount">
      Convalida l'uso dello sconto.
    </Card>
  </Accordion>

  <Accordion title="Delete discounts">
    Disattiva o rimuovi sconti che non sono più necessari.

    <Card title="API Reference" icon="code" href="/api-reference/discounts/delete-discount">
      Elimina uno sconto.
    </Card>
  </Accordion>
</AccordionGroup>

## Casi d'Uso Comuni

* **Offerte introduttive**: Promozioni di lancio a tempo limitato per nuovi prodotti
* **Bulk o B2B**: Sconti contrattati per insiemi selezionati di prodotti
* **Strategie di ritenzione**: Codici per il recupero in flussi di prevenzione del churn
* **Campagne stagionali**: Promozioni basate su festività o eventi

## Esempi di Integrazione

### Crea uno sconto con metadati

Allega coppie chiave-valore personalizzate per la tracciabilità interna.

```typescript theme={null}
const discount = await client.discounts.create({
  type: 'percentage',
  amount: 1500, // 15%
  code: 'SUMMER2025',
  metadata: {
    campaign: 'summer_promo',
    source: 'email_blast'
  }
});
```

<Tip>
  Usa i metadati per etichettare gli sconti per campagna, sorgente o ID di riferimento interno per poter conciliare l'utilizzo e misurare il ROI in seguito.
</Tip>

### Applica sconti nelle Sessioni di Checkout

Pre-applica uno o più sconti impilati e mostra l'interfaccia di input del codice.

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'prod_abc', quantity: 1 }
  ],
  discount_codes: ['BLACKFRIDAY2024', 'NEWUSER5'], // stacked in array order
  customer: { email: 'user@example.com', name: 'Jane Doe' },
  return_url: 'https://yoursite.com/return'
});
```

### Applica sconti durante i cambi di piano

Offri prezzi promozionali quando i clienti aggiornano o declassano il loro abbonamento.

```typescript theme={null}
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  discount_codes: ['UPGRADE20']
});
```

| `discount_codes` value             | Comportamento sul cambio di piano                                                                        |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `undefined` / `null` (non fornito) | Gli sconti esistenti con `preserve_on_plan_change=true` sono mantenuti se applicabili al nuovo prodotto. |
| `[]` (array vuoto)                 | **Tutti** gli sconti esistenti sono rimossi dall'abbonamento.                                            |
| `['CODE_A', 'CODE_B', ...]`        | Sostituisce eventuali sconti esistenti con questo set impilato, applicato nell'ordine dell'array.        |

<Info>
  Leggi tutti gli sconti applicati dall'abbonamento tramite il nuovo array `discounts` nella risposta dell'abbonamento. Ogni voce include `discount_id`, `position`, `cycles_remaining` (per abbonamenti), e il codice originale.
</Info>

### Abilita l'inserimento del codice senza pre-applicazione

Permetti ai clienti di inserire un codice al checkout senza passarlo in anticipo.

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'prod_abc', quantity: 1 }
  ],
  feature_flags: {
    allow_discount_code: true
  },
  return_url: 'https://yoursite.com/return'
});
```

## Migliori Pratiche

* **Nomina chiaramente**: Usa codici riconoscibili che corrispondano ai nomi delle campagne
* **Limita nel tempo**: Aggiungi scadenze per stimolare l'urgenza e prevenire usi impropri
* **Definisci bene l'ambito**: Limita a prodotti specifici per evitare la perdita di margine
* **Convalida presto**: Verifica l'applicabilità del codice prima di confermare il checkout
* **Monitora l'impatto**: Traccia l'uso e la conversione per campagna

<Info>
  I codici sconto sono potenti strumenti per l'acquisizione e la ritenzione. Inizia con offerte semplici e ben denominate, convalida accuratamente e sviluppa in base alle prestazioni.
</Info>