Billing systems are mostly scheduling systems with a database attached. Invoices run on cycle dates, usage rolls up every hour, dunning retries every N days, entitlements expire at midnight, and reconciliation compares ledgers nightly. Every one of those is a recurring job — which means the reliability of a billing stack is largely the reliability of its scheduler. This article walks a billing management architecture that treats recurring work as a first-class control plane, delivered via Recurrence Cloud.
Why billing is a scheduling problem
Look at where billing actually fails in production:
- Invoices fire late or never because a cron job silently died over the weekend
- Dunning retries stop after a deploy rotated the worker, and churn is discovered a quarter later
- Usage rollups drift because “hourly” jobs pile up behind each other with no run history
- Trial expirations land at the wrong hour because someone forgot the customer’s timezone
None of these are calculation bugs. They’re orchestration bugs. The conventional fix — building a scheduler into the billing service, with retries, run logs, and alerting — is undifferentiated infrastructure work.
The components
A billing management system decomposes into these concerns:
| Component | Responsibility | Cadence |
|---|---|---|
| Plan catalog | Prices, tiers, add-ons, entitlement rules | on change |
| Subscription registry | Lifecycle state: trial, active, past due, canceled | per customer event |
| Usage metering | Ingest raw usage events (API calls, seats, compute) | continuous |
| Rating & aggregation | Price the usage; roll up hourly/daily buckets | hourly / daily |
| Invoicing | Generate documents on cycle dates; apply credits/taxes | per billing anniversary |
| Payments & dunning | Charge; retry failed charges on a schedule | retry ladder (e.g. 1, 3, 7 days) |
| Ledger & rev rec | Append-only money records; recognize revenue over time | daily close |
| Notifications | Customer-facing reminders: renewal, card expiry, past due | per event + scheduled reminders |
| Reconciliation | Ledger vs. processor statements vs. invoiced totals | nightly |
Each row with a cadence is a recurring job. That’s the insight the architecture leans on.
Architecture
Recurrence Cloud acts as the schedule control plane: it owns when things fire, signs every delivery, and keeps a run history for audit. The billing service owns what happens.
┌──────────────────────────────────────┐
│ Recurrence Cloud │
│ schedules · events · run history │
└───────────────────┬──────────────────┘
│ signed webhook delivery
│ (HMAC-SHA256 x-webhook-signature)
▼
┌───────────────────────────────────────────────┐
│ Billing orchestrator │
│ verify signature → idempotency check → │
│ resolve scope → dispatch job → ack │
└──────┬──────────┬───────────┬──────────┬──────┘
▼ ▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────────┐
│ Invoice │ │ Usage │ │ Dunning │ │Notification/ │
│ engine │ │ rollup │ │ engine │ │reconciliation│
└────┬────┘ └────┬────┘ └────┬────┘ └──────┬───────┘
│ │ │ │
▼ ▼ ▼ ▼
┌──────────────────────────────────────────────────┐
│ Billing datastore (ledger, subs, │
│ usage, idempotency keys) │
└──────────────────────────────────────────────────┘
The delivery body carries enough context to route itself: schedule name, firedAt, and events grouped by subject (e.g. invoice_run, dunning_retry, usage_rollup).
One schedule per subscriber cohort, or per subscription?
Two viable placement strategies:
- Batch schedules — one schedule per cohort (“monthly invoices for org A’s customers, day 1, 00:00 Pacific”). The orchestrator fans out to all matching subscriptions. Fewer schedules, simpler to reason about.
- Per-subscription schedules — every subscription gets its own schedule pinned to its anniversary date and timezone. Max fidelity for anniversary billing and trial expiry; more schedules to manage.
The composite create endpoint makes per-subscription placement cheap — creating schedule + webhook + event data in one call:
POST /api/v1/schedules/with-webhook
{
"schedule": { "name": "inv-cust-1042", "frequency": "month", "byMonthDay": "14",
"startTime": "00:05", "timezone": "America/New_York" },
"webhook": { "url": "https://billing.example.com/hooks/jobs",
"secret": "<shared signing secret>" },
"event": { "subject": "invoice_run", "payload": { "customerId": "1042" } }
}
The webhook secret matters more here than in a typical integration: a signed delivery that can trigger invoicing or dunning is effectively money-moving authority, so verification isn’t optional.
The delivery handler is the trust boundary
Every scheduled webhook lands on one endpoint. The handler must be boring:
- Verify the HMAC signature. Reject anything unsigned or malformed — a billing endpoint that unauthenticated callers can hit is an incident waiting to happen.
- Dedupe on idempotency key. Schedule ID + fire timestamp gives you a natural key. Deliveries are at-least-once, not exactly-once; “generate invoice twice in a night” must be impossible.
- Resolve scope. Pull the customer/period referenced in the event payload and confirm it’s still billable (subscription active, not already invoiced, no hold flag).
- Dispatch as a durable job. Ack the webhook fast, then do the heavy work in your own queue. The webhook is a trigger, not the work unit.
- Record what happened. Your own job ledger plus Recurrence Cloud’s run history gives you two independent audit trails.
app.post('/hooks/jobs', async (req, res) => {
const signature = req.headers['x-webhook-signature'];
const payload = JSON.stringify(req.body);
const expected = crypto
.createHmac('sha256', BILLING_WEBHOOK_SECRET)
.update(payload)
.digest('hex');
if (signature !== expected) return res.status(401).end();
const idempotencyKey = `${req.body.scheduleId}:${req.body.firedAt}`;
const inserted = await jobs.insertIfAbsent(idempotencyKey, req.body);
if (!inserted) return res.status(200).end(); // duplicate delivery
await queue.enqueue(req.body.events.dunning_retry ?? req.body.events.invoice_run);
res.status(200).end();
});Reliability model
| Concern | Mechanism |
|---|---|
| Did it fire? | Schedule run history (GET /api/schedules/:id/runs) |
| Did the handler accept it? | Webhook activity trail with status codes and durations |
| Would it fire tomorrow? | Read-only dry-run via test-due before enabling a new cycle |
| Wrong cron? | Recurrence text + explicit timezone per schedule; no server-local time math |
| Pausing billing | Deactivate the app or individual schedules — incident switch |
| Lost trigger | The durable job in your queue is the unit of record; re-run idempotently |
The operational win: “did the nightly invoice run complete?” becomes a query, not a grep over box logs.
What stays out of the schedule control plane
Not everything in billing should be a scheduled webhook:
- Metering event ingestion — high-volume, real-time. That’s an event stream (Kafka/Kinesis) into the usage store, not a cron payload.
- Payment authorizations and gateway-side retries — the processor owns payment state; mirror it, don’t second-guess it. Your dunning schedule decides when to retry, the gateway decides whether the retry succeeded.
- Customer-initiated events (upgrade, cancel, card update) — synchronous handlers in the billing service.
Rule of thumb: if the trigger is time, it belongs in the schedule control plane. If the trigger is volume or user intent, it doesn’t.
Scaling characteristics
- Schedules are cheap control-plane rows — thousands of per-subscription schedules with individual anniversaries and timezones are fine, and cohort batching compresses it further when per-subscription fidelity isn’t needed.
- Throughput scaling lives in your queue and domain workers, not the scheduler. The webhook handler stays a fast, stateless accept-and-enqueue.
- The free tier (100 webhook deliveries/day) is enough to prove an architecture in dev; production billing volume needs a Pro/Enterprise plan — check the rate limits before committing.
Decision checklist
Choose this approach when most of these are true:
- Recurring billing jobs number in the dozens-to-thousands, not millions-per-second
- The billing service is HTTP-shaped (endpoints exist or are cheap to add)
- You need an audit-friendly record of when each job fired — finance and SOC 2 conversations both want this
- You’d otherwise be building and maintaining retry+logging inside a homegrown scheduler
Keep it in-process when the job shares tight transactional state with the metering stream, or when a single monolith with a library-level scheduler is genuinely sufficient. As with most architecture, start where the failures are painful.
Related
- Integrating scheduling with Recurrence Cloud — hands-on setup and signature verification
- Scheduling automated jobs without cron infrastructure — the general case
- Event-Driven Architecture — the async backbone underneath the orchestrator
- Recurrence Cloud docs — schedules, events, and deliveries