# Read the post-payment upgrade status

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/completion`

This human-facing endpoint backs the signed-in `/agent-upgrade/complete` page that Stripe returns the user to after an agent-requested checkout, and that the handoff page opens after an in-place upgrade. It requires the existing Neotask web sign-in of an account owner or administrator and either a `sessionId` (Checkout) or a `planChangeId` (in-place upgrade) body value.

The server re-reads the Checkout session from Stripe. It answers only for an agent checkout whose server-authored tenant binding matches the signed-in tenant; any other session is `not_found`. `purchaseRecorded` is true once the signed webhook has finished recording this session's payment: its server-owned purchase record (written only by the webhook, for both immediate and delayed payment methods) reads recorded, or the purchaser license still carries this session. Both are written after the plan, so a subscription pointer alone never counts. The status is `applied` when this payment is recorded and the current plan includes the requested operation; `already_active` when the plan includes it through another purchase but this payment is not recorded; `processing` while payment has cleared but the webhook has not finished recording it; `no_longer_active` when this payment was recorded but the plan no longer includes the operation; `payment_processing` for an asynchronous payment that has not cleared; `payment_failed` when Stripe reported that asynchronous payment failed; `not_paid` for an open session; `expired` for an expired one; and `refunded` when the session was paid but the account can never adopt it, so the signed webhook refunded the payment in full and asked Stripe to cancel its subscription (nothing was added to the account). `refundReason` is `app_store_subscription` when the account's plan is billed through the App Store (change the plan there) or `account_mismatch` when the payment could not be attached to this account (contact Neotask support). `refund_failed` has the same reasons but means Stripe refused the automatic refund: the webhook still asks Stripe to cancel the subscription, and Neotask support refunds the payment. The subscription counts as cancelled only once Stripe confirms it, which `subscriptionCancelled` reports: both statuses are final once it is true; while it is false the page keeps checking.

For an in-place upgrade (`planChangeId`), the server reads its server-owned plan-change record and, while payment is pending, the subscription from Stripe. `purchaseRecorded` is true once the signed webhook recorded the change (plan and license written). The status is `applied` when recorded and the current plan includes the operation, `no_longer_active` when recorded but the plan no longer includes it, `processing` while Stripe has applied the new price but the webhook has not recorded it, `payment_action_required` while Stripe holds the upgrade until its prorated invoice is paid (`paymentUrl` is that Stripe-hosted invoice, for authentication or a new card), and `payment_failed` when the pending change expired unpaid or Stripe refused it; nothing was applied or charged.

This read never changes the plan. The signed Stripe webhook is the only writer. Agents never call this endpoint; they retry their original operation, and the handoff request returns `already_active` once the plan includes it.

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