Services and responsibilities

Auth / Identity (Keycloak)

Responsibility: canonical customer profile (name, emails, billing address, company, contact info), payment-customer mapping (e.g., providerCustomerId), invoice delivery preferences, links to internal user records.
Data owned: customer table (customer_id, keycloak_id, contact info, provider customer id, metadata).
API examples: GET/PUT customer, attach payment method token, list customer’s subscriptions/orders.
When to call: read-heavy for CRM and billing, write when profile changes.

Responsibility: define and manage plans, price points, features, trial configuration, promotions/coupons, entitlements (features JSON).
Data owned: plans, SKUs, pricing tiers, feature flags, metadata.
Notes: Admin interfaces to create/retire plans; this is authoritative for what users can buy.

Responsibility: orchestrate purchase flows and create “orders” as transient/immutable records that represent a purchase attempt. Validate requested plan, pricing, coupons, compute totals and taxes, create provider checkout session or payment intent.
Data owned: orders (order_id, customer_id, plan_id, price_at_purchase, status: created/processing/succeeded/failed/expired, idempotency key).
Notes: Produces events (OrderCreated, OrderSucceeded, OrderFailed) consumed by Billing/Subscription and Customer services. Should be idempotent (use idempotency key).

Responsibility: map orders into subscriptions, maintain subscription lifecycle (trialing, active, past_due, canceled), reconcile provider subscription state with local state, schedule renewals and billing windows, track current_period_start/end, cancel_at_period_end flags.
Data owned: subscriptions table, subscription status history, subscription invoices (link to invoices table).
Notes: Acts on provider webhooks and Order events to create/update local subscription rows.

Responsibility: encapsulate provider SDKs (Stripe, Paddle, etc.), create customers, payment methods, checkout sessions, subscriptions, invoices; normalize webhook payloads and verify signatures.
Data owned: none (keeps provider ids for mapping).
Notes: Keep this pluggable; return normalized result objects and propagate provider ids back to Order/Billing/Customer services.

Responsibility: store invoices and payments, record payment attempts, refunds, reconciliation with provider invoices, retention of raw payloads for audits.
Data owned: invoices, payments, receipts.
Notes: Expose APIs to query invoices and download receipts.

Responsibility: record per-feature usage (tokens, API calls), aggregate usage for billing periods, report usage to provider or generate usage-based invoices.
Data owned: usage_records, aggregates.
Notes: Support batching and idempotency (external_id) to avoid double-counting.