Abbonamenti

​

Cosa Sono gli Abbonamenti?

• Licenze SaaS: App, API o accesso alla piattaforma
• Abbonamenti: Comunità, programmi o club
• Contenuti digitali: Corsi, media o contenuti premium
• Piani di supporto: SLA, pacchetti di successo o manutenzione

​

Vantaggi Chiave

• Entrate prevedibili: Fatturazione ricorrente con rinnovi automatici
• Cicli flessibili: Mensili, annuali, intervalli personalizzati e prove
• Agilità del piano: Ripartizione per aggiornamenti e riduzioni
• Add-on e posti: Allegare aggiornamenti opzionali e quantificabili
• Checkout senza soluzione di continuità: Checkout ospitato e portale clienti
• Sviluppatore-first: API chiare per creazione, modifiche e tracciamento dell’uso

​

Creazione di Abbonamenti

​

Creazione di un prodotto in abbonamento

​

Dettagli del prodotto

• Nome del prodotto (obbligatorio): Il nome visualizzato nel checkout, nel portale clienti e nelle fatture.
• Descrizione del prodotto (obbligatoria): Una chiara dichiarazione di valore che appare nel checkout e nelle fatture.
• Immagine del prodotto (obbligatoria): PNG/JPG/WebP fino a 3 MB. Utilizzata nel checkout e nelle fatture.
• Marca: Associa il prodotto a un marchio specifico per la tematizzazione e le email.
• Categoria fiscale (obbligatoria): Scegli la categoria (ad esempio, SaaS) per determinare le regole fiscali.

​

Prezzi

• Tipo di Prezzo: Scegli Abbonamento (questa guida). Le alternative sono Pagamento Singolo e Fatturazione Basata sull’Uso.
• Prezzo (obbligatorio): Prezzo ricorrente base con valuta.
• Sconto Applicabile (%): Percentuale di sconto opzionale applicata al prezzo base; riflessa nel checkout e nelle fatture.
• Ripeti pagamento ogni (obbligatorio): Intervallo per i rinnovi, ad esempio, ogni 1 Mese. Seleziona la cadenza (mesi o anni) e la quantità.
• Periodo di Abbonamento (obbligatorio): Termine totale per il quale l’abbonamento rimane attivo (ad esempio, 10 Anni). Dopo la scadenza di questo periodo, i rinnovi si fermano a meno che non vengano estesi.
• Giorni di Periodo di Prova (obbligatorio): Imposta la durata della prova in giorni. Usa 0 per disabilitare le prove. Il primo addebito avviene automaticamente al termine della prova.
• Seleziona add-on: Allegare fino a 10 add-on che i clienti possono acquistare insieme al piano base.

​

Impostazioni avanzate

• Prezzi inclusivi di tasse: Visualizza i prezzi inclusivi delle tasse applicabili. Il calcolo finale delle tasse varia comunque in base alla posizione del cliente.
• Genera chiavi di licenza: Emissione di una chiave unica a ciascun cliente dopo l’acquisto. Vedi la guida sulle Chiavi di Licenza.
• Consegna di prodotti digitali: Consegna automatica di file o contenuti dopo l’acquisto. Scopri di più in Consegna di Prodotti Digitali.
• Metadati: Allegare coppie chiave-valore personalizzate per tagging interno o integrazioni client. Vedi Metadati.

​

Prove di Abbonamento

​

Configurazione delle Prove

// Via subscription creation
const subscription = await client.subscriptions.create({
  customer_id: 'cus_123',
  product_id: 'prod_monthly',
  trial_period_days: 14  // Overrides product's trial period
});

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

​

Rilevamento dello Stato della Prova

const subscription = await client.subscriptions.retrieve('sub_123');
const payments = await client.payments.list({
  subscription_id: subscription.subscription_id
});

// Check if subscription is in trial
const isInTrial = payments.items.length === 1 && 
                  payments.items[0].total_amount === 0;

​

Aggiornamento del Periodo di Prova

await client.subscriptions.update('sub_123', {
  next_billing_date: '2025-02-15T00:00:00Z'  // New trial end date
});

​

Modifiche ai Piani di Abbonamento

​

Modalità di prorata

​

prorated_immediately

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

​

difference_immediately

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

​

full_immediately

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

Unused credit from Basic = $30 × (15 remaining / 30 total) = $15.00
Prorated cost of Pro     = $80 × (15 remaining / 30 total) = $40.00
────────────────────────────────────────────────────────────────────
Immediate charge         = $40.00 − $15.00 = $25.00

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

​

Modifiche ai piani con componenti aggiuntivi

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_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 ai piani

const preview = await client.subscriptions.previewChangePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

// Show customer the charge before confirming
console.log('You will be charged:', preview.immediate_charge.summary);

​

Stati delle sottoscrizioni

• active: la sottoscrizione è attiva e si rinnova automaticamente
• on_hold: la sottoscrizione è sospesa a causa di un pagamento fallito. È necessario aggiornare il metodo di pagamento per riattivarla
• cancelled: la sottoscrizione è annullata e non si rinnoverà
• expired: la sottoscrizione ha raggiunto la data di fine
• pending: la sottoscrizione è in fase di creazione o elaborazione

​

Stato “On Hold”

• un pagamento di rinnovo fallisce (fondi insufficienti, carta scaduta, ecc.)
• un addebito per il cambio piano fallisce
• l’autorizzazione del metodo di pagamento fallisce

​

Riattivazione dallo stato “On Hold”

1. crea un addebito per i debiti residui
2. genera una fattura
3. elabora il pagamento utilizzando il nuovo metodo di pagamento
4. riattiva la sottoscrizione nello stato active al completamento del pagamento

// Reactivate subscription from on_hold
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  type: 'new',
  return_url: 'https://example.com/return'
});

// For on_hold subscriptions, a charge is automatically created
if (response.payment_id) {
  console.log('Charge created:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
  // Monitor webhooks for payment.succeeded and subscription.active
}

​

Gestione API

​

Casi d’uso comuni

• 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 rilasci versionati

​

Esempi di integrazione

​

Checkout Sessions (sottoscrizioni)

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

​

Modifiche ai piani con prorata

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

​

Annulla alla prossima data di fatturazione

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

​

Sottoscrizioni on-demand

const onDemand = await client.subscriptions.create({
  customer_id: 'cus_123',
  product_id: 'prod_on_demand',
  on_demand: true
});

await client.subscriptions.createCharge(onDemand.id, {
  amount: 4900,
  currency: 'USD',
  description: 'Extra usage for September'
});

​

Aggiorna il metodo di pagamento per una sottoscrizione attiva

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

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

​

Riattiva la sottoscrizione da on_hold

// Update payment method - automatically creates charge for remaining dues
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  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
}

​

Sottoscrizioni con mandati conformi alla RBI

​

Limiti del mandato

• Addebiti inferiori a Rs 15.000: creiamo un mandato on-demand per Rs 15.000 INR. L’importo della sottoscrizione viene addebitato periodicamente secondo la frequenza della sottoscrizione, fino al limite del mandato.
• Addebiti pari o superiori a Rs 15.000: creiamo un mandato di sottoscrizione (o mandato on-demand) per l’esatto importo della sottoscrizione.

​

Considerazioni su upgrade e downgrade

• Se un upgrade/downgrade comporta un importo superiore a Rs 15.000 e supera il limite di pagamento on-demand esistente, l’addebito della transazione potrebbe fallire.
• In tali casi, il cliente potrebbe dover aggiornare il metodo di pagamento o modificare nuovamente la sottoscrizione per stabilire un nuovo mandato con il limite corretto.

​

Autorizzazione per addebiti di alto valore

• La banca del cliente richiederà l’autorizzazione della transazione.
• Se il cliente non autorizza la transazione, questa fallirà e la sottoscrizione verrà messa in sospeso.

​

Ritardo di elaborazione di 48 ore

• Gli addebiti vengono avviati nella data programmata in base alla frequenza della sottoscrizione.
• La deduzione effettiva 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 in base alle risposte delle API bancarie.

​

Finestra di cancellazione del mandato

• I clienti possono cancellare il mandato tramite le loro app bancarie.
• Se un cliente cancella il mandato durante questo periodo, la sottoscrizione rimane attiva (si tratta di un caso limite specifico per le sottoscrizioni AutoPay con carte indiane e UPI).
• Tuttavia, la deduzione effettiva potrebbe fallire e in tal caso metteremo la sottoscrizione in sospeso.

• Ritardare l’attivazione dei benefici fino alla conferma del pagamento
• Implementare periodi di grazia o accesso temporaneo
• Monitorare lo stato della sottoscrizione per cancellazioni del mandato
• Gestire gli stati di sospensione delle sottoscrizioni nella logica applicativa

​

Migliori pratiche

• Inizia con livelli chiari: 2–3 piani con differenze evidenti
• Comunica i prezzi: mostra totali, prorata e prossimo rinnovo
• Usa le prove in modo ponderato: converti con onboarding, non solo con il tempo
• Sfrutta i componenti aggiuntivi: mantieni i piani base semplici e vendi extra
• Testa le modifiche: convalida i cambi piano e la prorata in modalità test