An optional field on the subscribe page for entering a promotion code, switched on by the subscription_promotion_codes setting. It comes from the API settings, so the API that creates the session with promotion codes allowed is also the one deciding whether the field shows. With it off the session is created without them and the field never renders. This is a layer on top of Plans & Subscriptions, which reads the same without it.
There is no verify endpoint and no code travels with the confirm. The field applies the code to the session through Stripe's checkout actions and then re-reads the session, and the discount, the new total and any recalculated tax come back from Stripe. The App subtracts nothing. Because the confirm charges the session's total, the discount is already in it by the time the customer subscribes.
The discount row shows what Stripe reports, with a Remove link that takes the code back off the session so the total returns to what it was without reloading the page.
Expired, unknown and not applicable to the plan all come back the same way, as a message under the field the code was typed into rather than on the page. The customer types another code or confirms without one.
Everyone who reaches the subscribe page with the flag on, including a returning customer on the saved card confirm step. The App does not try to work out whether someone is a first time subscriber. A code limited to first time customers is a restriction on the code at Stripe, so a returning customer who tries one gets the same message under the field as any other bad code.