Overview

The Billing Event represents various billing-related events including subscription events, payment events, and usage-based billing calculations. This event is published to the Billing Event Queue and consumed by the Billing Event Processor.

Payload

The payload follows the BillingEventPayloadDTO schema:

{
  "eventType": "string",
  "tenantId": "string",
  "timestamp": "ISO 8601 date-time",
  "data": {
    // Event-specific data
  }
}

Schema Definition

const BillingEventPayloadSchema = z.object({
  eventType: z.string(),
  tenantId: z.string(),
  timestamp: z.string().datetime(),
  data: z.record(z.unknown())
});

Event Types

Common billing event types include:

• subscription.created: New subscription created
• subscription.updated: Subscription plan or details updated
• subscription.cancelled: Subscription cancelled
• payment.succeeded: Payment successfully processed
• payment.failed: Payment processing failed
• usage.calculated: Usage-based billing calculated
• invoice.generated: Invoice generated for tenant

Example Payloads

Subscription Created

{
  "eventType": "subscription.created",
  "tenantId": "tenant-123",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "subscriptionId": "sub-456",
    "planId": "plan-premium",
    "customerId": "cus-789"
  }
}

Payment Succeeded

{
  "eventType": "payment.succeeded",
  "tenantId": "tenant-123",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "paymentId": "pay-456",
    "amount": 99.99,
    "currency": "USD",
    "invoiceId": "inv-789"
  }
}

Producing the Event

Billing events are published to the Billing Event Queue by:

1. Stripe Webhook Handlers: When processing Stripe webhooks
2. Subscription Service: When managing subscriptions
3. Usage Tracking Services: When calculating usage-based billing
4. Payment Processors: When processing payments

import { SQSClient } from './clients/sqs-client';

const sqsClient = new SQSClient();

await sqsClient.sendMessage({
  eventType: 'subscription.created',
  tenantId: 'tenant-123',
  timestamp: new Date().toISOString(),
  data: {
    subscriptionId: 'sub-456',
    planId: 'plan-premium'
  }
}, 'billing_event');

Consuming the Event

The event is consumed by the billingEventProcessor Lambda function:

export const handler = async (event: SQSEvent): Promise<SQSBatchResponse> => {
  return sqsBatchProcessor<BillingEventPayloadDTO>({
    schema: BillingEventPayloadSchema,
    processPayload: async (payload, appContext) => {
      const billingEventService = appContext.get(BillingEventService);
      await billingEventService.processEvent(payload);
    },
  })(event);
};