# Confirm a paid-plan handoff

Launch state: **Live**. Agents can register at /auth.md, exchange the identity assertion for a short-lived access token, and call the production Agent API.

`POST /api/agent/checkout-handoffs/{handoffRef}/confirm`

This human-facing endpoint requires the existing Neotask web sign-in and a selected eligible `planId`. The server rechecks tenant ownership, claim state, current plan, eligibility, expiration, and confirmation limits before it changes anything.

For an account without a Stripe subscription (`mode: checkout`), the response contains an exact Stripe Checkout URL only after the verified user confirms. A repeated or concurrent confirmation reuses the handoff's open Checkout session only when that session charges the chosen plan at its current price. Choosing another plan first expires the open session in Stripe, then creates one for the chosen plan. A session that is already paid or whose payment is clearing is never replaced. `planId` always names the plan the returned session charges. The session expires with the handoff (Stripe's 30-minute minimum), and it is refused while another plan checkout for the account is open.

For an existing Stripe subscriber (`mode: plan_change`), the same subscription is upgraded in place: Stripe swaps the plan price, prorates, and invoices the difference at once. Send the quoted `prorationDate` so the charge matches the quote; a quote older than 30 minutes, or from before the subscription last renewed, is refused with `quote_expired` and nothing is charged (reload the page for the current price). The change is held until that invoice is paid, so a payment that needs authentication or fails never leaves the plan upgraded and never creates a second subscription. The response returns `planChangeId` and `status` (`processing` or `payment_action_required` with a Stripe-hosted `paymentUrl`); the signed Stripe webhook alone writes the plan. Concurrent confirmations make one Stripe update.

Agents must never call this endpoint with an agent bearer token or follow the returned URL themselves.

See [OpenAPI](https://neotask.ai/openapi.yaml) for request and response schemas.