Collect tax IDs in Stripe checkout

Author: RhysSullivan

apps/cloud/src/extensions/billing/route.node.test.ts

@@ -6,7 +6,11 @@ import { MemberDirectory } from "@executor-js/api/server";
 import { UserStoreService } from "../../auth/context";
 import { WorkOSClient, type WorkOSClientService } from "../../auth/workos";
 import { WorkOsMirror, type WorkOsMirrorShape } from "../../auth/workos-mirror";
-import { resolveBillingOrganization } from "./route";
+import {
+  CHECKOUT_TAX_ID_PARAMS,
+  resolveBillingOrganization,
+  withCheckoutTaxIdCollection,
+} from "./route";
 
 const createdAt = new Date("2026-01-01T00:00:00.000Z");
 
@@ -141,3 +145,21 @@ describe("billing route org selector", () => {
     }),
   );
 });
+
+describe("billing checkout tax ID collection", () => {
+  it("asks Stripe Checkout to collect a tax ID on attach", () => {
+    const body = withCheckoutTaxIdCollection("/api/billing/attach", {
+      planId: "team",
+      checkoutSessionParams: { locale: "auto", tax_id_collection: { enabled: false } },
+    });
+    expect(body).toEqual({
+      planId: "team",
+      checkoutSessionParams: { locale: "auto", ...CHECKOUT_TAX_ID_PARAMS },
+    });
+  });
+
+  it("leaves other billing routes unchanged", () => {
+    const body = { planId: "team" };
+    expect(withCheckoutTaxIdCollection("/api/billing/previewAttach", body)).toBe(body);
+  });
+});

apps/cloud/src/extensions/billing/route.ts

@@ -15,6 +15,29 @@ type BillingSession = {
   readonly userId: string;
 };
 
+const ATTACH_PATH = "/api/billing/attach";
+
+// Stripe Checkout hides the VAT / tax ID field unless the session asks for it.
+// Autumn always passes an existing Stripe customer, and Stripe then requires
+// `customer_update.name = "auto"` so it can save the business name. Set on the
+// server so every checkout gets it, whatever the client sends.
+export const CHECKOUT_TAX_ID_PARAMS = {
+  tax_id_collection: { enabled: true },
+  billing_address_collection: "required",
+  customer_update: { name: "auto", address: "auto" },
+} as const;
+
+export const withCheckoutTaxIdCollection = (pathname: string, body: unknown): unknown => {
+  if (pathname !== ATTACH_PATH || typeof body !== "object" || body === null) return body;
+  const { checkoutSessionParams, ...rest } = body as {
+    readonly checkoutSessionParams?: Record<string, unknown>;
+  };
+  return {
+    ...rest,
+    checkoutSessionParams: { ...checkoutSessionParams, ...CHECKOUT_TAX_ID_PARAMS },
+  };
+};
+
 export const resolveBillingOrganization = (request: Request, session: BillingSession) =>
   Effect.gen(function* () {
     // FAIL CLOSED: no header, no org. The AutumnProvider always sends the
@@ -84,7 +107,7 @@ const handler = Effect.gen(function* () {
       request: {
         url: url.pathname,
         method: request.method,
-        body,
+        body: withCheckoutTaxIdCollection(url.pathname, body),
       },
       customerId: org.id,
       customerData: {