Increase tenant quotas after user enters payment method

[psFried]

The goal is to automatically increase the task and collections quotas after a user enters a credit card.

[jwhartley]

I ran this once-off, in case it's useful for implementation:

UPDATE tenants
  SET
      tasks_quota = GREATEST(tasks_quota, 50),
      collections_quota = GREATEST(collections_quota, 5000)
  FROM stripe.customers
  WHERE customers.name = tenants.tenant
    AND customers."invoice_settings/default_payment_method" IS NOT NULL
    AND (tasks_quota <= 10 OR collections_quota <= 500);

[jshearer]

Problem

Tenant task and collection quotas live on the tenants table (tasks_quota, collections_quota, defaulting to 10 and 500). When a tenant becomes paid, either by setting a default payment method or by being marked as an external-payment customer (I think), these quotas are not raised automatically. The increase is applied by hand with a direct SQL update, so a customer who has started paying stays capped at trial limits until someone runs that update.

Goal

Raise a tenant's quotas to the paid floor automatically when it becomes paid, where "paid" means either of:

• the tenant has a non-null default payment method in Stripe, or
• the tenant's payment_provider is set to external.

The raise is one-way: it only ever increases a quota, never decreases it, and it never lowers a quota that has been set higher by hand. Stripe is the source of truth for whether a default payment method exists.

Approach

Drive this from the per-tenant controller added in #2902. That controller already runs a reconcile loop per tenant with a wake primitive and retry/backoff, and it already talks to Stripe. Add a quota reconcile that:

1. Determines paid status as (Stripe reports a non-null default payment method) OR (payment_provider = 'external'). The Stripe side is read live from Stripe at reconcile time, so the decision is sourced from Stripe rather than a cached flag.
2. Computes the desired quota. If paid, tasks_quota and collections_quota are each raised to at least the paid floor, applied as GREATEST(current, floor) so the change ratchets up and leaves higher manual values untouched.
3. Is idempotent, so it can run repeatedly and converge.

Triggering without webhooks

We are not adding Stripe webhooks, so the controller is woken from the paths we already control, with a periodic reconcile as the backstop:

• Default payment method set: wake the tenant controller from the setBillingPaymentMethod GraphQL mutation, right after the Stripe default-payment-method write it already performs. The dashboard's payment-method actions are being routed through that mutation (Fetch billing invoices via GraphQL ui#2004), so it is the right home for the wake.
• Marked external: a trigger on tenants.payment_provider wakes the controller, the same pattern as the billing-contact trigger in billing: add tenant billing contact fields and per-tenant controller #2902.
• Backstop: the controller's scheduled reconcile covers tenants that are not yet paid and catches default-payment-method changes made outside the dashboard, for example a card set directly in Stripe. Because each tenant reconciles on its own schedule, these reads spread out over time rather than arriving as a burst.

Open questions

• Should we treat being marked as "paid externally" as a signal to automatically raise the tenant quotas? This is a product question IMO.
• Paid-floor values. The current manual process raises to 50 tasks and 5000 collections. Confirm these values, and whether they should be constants or depend on the plan.
• Reconcile cadence for not-yet-paid tenants.
• Whether to run a one-time reconcile across existing paid tenants at rollout, so current customers are corrected and not only future transitions.
• Whether to cache the Stripe customer id on tenants so the controller reads the customer by id (immediately consistent) instead of searching by name. Optional, but it removes the eventually-consistent search and the name-match dependency.

[jwhartley]

Re the open questions:

• Yes, "park externally" should increase quotas.
• I think 100/10000 are reasonable starting points, although they should be publicised so we can anticipate when customers will need more. Once we have better automatic data plane scaling, I think we can increase that further.
• Can you explain "Reconcile cadence for not-yet-paid tenants." @jshearer ?
• Yes, we should apply to existing paid tenants. Given I ran the SQL in the earlier comment it shouldn't be a huge set
• No opinion

Adjacent, we should increase the caps to 50/5000 for POCs as well. Might need to be a manual step from the sales eng team, since I don't know if we have a trigger plumbed in

[jshearer]

Reconcile cadence for not-yet-paid tenants

The plan is to use Stripe as the source of truth for whether a payment method has been set or not, and this is just talking about how often we should poll Stripe for changes to the payment method method of unpaid tenants. Most of the time this will just be a backup as the setBillingPaymentMethod call will be the primary trigger, but in case someone manually updates Stripe, we should periodically poll to make sure we're in sync. I think 24h is sufficient here imo

[jshearer]

Adjacent, we should increase the caps to 50/5000 for POCs as well. Might need to be a manual step from the sales eng team, since I don't know if we have a trigger plumbed in

I eventually want us to have a tenant "state machine"/lifecycle. You start out as free tier, then you go free trial if you exceed limits, then either paid if you provide payment info, or expired or something if you don't after 30d. We could/should also have POC as a state we can manually transition tenants into with a defined end date and all that. I wrote up the above description as a good first task for @bbartman, maybe depending on priorities it can flow into this state machine thing as a follow-up