Subscription Management Integration
TrustWeave SaaS × Accountly × Kill Bill

Replace TrustWeave SaaS's direct Stripe billing with Accountly + Kill Bill as the single system of record for subscriptions and metered usage. TrustWeave integrates as a remote API client and a merchant ("Application owner") in Accountly: it declares its plan tiers into Accountly's catalog, provisions each Organization as an Accountly subscriber, meters billable activity, and enforces plan limits locally against a cached entitlement snapshot kept in sync via webhooks.

Settled decisions (from brainstorming)

1.Context & current state

TrustWeave SaaS (trustweave-saas, Spring Boot + React) is multi-tenant via Organization with OrganizationTier { FREE, PRO, ENTERPRISE }. It currently bills directly through Stripe: StripeService, SubscriptionService (Stripe-coupled Subscription entity), and TransactionCostBillingService (blockchain transaction costs → Stripe invoice items). These are the components this integration retires.

Accountly (accountly, Next.js frontend + Kotlin/Spring backend on :9393, Kill Bill on :8080) is already a multi-tenant metered-billing platform. Its model: an owner (merchant) registers Applications; each Application has Plans (FlatRate/PerUsage) with plan_quotas mapped to Kill Bill products; subscribers get Subscriptions carrying killbill_bundle_id/killbill_subscription_id; usage events are ingested idempotently → rollups → daily analytics → entitlement snapshots. Kill Bill performs invoicing; an inbound webhook feeds Kill Bill state back into Accountly.

2.Architecture & component map

TrustWeave SaaS (Spring)                       Accountly API (Spring)              Kill Bill
─────────────────────────                      ──────────────────────              ─────────
Organization                                   Owner: "TrustWeave SaaS" (service)
  ├ tier (local cache)        ┌─ AccountlyBillingClient ─►  Application
  ├ accountlySubscriberId     │   (service JWT, retry)      ├ Plans tw-free/pro/ent ──►  KB catalog
  ├ killbillAccountId         │                             │   └ plan_quotas            (products,
  └ entitlementSnapshot ◄──┐  ├─ CatalogReconciler ───────►  create/update plans         prices,
                           │  │                              usage-vars, KB mapping       usage units)
 issue / verify / anchor   │  ├─ UsageReporter (outbox) ──►  POST usage-events ──► rollups ──► KB usage
   │                       │  │                                                        │
   ▼                       │  ├─ OrganizationBillingSvc ──►  merchant subscribe/    ──►  KB bundle +
 EntitlementGate (local) ──┘  │                              change/cancel               subscription
   │                          └─ BillingProxyController ◄──  GET plans / snapshot
   ▼   (frontend)                  ▲
 React widgets:                    │
   PricingPlans · CurrentPlanCard · UsageMeter
                                   │
 AccountlyWebhookController ◄────── MerchantWebhookDispatcher ◄── KB inbound webhook
   (HMAC verify → update tier + refresh snapshot)   (subscription.updated, payment_failed)

New in TrustWeave SaaS — package billing/accountly/ (replaces billing/ Stripe code)

Retired in TrustWeave SaaS

3.Identity, catalog & tier mapping

Metered event types

Each event type is declared once per Application as an Accountly usage variable and referenced by plan_quotas.event_type. blockchain.tx carries its native/USD cost in the event's properties JSON so Kill Bill can bill the passthrough amount.

4.Catalog-as-code & plan widgets

4.1 TrustWeave declares the catalog

Rather than seeding Accountly by hand, TrustWeave owns a declarative tier definition (config / Kotlin DSL). CatalogReconciler pushes it into Accountly through existing owner APIs, idempotently:

ensure Application "TrustWeave SaaS"            // POST /api/v1/applications (once)
for each tier in [FREE, PRO, ENTERPRISE]:
    ensure Plan (name, pricingModel, monthlyFee, level, isDefault)   // POST …/plans
    set Kill Bill mapping (product, plan, priceList)                 // PATCH …/killbill-mapping
    for each quota (eventType, hardLimit, period):                   // POST …/quotas
        ensure quota
ensure usage variables [credential.issued, credential.verified,      // POST …/usage-variables
                        blockchain.tx, wallet.seat]

4.2 Widgets render tiers from Accountly

Accountly is the single source of truth for plan presentation. GET …/applications/{appId}/plans returns PlanResponse with name, monthlyFee, level, isDefault, KB mapping, and the full quotas list — enough to render price + feature bullets. Two widget families, both served via the TrustWeave backend proxy (browser never calls Accountly):

5.Metering & entitlement enforcement (Approach A)

The core paths (issue / verify / anchor) must stay fast and resilient to Accountly being briefly unavailable, so enforcement is local against a cached entitlement snapshot; usage is reported asynchronously; authoritative state changes flow back via webhook.

Read path — gating

1. Billable action requested → EntitlementGate.check(org, eventType, qty) against the cached snapshot.
2. Allow (under limit) → proceed. Soft-warn (near limit) → proceed + surface upgrade nudge. Hard-block (over a hard limit on a non-overage tier) → reject with an "upgrade to continue" error.
3. Snapshot is refreshed on a TTL and on webhook events; an optional tunable forces a synchronous refresh when within N% of a hard limit to tighten the overshoot bound.

Write path — reporting

1. On a successful billable action, append a row to a durable usage_outbox (same DB tx as the business write — no lost/double events).
2. UsageReporter drains the outbox and calls POST …/applications/{appId}/usage-events with a stable idempotency key (org:eventType:businessId) and explicit subscriberAccountId; Accountly de-dupes replays.
3. Retry with backoff; mark rows sent/failed; expose a metric for outbox lag.

6.Lifecycle flows

A. Catalog reconciliation (startup / admin)

TrustWeave CatalogReconciler ──► Accountly (owner JWT)
  ensure Application → ensure Plans + quotas + KB mapping + usage variables  (idempotent)

B. Organization provisioning (lazy — on org creation or first billable use)

OrganizationBillingService.provision(org)
  → POST …/applications/{appId}/subscribers { externalRef: "trustweave:org:" }   (NEW endpoint)
       Accountly: create app_user + Kill Bill account → returns subscriberId, killbillAccountId
  → POST …/applications/{appId}/subscribers/{subscriberId}/subscriptions { plan: tw-free }  (NEW)
  → cache subscriberId, killbillAccountId, tier=FREE, initial entitlement snapshot on Organization

C. Billable action (e.g. issue credential)

issueCredential()
  → EntitlementGate.check(org, "credential.issued", 1)         // local, cached snapshot
  → [allowed] persist credential + append usage_outbox row     // single DB tx
  → UsageReporter → POST …/usage-events (idempotent)           // async
       Accountly → rollups → daily analytics → Kill Bill usage

D. Upgrade / downgrade / cancel (embedded proxy UX)

React → TrustWeave BillingProxyController → OrganizationBillingService.changePlan(org, tw-pro)
  → PATCH …/subscribers/{id}/subscriptions/{subId} { plan: tw-pro }   (NEW merchant-mediated)
       Accountly → Kill Bill change plan
  → MerchantWebhookDispatcher → TrustWeave AccountlyWebhookController  (authoritative confirm)
       → update OrganizationTier + refresh snapshot

E. Inbound state sync (payment failure, cancellation, KB-driven change)

Kill Bill → Accountly inbound webhook → MerchantWebhookDispatcher (HMAC)
  → TrustWeave AccountlyWebhookController
       subscription.updated  → set tier, refresh snapshot
       invoice.payment_failed → mark PAST_DUE, optionally restrict features

7.Changes — TrustWeave SaaS

8.Changes — Accountly

The integration relies mostly on existing Accountly APIs, plus this focused set of additions:

9.Changes — Kill Bill catalog

Provide the priced catalog that Accountly plans reference. Author a catalog.xml (versioned, e.g. in accountly or an ops repo) with:

• Products trustweave-free / trustweave-pro / trustweave-enterprise with recurring monthly prices.
• Usage units for credential.issued, credential.verified, blockchain.tx, wallet.seat with tiered/usage pricing (and overage where applicable).
• Price list DEFAULT (matches Accountly's default mapping).

Provisioning method (uploaded XML vs KB catalog API automation) and price authoring ownership are open questions — see §14.

10.Data model changes

TrustWeave — organizations

+ accountly_subscriber_id   text
+ killbill_account_id       text
+ entitlement_snapshot_json jsonb
+ snapshot_refreshed_at     timestamptz
  tier                      (kept — local feature-gate cache, synced from Accountly)

TrustWeave — subscriptions (refactor)

- stripe_subscription_id, stripe_customer_id
+ accountly_subscription_id text
+ killbill_subscription_id  text
+ killbill_bundle_id        text
+ plan_code                 text   // tw-free | tw-pro | tw-enterprise
  status                    enum   // ACTIVE | PAST_DUE | CANCELED | TRIALING

TrustWeave — usage_outbox (new)

id, organization_id, event_type, quantity, unit, occurred_at,
idempotency_key (unique), correlation_id, properties_json,
status (PENDING|SENT|FAILED), attempts, created_at, sent_at

Accountly — app_users

+ external_ref text  (unique per owner/application)   // "trustweave:org:"

11.API contracts

Accountly — existing, reused

POST   /api/v1/applications
POST   /api/v1/applications/{appId}/plans
POST   /api/v1/plans/{planId}/quotas
PATCH  /api/v1/plans/{planId}/killbill-mapping
POST   /api/v1/applications/{appId}/usage-variables
GET    /api/v1/applications/{appId}/plans               // drives PricingPlans widget
POST   /api/v1/applications/{appId}/usage-events        // idempotent usage ingest
GET    /api/v1/applications/{appId}/subscribers/{id}/entitlement

Accountly — new (merchant-mediated)

POST   /api/v1/applications/{appId}/subscribers
       { externalRef } → { subscriberId, killbillAccountId }
POST   /api/v1/applications/{appId}/subscribers/{subscriberId}/subscriptions
       { planId | planCode } → 201
PATCH  /api/v1/applications/{appId}/subscribers/{subscriberId}/subscriptions/{subId}
       { planId | planCode }            // upgrade/downgrade
DELETE /api/v1/applications/{appId}/subscribers/{subscriberId}/subscriptions/{subId}   // cancel

TrustWeave — frontend-facing proxy

GET    /billing/plans                 // sanitized Accountly plan list (public)
GET    /billing/me/subscription       // current plan + snapshot (in-app)
GET    /billing/me/usage              // per-quota used/remaining
POST   /billing/me/subscribe          { planCode }
POST   /billing/me/change-plan        { planCode }
POST   /billing/me/cancel
POST   /billing/webhooks/accountly    // inbound, HMAC-verified

12.Testing strategy

• TrustWeave unit: EntitlementGate (allow/warn/block boundaries), UsageReporter (idempotency, retry/backoff, outbox state machine), CatalogReconciler (idempotent create-vs-update), webhook HMAC verification.
• TrustWeave client contract: AccountlyBillingClient against a WireMock stub of Accountly's contract (success, 4xx, 5xx, replay).
• Accountly integration: reuse existing H2 + dev-JWT harness for the new merchant endpoints (provision subscriber, merchant subscribe, change/cancel, relaxed guard); external-ref provisioning; MerchantWebhookDispatcher emission + signature.
• End-to-end smoke: docker-compose (Kill Bill + Accountly + TrustWeave) — reconcile catalog → provision org → subscribe → issue credential → assert usage event lands in analytics and a Kill Bill invoice line appears.
• Migration test: a Stripe-era Subscription row maps to an Accountly subscription with correct tier (see §13).

13.Migration & rollout

Data migration: for each existing Organization, provision an Accountly subscriber and a subscription matching its current OrganizationTier; backfill mapping ids; reconcile any open TransactionCostAllocation balances before turning off the Stripe invoice path.

14.Risks & open questions