Abbonamenti

​

Cosa sono gli abbonamenti?

• Licenze SaaS: app, API o accesso alla piattaforma
• Membership: community, programmi o club
• Contenuti digitali: corsi, media o contenuti premium
• Piani di assistenza: SLA, pacchetti di successo o manutenzione

​

Vantaggi principali

• Ricavi prevedibili: fatturazione ricorrente con rinnovi automatizzati
• Cicli flessibili: intervalli mensili, annuali, personalizzati e periodi di prova
• Agilità dei piani: pro-rata per upgrade e downgrade
• Componenti aggiuntivi e postazioni: aggiungi upgrade opzionali e quantificabili
• Checkout ospitato: pagine di checkout e Customer Portal
• Developer-first: API chiare per creazione, modifiche e monitoraggio dell’utilizzo

​

Creazione degli abbonamenti

​

Creazione di un prodotto in abbonamento

​

Dettagli del prodotto

• Nome del prodotto (obbligatorio): il nome visualizzato nel checkout, nel Customer Portal e nelle fatture.
• Descrizione del prodotto (facoltativa): una descrizione chiara del valore che appare nel checkout e nelle fatture.
• Immagine del prodotto (facoltativa): PNG/JPG/WebP fino a 3 MB. Utilizzata nel checkout e nelle fatture.
• Brand: associa il prodotto a un brand specifico per la personalizzazione del tema e delle email.
• Categoria fiscale (obbligatoria): scegli la categoria (ad esempio, SaaS) per determinare le regole fiscali.

​

Prezzi

• Tipo di prezzo: scegli Subscription (questa guida). Le alternative sono Single Payment e Usage Based Billing.
• Prezzo (obbligatorio): prezzo ricorrente di base con valuta. Un prezzo diverso da zero deve essere almeno $1 (o l’equivalente nella valuta scelta); gli importi inferiori a questo minimo non sono supportati. Un prezzo esattamente pari a $0 è un caso distinto e supportato; consulta Card-Optional at Zero Price.
• Sconto applicabile (%): sconto percentuale facoltativo applicato al prezzo di base; viene riportato nel checkout e nelle fatture.
• Ripeti il pagamento ogni (obbligatorio): intervallo per i rinnovi, ad esempio ogni 1 Month. Seleziona la frequenza (mesi o anni) e la quantità.
• Periodo dell’abbonamento (obbligatorio): durata totale per cui l’abbonamento rimane attivo (ad esempio 10 Years). Al termine di questo periodo, i rinnovi si interrompono se non viene esteso.
• Giorni del periodo di prova (obbligatorio): imposta la durata del periodo di prova in giorni. Usa 0 per disabilitare i periodi di prova. Il primo addebito avviene automaticamente al termine del periodo di prova.
• Importo del periodo di prova: addebito iniziale facoltativo per un periodo di prova a pagamento. Lascialo non impostato per un periodo di prova gratuito. Consulta Paid Trials.
• Card-optional at $0 Price: consenti ai clienti di avviare l’abbonamento senza aggiungere una carta quando il prezzo è pari a $0 o uno sconto non lascia nulla da pagare oggi. Un periodo di prova gratuito dispone della propria casella Start the trial without a card. Consulta Card-Optional at Zero Price.
• Seleziona componente aggiuntivo: aggiungi fino a 10 componenti aggiuntivi che i clienti possono acquistare insieme al piano di base.

​

Impostazioni avanzate

• Prezzi comprensivi delle imposte: mostra i prezzi comprensivi delle imposte applicabili. Il calcolo fiscale finale varia comunque in base alla posizione del cliente.
• Genera chiavi di licenza: assegna una chiave univoca a ogni cliente dopo l’acquisto. Consulta la guida License Keys.
• Distribuzione di prodotti digitali: distribuisci automaticamente file o contenuti dopo l’acquisto. Scopri di più in Digital Product Delivery.
• Metadati: associa coppie chiave-valore personalizzate per tag interni o integrazioni client. Consulta Metadata.

​

Periodi di prova degli abbonamenti

​

Configurazione dei periodi di prova

// Via checkout session (recommended)
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_monthly', quantity: 1 }],
  subscription_data: { trial_period_days: 14 }
});

// Via subscription creation (deprecated)
// Note: POST /subscriptions is deprecated — prefer checkout sessions
const subscription = await client.subscriptions.create({
  customer: { customer_id: 'cus_123' },
  billing: { country: 'US' },
  product_id: 'pdt_monthly',
  quantity: 1,
  trial_period_days: 14
});

​

Periodi di prova a pagamento

const product = await client.products.create({
  name: 'Pro Plan',
  tax_category: 'saas',
  price: {
    type: 'recurring_price',
    price: 2900,                      // $29.00 per month after the trial
    currency: 'USD',
    discount_bps: 0,
    purchasing_power_parity: false,
    payment_frequency_count: 1,
    payment_frequency_interval: 'Month',
    subscription_period_count: 1,
    subscription_period_interval: 'Year',
    trial_period_days: 14,
    trial_amount: 500,                // $5.00 charged today
    trial_apply_discounts: false
  }
});

​

Card-Optional at Zero Price

• Un periodo di prova gratuito: trial_period_days è impostato senza trial_amount, quindi il primo addebito è pari a $0 durante il periodo di prova. Seleziona Start the trial without a card in Trial Period (Days).
• Un prezzo ricorrente di $0: il prezzo è pari a $0 oppure uno sconto lo porta a $0 (il Default Discount (%) del prodotto o un codice sconto applicato durante il checkout). Seleziona Card-optional at $0 Price.

​

Cosa succede senza una carta

1. Viene inviata un’e-mail di promemoria prima dell’inizio della fatturazione. Il numero di giorni è impostato in Settings → Subscriptions → Payment Method Reminder (consulta Subscription Settings). L’e-mail Add Payment Method Reminder (consulta Customer Emails) indirizza il cliente al Customer Portal per aggiungere una carta.
2. Se non viene aggiunta una carta in tempo, l’abbonamento passa a on_hold al termine del periodo di prova o del periodo scontato, quando è dovuto un addebito reale. Il cliente riceve l’e-mail Subscription On Hold, No Payment Method.
3. L’aggiunta di un metodo di pagamento riattiva l’abbonamento (consulta Reactivating from On Hold). Viene creato un addebito per l’importo ora dovuto e, in caso di successo, l’abbonamento torna a active.
4. Viene inviata un’email di promemoria prima dell’inizio della fatturazione effettiva. Il numero di giorni di anticipo viene impostato a livello aziendale in Payment Method Reminder, nella sezione Settings → Subscriptions; consulta Subscription Settings. L’email Add Payment Method Reminder del cliente (consulta Customer Emails) contiene un link diretto al Customer Portal per aggiungere una carta.
5. Se non viene aggiunta una carta in tempo, l’abbonamento passa a on_hold quando termina la prova o il periodo scontato e diventa dovuto un addebito effettivo: è lo stesso stato on_hold in cui può entrare qualsiasi abbonamento, in questo caso perché non è mai stato aggiunto un metodo di pagamento. Il cliente riceve l’email Subscription On Hold, No Payment Method.
6. L’aggiunta di un metodo di pagamento lo riattiva, esattamente come descritto in Reactivating from On Hold: viene creato un addebito per l’importo ora dovuto e, in caso di successo, l’abbonamento torna a active.

​

Prevenzione dell’uso improprio dei periodi di prova

• I clienti vengono associati tramite e-mail normalizzata (gli alias con il simbolo più vengono rimossi), quindi user+trial@example.com e user@example.com vengono considerati la stessa persona.
• Le richieste vengono registrate all’attivazione del periodo di prova, quindi un cliente che annulla lo stesso giorno ha comunque utilizzato il proprio periodo di prova.
• I clienti esistenti vengono recuperati dai periodi di prova storici tramite e-mail, quindi gli utenti che hanno già usufruito di un periodo di prova vengono riconosciuti immediatamente.
• Passare trial_period_days esplicitamente in una checkout session o in un abbonamento ignora il controllo e concede il periodo di prova.
• I clienti vengono associati tramite email normalizzata, rimuovendo gli alias con il simbolo più, quindi user+trial@example.com e user@example.com vengono considerati la stessa persona.
• Gli utilizzi vengono registrati al momento dell’attivazione della prova, quindi un cliente che annulla lo stesso giorno ha comunque consumato la propria prova.
• I clienti esistenti vengono recuperati dalle loro prove storiche tramite email, quindi gli utenti che hanno già usufruito di una prova vengono riconosciuti immediatamente.

​

Rilevamento dello stato del periodo di prova

​

Rilevamento dello stato della prova

​

Aggiornamento del periodo di prova

​

Aggiornamento del periodo di prova

​

Modifiche al piano dell’abbonamento

​

Modifiche al piano dell’abbonamento

​

Modalità di pro-rata

​

Modalità di proroga

​

prorated_immediately

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

​

difference_immediately

// Upgrade: charges $50 (difference between $30 and $80)
// Downgrade: credits the price difference, auto-applied to renewals
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});

​

full_immediately

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_monthly',
  quantity: 1,
  proration_billing_mode: 'full_immediately'
});

​

do_not_bill

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_new_plan',
  quantity: 1,
  proration_billing_mode: 'do_not_bill'
});

Credit for unused time on Basic = $30 × (15 remaining / 30 total) = $15.00
Full cycle of Pro               = $80.00 (never prorated)
────────────────────────────────────────────────────────────────────
Immediate charge                = $80.00 − $15.00 = $65.00

Credit = Old plan − New plan = $80 − $20 = $60.00

​

Modifica dei piani con componenti aggiuntivi

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [{ addon_id: 'addon_extra_seats', quantity: 2 }]  // Add add-ons
  // addons: []  // Empty array removes all existing add-ons
});

​

Anteprima delle modifiche al piano

​

Sospensione e ripresa degli abbonamenti

​

Sospensione e ripresa degli abbonamenti

​

Cosa succede quando sospendi

​

Cosa accade quando sospendi

• I rinnovi si interrompono. Durante la sospensione non viene generata alcuna fattura né tentato alcun addebito di rinnovo.
• L’accesso viene revocato immediatamente. La sospensione revoca ogni entitlement grant già distribuito o in sospeso sull’abbonamento, disabilitando le relative license keys e impedendo la generazione di nuovi URL per il download di prodotti digitali. La ripresa li assegna nuovamente, come avviene recuperando da on_hold.
• L’orologio della fatturazione si congela. next_billing_date e expires_at avanzano entrambi esattamente per la durata della sospensione, così il cliente conserva il tempo già pagato.
• Non esiste un limite alla durata della sospensione. Un abbonamento sospeso rimane tale finché qualcuno non lo riprende. Non è necessario impostare in anticipo la durata della sospensione.

​

Sospensione degli abbonamenti basati sull’utilizzo

​

Consentire ai clienti di sospendere autonomamente gli abbonamenti

​

Consentire ai clienti di sospendere autonomamente gli abbonamenti

​

Sospensione tramite API

​

Sospensione tramite API

// Pause
await client.subscriptions.update('sub_123', { status: 'paused' });

// Resume
await client.subscriptions.update('sub_123', { status: 'active' });

​

Stati dell’abbonamento

• La cancellazione continua a funzionare. Puoi cancellare un abbonamento sospeso esattamente come uno attivo. Qualsiasi fattura di regolazione aperta derivante dalla sospensione viene stornata.
• Le modifiche programmate del piano vengono ritardate, non eliminate. Una modifica del piano programmata per la prossima data di fatturazione rimane intatta durante la sospensione e viene applicata alla data di fatturazione posticipata quando l’abbonamento riprende. Il suo scheduled_change.effective_at è un’istantanea del momento della programmazione e non viene modificato dalla sospensione, quindi può mostrare una data passata: leggilo come “era programmato per”, non come una data garantita. Per eliminare la modifica invece di mantenerla, usa Cancel Scheduled Plan Change.

​

Stati degli abbonamenti

​

Macchina a stati

​

Stato sospeso

​

Stato On Hold

• Un pagamento di rinnovo non va a buon fine (fondi insufficienti, carta scaduta ecc.)
• Un addebito per una modifica del piano non va a buon fine
• L’autorizzazione del metodo di pagamento non va a buon fine
• Una fattura di regolazione della sospensione per un abbonamento basato sull’utilizzo rimane insoluta
• Un periodo di tolleranza termina con il debito del rinnovo insoluto e l’azione di scadenza è on_hold
• Il periodo di prova gratuito o il periodo a $0 di un abbonamento [Card-Optional at$0 Price](#card-optional-at-0-price) termina senza che sia mai stato aggiunto un metodo di pagamento

​

Riattivazione dallo stato sospeso

​

Riattivazione dallo stato On Hold

1. Crea un addebito per gli importi ancora dovuti
2. Genera una fattura
3. Elabora il pagamento usando il nuovo metodo di pagamento
4. Riattiva l’abbonamento allo stato active dopo il pagamento riuscito

​

Periodo di tolleranza

​

Periodo di tolleranza

​

Impostazioni

​

Cosa accade durante la finestra

• Il cliente mantiene l’accesso. Le entitlement grant, le license keys e i download dei prodotti digitali rimangono attivi.
• La fatturazione basata sull’utilizzo continua a registrare l’utilizzo.
• L’abbonamento non si rinnova.
• L’abbonamento non può essere sospeso.
• Vengono inviate email di Dunning e continuano i payment retries.
• subscription.past_due viene emesso all’ingresso nello stato.

​

Recupero

​

Quando termina la finestra

• Una modifica programmata del piano sull’abbonamento viene cancellata.
• Una modifica del piano in sospeso la cui fattura è ancora insoluta viene cancellata.

​

Eventi webhook per transizione

​

Gestione tramite API

​

Gestione tramite API

​

Esempi di integrazione

• SaaS e API: accesso a livelli con componenti aggiuntivi per posti o utilizzo
• Contenuti e media: accesso mensile con prove introduttive
• Piani di supporto B2B: contratti annuali con componenti aggiuntivi di supporto premium
• Strumenti e plugin: chiavi di licenza e release versionate

​

Esempi di integrazione

​

Checkout Sessions (abbonamenti)

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_subscription',
      quantity: 1
    }
  ]
});

​

Modifiche del piano con proroga

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});

​

Cancellazione alla prossima data di fatturazione

await client.subscriptions.update('sub_123', {
  cancel_at_next_billing_date: true
});

​

Estensione del periodo dell’abbonamento

await client.subscriptions.update('sub_123', {
  subscription_period_count: 5,
  subscription_period_interval: 'Month'
});

​

Abbonamenti on-demand

// Note: POST /subscriptions is deprecated — prefer checkout sessions for new integrations
const onDemand = await client.subscriptions.create({
  customer: { customer_id: 'cus_123' },
  billing: { country: 'US' },
  product_id: 'pdt_on_demand',
  quantity: 1,
  on_demand: { mandate_only: true }
});

await client.subscriptions.charge(onDemand.subscription_id, {
  product_price: 4900,
  product_currency: 'USD',
  product_description: 'Extra usage for September'
});

​

Aggiornamento del metodo di pagamento per un abbonamento attivo

// Update with new payment method
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

// Or use existing payment method
await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'existing',
    payment_method_id: 'pm_abc123'
  }
});

​

Riattivazione di un abbonamento da on_hold

// Update payment method - automatically creates charge for remaining dues
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

if (response.payment_id) {
  // Charge created for remaining dues
  // Redirect customer to response.payment_link
  // Monitor webhooks: payment.succeeded → subscription.active
}

​

Abbonamenti con mandati conformi a RBI

​

Limiti dei mandati

• Addebiti inferiori alla soglia del mandato (₹15.000 per impostazione predefinita): creiamo un mandato on-demand per l’importo della soglia. L’importo dell’abbonamento viene addebitato periodicamente in base alla frequenza, fino al limite del mandato.
• Addebiti pari o superiori alla soglia del mandato: creiamo un mandato di abbonamento (o un mandato on-demand) per l’importo esatto dell’abbonamento.

​

Considerazioni su upgrade e downgrade

• Se un upgrade o downgrade produce un importo superiore a Rs 15.000 e oltrepassa il limite di pagamento on-demand esistente, l’addebito della transazione potrebbe non riuscire.
• In questi casi, il cliente potrebbe dover aggiornare il metodo di pagamento o modificare nuovamente l’abbonamento per stabilire un nuovo mandato con il limite corretto.

​

Autorizzazione per addebiti di importo elevato

• La banca chiederà al cliente di autorizzare la transazione.
• Se il cliente non autorizza la transazione, questa non andrà a buon fine e l’abbonamento verrà sospeso.

​

Ritardo di elaborazione di 48 ore

• Se un upgrade/downgrade comporta un importo addebitato superiore alla soglia minima del mandato (₹15.000 per impostazione predefinita) e oltrepassa il limite di pagamento on-demand esistente, l’addebito della transazione potrebbe non riuscire.
• Il cliente potrebbe dover aggiornare il metodo di pagamento o modificare nuovamente l’abbonamento per stabilire un nuovo mandato con il limite corretto.
  • Gli addebiti vengono avviati nella data programmata secondo la frequenza dell’abbonamento.
  • L’effettiva detrazione dal conto del cliente avviene solo dopo 48 ore dall’avvio del pagamento.
  • Questa finestra di 48 ore può estendersi fino a 2-3 ore aggiuntive a seconda delle risposte delle API bancarie.

  ​

  Finestra di cancellazione del mandato

  Durante la finestra di elaborazione di 48 ore:
  • I clienti possono cancellare il mandato tramite le proprie app bancarie.
  • Se un cliente cancella il mandato durante questo periodo, l’abbonamento rimane attivo (si tratta di un caso limite specifico degli abbonamenti con carte indiane e UPI AutoPay).
  • Tuttavia, la detrazione effettiva potrebbe non riuscire e, in tal caso, l’abbonamento verrà messo on hold.
  Gestione dei casi limite: se fornisci vantaggi, crediti o utilizzo dell’abbonamento ai clienti immediatamente dopo l’avvio dell’addebito, devi gestire correttamente questa finestra di 48 ore nella tua applicazione. Valuta di:
  • Ritardare l’attivazione dei vantaggi fino alla conferma del pagamento
  • Implementare periodi di tolleranza o accesso temporaneo
  • Monitorare lo stato dell’abbonamento per rilevare cancellazioni dei mandati
  • Gestire gli stati di sospensione dell’abbonamento nella logica dell’applicazione
  Monitora i webhook degli abbonamenti per seguire le modifiche dello stato dei pagamenti e gestire i casi limite in cui i mandati vengono cancellati durante la finestra di 48 ore.

​

Procedure consigliate

• Inizia con livelli chiari: 2-3 piani con differenze evidenti
• Comunica i prezzi: mostra totali, proroga e prossimo rinnovo
• Usa i periodi di prova con criterio: converti con l’onboarding, non solo con il tempo
• Sfrutta i componenti aggiuntivi: mantieni semplici i piani di base e fai upselling degli extra
• Testa le modifiche: convalida le modifiche del piano e la proroga in modalità di test

• Delay benefit activation until payment confirmation
• Implement grace periods or temporary access
• Monitor subscription status for mandate cancellations
• Handle subscription hold states in your application logic

​

Procedure consigliate

• Start with clear tiers: 2-3 plans with obvious differences
• Communicate pricing: Show totals, proration, and next renewal date
• Use trials thoughtfully: Convert with onboarding, not just time
• Leverage add-ons: Keep base plans simple and upsell extras
• Test changes: Validate plan changes and proration in test mode