ARCH-303: Billing Service Event Publishing, Retries, And Idempotency

Date: 2025-11-01 Service: Billing Service Owner: Revenue Platform APIs: API-BILLING-01, API-BILLING-02, API-BILLING-03, API-BILLING-04 Related Services: Authentication Service, Checkout Service, Inventory Service, Notification Service

Context

This document defines event publishing, retries, and idempotency for the Billing Service in the Acme Commerce platform. The service participates in customer journeys that span Authentication Service, Checkout Service, Billing Service, Inventory Service, and Notification Service.

Design

The Billing Service owns the authoritative model for the payments domain. Synchronous API calls use the contracts API-BILLING-01, API-BILLING-02; asynchronous updates use API-BILLING-03. Internal worker coordination uses API-BILLING-04.

Requests must include a correlation identifier, tenant context, and caller identity. Write operations are idempotent and expose deterministic conflict responses so Checkout Service and Billing Service can retry safely. Read paths prefer bounded caching with explicit invalidation events.

Failure Modes

Recent incident references for this design include INC-2025-301, INC-2025-302. Architecture reviews require verifying timeout budgets, retry policies, circuit breakers, and audit logging for all cross-service calls.

Operational Requirements

• SLO target: 99.95 percent monthly availability.
• Dashboards must break down traffic by API reference and downstream dependency.
• Runbooks must explain degraded-mode behavior for Billing Service.
• Changes to these contracts require Jira approval and linked GitHub implementation work.