Billing Service — Event Schemas

Status: populated Owner: Platform Engineering + Finance Last updated: 2026-04-18

1. Consumed

Subject	Stream	Producer	Consumer group	Retention
billing.events	BILLING_EVENTS	dlr-processor	billing-consumer (durable)	WorkQueue, 48h

billing.message.charged.v1

interface BillingMessageCharged {
  schemaVersion: '1';
  messageId: string;            // UUIDv4 — dedup key
  tenantId: string;
  accountId: string;
  accountTier: string;          // e.g. 'GROWTH'
  operatorId: string;
  direction: 'MT';
  segmentCount: number;
  currency: string;             // ISO 4217
  chargedAt: string;            // ISO 8601 UTC
  dlrStatus: string;            // e.g. 'DELIVERED'
}

NATS headers: Nats-Msg-Id = messageId (for JetStream dedup), traceparent, X-Tenant-Id.

2. Produced

Subject	Stream	Consumer(s)	Retention
billing.invoice.generated	BILLING_EVENTS	notification-service, customer-portal, analytics-service	Limits, 7d

billing.invoice.generated.v1

interface BillingInvoiceGenerated {
  schemaVersion: '1';
  invoiceId: string;            // UUIDv4
  tenantId: string;
  accountId: string;
  periodStart: string;          // ISO date 'YYYY-MM-DD'
  periodEnd: string;
  totalMessages: number;
  totalSegments: number;
  subtotalAmount: string;       // decimal string e.g. '9000.00'
  currency: string;
  s3Key: string;
  generatedAt: string;          // ISO 8601 UTC
}

NATS headers: Nats-Msg-Id = invoiceId, traceparent, X-Tenant-Id.

3. Retention Classes

Class	Subject	Rationale
Regulated	billing.events	Revenue-critical; 48h WorkQueue (ACK on success, NAK on transient failure)
Operational	billing.invoice.generated	Downstream notification trigger; 7d Limits

4. PII Policy

• billing.events contains accountId, tenantId, operatorId — no MSISDN or body.
• billing.invoice.generated contains account identifiers and monetary amounts — no PII.
• Both subjects are safe for downstream consumption without scrubbing.

5. Schema Evolution

• Minor additions (new optional field): backward-compatible; consumers ignore unknown fields.
• Breaking changes: increment schemaVersion; dual-publish during migration window.
• Schema registered in platform schema registry; CI validates on PR.