Billing Management Architecture

A billing management architecture built around scheduled events — using Recurrence Cloud as the schedule control plane for invoicing, dunning, rollups, and reconciliation.

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:

  1. Verify the HMAC signature. Reject anything unsigned or malformed — a billing endpoint that unauthenticated callers can hit is an incident waiting to happen.
  2. 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.
  3. 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).
  4. 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.
  5. 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.