How to warn customers before an action incurs a new seat charge

To decide whether an in-app action should warn a customer that it will trigger a new seat charge, compare the seats the action would consume against the seats already paid for this period. Warn only when the action pushes the seat count above what has already been billed. This is a common product need on top of pay-in-advance fixed charges: telling a user "this will add a seat" versus letting them silently reclaim a seat that is already covered.

For the underlying mechanics (why the fixed charge endpoint shows future units, and how to read the currently paid-for units from the fees API) see the companion article, "Why a subscription fixed charge shows future units after an update with apply_units_immediately false." This article assumes that background and focuses only on the warning decision.

The warning rule

Let paid_units be the sum of units across the current-period pay-in-advance fixed charge fees (the fee-sum method from the companion article). For a proposed action that would move the customer to target_units:

• If target_units > paid_units, the action bills the difference. Warn the customer that it will incur a new charge, and optionally surface how many new seats.

• If target_units <= paid_units, the action is already covered. Do not warn, even when the fixed charge object shows a lower number, because those seats stay paid through period end.

The key consequence for UX: a seat un-assigned earlier in the period is still paid for, so reassigning it is free and should be silent. Only genuine growth beyond the paid capacity warrants a warning.

Why the fixed charge object is the wrong input

It is tempting to gate the warning on the fixed charge endpoint's units, but that field is the target state, not what is currently paid for. After a mid-period decrease with apply_units_immediately: false it understates the customer's real entitlement, which would make your logic warn on a reassignment that is actually free. The current-period fee sum is the only input that reflects paid capacity, which is why the decision compares against it rather than against the fixed charge object.

This article reflects guidance drawn from customer case resolutions. It is not officially supported documentation and may not apply to all situations.