feat(billing): add and end billing arrangements from the admin billing tab

Merged
ET
17h ago
+1075-12

Part of twentyhq/core-team-issues#2997. Stacked on #30564, which lists arrangements and opens their details. Staff can now add and end billing arrangements from Admin panel > Workspace > Billing. This is the writer that #29424 (seats) and #29426 (allowance) left for later. Limit overrides (#29469) already write their own LIMIT_OVERRIDE arrangements; they stay read-only here.

Summary

 <SettingsAdminWorkspaceBillingArrangementsSection>          from #30564
+  row menu on active or scheduled admin-managed rows -> End, then a confirmation
+  Add arrangement -> <SettingsAdminWorkspaceBillingArrangementModal>   free seats | committed seats | credit allowance, then Ends, Reason, Comment
workspaceBillingArrangements(workspaceId)
  + isManageable on each row

createWorkspaceBillingArrangement(workspaceId, type, label, comment?, endsAt?, seats?, seatCapMode?, creditAllowance?)
  type not admin-managed, or billing off                        -> BILLING_ARRANGEMENT_NOT_MANAGEABLE (400)
  under the billing seat lock (the one member joins take):
    hard cap < computeBilledSeats(members, active free seats)   -> BILLING_ARRANGEMENT_SEAT_CAP_BELOW_MEMBERS (400)
    BillingArrangementService.insertArrangement, starting now   -> BILLING_ARRANGEMENT_INVALID / _OVERLAP (400)
  seat types -> enqueue UpdateSubscriptionQuantityJob now
  allowance  -> refreshWorkspaceCreditState (currentBillingSubscription cache)

endWorkspaceBillingArrangement(workspaceId, billingArrangementId)
  not found -> BILLING_ARRANGEMENT_NOT_FOUND (404), same type check
  revokedAt = now, revokedByUserId = operator (nothing is deleted), same side effects
  • Both mutations sit on AdminPanelBillingArrangementResolver from #30564, behind AdminPanelGuard.
  • Only FREE_SEATS, COMMITTED_SEATS and WORKSPACE_CREDIT_ALLOWANCE can be added or ended here, because their effect is computed from the row. DISCOUNT, TRIAL_EXTENSION, LIMIT_OVERRIDE, REFUND and CREDIT_GRANT stay read-only: each needs a Stripe or usage limit write first. A LIMIT_OVERRIDE row ends when its override is deleted from Limits (endLimitOverride, #29469).
  • An arrangement starts when it is added. COMMITTED_SEATS needs an end date, as BILLING_ARRANGEMENT_SETTINGS_BY_TYPE already requires. creditAllowance is in display credits per month, converted to micro like grantWorkspaceCredits.
  • The hard-cap check reuses BillingSeatService and computeBilledSeats, so it counts members the same way the join-time cap does.
  • Reaching the end date is left to the renewal seat sync already on main (enqueueSeatSyncForSeatArrangements), so an arrangement that ends mid-period changes the billed seats at the next renewal.
  • Overlaps now throw BILLING_ARRANGEMENT_OVERLAP with a readable message, and BILLING_ARRANGEMENT_INVALID becomes a 400. Both used to reach staff as "An unexpected billing error occurred".
  • The modal asks for the reason with the labels limit overrides use.

Evidence

Local lane with billing on and Stripe test webhooks forwarded, on a workspace with a monthly plan and 3 members:

  • Free seats. Before: 3 seats billed. After adding 1 free seat: Stripe subscription at 2 seats, customer.subscription.updated webhook answered 200, stored item quantity 2.
  • Credit allowance. Before: usage 0 / 12. After adding 50 per month: 0 / 50. After ending it: back to 0 / 12.
  • Hard cap. A cap of 1 with 2 billed members is refused: "A hard seat cap cannot be below the current number of billed members." A cap of 2 is added and the bill stays at 2 seats.
  • Overlap. A second free seats arrangement while one is active is refused: "This workspace already has an arrangement of this type over that period."
  • End. revokedAt and revokedByUserId are set; the row shows Ended, stays listed, and its details show who ended it.
  • The row menu opens without opening the details, and End only opens its confirmation.
  • generated-admin regenerated by admin codegen against a lane running this branch.
  • Scoped server and front typecheck, oxlint and oxfmt clean. Unit tests pass: billing (429), admin panel front utils (71).

Merge Danger

Door: two-way

No schema change. Reverting removes two admin mutations and the add and end controls. Arrangements created in the meantime stay in core.billingArrangement and keep applying through the seat and allowance logic already on main.

Blast Radius: admin-panel

Staff only. Adding or ending a seat arrangement triggers a real Stripe quantity update with proration, as a member change does. BILLING_ARRANGEMENT_INVALID moves from 500 to 400.