Geconsolideerde abonnementsfacturatie

Eén verlengingsbestelling voor meerdere abonnementen

Heeft een klant meerdere actieve abonnementen die rond hetzelfde moment verlengen, dan kan Agovena ze samen factureren: één verlengingsbestelling met een regel per abonnement, één betaling en één factuur. Dit is gedrag van Core recurring billing. Het draait binnen php artisan agovena:process-subscription-renewals, dat de scheduler elke minuut start. Je hoeft niets te installeren.

De logica staat in SubscriptionService, ConsolidatedRenewalOrderBuilder en ConsolidatedBillingLine.

Welke abonnementen samengaan

Abonnementen worden gegroepeerd als ze al deze kenmerken delen:

• klant en e-mailadres van de klant;
• valuta;
• payment gateway;
• verlengingsmodus;
• factuurinterval en intervalaantal.

Binnen een groep komt een abonnement in aanmerking als het active of past_due is, niet op opzegging aan het einde van de periode staat, geen openstaande verlenging heeft en de volgende factuurdatum binnen het consolidatievenster valt. Een groep wordt alleen samen gefactureerd als ze minstens twee geschikte abonnementen heeft en er minstens één vervallen is.

Abonnementen die niet in aanmerking komen, verlengen zoals voorheen afzonderlijk. Groepen met handmatige verlenging en abonnementen die de provider zelf beheert, worden nooit samengevoegd. Verschillende valuta, gateways, intervallen of intervalaantallen blijven altijd in aparte bestellingen.

Consolidatievenster

Het venster bepaalt hoe ver vooruit een nog niet vervallen abonnement in de huidige bestelling mag worden opgenomen. Stel het in onder Admin → Instellingen → Winkel bij Venster voor gebundelde facturatie (dagen) (instelling subscription_consolidation_window_days), standaard 31. Het veld accepteert 1 tot en met 31 dagen, zodat een abonnement met een veel latere factuurdatum niet op de huidige factuur belandt.

Regels naar rato en een gedeelde periode

De vroegste vervaldatum in de groep wordt de vervaldatum van bestelling en factuur. Alle abonnementen in de bestelling krijgen een nieuwe periode die op die datum begint.

Een abonnement dat later verviel, is al betaald voor de dagen tussen de vroegste vervaldatum en zijn eigen vervaldatum. De regelprijs wordt met die dagen verlaagd:

te factureren eenheidsbedrag = eenheidsbedrag × (dagen in periode − al betaalde dagen) ÷ dagen in periode

De berekening gebruikt gehele minor units en rondt half naar boven af. Dekken de al betaalde dagen de hele periode, dan wordt het regeltotaal nul. Elke bestelregel bewaart zijn bron in options_snapshot.consolidated_billing: brontype en -ID, vervaldatum, einde van de volgende periode, dagen in de periode en al betaalde dagen.

Betaling, factuur en audit

De order builder maakt de bestelling, de regels, één openstaande betaling en de factuur aan in één databasetransactie. De factuur neemt de vervaldatum van de bestelling over. Daarna probeert Agovena de verlenging af te rekenen met de opgeslagen autorisatie van de gateway, net als bij een enkele verlenging. Zonder herbruikbare autorisatie blijft de bestelling betaalbaar en geldt de gewone afhandeling voor achterstallige betalingen.

Wordt de bestelling betaald, dan worden alle openstaande verlengingen van die bestelling in één transactie als betaald gemarkeerd en krijgt elk abonnement dezelfde gelijkgetrokken periode.

Elke run gebruikt een deterministische idempotency key, opgebouwd uit klant, valuta, gateway en elk abonnements-ID met zijn vervaldatum. Een gelijktijdige of herhaalde schedulerrun vindt daardoor de bestaande bestelling in plaats van een tweede aan te maken. De auditlog registreert billing.renewal_consolidated met bestelnummer, aantal bronnen, vervaldatum en totaalbedrag.

Controleer het resultaat

Open de verlengingsbestelling in Admin → Bestellingen. Controleer of elke regel bij een abonnement hoort, of de bedragen naar rato kloppen voor de betrokken datums en of de vervaldatum van de factuur gelijk is aan de vroegste vervaldatum. Lees bestellingen, betalingen en levering voor de rest van de bestelflow.