> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Integrationsguide för prenumerationer
> Denna guide hjälper dig att integrera Dodo Payments prenumerationsprodukt på din webbplats.
## Förutsättningar
För att integrera Dodo Payments API behöver du:
* Ett Dodo Payments handelskonto
* API-uppgifter (API-nyckel och webhook hemlig nyckel) från instrumentpanelen
För en mer detaljerad guide om förutsättningarna, kolla in den här [sektionen](/developer-resources/integration-guide#dashboard-setup).
## API-integration
### Utcheckningssessioner
Använd Checkout Sessions för att sälja prenumerationsprodukter via en säker, värdhanterad kassa. Skicka din prenumerationsprodukt i `product_cart` och omdirigera kunderna till den returnerade `checkout_url`.
**Mixed Checkout**: Du kan kombinera prenumerationsprodukter med engångsprodukter i samma kassasession. Detta möjliggör användningsfall som installationsavgifter tillsammans med prenumerationer, hårdvarupaket med SaaS och mer. Se [Checkout Sessions guide](/developer-resources/checkout-session) för exempel.
```javascript theme={null}
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();
```
```python theme={null}
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)
```
```javascript theme={null}
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-svar
Följande är ett exempel på svaret:
```json theme={null}
{
"session_id": "cks_Gi6KGJ2zFJo9rq9Ukifwa",
"checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}
```
Omdirigera kunden till `checkout_url`.
### Webhooks
När du integrerar prenumerationer kommer du att få webhooks för att spåra prenumerationslivscykeln. Dessa webhooks hjälper dig att hantera prenumerationsstatusar och betalningsscenarier effektivt.
För att ställa in din webhook-slutpunkt, följ vår [Detaljerade integrationsguide](/developer-resources/integration-guide#implementing-webhooks).
#### Prenumerationseventtyper
Följande webhook-händelser spårar ändringar i prenumerationsstatus:
1. **`subscription.active`** - Prenumerationen aktiveras framgångsrikt.
2. **`subscription.updated`** - Prenumerationsobjektet uppdaterades (utlöses vid alla fältändringar).
3. **`subscription.on_hold`** - Prenumerationen sätts på paus på grund av misslyckad förnyelse.
4. **`subscription.failed`** - Skapandet av prenumerationen misslyckades under skapandet av mandatet.
5. **`subscription.renewed`** - Prenumerationen förnyas för nästa faktureringsperiod.
För pålitlig hantering av prenumerationslivscykeln rekommenderar vi att spåra dessa prenumerationsevent.
Använd `subscription.updated` för att få realtidsnotifikationer om alla prenumerationsändringar och hålla din applikationsstatus synkroniserad utan att poll:a API:et.
#### Betalningsscenarier
**Framgångsrik betalningsflöde**
När en betalning lyckas kommer du att få följande webhooks:
1. `subscription.active` - Anger prenumerationsaktivering
2. `payment.succeeded` - Bekräftar den initiala betalningen:
* För omedelbar fakturering (0 provdagar): Förvänta inom 2–10 minuter
* För provdagar: när de avslutas
3. `subscription.renewed` - Indikerar att betalning dragits och förnyelse sker för nästa cykel. (I princip, när betalning dras för prenumerationsprodukter får du `subscription.renewed` webhook tillsammans med `payment.succeeded`)
**Betalningsfelsscenarier**
1. Prenumerationsfel
* `subscription.failed` - Skapandet av prenumerationen misslyckades eftersom mandatet inte kunde skapas.
* `payment.failed` - Indikerar misslyckad betalning.
2. Prenumerationen pausas
* `subscription.on_hold` - Prenumerationen sätts på paus på grund av misslyckad förnyelsebetalning eller misslyckad avgift vid planändring.
* När en prenumeration pausas förnyas den inte automatiskt förrän betalningsmetoden uppdateras.
**Bästa praxis**: För att förenkla implementeringen rekommenderar vi att du främst spårar prenumerationsevenemang för att hantera prenumerationslivscykeln.
### Hantera prenumeration på paus
När en prenumeration går in i `on_hold`-tillståndet måste du uppdatera betalningsmetoden för att återaktivera den. Detta avsnitt förklarar när prenumerationer pausas och hur du hanterar dem.
#### När prenumerationer sätts på paus
En prenumeration sätts på paus när:
* **Förnyelsebetalning misslyckas**: Den automatiska förnyelseavgiften misslyckas på grund av otillräckliga medel, utgången kort eller bankavslag
* **Avgift vid planändring misslyckas**: En omedelbar avgift under planuppgradering/nedgradering misslyckas
* **Behörighet för betalningsmetod misslyckas**: Betalningsmetoden kan inte auktoriseras för återkommande avgifter
Prenumerationer i `on_hold`-tillstånd förnyas inte automatiskt. Du måste uppdatera betalningsmetoden för att återaktivera prenumerationen.
#### Återaktivera prenumerationer från paus
För att återaktivera en prenumeration från `on_hold`-tillståndet, använd Update Payment Method API. Detta gör automatiskt:
1. Skapar en avgift för återstående skuld
2. Skapar en faktura för avgiften
3. Bearbetar betalningen med den nya betalningsmetoden
4. Återaktiverar prenumerationen till `active`-tillstånd efter lyckad betalning
När du mottar en `subscription.on_hold`-webhook, uppdatera applikationens tillstånd och meddela kunden:
```javascript theme={null}
// 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 });
});
```
När kunden är redo att uppdatera sin betalningsmetod, anropa Update Payment Method API:
```javascript Node.js theme={null}
// 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
}
```
```python Python theme={null}
# 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
```
Du kan också använda ett befintligt betalningsmetod-ID om kunden har sparade betalningsmetoder:
```javascript theme={null}
await client.subscriptions.updatePaymentMethod(subscriptionId, {
type: 'existing',
payment_method_id: 'pm_abc123'
});
```
Efter att ha uppdaterat betalningsmetoden, övervaka dessa webhook-händelser:
1. **`payment.succeeded`** - Avgiften för återstående skuld lyckades
2. **`subscription.active`** - Prenumerationen har återaktiverats
```javascript theme={null}
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.'
});
}
```
### Exempel på prenumerationseventpayload
***
| Egenskap | Typ | Obligatorisk | Beskrivning |
| ------------- | ------ | ------------ | -------------------------------------------------------------------------------------------- |
| `business_id` | string | Ja | Det unika identifieraren för företaget |
| `timestamp` | string | Ja | Tidsstämpeln för när händelsen inträffade (inte nödvändigtvis samma som när den levererades) |
| `type` | string | Ja | Typen av händelse. Se [Event Types](#event-types) |
| `data` | object | Ja | Huvuddatafältet. Se [Data Object](#data-object) |
## Ändra prenumerationsplaner
Du kan uppgradera eller nedgradera en prenumerationsplan med hjälp av API-slutpunkten för att ändra plan. Detta gör att du kan modifiera prenumerationens produkt, kvantitet och hantera proration.
För detaljerad information om att ändra prenumerationsplaner, se vår Change Plan API-dokumentation.
### Prorationsalternativ
När du ändrar prenumerationsplaner har du två alternativ för att hantera den omedelbara avgiften:
#### 1. `prorated_immediately`
* Beräknar det pro rata-belopp som baseras på den återstående tiden i den nuvarande faktureringscykeln
* Debiterar kunden endast för skillnaden mellan den gamla och den nya planen
* Under en provperiod kommer detta omedelbart att byta användaren till den nya planen och debitera kunden direkt
#### 2. `full_immediately`
* Debiterar kunden hela prenumerationsbeloppet för den nya planen
* Ignorerar kvarvarande tid eller krediter från den tidigare planen
* Användbart när du vill återställa faktureringscykeln eller debitera hela beloppet oberoende av proration
#### 3. `difference_immediately`
* Vid uppgradering debiteras kunden omedelbart skillnaden mellan de två planbeloppen.
* Till exempel, om den nuvarande planen är 30 dollars och kunden uppgraderar till 80 dollars, debiteras 50 dollars direkt.
* Vid nedgradering läggs det oanvända beloppet från den aktuella planen till som intern kredit och appliceras automatiskt på framtida prenumerationsförnyelser.
* Till exempel, om den nuvarande planen är 50 dollars och kunden byter till en 20 dollars-plan, krediteras resterande 30 dollars och används för nästa faktureringscykel.
### Beteende
* När du anropar detta API initierar Dodo Payments omedelbart en avgift baserat på ditt valda proration-alternativ
* Om planändringen är en nedgradering och du använder `prorated_immediately`, beräknas krediter automatiskt och läggs till prenumerationens kreditbalans. Dessa krediter är specifika för den prenumerationen och används endast för att kvitta framtida återkommande betalningar för samma prenumeration
* Alternativet `full_immediately` kringgår kreditberäkningar och debiterar hela det nya planbeloppet
**Välj ditt proration-alternativ noggrant**: Använd `prorated_immediately` för rättvis fakturering som tar hänsyn till oanvänd tid, eller `full_immediately` när du vill debitera hela det nya planbeloppet oberoende av den nuvarande faktureringscykeln.
### Avgiftsbehandling
* Den omedelbara avgiften som initieras vid planändring slutförs vanligtvis inom mindre än 2 minuter
* Om denna omedelbara avgift misslyckas av någon anledning, sätts prenumerationen automatiskt på paus tills problemet är löst
## On-Demand Prenumerationer
On-demand-prenumerationer låter dig debitera kunder flexibelt, inte bara enligt ett fast schema. Denna funktion är tillgänglig för alla konton.
**För att skapa en on-demand prenumeration:**
För att skapa en on-demand-prenumeration, använd [POST /subscriptions](/api-reference/subscriptions/post-subscriptions) API-slutpunkt och inkludera fältet `on_demand` i din förfrågningskropp. Detta låter dig auktorisera en betalningsmetod utan omedelbar debitering eller ange ett anpassat startpris.
**För att ta betalt för en on-demand prenumeration:**
För efterföljande debiteringar, använd slutpunkten [POST /subscriptions/{subscription_id}/charge](/api-reference/subscriptions/create-charge) och ange beloppet som kunden ska debiteras för den transaktionen.
För en komplett, steg-för-steg-guide—including request/response-exempel, säkra retry-policyer och webhook-hantering—se On-Demand Subscriptions Guide.
## Relaterad API-referens
API-referens för att skapa prenumerationsprodukter och hantera prenumerationslivscykel
API-referens för uppgradering, nedgradering eller ändring av prenumerationsplaner med proratering
API-referens för att uppdatera betalningsmetoder och återaktivera prenumerationer på väntelista
API-referens för att uppdatera prenumerationsdetaljer och konfiguration
**För att debitera en on-demand-prenumeration:**
För efterföljande debiteringar, använd slutpunkten [POST /subscriptions/{subscription_id}/charge](/api-reference/subscriptions/create-charge) och specificera beloppet som ska debiteras kunden för den transaktionen.
För en komplett, steg-för-steg-guide—inklusive exempel på begäran/svar, säkra återföringspolicyer och webhook-hantering—se Guiden för On-Demand-prenumerationer.
## Relaterad API-referens
API-referens för att skapa prenumerationsprodukter och hantera prenumerationens livscykel
API-referens för att uppgradera, nedgradera eller ändra prenumerationsplaner med prorateringsalternativ
API-referens för att uppdatera betalningsmetoder och återaktivera prenumerationer som är i vänteläge
API-referens för att uppdatera prenumerationsdetaljer och konfiguration