Automated Recurring Billing & Dunning
Daily billing cycle orchestration, automated renewal notices, trial expirations, and dunning engine.
Automated Recurring Billing & Dunning
SubsManager incorporates an automated recurring billing worker (processRecurringBilling) that evaluates subscription horizons, generates upcoming renewal invoices, warns customers before renewals, handles free trial expirations, and executes dunning procedures for delinquent accounts.
1. The Automated Billing Cycle Pipeline
The recurring billing engine runs in three decoupled phases:
[Recurring Billing Engine]
│
┌───────────────────────────────┼───────────────────────────────┐
▼ ▼ ▼
[Phase 1: Upcoming Renewals] [Phase 2: Renewals Due] [Phase 3: Trial Expirations]
• Subscriptions ending in • Subscriptions where • Trials ending in 3 days:
3 days endDate <= now sends trial ending warning
• Pre-generates invoice • Status -> past_due • Expired trials: transitions
• Sends upcoming renewal • Generates renewal invoice to past_due & generates
warning email with bank and dispatches overdue 1st billing invoice
details & invoice link dunning notice2. The 5 Transactional Email Notifications
SubsManager dispatches 5 distinct, responsive HTML email templates over secure SSL/TLS sockets (port 465):
| Template | Trigger Event | Key Email Contents |
|---|---|---|
| 1. Invoice & Banking Details Notice | Subscription created (EFT) or renewal due | Official invoice number, line items, bank name, account number, branch code, SWIFT, payment reference, and hosted invoice link. |
| 2. Upcoming Renewal Warning Notice | 3 days before subscription expiration | Advance warning that renewal is approaching, pre-generated invoice link, and bank transfer instructions. |
| 3. Free Trial Ending Warning Notice | 3 days before free trial ends | Notice that trial period is concluding, renewal pricing, and steps to retain service access. |
| 4. Payment Receipt / Subscription Activated | Invoice marked paid (EFT confirmed) | Official tax receipt, amount paid, payment reference, and new subscription expiration date. |
| 5. Overdue Dunning Reminder Notice | Subscription enters past_due | Urgent notice that payment is past due, banking details, and direct invoice link to settle. |
3. Triggering the Billing Cycle via API
You can trigger the billing cycle execution at any time by issuing an authenticated POST request to the billing trigger endpoint:
- Endpoint:
POST /billing/trigger-cycle - Authentication Options:
- Option A (Tenant Scope): Include your application's API key (
Authorization: Bearer ap_live_...). This evaluates only subscriptions belonging to your application. - Option B (Global Engine): Include the system
CRON_SECRET(Authorization: Bearer your_cron_secret). This processes all subscriptions across all tenants.
- Option A (Tenant Scope): Include your application's API key (
Request:
POST /api/v1/billing/trigger-cycle
Authorization: Bearer ap_live_your_api_keyResponse (200 OK):
{
"success": true,
"message": "Recurring billing process executed successfully",
"summary": {
"upcomingRenewalsWarned": 14,
"trialsEndingWarned": 5,
"trialsExpired": 2,
"subscriptionsDueProcessed": 8,
"overdueNoticesSent": 3,
"errors": []
}
}4. Scheduling Automated Billing with Cron
GitHub Actions Workflow Recipe
Create .github/workflows/billing-cron.yml in your repository:
name: Trigger SubsManager Recurring Billing
on:
schedule:
- cron: '0 0 * * *' # Executes daily at 00:00 UTC
workflow_dispatch:
jobs:
trigger-billing:
runs-on: ubuntu-latest
steps:
- name: Trigger Cycle
run: |
curl -s -X POST "https://subsmanager.vertueal.com/api/v1/billing/trigger-cycle" \
-H "Authorization: Bearer ${{ secrets.SUBSMANAGER_API_KEY }}" \
-H "Content-Type: application/json"