at-container-registry/docs/BILLING.md

Billing Integration

Optional Stripe billing integration. Allows charging for subscription tiers, which map to storage quotas and feature gates on managed holds.

Overview

• Compile-time optional: Build the appview with -tags billing to enable Stripe support
• AppView owns billing: All Stripe interaction (checkout, customer portal, webhook handling) lives in the appview (pkg/billing/)
• Holds enforce quota: On a subscription change, the appview pushes a tier update to each managed hold; the hold maps the tier rank to its own quota tier and enforces it
• Customer-DID mapping: User DIDs are stored in Stripe customer metadata (no extra database)

Architecture

User → AppView Settings UI → AppView (pkg/billing) → Stripe
                                    ↑
                  Stripe webhook → POST /api/stripe/webhook (AppView)
                                    ↓
       io.atcr.hold.updateCrewTier (signed appview token) → Hold → update crew tier / enforce quota

The appview is the sole billing authority: it creates checkout and portal sessions, receives Stripe webhooks at POST /api/stripe/webhook, and resolves the subscription's price ID to a tier rank. On a subscription change it calls each managed hold's io.atcr.hold.updateCrewTier endpoint (pkg/appview/holdclient/tier_update.go), authenticated with a short-lived JWT signed by the appview's P-256 key. The hold verifies that token against its configured appview DID and only then updates the crew member's quota tier (pkg/hold/pds/xrpc.go, HandleUpdateCrewTier). Holds never talk to Stripe and trust nothing but a valid appview-signed token; their job is quota enforcement, not payment.

Building with Billing Support

Billing lives entirely in the AppView (pkg/billing/). The hold binary does not need a special build tag.

# AppView without billing (default)
go build -o bin/atcr-appview ./cmd/appview

# AppView with billing
go build -tags billing -o bin/atcr-appview ./cmd/appview

# Docker (Dockerfile.appview does not include -tags billing by default;
# build locally with the tag if you need billing support)
go build -tags billing -o bin/atcr-appview ./cmd/appview

Configuration

Environment Variables

# Required for billing
STRIPE_SECRET_KEY=sk_live_xxx        # or sk_test_xxx for testing
STRIPE_WEBHOOK_SECRET=whsec_xxx      # from Stripe Dashboard or CLI

# Optional
STRIPE_PUBLISHABLE_KEY=pk_live_xxx   # for client-side (not currently used)

Billing tiers (appview config)

Stripe tiers are configured as a list under the billing: section of the appview config (pkg/billing/config.go). Position in the list determines tier rank (0-based, lowest to highest). Billing auto-enables when a Stripe secret key is set and at least one tier is configured.

billing:
  # Can also be set via STRIPE_SECRET_KEY env var (takes precedence).
  stripe_secret_key: sk_live_xxx
  # Can also be set via STRIPE_WEBHOOK_SECRET env var (takes precedence).
  webhook_secret: whsec_xxx
  currency: usd
  success_url: "{base_url}/settings/billing"
  cancel_url: "{base_url}/settings/billing"
  tiers:
    - name: Free
      description: Get started with basic storage
      features: []
      stripe_price_monthly: ""        # empty = free tier
      stripe_price_yearly: ""
      max_webhooks: 1
      webhook_all_triggers: false
      ai_advisor: false
      supporter_badge: false
    - name: Supporter
      description: Support the project
      stripe_price_yearly: price_xxx
      max_webhooks: 1
      webhook_all_triggers: true
      ai_advisor: true
      supporter_badge: true
    - name: Pro
      description: More storage with scan-on-push
      stripe_price_monthly: price_xxx
      stripe_price_yearly: price_xxx
      max_webhooks: 10
      webhook_all_triggers: true
      ai_advisor: true
      supporter_badge: true

Quota tiers (hold config)

Storage quotas are configured separately, in the quota: section of each hold's config (pkg/hold/quota/config.go). These are also a position-ranked list. The appview pushes a tier rank to the hold via updateCrewTier; the hold maps that rank onto its own quota tier list, so the billing tier names and quota tier names do not need to match (only ranks line up). Real quota tier names are deckhand, bosun, quartermaster (there is no "swabbie" tier).

quota:
  tiers:
    - name: free
      quota: 5GB
      scan_on_push: false
    - name: deckhand
      quota: 5GB
      scan_on_push: false
    - name: bosun
      quota: 50GB
      scan_on_push: true
    - name: quartermaster
      quota: 100GB
      scan_on_push: true
  defaults:
    new_crew_tier: deckhand

Stripe Price IDs

Use Price IDs (price_xxx), not Product IDs (prod_xxx).

To find Price IDs:

1. Stripe Dashboard → Products → Select product
2. Look at Pricing section
3. Copy the Price ID

Or via API:

curl https://api.stripe.com/v1/prices?product=prod_xxx \
  -u sk_test_xxx:

HTTP Endpoints

All billing routes live on the appview and only register when built with -tags billing.

Route	Auth	Description
POST /api/stripe/webhook	Stripe signature	Handle subscription lifecycle events from Stripe
GET /settings/subscription/checkout	OAuth session	Redirect to a Stripe Checkout session for the selected tier
GET /settings/subscription/portal	OAuth session	Redirect to the Stripe billing portal for the current customer

The settings page's "Subscription" panel is rendered server-side via the HTMX /settings/billing tab, which calls BillingManager.GetSubscriptionInfo(userDID) internally — there is no standalone JSON endpoint for it.

Local Development

Stripe CLI Setup

The Stripe CLI forwards webhooks to localhost:

# Install
brew install stripe/stripe-cli/stripe
# Or: https://stripe.com/docs/stripe-cli

# Login
stripe login

# Forward webhooks to local appview
stripe listen --forward-to localhost:5000/api/stripe/webhook

The CLI outputs a webhook signing secret:

Ready! Your webhook signing secret is whsec_xxxxxxxxxxxxx

Use that as STRIPE_WEBHOOK_SECRET for local dev.

Running Locally

# Terminal 1: Run appview with billing
export STRIPE_SECRET_KEY=sk_test_xxx
export STRIPE_WEBHOOK_SECRET=whsec_xxx  # from 'stripe listen'
go run -tags billing ./cmd/appview serve --config config-appview.yaml

# Terminal 2: Forward webhooks
stripe listen --forward-to localhost:5000/api/stripe/webhook

# Terminal 3: Trigger test events
stripe trigger checkout.session.completed
stripe trigger customer.subscription.created
stripe trigger customer.subscription.updated
stripe trigger customer.subscription.paused
stripe trigger customer.subscription.resumed
stripe trigger customer.subscription.deleted

Testing the Flow

1. Start appview with billing enabled (-tags billing)
2. Start Stripe CLI webhook forwarding
3. Navigate to AppView settings page
4. Click "Upgrade" on a tier
5. Complete Stripe checkout (use test card 4242 4242 4242 4242)
6. Webhook fires → appview updates crew tier on the user's hold
7. Refresh settings to see new tier

Webhook Events

The canonical list of subscribed events lives in pkg/billing/events.go as the SubscribedEvents slice. Use it when configuring a Stripe Dashboard webhook endpoint or auditing an existing one.

Event	Action
checkout.session.completed	No-op (subscription.created does the tier work)
customer.subscription.created	Set crew tier from price ID
customer.subscription.updated	Update tier; handles past_due (keep), unpaid / incomplete_expired (downgrade), incomplete (await)
customer.subscription.paused	Downgrade to free tier
customer.subscription.resumed	Restore tier from subscription price
customer.subscription.deleted	Downgrade to free tier
invoice.payment_failed	Log only (Stripe Smart Retries handle retry + customer email)
charge.dispute.created	Log only (Stripe emails the account owner by default)

Plankowners (planned)

io.atcr.hold.crew records carry a plankowner boolean flag (Plankowner on CrewRecord in pkg/atproto/lexicon.go) intended to mark early adopters:

{
  "$type": "io.atcr.hold.crew",
  "member": "did:plc:xxx",
  "tier": "deckhand",
  "plankowner": true,
  "permissions": ["blob:read", "blob:write"],
  "addedAt": "2025-01-01T00:00:00Z"
}

The flag exists on the record, but automated grandfathering behavior is not implemented. There is no plankowner_crew_tier config field, and nothing currently grants a paid tier for free or treats plankowners differently from other crew members at billing time. Their assigned tier is whatever is set on the crew record. Treat this section as a placeholder for future grandfathering logic.

Customer-DID Mapping

The user's DID is stored in Stripe customer metadata (set by getOrCreateCustomer in pkg/billing/billing.go):

{
  "metadata": {
    "user_did": "did:plc:xxx"
  }
}

Only user_did is stored. The appview resolves the customer for a DID by searching Stripe customer metadata, and reads user_did back from webhook events to know which user to update.

The appview uses an in-memory customer cache (10 min TTL) to reduce Stripe API calls. On webhook events, the cache is invalidated for the affected user.

Production Checklist

• Create Stripe products and prices in live mode
• Set STRIPE_SECRET_KEY to live key (sk_live_xxx)
• Configure webhook endpoint in Stripe Dashboard:
  • URL: https://your-appview.com/api/stripe/webhook
  • Events: checkout.session.completed, customer.subscription.created, customer.subscription.updated, customer.subscription.paused, customer.subscription.resumed, customer.subscription.deleted, invoice.payment_failed
• Set STRIPE_WEBHOOK_SECRET from Dashboard webhook settings
• Update the appview config billing.tiers with live price IDs
• Build appview with -tags billing
• Test with a real payment (can refund immediately)

Troubleshooting

Webhook signature verification failed

• Ensure STRIPE_WEBHOOK_SECRET matches the webhook endpoint in Stripe Dashboard
• For local dev, use the secret from stripe listen output

Customer not found

• Customer is created on first checkout
• Check Stripe Dashboard → Customers for the DID in metadata

Tier not updating after payment

• Check appview logs for webhook processing errors
• Verify the price ID in the appview config billing.tiers matches Stripe
• Confirm the appview was built with -tags billing (otherwise /api/stripe/webhook returns 404)
• Confirm each managed hold has the appview DID configured (so it accepts the signed updateCrewTier call) and has matching quota tier ranks

"Billing not enabled" error

There is no billing.enabled flag. Billing auto-enables when all of the following hold (see Manager.Enabled() in pkg/billing/billing.go):

• The appview was built with -tags billing
• A Stripe secret key is set (via STRIPE_SECRET_KEY env var or billing.stripe_secret_key)
• At least one tier is configured under billing.tiers