Subscription Integration Guide

​

Prerequisiti

• Un account merchant Dodo Payments
• Una chiave API disponibile in Developer → API Keys nella dashboard, salvata in DODO_PAYMENTS_API_KEY
• Un webhook secret disponibile in Developer → Webhooks, salvato in DODO_PAYMENTS_WEBHOOK_KEY
• Almeno un prodotto in abbonamento creato in Products

​

Integrazione API

​

Sessioni di checkout

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

async function main() {
  const session = await client.checkoutSessions.create({
    product_cart: [
      { product_id: 'pdt_subscription_monthly', quantity: 1 }
    ],
    // Optional: configure trials for subscription products
    subscription_data: { trial_period_days: 14 },
    customer: {
      email: 'subscriber@example.com',
      name: 'Jane Doe',
    },
    return_url: 'https://example.com/success',
  });

  console.log(session.checkout_url);
}

main();

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",  # defaults to "live_mode"
)

session = client.checkout_sessions.create(
    product_cart=[
        {"product_id": "pdt_subscription_monthly", "quantity": 1}
    ],
    subscription_data={"trial_period_days": 14},  # optional
    customer={
        "email": "subscriber@example.com",
        "name": "Jane Doe",
    },
    return_url="https://example.com/success",
)

print(session.checkout_url)

const response = await fetch('https://test.dodopayments.com/checkouts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`
  },
  body: JSON.stringify({
    product_cart: [
      { product_id: 'pdt_subscription_monthly', quantity: 1 }
    ],
    subscription_data: { trial_period_days: 14 }, // optional
    customer: {
      email: 'subscriber@example.com',
      name: 'Jane Doe'
    },
    return_url: 'https://example.com/success'
  })
});

if (!response.ok) {
  throw new Error(`HTTP error! status: ${response.status}`);
}

const session = await response.json();
console.log(session.checkout_url);

​

Risposta API

{
  "session_id": "cks_Gi6KGJ2zFJo9rq9Ukifwa",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}

​

Webhook

​

Tipi di eventi dell’abbonamento

1. subscription.active — L’abbonamento è attivato
2. subscription.updated — Un campo dell’abbonamento è cambiato
3. subscription.on_hold — Un addebito di rinnovo o di modifica del piano non è riuscito
4. subscription.failed — La creazione dell’abbonamento non è riuscita (stato terminale; il cliente deve sottoscrivere nuovamente l’abbonamento)
5. subscription.renewed — Un addebito ricorrente è riuscito
6. subscription.past_due — Un rinnovo non è riuscito ed è iniziato il periodo di tolleranza; il cliente mantiene l’accesso fino a past_due_ends_at
7. subscription.plan_changed — Il piano è stato aggiornato, declassato o modificato
8. subscription.cancelled — L’abbonamento è stato annullato
9. subscription.expired — L’abbonamento ha raggiunto la fine del proprio periodo

​

Scenari di pagamento

1. subscription.active: il mandato viene autorizzato e l’abbonamento viene attivato.
2. payment.succeeded: conferma il primo addebito. Dovresti riceverlo entro 2–10 minuti dal checkout.

1. All’inizio della prova (checkout): subscription.active viene inviato quando il metodo di pagamento è autorizzato. Non viene ancora effettuato alcun addebito ricorrente. Il primo addebito effettivo viene posticipato fino alla fine del periodo di prova.
2. Alla fine della prova: viene addebitato l’importo ricorrente e ricevi payment.succeeded insieme a subscription.renewed.

• subscription.renewed: viene inviato a ogni ciclo di fatturazione quando il pagamento del rinnovo viene detratto, sempre insieme a payment.succeeded. Contiene anche il valore aggiornato di next_billing_date.

1. Errore dell’abbonamento

• subscription.failed - La creazione dell’abbonamento non è riuscita perché non è stato possibile creare un mandato.
• payment.failed - Indica un pagamento non riuscito.

2. Abbonamento sospeso

• subscription.on_hold - L’abbonamento viene sospeso a causa di un pagamento di rinnovo non riuscito o di un addebito per la modifica del piano non riuscito. Se la tua attività prevede un periodo di tolleranza, un rinnovo non riuscito sposta prima l’abbonamento in past_due (subscription.past_due), quindi lo sposta in on_hold (o cancelled, a seconda delle impostazioni del periodo di tolleranza) solo al termine del periodo di tolleranza. Consulta Subscription States.
• Quando un abbonamento viene sospeso, non si rinnoverà automaticamente finché il metodo di pagamento non viene aggiornato.

​

subscription.failed vs. subscription.on_hold

​

Gestione degli abbonamenti sospesi

​

Quando gli abbonamenti vengono sospesi

• Il pagamento del rinnovo non riesce: l’addebito automatico del rinnovo non riesce a causa di fondi insufficienti, carta scaduta o rifiuto della banca
• L’addebito per la modifica del piano non riesce: un addebito immediato durante l’upgrade o il downgrade del piano non riesce
• L’autorizzazione del metodo di pagamento non riesce: il metodo di pagamento non può essere autorizzato per addebiti ricorrenti

​

Riattivazione degli abbonamenti sospesi

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

// Webhook handler
app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;
  
  if (event.type === 'subscription.on_hold') {
    const subscription = event.data;
    
    // Update subscription status in your database
    await updateSubscriptionStatus(subscription.subscription_id, 'on_hold');
    
    // Notify customer to update payment method
    await sendEmailToCustomer(subscription.customer_id, {
      subject: 'Payment Required - Subscription On Hold',
      message: 'Your subscription is on hold. Please update your payment method to continue service.'
    });
  }
  
  res.json({ received: true });
});

// Update with new payment method
const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
  payment_method: { 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 for remaining dues:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
}

# Update with new payment method
response = client.subscriptions.update_payment_method(
    subscription_id=subscription_id,
    payment_method={"type": "new", "return_url": "https://example.com/return"},
)

# For on_hold subscriptions, a charge is automatically created
if response.payment_id:
    print("Charge created for remaining dues:", response.payment_id)
    # Redirect customer to response.payment_link to complete payment

await client.subscriptions.updatePaymentMethod(subscriptionId, {
  payment_method: { type: 'existing', payment_method_id: 'pm_abc123' }
});

if (event.type === 'payment.succeeded') {
  const payment = event.data;
  
  // Check if this payment is for an on_hold subscription
  if (payment.subscription_id) {
    // Wait for subscription.active webhook to confirm reactivation
  }
}

if (event.type === 'subscription.active') {
  const subscription = event.data;
  
  // Update subscription status in your database
  await updateSubscriptionStatus(subscription.subscription_id, 'active');
  
  // Restore customer access
  await restoreCustomerAccess(subscription.customer_id);
  
  // Notify customer of successful reactivation
  await sendEmailToCustomer(subscription.customer_id, {
    subject: 'Subscription Reactivated',
    message: 'Your subscription has been reactivated successfully.'
  });
}

​

Payload di esempio di un evento dell’abbonamento

​

Modifica dei piani di abbonamento

​

Opzioni di proroga

​

1. prorated_immediately

• Accredita la parte inutilizzata del ciclo di fatturazione corrente, calcolata proporzionalmente in base al tempo rimanente. Il credito copre il piano base, la quantità e tutti gli add-on
• Quindi addebita un ciclo completo con il nuovo piano, la nuova quantità e i nuovi add-on. L’addebito non viene mai calcolato proporzionalmente
• Addebito immediato netto = (nuovo ciclo completo) meno (frazione rimanente × vecchio ciclo completo). Se il credito è maggiore, la differenza viene conservata come credito associato all’abbonamento per i rinnovi futuri
• Durante un periodo di prova, l’utente passa immediatamente al nuovo piano e al cliente viene addebitato subito l’importo

​

2. full_immediately

• Addebita al cliente l’intero importo dell’abbonamento per il nuovo piano, senza alcun credito per il ciclo precedente
• Sia in caso di upgrade che di downgrade, il cliente paga da zero l’intero prezzo del nuovo piano
• Utile quando vuoi addebitare l’intero importo indipendentemente dal tempo rimasto sul vecchio piano

​

3. difference_immediately

• Il cliente paga solo la differenza tra il prezzo del vecchio piano e quello del nuovo piano
• L’importo non dipende dal momento del ciclo in cui viene effettuata la modifica. Lo stesso upgrade costa uguale il giorno 1 e il giorno 29
• In caso di upgrade, al cliente viene addebitata immediatamente la differenza. Ad esempio, $30/mese → $80/mese = $50 addebitati immediatamente
• In caso di downgrade, la differenza di prezzo viene conservata come credito associato all’abbonamento e applicata automaticamente ai rinnovi futuri. Ad esempio, $50/mese → $20/mese = $30 conservati come credito

​

4. do_not_bill

• Applica immediatamente la modifica del piano, ma non addebita alcun importo al momento della modifica. Il nuovo piano, la nuova quantità e i nuovi add-on sono utilizzabili immediatamente
• Poiché non viene addebitato nulla subito, un upgrade offre al cliente il piano superiore gratuitamente per il resto del ciclo corrente. Un downgrade ha effetto immediato senza alcun credito per la parte inutilizzata del ciclo già pagato
• Gli add-on concessi tramite do_not_bill non vengono accreditati in una modifica successiva del piano, perché non sono mai stati fatturati. Una modifica successiva addebita per intero la nuova quantità di add-on
• Il piano aggiornato (e la quantità/gli add-on) viene fatturato al rinnovo programmato successivo e la data di fatturazione originale viene mantenuta

​

Comportamento

• Quando invochi questa API, Dodo Payments avvia immediatamente un addebito in base all’opzione di proroga selezionata
• Con prorated_immediately, a ogni modifica viene calcolato un credito per la parte inutilizzata del ciclo corrente, sia in caso di upgrade che di downgrade. Se tale credito supera l’addebito per il nuovo ciclo, il residuo viene aggiunto al saldo crediti dell’abbonamento. Questi crediti sono specifici dell’abbonamento e verranno utilizzati solo per compensare i pagamenti ricorrenti futuri dello stesso abbonamento
• Con difference_immediately, il netto corrisponde sempre all’esatta differenza di prezzo. In caso di downgrade, l’eccedenza viene conservata come credito associato all’abbonamento, come con prorated_immediately
• L’opzione full_immediately ignora i calcoli dei crediti e addebita l’intero importo del nuovo piano
• L’opzione do_not_bill applica immediatamente la modifica, ma rimanda la fatturazione alla data del rinnovo successivo, che viene mantenuta

​

Elaborazione degli addebiti

• L’addebito immediato avviato dopo la modifica del piano di solito completa l’elaborazione in meno di 2 minuti
• Se questo addebito immediato non riesce per qualsiasi motivo, l’abbonamento viene automaticamente sospeso finché il problema non viene risolto

​

Abbonamenti on-demand

​

Aspetti fondamentali della fatturazione degli abbonamenti

​

Riferimenti API correlati