Subscription Integration Guide

​

Prerequisites

• A Dodo Payments merchant account
• API credentials (API key and webhook secret key) from the dashboard

​

API Integration

​

Checkout Sessions

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: 'prod_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": "prod_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: 'prod_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);

​

API Response

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

​

Webhook

​

Tipi di eventi di abbonamento

1. subscription.active - L’abbonamento è stato attivato con successo.
2. subscription.updated - L’oggetto dell’abbonamento è stato aggiornato (si attiva su qualsiasi modifica del campo).
3. subscription.on_hold - L’abbonamento è messo in attesa a causa di un rinnovo fallito.
4. subscription.failed - La creazione dell’abbonamento è fallita durante la creazione del mandato.
5. subscription.renewed - L’abbonamento è rinnovato per il prossimo periodo di fatturazione.

​

Scenari di pagamento

1. subscription.active: il mandato viene autorizzato e la sottoscrizione viene attivata.
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 emesso quando il metodo di pagamento è autorizzato. Non viene ancora effettuato alcun addebito ricorrente. Il primo addebito effettivo viene posticipato fino al termine della prova.
2. Al termine della prova: viene addebitato l’importo ricorrente e ricevi payment.succeeded insieme a subscription.renewed.

• subscription.renewed: viene emesso 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 della sottoscrizione

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

2. Sottoscrizione sospesa

• subscription.on_hold - La sottoscrizione viene sospesa a causa di un pagamento di rinnovo non riuscito o di un addebito per la modifica del piano non riuscito.
• Quando una sottoscrizione viene sospesa, non si rinnoverà automaticamente finché il metodo di pagamento non verrà aggiornato.

​

subscription.failed vs. subscription.on_hold

​

Gestione delle sottoscrizioni sospese

​

Quando le sottoscrizioni vengono sospese

• Il pagamento del rinnovo non riesce: l’addebito automatico del rinnovo non riesce a causa di fondi insufficienti, carta scaduta o rifiuto da parte 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: non è possibile autorizzare il metodo di pagamento per gli addebiti ricorrenti

​

Riattivazione delle sottoscrizioni sospese

1. Crea un addebito per gli importi ancora dovuti
2. Genera una fattura per l’addebito
3. Elabora il pagamento utilizzando il nuovo metodo di pagamento
4. Riattiva la sottoscrizione nello stato active dopo il pagamento effettuato correttamente

// 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, {
  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,
    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, {
  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.'
  });
}

​

Esempio di payload di un evento Subscription

​

Modifica dei piani di sottoscrizione

​

Opzioni di proroga

​

1. prorated_immediately

• Calcola l’importo pro rata in base al tempo rimanente nel ciclo di fatturazione corrente
• Addebita al cliente solo la differenza tra il piano precedente e quello nuovo
• Durante un periodo di prova, passa immediatamente l’utente al nuovo piano, addebitando subito il cliente

​

2. full_immediately

• Addebita al cliente l’intero importo della sottoscrizione per il nuovo piano
• Ignora il tempo rimanente o i crediti del piano precedente
• È utile quando vuoi reimpostare il ciclo di fatturazione o addebitare l’intero importo indipendentemente dalla proroga

​

3. difference_immediately

• In caso di upgrade, al cliente viene immediatamente addebitata la differenza tra gli importi dei due piani.
• Ad esempio, se il piano corrente costa 30 Dollari e il cliente passa a un piano da 80 Dollari, gli vengono addebitati istantaneamente $50.
• In caso di downgrade, l’importo inutilizzato del piano corrente viene aggiunto come credito interno e applicato automaticamente ai rinnovi futuri della sottoscrizione.
• Ad esempio, se il piano corrente costa 50 Dollari e il cliente passa a un piano da 20 Dollari, i $30 rimanenti vengono accreditati e utilizzati per il ciclo di fatturazione successivo.

​

4. do_not_bill

• Applica immediatamente la modifica del piano, ma non effettua alcun addebito al momento della modifica.
• Il piano aggiornato (e la quantità/gli extra) viene fatturato al rinnovo programmato successivo e la data di fatturazione originale viene mantenuta.

​

Comportamento

• Quando richiami questa API, Dodo Payments avvia immediatamente un addebito in base all’opzione di proroga selezionata
• Se la modifica del piano è un downgrade e utilizzi prorated_immediately, i crediti vengono calcolati automaticamente e aggiunti al saldo crediti della sottoscrizione. Questi crediti sono specifici di quella sottoscrizione e verranno utilizzati solo per compensare i futuri pagamenti ricorrenti della stessa sottoscrizione
• L’opzione full_immediately ignora i calcoli dei crediti e addebita l’intero importo del nuovo piano

​

Elaborazione degli addebiti

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

​

Sottoscrizioni on-demand

​

Aspetti fondamentali della fatturazione delle sottoscrizioni

​

Riferimenti API correlati