Subscription Service

The Subscription Service is the authority for subscription billing within the FloatMe platform. It owns the full subscription lifecycle — from activation and plan management through scheduled and event-driven collections, ACH payment processing, membership event handling, and pre-subscription notifications.

What This Service Owns

Domain Responsibility

Domain	Responsibility
Subscriptions	Subscription records and lifecycle — creation, activation, status transitions, upgrade, downgrade, reactivation, and ban
Collections	Automated scheduled and webhook-driven collection engine with retry logic, pause handling, ML-based collection decisions, and distributed locking
Memberships	Kinesis-driven membership lifecycle event processing — UPGRADE, DOWNGRADE, CANCEL, RETRACT, CLOSEACCOUNT, PAUSE, UNPAUSE, and related transitions
Notifications	Three-day pre-subscription notifier — daily scheduler queries upcoming subscribers and enqueues worker messages for Segment, Iterable, and push delivery
ACH Callbacks	Kinesis-driven ACH payment outcome processing — COMPLETED, RETURNED, REFUNDED, and CHARGED_BACK events from the payments stream mapped to billing status transitions
Administration	User bans from subscription eligibility, QA tooling for automated subscription creation, and admin notes via the Admin Service
Events	Billing activity events published to EventBridge and the `site-subscriptions` Kinesis stream via the kinesis-feeder Lambda for downstream consumer services

Subscriptions

Subscription records and lifecycle — creation, activation, status transitions, upgrade, downgrade, reactivation, and ban

Collections

Automated scheduled and webhook-driven collection engine with retry logic, pause handling, ML-based collection decisions, and distributed locking

Memberships

Kinesis-driven membership lifecycle event processing — UPGRADE, DOWNGRADE, CANCEL, RETRACT, CLOSEACCOUNT, PAUSE, UNPAUSE, and related transitions

Notifications

Three-day pre-subscription notifier — daily scheduler queries upcoming subscribers and enqueues worker messages for Segment, Iterable, and push delivery

ACH Callbacks

Kinesis-driven ACH payment outcome processing — COMPLETED, RETURNED, REFUNDED, and CHARGED_BACK events from the payments stream mapped to billing status transitions

Administration

User bans from subscription eligibility, QA tooling for automated subscription creation, and admin notes via the Admin Service

Events

Billing activity events published to EventBridge and the site-subscriptions Kinesis stream via the kinesis-feeder Lambda for downstream consumer services

Lambda Functions

Function Trigger Purpose

Function	Trigger	Purpose
`site-subscriptions-api`	API Gateway (IAM + JWT)	Primary REST API — subscription activation, reactivation, upgrade, downgrade, manual collection, billing history, billing details, active term, ban, and QA create
`site-subscriptions-memberships`	Kinesis (`site-user-service-users`)	Processes membership lifecycle events from the user service and drives subscription state transitions for upgrades, downgrades, cancellations, pauses, and account closures
`site-subscriptions-ach-handler`	Kinesis (`site-payments`)	Processes ACH payment callbacks for subscription debits; maps COMPLETED, RETURNED, REFUNDED, and CHARGED_BACK outcomes to billing status; emits notifications via Segment, Iterable, and AppsFlyer
`site-subscriptions-kinesis-feeder`	DynamoDB Stream (`billing-activity`)	Reads DynamoDB Stream change records from `billing-activity` and publishes them to the `site-subscriptions` Kinesis stream for downstream consumers
`site-subscriptions-batch-worker`	SQS (`site-subscription-service-batch-worker`, batch size 10)	Handles bulk subscription operations and data management tasks dispatched to the batch queue
`site-subscriptions-collections-job`	CloudWatch scheduled rules (Mon–Fri) + SQS paging queues	Queries DynamoDB for subscriptions due for collection and enqueues them to scheduled, retry, and pause collection queues; pages through results using SQS-backed pagination
`site-subscriptions-collections-worker`	SQS (`collections-scheduled`, `collections-retry`, `collections-pause`, max concurrency 50)	Attempts subscription collection via the payments service; applies ML-based collection decisions; advances billing status and re-enqueues on retry and pause outcomes
`site-subscriptions-webhook-worker`	SQS (`site-subscription-service-income-event-tap`) via EventBridge	Triggers opportunistic collection for subscriptions in a collectible state when an income transaction event exceeds the configured `ACH_INCOME_EVENT_THRESHOLD`
`site-subscriptions-webhook-balance-worker`	SQS (`site-subscription-service-balance-event-tap`) via EventBridge	Triggers opportunistic collection when a new account balance update event is received from the transaction service
`site-subscriptions-notifier-scheduler`	CloudWatch daily cron (12:00 UTC) + SQS paging queue	Queries upcoming subscribers within the notification window and enqueues them to the notifier worker queue; pages through results via SQS
`site-subscriptions-notifier-worker`	SQS (`site-subscription-service-pre-subscription-notifier-worker`, max concurrency 5)	Sends pre-subscription notifications via Segment, Iterable, and push channels for users approaching their subscription billing date

site-subscriptions-api

API Gateway (IAM + JWT)

Primary REST API — subscription activation, reactivation, upgrade, downgrade, manual collection, billing history, billing details, active term, ban, and QA create

site-subscriptions-memberships

Kinesis (site-user-service-users)

Processes membership lifecycle events from the user service and drives subscription state transitions for upgrades, downgrades, cancellations, pauses, and account closures

site-subscriptions-ach-handler

Kinesis (site-payments)

Processes ACH payment callbacks for subscription debits; maps COMPLETED, RETURNED, REFUNDED, and CHARGED_BACK outcomes to billing status; emits notifications via Segment, Iterable, and AppsFlyer

site-subscriptions-kinesis-feeder

DynamoDB Stream (billing-activity)

Reads DynamoDB Stream change records from billing-activity and publishes them to the site-subscriptions Kinesis stream for downstream consumers

site-subscriptions-batch-worker

SQS (site-subscription-service-batch-worker, batch size 10)

Handles bulk subscription operations and data management tasks dispatched to the batch queue

site-subscriptions-collections-job

CloudWatch scheduled rules (Mon–Fri) + SQS paging queues

Queries DynamoDB for subscriptions due for collection and enqueues them to scheduled, retry, and pause collection queues; pages through results using SQS-backed pagination

site-subscriptions-collections-worker

SQS (collections-scheduled, collections-retry, collections-pause, max concurrency 50)

Attempts subscription collection via the payments service; applies ML-based collection decisions; advances billing status and re-enqueues on retry and pause outcomes

site-subscriptions-webhook-worker

SQS (site-subscription-service-income-event-tap) via EventBridge

Triggers opportunistic collection for subscriptions in a collectible state when an income transaction event exceeds the configured ACH_INCOME_EVENT_THRESHOLD

site-subscriptions-webhook-balance-worker

SQS (site-subscription-service-balance-event-tap) via EventBridge

Triggers opportunistic collection when a new account balance update event is received from the transaction service

site-subscriptions-notifier-scheduler

CloudWatch daily cron (12:00 UTC) + SQS paging queue

Queries upcoming subscribers within the notification window and enqueues them to the notifier worker queue; pages through results via SQS

site-subscriptions-notifier-worker

SQS (site-subscription-service-pre-subscription-notifier-worker, max concurrency 5)

Sends pre-subscription notifications via Segment, Iterable, and push channels for users approaching their subscription billing date

External Dependencies

Service Role

Service	Role
Payments Service	Executes subscription collection attempts (pinless debit and ACH) and ACH disbursements
User Service	User profiles and identity data consumed by the memberships Lambda and queried by the API and notifier
Underwriting Service	Validates subscription eligibility and plan availability during activation and upgrade flows
Transactions Service	Bank account balance data queried during webhook-triggered collection decisions
Insight Service	Source of income detection events (via EventBridge) that drive webhook-triggered collection
Admin Service	Internal admin tooling client used to attach notes to user accounts during subscription lifecycle events
GrowthBook	Feature flags controlling collection behavior, ACH routing, ML decider gating, and webhook collection eligibility
SageMaker	ML model endpoint backing the `mldecider` package — determines whether to attempt collection for a given subscriber
EventBridge	Subscription billing event bus; income and balance event sources for webhook workers; scheduled rules for collections-job and notifier-scheduler
Segment	User analytics events for subscription activation, collection outcomes, ACH callbacks, and pre-subscription notifications
Iterable	Email and in-app notifications triggered by ACH payment events and pre-subscription notifier
AppsFlyer	Mobile attribution tracking for subscription activation and ACH payment events

Payments Service

Executes subscription collection attempts (pinless debit and ACH) and ACH disbursements

User Service

User profiles and identity data consumed by the memberships Lambda and queried by the API and notifier

Underwriting Service

Validates subscription eligibility and plan availability during activation and upgrade flows

Transactions Service

Bank account balance data queried during webhook-triggered collection decisions

Insight Service

Source of income detection events (via EventBridge) that drive webhook-triggered collection

Admin Service

Internal admin tooling client used to attach notes to user accounts during subscription lifecycle events

GrowthBook

Feature flags controlling collection behavior, ACH routing, ML decider gating, and webhook collection eligibility

SageMaker

ML model endpoint backing the mldecider package — determines whether to attempt collection for a given subscriber

EventBridge

Subscription billing event bus; income and balance event sources for webhook workers; scheduled rules for collections-job and notifier-scheduler

Segment

User analytics events for subscription activation, collection outcomes, ACH callbacks, and pre-subscription notifications

Iterable

Email and in-app notifications triggered by ACH payment events and pre-subscription notifier

AppsFlyer

Mobile attribution tracking for subscription activation and ACH payment events

Documentation

Architecture — System context diagrams, Lambda functions, data storage, and integration overview
Infrastructure — Terraform layout, Lambda configuration, SQS queues, Kinesis streams, EventBridge rules, Secrets Manager, and monitoring
API Specification — Full OpenAPI spec (Swagger UI)
API Endpoints — Human-readable endpoint reference with request/response tables and error codes
Feature Summary — Categorized feature reference
DynamoDB Tables — Table schemas, access patterns, GSIs, and enumerated value references
Event Flows — Published events, scheduled rules, webhook event paths, and notifier flows
Subscription Lifecycle — Billing statuses, state transitions, activation, upgrade/downgrade, ban, and reactivation flows
Collections Engine — Scheduled, webhook income, webhook balance, and ACH settlement collection flows
ACH Processing — Kinesis ACH callback handling, status mapping, and notification emission
Memberships — Membership Kinesis consumer, event types, and state transitions
Notifications — Three-day pre-subscription notifier scheduler and worker
Collections: Processes — Collection process detail and decision flows
Collections: Architecture — Collections subsystem architecture
Collections: Module Architecture — Collections Go module structure