API-referens för ändring av plan
Förhandsgranska API för planändring
Guide för prenumerationsintegration
Vad är en uppgradering eller nedgradering av prenumeration?
Att ändra planer låter dig flytta en kund mellan prenumerationsnivåer eller kvantiteter. Använd det för att:- Justera prissättning med användning eller funktioner
- Flytta från månadsvis till årlig (eller vice versa)
- Justera kvantitet för produktbaserade platser
När ska man använda planändringar
- Uppgradera när en kund behöver fler funktioner, användning eller platser
- Nedgradera när användningen minskar
- Migrera användare till en ny produkt eller pris utan att avbryta deras prenumeration
Förutsättningar
Innan du implementerar ändringar av prenumerationsplaner, se till att du har:- Ett Dodo Payments-handelskonto med aktiva prenumerationsprodukter
- API-referenser (API-nyckel och webhook-hemlig nyckel) från instrumentpanelen
- En befintlig aktiv prenumeration att modifiera
- Webhook-slutpunkt konfigurerad för att hantera prenumerationsevenemang
Steg-för-steg-implementeringsguide
Följ denna omfattande guide för att implementera ändringar av prenumerationsplaner i din applikation:Förstå kraven för planändring
- Vilka prenumerationsprodukter som kan ändras till vilka andra
- Vilken proration som passar din affärsmodell
- Hur man hanterar misslyckade planändringar på ett smidigt sätt
- Vilka webhook-händelser som ska spåras för tillståndshantering
Välj din prorationstrategi
- prorated_immediately
- difference_immediately
- full_immediately
- Beräknar exakt proraterat belopp baserat på återstående cykeltid
- Debiterar ett proraterat belopp baserat på oanvänd tid som återstår i cykeln
- Ger transparent fakturering till kunder
Implementera Change Plan API
prorated_immediately, full_immediately, eller difference_immediately.Hantera webhook-händelser
subscription.active: Planändring lyckades, prenumeration uppdateradsubscription.plan_changed: Prenumerationsplan ändrad (uppgradering/nedgradering/tilläggsuppdatering)subscription.on_hold: Planändringsdebitering misslyckades, prenumeration pausadpayment.succeeded: Omedelbar debitering för planändring lyckadespayment.failed: Omedelbar debitering misslyckades
Uppdatera din applikationstillstånd
- Ge/tillbaka funktioner baserat på ny plan
- Uppdatera kundens instrumentpanel med nya plandetaljer
- Skicka bekräftelsemejl om planändringar
- Logga faktureringsändringar för revisionsändamål
Testa och övervaka
- Testa alla prorationlägen med olika scenarier
- Verifiera att webhook-hanteringen fungerar korrekt
- Övervaka framgångsrater för planändringar
- Ställ in aviseringar för misslyckade planändringar
Förhandsgranska planändringar
Innan du bekräftar en planändring, använd Förhandsgranska API för att visa kunder exakt vad de kommer att debiteras:- Node.js SDK
- Python SDK
Change Plan API
Använd Change Plan API för att modifiera produkt, kvantitet och prorationbeteende för en aktiv prenumeration.Snabbstartsexempel
- Node.js SDK
- Python SDK
- Go SDK
- HTTP
invoice_id och payment_id returneras endast när en omedelbar debitering och/eller faktura skapas under planändringen. Lita alltid på webhook-händelser (t.ex. payment.succeeded, subscription.plan_changed) för att bekräfta resultat.Hantera tillägg
När du ändrar prenumerationsplaner kan du också modifiera tillägg:Prorationslägen
Välj hur du ska fakturera kunden när du ändrar planer:prorated_immediately
- Debiterar för den delvisa skillnaden i den aktuella cykeln
- Om i provperiod, debiterar omedelbart och byter till den nya planen nu
- Nedgradering: kan generera en proraterad kredit som tillämpas på framtida förnyelser
full_immediately
- Debiterar hela beloppet för den nya planen omedelbart
- Ignorerar återstående tid från den gamla planen
difference_immediately är prenumerationsspecifika och åtskilda från Kundkrediter. De tillämpas automatiskt på framtida förnyelser av samma prenumeration och är inte överförbara mellan prenumerationer.difference_immediately
- Uppgradering: debiterar omedelbart prisskillnaden mellan gamla och nya planer
- Nedgradering: lägger till återstående värde som intern kredit till prenumerationen och tillämpar automatiskt vid förnyelser
Exempel på scenarier
Uppgradering: Basic ($30) → Pro ($80) med difference_immediately
Uppgradering: Basic ($30) → Pro ($80) med difference_immediately
Nedgradering: Plus ($50) → Starter ($20) med difference_immediately
Nedgradering: Plus ($50) → Starter ($20) med difference_immediately
Uppgradering mitt i cykeln med prorated_immediately
Uppgradering mitt i cykeln med prorated_immediately
Återställ fakturering med full_immediately
Återställ fakturering med full_immediately
Hantera webhooks
Spåra prenumerationstillstånd genom webhooks för att bekräfta planändringar och betalningar.Händelsetyper att hantera
subscription.active: prenumeration aktiveradsubscription.plan_changed: prenumerationsplan ändrad (uppgradering/nedgradering/tilläggsändringar)subscription.on_hold: debitering misslyckades, prenumeration pausadsubscription.renewed: förnyelse lyckadespayment.succeeded: betalning för planändring eller förnyelse lyckadespayment.failed: betalning misslyckades
Verifiera signaturer och hantera avsikter
- Next.js Route Handler
- Express.js
Bästa praxis
Följ dessa rekommendationer för tillförlitliga ändringar av prenumerationsplaner:Strategi för planändring
- Testa noggrant: Testa alltid planändringar i testläge innan produktion
- Välj proration noggrant: Välj prorationläget som stämmer överens med din affärsmodell
- Hantera misslyckanden smidigt: Implementera korrekt felhantering och återföringslogik
- Övervaka framgångsrater: Spåra framgångs-/misslyckandefrekvenser för planändringar och undersök problem
Implementering av webhook
- Verifiera signaturer: Verifiera alltid webhook-signaturer för att säkerställa äkthet
- Implementera idempotens: Hantera dubblettwebhook-händelser smidigt
- Bearbeta asynkront: Blockera inte webhook-svar med tunga operationer
- Logga allt: Upprätthåll detaljerade loggar för felsökning och revisionsändamål
Användarupplevelse
- Kommunicera tydligt: Informera kunder om faktureringsändringar och tidpunkter
- Ge bekräftelser: Skicka e-postbekräftelser för lyckade planändringar
- Hantera kantfall: Tänk på provperioder, prorationer och misslyckade betalningar
- Uppdatera UI omedelbart: Återspegla planändringar i din applikationsgränssnitt
Vanliga problem och lösningar
Lös typiska problem som uppstår vid ändringar av prenumerationsplaner:Debitering skapad men prenumeration inte uppdaterad
Debitering skapad men prenumeration inte uppdaterad
- Webhook-bearbetning misslyckades eller fördröjdes
- Applikationstillståndet uppdaterades inte efter att ha mottagit webhooks
- Databastransaktionsproblem under tillståndsuppdatering
- Implementera robust webhook-hantering med återföringslogik
- Använd idempotenta operationer för tillståndsuppdateringar
- Lägg till övervakning för att upptäcka och varna om missade webhook-händelser
- Verifiera att webhook-slutpunkten är tillgänglig och svarar korrekt
Krediter tillämpas inte efter nedgradering
Krediter tillämpas inte efter nedgradering
- Förväntningar på prorationläge: nedgraderingar krediterar hela planprisskillnaden med
difference_immediately, medanprorated_immediatelyskapar en proraterad kredit baserat på återstående tid i cykeln - Krediter är prenumerationsspecifika och överförs inte mellan prenumerationer
- Kreditbalansen är inte synlig i kundens instrumentpanel
- Använd
difference_immediatelyför nedgraderingar när du vill ha automatiska krediter - Förklara för kunderna att krediter tillämpas på framtida förnyelser av samma prenumeration
- Implementera kundportal för att visa kreditbalanser
- Kontrollera nästa fakturaprevia för att se tillämpade krediter
Webhook-signaturverifiering misslyckas
Webhook-signaturverifiering misslyckas
- Felaktig webhook-hemlig nyckel
- Rå begärningskropp modifierad före signaturverifiering
- Fel signaturverifieringsalgoritm
- Verifiera att du använder den korrekta
DODO_WEBHOOK_SECRETfrån instrumentpanelen - Läs den råa begärningskroppen innan någon JSON-parsing-mellanprogram
- Använd det standardiserade webhook-verifieringsbiblioteket för din plattform
- Testa webhook-signaturverifiering i utvecklingsmiljö
Planändring misslyckas med 422-fel
Planändring misslyckas med 422-fel
- Ogiltigt prenumerations-ID eller produkt-ID
- Prenumerationen är inte i aktivt tillstånd
- Saknas obligatoriska parametrar
- Produkten är inte tillgänglig för planändringar
- Verifiera att prenumerationen finns och är aktiv
- Kontrollera att produkt-ID:t är giltigt och tillgängligt
- Se till att alla obligatoriska parametrar tillhandahålls
- Granska API-dokumentationen för parameterkrav
Omedelbar debitering misslyckas under planändring
Omedelbar debitering misslyckas under planändring
- Otillräckliga medel på kundens betalningsmetod
- Betalningsmetoden har gått ut eller är ogiltig
- Banken avslog transaktionen
- Bedrägeridetektering blockerade debiteringen
- Hantera
payment.failedwebhook-händelser på lämpligt sätt - Meddela kunden att uppdatera betalningsmetoden
- Implementera återföringslogik för tillfälliga misslyckanden
- Överväg att tillåta planändringar med misslyckade omedelbara debiteringar
Prenumeration på paus efter planändring
Prenumeration på paus efter planändring
on_hold tillståndVad händer:
När en planändringsdebitering misslyckas placeras prenumerationen automatiskt i on_hold tillstånd. Prenumerationen kommer inte att förnyas automatiskt förrän betalningsmetoden uppdateras.Lösning: Uppdatera betalningsmetoden för att återaktivera prenumerationenFör att återaktivera en prenumeration från on_hold tillstånd efter en misslyckad planändring:- Uppdatera betalningsmetoden med hjälp av Update Payment Method API
- Automatisk debiteringsskapelse: API:t skapar automatiskt en debitering för utestående belopp
- Fakturagenerering: En faktura genereras för debiteringen
- Betalningsbearbetning: Betalningen behandlas med den nya betalningsmetoden
- Återaktivering: Vid lyckad betalning återaktiveras prenumerationen till
activetillstånd
subscription.on_hold: Prenumeration placerad på paus (mottagen när planändringsdebiteringen misslyckas)payment.succeeded: Betalning för utestående belopp lyckades (efter att betalningsmetoden uppdaterats)subscription.active: Prenumeration återaktiverad efter lyckad betalning
- Meddela kunder omedelbart när en planändringsdebitering misslyckas
- Ge tydliga instruktioner om hur de ska uppdatera sin betalningsmetod
- Övervaka webhook-händelser för att spåra återaktiveringsstatus
- Överväg att implementera automatisk återföringslogik för tillfälliga betalningsmisslyckanden
API-referens för uppdatering av betalningsmetod
Testa din implementation
Följ dessa steg för att noggrant testa din implementation av ändringar av prenumerationsplaner:Ställ in testmiljö
- Använd test-API-nycklar och testprodukter
- Skapa testprenumerationer med olika planformer
- Konfigurera test-webhook-slutpunkt
- Ställ in övervakning och loggning
Testa olika prorationlägen
- Testa
prorated_immediatelymed olika faktureringscykelpositioner - Testa
difference_immediatelyför uppgraderingar och nedgraderingar - Testa
full_immediatelyför att återställa faktureringscykler - Verifiera att kreditberäkningarna är korrekta
Testa webhook-hantering
- Verifiera att alla relevanta webhook-händelser mottas
- Testa webhook-signaturverifiering
- Hantera dubblettwebhook-händelser smidigt
- Testa scenarier för misslyckande av webhook-bearbetning
Testa fel-scenarier
- Testa med ogiltiga prenumerations-ID:n
- Testa med utgångna betalningsmetoder
- Testa nätverksfel och tidsgränser
- Testa med otillräckliga medel
Övervaka i produktion
- Ställ in aviseringar för misslyckade planändringar
- Övervaka webhook-bearbetningstider
- Spåra framgångsrater för planändringar
- Granska kundsupportärenden för problem med planändringar
Felhantering
Hantera vanliga API-fel smidigt i din implementation:HTTP-statuskoder
200 OK
200 OK
400 Bad Request
400 Bad Request
401 Unauthorized
401 Unauthorized
404 Not Found
404 Not Found
422 Unprocessable Entity
422 Unprocessable Entity
500 Internal Server Error
500 Internal Server Error
Felresponsformat
Nästa steg
- Granska Change Plan API
- Utforska Kundkrediter
- Implementera aviseringar för
subscription.on_hold - Kolla in vår Webhook-integrationsguide