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 degli abbonamenti

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 (terminale; il cliente deve sottoscrivere nuovamente l’abbonamento)
5. subscription.renewed — Un addebito ricorrente è riuscito
6. subscription.past_due — Un rinnovo non è riuscito e il periodo di tolleranza è iniziato; il cliente mantiene l’accesso fino a past_due_ends_at
7. subscription.plan_changed — Il piano è stato migliorato, ridotto 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. Attendi questo evento entro 2–10 minuti dal checkout.

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

• subscription.renewed: viene generato 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 di modifica del piano non riuscito. Se la tua attività dispone di un periodo di tolleranza, un rinnovo non riuscito sposta inizialmente 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. Consulta Stati degli abbonamenti.
• Quando un abbonamento viene sospeso, non si rinnoverà automaticamente finché il metodo di pagamento non verrà aggiornato.

​

subscription.failed vs. subscription.on_hold

​

Gestire un abbonamento sospeso

​

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 il miglioramento o la riduzione del piano non riesce
• L’autorizzazione del metodo di pagamento non riesce: non è possibile autorizzare il metodo di pagamento per gli addebiti ricorrenti

​

Riattivare gli abbonamenti sospesi

1. Creato un addebito per gli importi ancora dovuti
2. Generata una fattura per l’addebito
3. Elaborato il pagamento usando il nuovo metodo di pagamento
4. Riattivato l’abbonamento allo 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

​

Modificare i piani degli abbonamenti

​

Opzioni di prorating

​

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 gli eventuali componenti aggiuntivi
• Quindi addebita un ciclo completo con il nuovo piano, la nuova quantità e i nuovi componenti aggiuntivi. 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 il cliente viene addebitato subito

​

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 miglioramento sia di riduzione, il cliente paga da zero l’intero prezzo del nuovo piano
• Utile quando vuoi addebitare l’intero importo indipendentemente dal tempo rimasto nel 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 miglioramento costa uguale al giorno 1 e al giorno 29
• Quando si effettua un miglioramento, al cliente viene addebitata immediatamente la differenza. Ad esempio, $30/mese → $80/mese = $50 addebitati subito
• Quando si effettua una riduzione, 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 quantità e i componenti aggiuntivi sono utilizzabili subito
• Poiché non viene addebitato nulla subito, un miglioramento offre al cliente il piano superiore gratuitamente per il resto del ciclo corrente. Una riduzione entra in vigore immediatamente senza credito per la parte inutilizzata del ciclo già pagata
• I componenti aggiuntivi concessi tramite do_not_bill non vengono accreditati in una modifica successiva del piano, perché non sono mai stati fatturati. Una modifica successiva fattura interamente la nuova quantità dei componenti aggiuntivi
• Il piano aggiornato (e la quantità/i componenti aggiuntivi) viene fatturato al prossimo rinnovo programmato e la data di fatturazione originale viene mantenuta

​

Comportamento

• Quando richiami questa API, Dodo Payments avvia immediatamente un addebito in base all’opzione di prorating selezionata
• Con prorated_immediately, a ogni modifica, sia miglioramento sia riduzione, viene calcolato un credito per la parte inutilizzata del ciclo corrente. Se il credito supera l’addebito del nuovo ciclo, il residuo viene aggiunto al saldo dei crediti dell’abbonamento. Questi crediti sono specifici dell’abbonamento e verranno utilizzati solo per compensare i futuri pagamenti ricorrenti dello stesso abbonamento
• Con difference_immediately, il netto corrisponde sempre esattamente alla differenza di prezzo. Per le riduzioni, 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 dell’addebito

• L’elaborazione dell’addebito immediato avviato dopo la modifica del piano generalmente si completa 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