The Trinity Beast — Subscription Lifecycle

1. Overview

The Trinity Beast subscription lifecycle is managed by the trinity-beast-receipt Lambda function, which handles two distinct entry points:

• Checkout completion — Called by the thank-you page after a Stripe Checkout session completes. Processes new subscriptions, donations, and LRS add-on purchases.
• Stripe webhooks — Called by Stripe via API Gateway when subscription events occur (tier changes, cancellations, payment failures, payment recoveries, refunds).

2. Subscription Tiers

3. New Subscription Flow

When a customer completes a Stripe Checkout session on the subscription page, the thank-you page calls the Lambda with the session ID and type.

sequenceDiagram
    participant C as Customer
    participant S as Stripe Checkout
    participant TY as Thank-You Page
    participant L as Lambda (receipt)
    participant DB as Aurora
    participant EC as ElastiCache
    participant SES as SES Email

    C->>S: Select tier & pay
    S->>TY: Redirect with session_id
    TY->>L: POST {session_id, type: "subscription"}
    L->>EC: Check session dedup
    EC-->>L: Not found (first call)
    L->>S: Get checkout session
    S-->>L: Session details (email, amount, tier, customer_id)
    L->>DB: INSERT INTO users (upsert by email)
    DB-->>L: user_id
    L->>L: Generate API key
    L->>DB: INSERT INTO api_keys (user_id, tier, limits)
    L->>DB: UPDATE api_keys SET stripe_customer_id, stripe_subscription_id
    L->>DB: INSERT INTO transactions
    DB-->>L: transaction_id
    L->>SES: Send SubscriptionReceipt email
    L->>EC: Cache response (1hr dedup)
    L-->>TY: {success, api_key, transaction_id}
    TY->>C: Display API key & receipt
        

Processing Steps

1. Session dedup check — ElastiCache key receipt:session:{id} with 1-hour TTL prevents double-processing if the thank-you page calls twice.
2. Read Stripe session — Retrieves customer email, name, amount, payment status, customer ID, and metadata (tier, LRS addon flag, locale).
3. Create/update user — Upserts into users table by email, returns user_id. Stores preferred_lang from the Stripe checkout locale.
4. Generate API key — Creates a unique key in format {random}-{timestamp}.
5. Insert API key — Writes to api_keys with tier-specific limits from the rate_limit_template table in Aurora (query_limit, rate_limit_qps, burst_limit, minimum_wait_seconds).
6. Link Stripe IDs — Stores stripe_customer_id and stripe_subscription_id on the API key row for webhook lookups.
7. Lifetime tier — Automatically sets lrs_enabled = true (LRS included at no extra cost).
8. Preferred language — The visitor's cpmp-lang setting is passed to Stripe via the locale parameter and client_reference_id. The Lambda reads this from the Stripe session and stores it on users.preferred_lang and transactions.preferred_lang. This enables future localized communications in the subscriber's language.
9. Record transaction — Inserts into transactions table with all payment details including preferred language.
10. Send receipt — SES email using the SubscriptionReceipt template with API key, portal URL, and receipt link.
11. Cache response — Stores the full response in ElastiCache for session dedup.

4. LRS Add-On Activation

The LRS (Listener Reporting Service) add-on upgrades a subscriber from 10 reports/month to unlimited reports. It's a separate Stripe subscription linked to the same customer.

Activation Steps

1. Look up subscriber — Finds the active API key by email via users → api_keys join.
2. Validate eligibility — Rejects if tier is Unlimited/Lifetime (LRS already included) or if LRS is already enabled.
3. Enable LRS — Sets lrs_enabled = true on the API key row.
4. Record transaction — Inserts lrs-addon type transaction.
5. Link LRS subscription — Stores stripe_lrs_subscription_id on the API key row (separate from the main subscription ID).
6. Invalidate cache — Calls /admin/invalidate-key on both api.cpmp-site.org and lrs.cpmp-site.org so the change takes effect immediately.
7. Send receipt — SES email using the LRSAddonReceipt template.

5. Donation Processing

Donations follow a simpler flow — no API key generation, no tier assignment. The Lambda creates a user record, records the transaction, and sends a DonationReceipt email.

6. Stripe Webhook Events

Stripe sends webhook events to POST /webhook via API Gateway → Lambda. Events are verified using the Stripe webhook signing secret and deduplicated by event ID in ElastiCache.

flowchart TD
    S[Stripe Event] --> V{Verify Signature}
    V -->|Invalid| R400[400 Invalid]
    V -->|Valid| D{Duplicate Check}
    D -->|Already processed| R200D[200 Already processed]
    D -->|New event| Route{Event Type}
    Route -->|customer.subscription.updated| SU[handleSubscriptionUpdated]
    Route -->|customer.subscription.deleted| SD[handleSubscriptionDeleted]
    Route -->|invoice.payment_failed| PF[handlePaymentFailed]
    Route -->|invoice.paid| PR[handlePaymentRecovered]
    Route -->|charge.refunded| RF[handleChargeRefunded]
    Route -->|Other| Skip[Log & skip]
    SU --> Mark[Mark processed in ElastiCache]
    SD --> Mark
    PF --> Mark
    PR --> Mark
    RF --> Mark
    Mark --> R200[200 OK]

    style S fill:#1e3a5f,stroke:#0f172a,color:#ffffff,font-weight:bold
    style V fill:#7c3aed,stroke:#0f172a,color:#ffffff,font-weight:bold
    style D fill:#7c3aed,stroke:#0f172a,color:#ffffff,font-weight:bold
    style Route fill:#b45309,stroke:#0f172a,color:#ffffff,font-weight:bold
    style SU fill:#065f46,stroke:#0f172a,color:#ffffff,font-weight:bold
    style SD fill:#991b1b,stroke:#0f172a,color:#ffffff,font-weight:bold
    style PF fill:#991b1b,stroke:#0f172a,color:#ffffff,font-weight:bold
    style PR fill:#065f46,stroke:#0f172a,color:#ffffff,font-weight:bold
    style RF fill:#991b1b,stroke:#0f172a,color:#ffffff,font-weight:bold
    style Skip fill:#475569,stroke:#0f172a,color:#ffffff
    style Mark fill:#1e3a5f,stroke:#0f172a,color:#ffffff,font-weight:bold
    style R200 fill:#065f46,stroke:#0f172a,color:#ffffff,font-weight:bold
    style R200D fill:#475569,stroke:#0f172a,color:#ffffff
    style R400 fill:#991b1b,stroke:#0f172a,color:#ffffff,font-weight:bold
        

7. Tier Upgrades & Downgrades

When a subscriber changes their plan in the Stripe Customer Portal, Stripe sends a customer.subscription.updated event with the new tier in the subscription metadata.

Upgrade Logic

• New tier limits (query_limit, rate_limit_qps, burst_limit, minimum_wait_seconds) are applied immediately from the rate_limit_template table in Aurora.
• If upgrading to Unlimited or Lifetime, lrs_enabled is automatically set to true.
• API key cache is invalidated so the new limits take effect on the next request.

Downgrade Logic

• New tier limits are applied immediately.
• If downgrading FROM Unlimited/Lifetime to a lower tier, lrs_enabled is set to false — unless the subscriber has a separate LRS add-on subscription (stripe_lrs_subscription_id is not empty).
• API key cache is invalidated.

8. Cancellation Flow

When a subscription is cancelled (via Customer Portal or Stripe dashboard), Stripe sends a customer.subscription.deleted event.

LPO Subscription Cancelled

1. Tier is set to free with free-tier limits.
2. subscription_status set to canceled.
3. lrs_enabled set to false.
4. stripe_subscription_id and stripe_lrs_subscription_id cleared.
5. If an LRS add-on subscription exists, it is automatically cancelled in Stripe via the API.
6. API key cache invalidated on all containers.

LRS Add-On Cancelled (separately)

1. Identified by matching subscription.id to stripe_lrs_subscription_id.
2. lrs_enabled set to false.
3. stripe_lrs_subscription_id cleared.
4. The main LPO subscription remains active and unaffected.
5. API key cache invalidated.

9. Payment Failure & Grace Period

stateDiagram-v2
    [*] --> Active: Subscription created
    Active --> PastDue: invoice.payment_failed
    PastDue --> Active: invoice.paid (recovered)
    PastDue --> Blocked: Grace period expired
    Blocked --> Active: invoice.paid (recovered)
    Active --> Canceled: customer.subscription.deleted
    PastDue --> Canceled: customer.subscription.deleted
    Canceled --> [*]: Downgraded to free

    classDef active fill:#065f46,stroke:#0f172a,color:#ffffff,font-weight:bold
    classDef pastdue fill:#b45309,stroke:#0f172a,color:#ffffff,font-weight:bold
    classDef blocked fill:#991b1b,stroke:#0f172a,color:#ffffff,font-weight:bold
    classDef canceled fill:#475569,stroke:#0f172a,color:#ffffff,font-weight:bold

    class Active active
    class PastDue pastdue
    class Blocked blocked
    class Canceled canceled
        

Payment Failure (invoice.payment_failed)

• subscription_status set to past_due.
• payment_failed_at set to current timestamp (only on first failure — uses COALESCE to preserve the original date).
• API key cache invalidated.

Grace Period

The LPO server checks the grace period on every price request for past_due subscribers:

• Grace period: payment_grace_period_days application parameter (default: 7 days).
• If time.Since(payment_failed_at) < grace_period, the subscriber continues to have full access.
• If the grace period expires, the server returns HTTP 402 (Payment Required) with a message to update their payment method.

Payment Recovery (invoice.paid)

• Only acts if current status is past_due.
• subscription_status restored to active.
• payment_failed_at cleared (set to NULL).
• API key cache invalidated — full access restored immediately.

10. Refund Processing

When a charge is refunded via the Stripe Dashboard or mobile app, Stripe sends a charge.refunded webhook event. The Lambda automatically revokes the associated API key.

Refund Flow

1. Stripe fires charge.refunded — triggered when you process a refund in the Stripe Dashboard or mobile app.
2. Look up customer — Uses the charge's customer ID to find the API key via lookupByStripeCustomer.
3. Revoke API key — Sets revoked = true and subscription_status = 'refunded' on the API key row.
4. Record transaction — Inserts a refund transaction record with type 'refund', the refunded amount, and the associated API key.
5. Invalidate cache — Calls invalidateAPIKeyCache on all LPO/LRS servers so the revoked key stops working immediately.

11. Cache Invalidation

Every lifecycle event that changes API key data triggers cache invalidation to ensure changes take effect immediately across all containers.

12. Database Schema

api_keys — Subscription Lifecycle Columns

Indexes for Webhook Lookups

13. Stripe Customer Portal

Each subscription receipt email includes a link to the Stripe Customer Portal, generated dynamically by the Lambda using billingportal.Session. The portal allows subscribers to:

• Update payment method
• View billing history and download invoices
• Change subscription plan (upgrade/downgrade)
• Cancel subscription