Subscription Renewal & Trial Expiry Sweep

The Subscription Renewal & Trial Expiry Sweep is an automated daily workflow (introduced in v1.0.35) that keeps subscription billing state accurate and initiates dunning for lapsed trials — without any manual intervention.

Schedule

The sweep runs once per day at 05:00 UTC (cron: 0 5 * * *).

What the Sweep Does

Each run performs two independent passes over the subscriptions entity:

Pass 1 — Upcoming Renewals (Active Subscriptions)

Condition: status = active AND currentPeriodEnd <= NOW() + 3 days

For each matching subscription the workflow:

1. Resolves the billing interval from the linked products record.
2. Advances currentPeriodStart and currentPeriodEnd by one billing interval.
3. Creates a new invoice draft in the invoices entity tied to the customer and subscription.

This gives billing infrastructure a 3-day lead time to attempt charge collection before the period lapses.

Pass 2 — Expired Trials (No Payment Method)

Condition: status = trialing AND currentPeriodEnd <= NOW() AND no payment method on file for the customer

For each matching subscription the workflow:

1. Transitions the subscription status from trialing → past_due.
2. Queues a dunning sequence via the dunningActions entity to prompt the customer to add a payment method.

Trialing subscriptions where a payment method is on file are handled by the renewal pass above once they convert to active.

Entities

Entity	Access	Purpose
subscriptions	Read / Write	Source of truth for status and period boundaries
customers	Read	Payment method presence check
products	Read	Billing interval for period advancement
invoices	Write	Invoice draft creation on renewal
dunningActions	Write	Dunning sequence initiation for lapsed trials

Status Transitions

trialing  ──(period expired, no payment method)──▶  past_due
                                                        │
                                                        └──▶ dunning sequence queued

active    ──(within 3 days of period end)──────────▶  period advanced
                                                        │
                                                        └──▶ invoice draft created

Operational Notes

• The workflow is idempotent within a single day — re-runs will not double-advance periods or create duplicate invoice drafts for the same subscription.
• Dunning sequence behaviour (email cadence, retry attempts, escalation) is configured separately in the dunningActions system.
• The 3-day renewal lookahead window (NOW() + 3 days) is fixed at the workflow level. Adjustments require a workflow configuration change.

Trigger Details

Property	Value
Type	Scheduled (cron)
Expression	0 5 * * *
Timezone	UTC
Category	Financial