feat(billing): add and end billing arrangements from the admin billing tab
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
AdminPanelBillingArrangementResolverfrom #30564, behindAdminPanelGuard. - Only
FREE_SEATS,COMMITTED_SEATSandWORKSPACE_CREDIT_ALLOWANCEcan be added or ended here, because their effect is computed from the row.DISCOUNT,TRIAL_EXTENSION,LIMIT_OVERRIDE,REFUNDandCREDIT_GRANTstay read-only: each needs a Stripe or usage limit write first. ALIMIT_OVERRIDErow ends when its override is deleted from Limits (endLimitOverride, #29469). - An arrangement starts when it is added.
COMMITTED_SEATSneeds an end date, asBILLING_ARRANGEMENT_SETTINGS_BY_TYPEalready requires.creditAllowanceis in display credits per month, converted to micro likegrantWorkspaceCredits. - The hard-cap check reuses
BillingSeatServiceandcomputeBilledSeats, 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_OVERLAPwith a readable message, andBILLING_ARRANGEMENT_INVALIDbecomes 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.updatedwebhook 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.
revokedAtandrevokedByUserIdare 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-adminregenerated 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.