Shopify-abonnementen migreren: de audit die we eerst doen

Vorig kwartaal stapte een DTC-koffiemerk bij ons binnen. Ze betaalden $2.400 per maand aan Recharge. Hun abonneebestand telde 4.100 klanten. De eigenaar deed op een woensdag de rekensom, opende de documentatie van de native selling plans van Shopify en stuurde ons één regel: "hoe moeilijk kan dit zijn."

Het eerlijke antwoord: dat hangt volledig af van wat de audit aantreft. We hebben Shopify Plus-stores meegemaakt waar de migratie elf werkdagen kostte. We hebben ook stores meegemaakt waar we na twee weken auditwerk de merchant adviseerden nog een jaar op de externe app te blijven. De prijs van die keuze verkeerd inschatten loopt in zes cijfers aan verloren abonnees.

Dit is de checklist die we doorlopen voordat we het project aannemen.

De vijf vragen die de audit moet beantwoorden

Elke audit beantwoordt dezelfde vijf vragen. Sla er één over en de migratie laat het gat opduiken tijdens het cutover-weekend, als de customer-success inbox toch al in lichterlaaie staat.

1. Is elk actief abonnement te reconstrueren binnen het datamodel van Shopify?
2. Overleeft elke actieve betaalmethode de overstap?
3. Welke downstream-systemen breken er als de source-of-truth verschuift?
4. Welke klantgerichte features draaien op de oude app en hebben geen native tegenhanger?
5. Wat is het rollback-pad als de cutover faalt?

We werken ze stuk voor stuk af. De audit-deliverable is één document, meestal 12 tot 20 pagina's, dat elke vraag beantwoordt met bewijs uit de live store. Geen schattingen, geen "komt vast goed", geen mondelinge afspraken.

Abonnementscontracten en het selling-plan-datamodel

De selling plans API van Shopify is de bestemming. Die modelleert vier dingen: een selling plan group, een selling plan, een subscription contract en een billing attempt. Elk abonnement dat nu in Recharge, Bold, Skio of Loop staat, moet in die vorm passen.

Drie patronen breken die pasvorm, en we zoeken op dag één naar alle drie.

Het eerste is "swap any product". Sommige merchants laten een abonnee de doos van volgende maand vervangen door wat dan ook uit de catalogus. Het contract van Shopify hangt vast aan specifieke varianten. Je kunt de swap-flow opnieuw bouwen met custom code, maar dat is bouwen, geen migreren.

Het tweede is dynamische prijsstelling. Verandert de abonnementsprijs per cyclus op basis van de loyalty tier van de klant, de regio, of een coupon die ze negen maanden geleden inwisselden, dan leeft die logica in de database van de externe app. Selling plans ondersteunen vaste bedragen en vaste percentages korting, plus een prijswijziging na N cycli. Al het andere is custom.

Het derde is het prepaid plan. Een 12-maandse vooruitbetaling met maandelijkse fulfillment wordt native ondersteund, maar de boekhoudkundige verwerking van de onverdiende omzet leeft vaak in een finance-integratie die nog niet weet hoe ze Shopify subscription contracts moet lezen. We checken de GL-mapping voordat we een datum beloven.

# Run this against the destination store to confirm the model fits.
query sellingPlanGroupShape($id: ID!) {
  sellingPlanGroup(id: $id) {
    name
    appId
    sellingPlans(first: 50) {
      edges {
        node {
          name
          billingPolicy {
            ... on SellingPlanRecurringBillingPolicy {
              interval
              intervalCount
            }
          }
          pricingPolicies {
            ... on SellingPlanFixedPricingPolicy {
              adjustmentType
              adjustmentValue {
                ... on MoneyV2 { amount currencyCode }
              }
            }
          }
        }
      }
    }
  }
}

De vraag van de payment vault

Dit is de vraag die migraties om zeep helpt.

Gebruikt de bestaande app Shopify Payments als gateway, dan staan de opgeslagen betaalmethoden al in de vault van Shopify. De migratie verplaatst de contract-pointer, de kaart blijft staan. Schoon.

Gebruikt de bestaande app Stripe direct onder zijn eigen platform-account, dan staan de kaarten in een Stripe-vault die eigendom is van de app-leverancier, niet van de merchant. Die kaarten verplaatsen vereist een PCI-DSS Level 1 vault-to-vault transfer tussen Stripe-accounts, opgestart door het compliance-team van het bronplatform. We hebben dit gedaan. Het kost vier tot zes weken papierwerk, de bronleverancier moet akkoord gaan, en op het eind moet elke klant in de EU bij de volgende billing attempt alsnog een verse SCA-challenge doorlopen.

Weigert de leverancier de transfer, dan heeft de merchant twee opties: betaalmethoden opnieuw verzamelen via een e-mailcampagne en de churn accepteren, of bij de leverancier blijven. We hebben de e-mailcampagne-route tussen de 62% en 89% van de abonnees zien terughalen, afhankelijk van hoe de merchant het bracht. Reken op het verlies, beslis daarna.

Payment-rail migraties gaan over contracten en vault-custody, niet over welke provider het mooiste dashboard heeft. De merchant die deze vraag overslaat, betaalt de rekening op cutover-zaterdag.

Webhook-oppervlak en de downstream-systemen

Open de Shopify admin, ga naar Instellingen, Notificaties, Webhooks, en noteer elke URL die subscription_contracts/*, subscription_billing_attempts/* of orders/* events ontvangt van de externe app. Vraag dan aan de merchant: welke hiervan ken je? In onze ervaring is het antwoord ruwweg de helft.

De andere helft bestaat uit Klaviyo flows, de order-routing webhook van het magazijn, een finance Zap die post naar QuickBooks, een churn-prediction model dat iemand twee jaar geleden bouwde en weer vergat, en een Slack-notifier die de oprichter waarschuwt als een high-LTV klant een levering overslaat. Elk hiervan luistert naar een specifieke event-vorm van de bronapp. De native subscription webhooks van Shopify hebben die vorm niet.

De webhook-payload van de externe app bevat vaak afgeleide velden, next charge date, churn risk score, lifetime value, die de native webhook van Shopify niet uitstuurt. Elke consumer van die velden heeft een rewrite of een vertaallaag nodig vóór cutover.

We catalogiseren elke consumer, classificeren als "in beheer bij ons / in beheer bij een ander team / in beheer bij niemand", en taggen wat herschreven moet worden. De stapel "in beheer bij niemand" is waar de branden na launch vandaan komen. We hebben gezien hoe één vergeten Zap, geschreven door een freelancer in 2022, de boekhoudkundige reconciliatie van een merchant twee weken platlegde na een cutover.

Het storefront-oppervlak

Twee specifieke plekken om te inspecteren.

De product detail page. De externe app injecteert een widget die de subscribe-and-save toggle, de cadence selector en eventuele "first order discount"-tekst rendert. Die widget is meestal gebouwd met de SDK van de app en een script tag. Na migratie moet die opnieuw gebouwd worden met het native subscription block van Shopify of met een custom UI extension. Het Liquid template eromheen verwijst naar variabelen die niet meer bestaan. Elke theme section die een abonnementsbadge, een besparingsregel of een cadence selector toont, komt met screenshot op de audit-lijst.

De customer account page. Dat is het zwaardere werk. Klanten beheren hun abonnement, skip, swap, cadence wijzigen, kaart updaten, binnen het hosted portal van de app. De nieuwe customer accounts van Shopify hebben native subscription management, maar dat dekt de basis. Elke merchant-specifieke feature, een "schenk deze doos aan een vriend"-knop, een "pauze voor de zomer"-flow, een referral credit die bij de volgende renewal wordt verrekend, moet opnieuw gebouwd worden als customer account UI extension of als custom app embed.

De audit lijst elk klantgericht oppervlak op dat de externe app raakt, met screenshot per stuk. De merchant tekent af op de visuele diff voordat wij offreren.

Het rollback-plan

De cutover is geen enkele transactie. Het is een reeks: nieuwe sign-ups op de oude app pauzeren, contracten exporteren, contracten naar Shopify importeren, webhooks omleiden, de billing queue van de oude app legen voor de mislukte retries van die dag, de storefront widget omzetten. Elke stap heeft een rollback.

De audit definieert, op papier, wat een rollback triggert en wie de bevoegdheid heeft om die te roepen. "Mislukte billing attempts overstijgen 4% van het verwachte dagvolume gedurende twee opeenvolgende cycli" is een trigger. "De oprichter voelt zich nerveus op zaterdagochtend" is dat niet. Hoe scherper dit document, hoe rustiger het weekend.

Een opmerking over timing

Start de audit niet in hetzelfde kwartaal als het piekseizoen van de merchant. We hebben dat één keer gedaan en doen het niet nog eens. De audit vraagt interviews met de operations lead, de finance lead en degene die het e-mailprogramma beheert, en tijdens een Q4 zijn die alle drie onbereikbaar. Draai de audit in januari of februari voor een lente-cutover, of in juni voor een najaars-cutover. De agenda is de goedkoopste variabele om te sturen. Gebruik 'm.

Wat je vandaag kunt doen

Draai je een Plus-store op een externe subscription app en denk je aan de overstap, open dan één document en beantwoord dit: lijst elke klantgerichte feature op die de externe app levert, met de URL van de pagina waar die verschijnt. Kost die lijst je meer dan vijftien minuten, dan is de migratie geen project van twee weken, en is de audit het waard voordat iemand een statement of work tekent.

Toen we deze audit afgelopen voorjaar draaiden voor een Plus-merchant in Rotterdam, was wat we niet zagen aankomen dat de "swap any product"-feature door 0,4% van de abonnees werd gebruikt en tóch de grootste blocker bleek. We losten het op door een custom subscription portal te bouwen bovenop de native API en de swap-flow uit te leveren als een eenmalige account extension. Wil je dat type maatwerkontwikkeling dat de gaten dicht die de native API van Shopify nog niet dekt, dan is dat het werk dat wij doen.