Billing GraphQL by jshearer · Pull Request #2883 · estuary/flow

jshearer · 2026-04-23T01:26:50Z

This PR moves the billing endpoints from edge functions into GraphQL.

`Tenant.billing`

Billing is a field on Tenant rather than a standalone top-level query, because tenant is the natural aggregation root and other fields will follow.

type Query {
  tenant(name: String!): Tenant
}

type Tenant {
  name: String!
  billing: TenantBilling!
}

type TenantBilling {
  paymentMethods: [PaymentMethod!]!
  primaryPaymentMethod: PaymentMethod
  invoices(
    filter: InvoiceFilter, 
    before: String, 
    after: String, 
    first: Int, 
    last: Int
  ): InvoiceConnection!
}

This is a design choice I went with as it felt like we were starting to pollute the global namespace with queries that ought to be scoped under their natural owner. It's possible that we should move some other queries as well, but that's out of scope.

WRT permissions: Tenant.billing is non-nullable which means that a request that selects it without Admin on the tenant gets an error, rather than a partial response containing null and a path-scoped entry in errors.

Invoices

Invoice merges two data sources. Database fields (dateStart, dateEnd, invoiceType, subtotal, lineItems, extra) come from the invoices_ext Postgres view. Stripe fields (amountDue, status, invoicePdf, hostedInvoiceUrl) are resolved directly from Stripe.

Mutations

type MutationRoot {
  createBillingSetupIntent(tenant: String!): CreateBillingSetupIntentPayload
  setBillingPaymentMethod(tenant: String!, paymentMethodId: String!): SetBillingPaymentMethodPayload
  deleteBillingPaymentMethod(tenant: String!, paymentMethodId: String!): DeleteBillingPaymentMethodPayload
}

createBillingSetupIntent finds or creates a Stripe customer for the tenant, then returns the clientSecret the browser needs for the Stripe Elements flow.
setBillingPaymentMethod updates invoice_settings.default_payment_method on the customer.
deleteBillingPaymentMethod detaches the method; if the deleted method was the primary, the first remaining method is auto-promoted as default.

All three require Admin on the tenant and validate that the payment method belongs to the tenant's Stripe customer before acting.

`billing-types`

Shared Stripe types and search-query builders (InvoiceType, InvoiceSearch, InvoiceMetadata, customer_search_query, stripe_search) are extracted into a billing-types crate. billing-integrations now imports these instead of defining its own copies.

CI

deploy-agent-api.yaml injects STRIPE_API_KEY from Cloud Run secret manager. platform-test.yaml conditionally runs the graphql_billing_live_stripe integration test when STRIPE_TESTMODE_API_KEY is available in the environment.

Closes #2879
Part of #2877

jshearer · 2026-04-27T16:36:16Z

+
+/// Fetch invoices older than `cursor` (or the newest invoices when `cursor`
+/// is `None`). Returned rows are ordered newest-first.
+pub async fn fetch_invoice_rows_forward(


I really tried to not have fetch_invoice_rows_forward and fetch_invoice_rows_backward since they're almost identical, but the alternative (dynamic query generation) was worse, so I kept it. If anyone has any better ideas I'm all ears

i struggled with this a while ago when working on invite links and i think this duplication is just the price of admission for the query cache. At least it's easy to reason about...

jshearer · 2026-04-27T19:50:03Z

+    type Value = stripe::Invoice;
+    type Error = async_graphql::Error;
+
+    async fn load(


This could be parallelized.. wanted to KISS where possible tho. Happy to be convinced otherwise

jshearer · 2026-04-28T15:57:43Z

    /// The port to listen on for API requests.
    #[clap(long, default_value = "8080", env = "API_PORT")]
    api_port: u16,
+    /// Stripe secret API key. When provided, the billing GraphQL queries and


This is Option so that a Stripe API key is not required to run locally.

jshearer · 2026-04-28T16:18:27Z

 /// App is the wired application state of the control-plane API.
 pub struct App {
    pub _id_generator: std::sync::Mutex<models::IdGenerator>,
+    pub billing_provider: Option<Arc<dyn crate::billing::BillingProvider>>,


I really wanted this to be generic, but it would have exploded the complexity of this PR even further and it wasn't worth it

jshearer · 2026-04-28T19:13:41Z

-        // ensures that things still work correctly without it.
-        sqlx::query!(r#"delete from role_grants where subject_role = 'estuary_support/';"#)
-            .execute(&mut *txn)
+        control_plane_api::test_support::provision_test_tenant(&self.pool, tenant, &email, meta)


Moved this to control_plane_api so it could be shared, rather than duplicating it.

travjenkins · 2026-05-01T17:48:15Z

Not sure where to put these thoughts - so putting them on the PR.

Should the concept of fetching the payment_provider stay on the tenant or should we expose this through billing? I feel billing is interesting because it overlaps with tenant level settings and even some billing specific alerts/notifications. I have no strong opinion here - so mainly just mentioning it to be mentioned.

The UI will only ever fetch up to 5 tenant's payment methods at once. We do this so support doesn't spam calls. If it is easy (and more importantly makes sense) to allow us to search for an array of tenants that could reduce the number of calls.

To be clear - none of these things are blockers... just thoughts.

GregorShear · 2026-05-05T21:29:55Z

+
+/// Fetch invoices older than `cursor` (or the newest invoices when `cursor`
+/// is `None`). Returned rows are ordered newest-first.
+pub async fn fetch_invoice_rows_forward(


i struggled with this a while ago when working on invite links and i think this duplication is just the price of admission for the query cache. At least it's easy to reason about...

GregorShear

sorry to leave a couple of raw agent comments - i'm rushing out the door and wanted to get this up before i leave

Introduce a `BillingProvider` abstraction over the Stripe operations we need for customer, payment-method, invoice, and setup-intent handling, together with a Stripe-backed implementation and an in-memory test mock. The trait is deliberately scoped to outbound Stripe API calls so integration tests can stub them. * `BillingProvider` trait: Stripe primitives plus composed default methods (`find_customer`, `require_customer`, `find_or_create_customer`, `fetch_invoice`). * `StripeBillingProvider`: production implementation over `stripe::Client`. * `InMemoryBillingProvider`: stateful test mock used by integration tests and local agent startup. * `billing::db::fetch_invoice_rows`: typed read over the `invoices_ext` view with date-range and invoice-type filters.

…L surface Add `BillingProvider` (optional) to the `App` struct and wire `--stripe-api-key` from CLI args. When absent, billing operations return "Billing is not configured". Add billing GraphQL mutations (`createBillingSetupIntent`, `setBillingPaymentMethod`, `deleteBillingPaymentMethod`) and `Tenant.billing` query with invoices, payment methods, and customer data. DataLoaders (`StripeInvoiceLoader`, `ChargeDataLoader`, `CustomerDataLoader`) are injected per-request when a billing provider is configured.

The agent refuses to start without either `STRIPE_API_KEY` or `BILLING_IN_MEMORY=true`, so every environment that starts the agent now has to supply one. * `deploy-agent-api.yaml`: inject `STRIPE_API_KEY` from Cloud Run secret manager so the deployed agent starts. * `platform-test.yaml`: conditionally run `graphql_billing_live_stripe` against `STRIPE_TESTMODE_API_KEY` when the secret is present. * `mise/tasks/local/control-plane`: forward a shell-provided `STRIPE_API_KEY` into `agent.env`, or fall back to `BILLING_IN_MEMORY=true` so local dev works without additional setup.

Instead of building queries ad-hoc, let's centralize it a bit

* `CustomerDataLoader` resolves tenant names to Stripe customers. All customer lookups across `payment_methods`, `primary_payment_method`, and invoice resolution share this single DataLoader per request. * `StripeInvoiceLoader` resolves invoices by customer ID, period, and type. Its keys now carry a `CustomerId` rather than a tenant name, so it has no customer-lookup logic of its own. Searches are parallelized via `join_all`. * `ChargeDataLoader` resolves charges by `PaymentIntentId`, only hit when `paymentDetails` is selected. Also moves `receipt_url` into `InvoicePaymentDetails` (both fields come from the charge) and adds a `ChargeStatus` enum so consumers can distinguish payment outcomes. Removes the unused `BillingProvider::fetch_invoice` default method.

…cy-Key `find_or_create_customer` and `get_or_create_customer_for_tenant` search Stripe by tenant metadata then create if the search misses, but `customers.search` is eventually consistent so two near-simultaneous calls can both miss and both create a duplicate customer row for the same tenant. Use a deterministic `Idempotency-Key` per tenant on `Customer::create` so concurrent or retried creations collapse inside Stripe's 24h window

jshearer mentioned this pull request Apr 23, 2026

A couple of billing updates #2849

Closed

jshearer self-assigned this Apr 23, 2026

jshearer added this to the GraphQL Migration milestone Apr 23, 2026

jshearer force-pushed the jshearer/billing_graphql branch 20 times, most recently from c65a777 to 8d1970c Compare April 27, 2026 16:30

jshearer commented Apr 27, 2026

View reviewed changes

jshearer mentioned this pull request Apr 28, 2026

PostgREST surface area / GraphQL Migration #2877

Open

jshearer commented Apr 28, 2026

View reviewed changes

jshearer force-pushed the jshearer/billing_graphql branch from c00bc9f to cc73e15 Compare April 28, 2026 19:38

jshearer requested a review from a team April 30, 2026 17:17

jshearer added the control-plane label May 4, 2026

jshearer force-pushed the jshearer/billing_graphql branch 2 times, most recently from 183cb12 to e3ba37e Compare May 4, 2026 17:35

GregorShear reviewed May 5, 2026

View reviewed changes

jshearer force-pushed the jshearer/billing_graphql branch 5 times, most recently from ca57448 to 98a8373 Compare May 6, 2026 20:06

jshearer requested a review from GregorShear May 6, 2026 22:56

GregorShear reviewed May 11, 2026

View reviewed changes

Comment thread crates/control-plane-api/src/server/public/graphql/billing/tenant.rs Outdated

GregorShear reviewed May 11, 2026

View reviewed changes

Comment thread crates/control-plane-api/src/server/public/graphql/billing/invoices.rs Outdated

GregorShear reviewed May 11, 2026

View reviewed changes

GregorShear approved these changes May 13, 2026

View reviewed changes

jshearer force-pushed the jshearer/billing_graphql branch 3 times, most recently from 955f630 to d1317da Compare May 18, 2026 17:13

jshearer added 9 commits May 19, 2026 10:52

billing-types: add shared Stripe billing types

4683734

billing: refactor Stripe metadata searching/creation a bit

b5b8052

Instead of building queries ad-hoc, let's centralize it a bit

agent: Move provision_test_tenant to a shared location

f32d7cc

agent-api: address some pr feedback

29df22e

jshearer force-pushed the jshearer/billing_graphql branch from 0b50ea6 to 29df22e Compare May 19, 2026 14:53

jshearer merged commit 5b215cf into master May 19, 2026
11 checks passed

Conversation

jshearer commented Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Tenant.billing

Invoices

Mutations

billing-types

CI

Uh oh!

jshearer Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GregorShear May 5, 2026

Choose a reason for hiding this comment

Uh oh!

jshearer Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

jshearer Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

jshearer Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

jshearer Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

travjenkins commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

GregorShear May 5, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

GregorShear left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jshearer commented Apr 23, 2026 •

edited

Loading

`Tenant.billing`

`billing-types`

jshearer Apr 27, 2026 •

edited

Loading

travjenkins commented May 1, 2026 •

edited

Loading