# Request a paid-plan checkout 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.

Contract status: **implemented**. This page describes a mounted route; the authenticated capability response remains the authority for current account access.

## Request

`POST /api/agent/checkout-handoffs/request`

Operation ID: `requestAgentCheckoutHandoff`

Send a short-lived access token obtained through [auth.md](https://neotask.ai/auth.md) for `https://neotask.ai/api/agent` in the `Authorization: Bearer` header. The token must include `neotask:billing:handoff`.

Send an `Idempotency-Key` header with 8-200 characters. Reuse it only for an identical retry. For 24 hours, an identical retry returns the outcome recorded for the first request, with the same status and body, instead of running the operation again; a recorded failure is returned as that same failure. A readiness refusal returned before the operation started (for example `setup_required` with `runner_not_enrolled`, or `temporarily_disabled` with `run_execution_disabled`, `runner_offline` or `cloud_gateway_not_connected`) is not recorded, so the identical retry runs once the runner or gateway is ready.

The JSON request body uses `AgentCheckoutHandoffRequest` in OpenAPI.

## Response

The server-recognized plan-required denial and opaque human handoff. The JSON schema is `AgentPlanRequiredResponse` in [OpenAPI](https://neotask.ai/openapi.yaml).

- The operation and required feature are validated against the server-owned upgrade catalog.
- The handoff URL has no authority by itself; a signed-in human confirms the plan.
- A pre-claim registration cannot create a paid-plan handoff.
- Plan upgrades are an owner or administrator action; an agent whose linked member is not an owner or administrator returns role_denied.
- Once the plan includes the operation, this returns already_active; retry the original operation.

## Errors

| HTTP | Codes | Meaning | Next action |
|---:|---|---|---|
| 400 | `invalid_request`, `invalid_idempotency_key` | The request body or Idempotency-Key is malformed. | Correct the documented input. Reuse an idempotency key only for the identical mutation. |
| 402 | `plan_required` | The ordinary account plan does not include the operation. | Give the user only the opaque Neotask checkout handoff returned by the server. |
| 409 | `idempotency_conflict`, `idempotency_in_progress` | The idempotency key belongs to another request or its first request is still running. | Do not change the request under the same key. Retry later or use a new key for new work. |
| 409 | `already_active` | The current account plan already includes the operation, for example after the human completed the upgrade. | Do not relay another checkout link. Retry the original operation. |
| 409 | `payment_processing` | Another payment for the account is in progress: a delayed payment still clearing (for example ACH or SEPA), a failed one still being closed, another open checkout, or a plan change still being applied. | Do not relay another checkout link. Retry the original operation after that payment completes. |
| 409 | `app_store_subscription` | The account plan is billed through the App Store, so it cannot be changed through Neotask billing. | Do not relay a checkout link. Ask the user to change the plan in the App Store. |
| 409 | `billing_action_required` | The existing subscription cannot be upgraded until billing is fixed: it is past due, unpaid, paused, incomplete, set to cancel, or needs support. | Do not relay a checkout link. Relay the returned message; the account owner resolves it on the account billing page. |
| 409 | `manual_review_required` | An earlier failed payment left a subscription that could not be verified, so it was not cancelled automatically. | Do not relay a checkout link. Ask the user to contact Neotask support before another purchase. |
| 403 | `role_denied` | A claimed agent acts as its linked tenant member, and plan upgrades require an account owner or administrator. | Ask an account owner or administrator to upgrade the plan. |
| 403 | `scope_denied`, `tenant_inactive`, `model_not_allowed` | The credential, account, or requested model cannot perform the operation. | Use an allowed model, request the documented scope, or ask the user to restore account access. |
| 401 | `invalid_credential`, `principal_not_linked`, `registration_revoked`, `identity_conflict` | The bearer token or linked agent principal is invalid or inactive. | Register, refresh, or claim through the documented Auth.md flow, then retry with a new token. |
| 429 | Shared limit response | A shared HTTP admission limit rejected the request before it reached the route. | Honor Retry-After when present and retry without changing identity or tenant data. |
| 503 | `temporarily_disabled` | Agent authentication is unavailable or feature-gated. | Do not bypass authentication. Retry only after the returned guidance or launch state changes. |

## Related resources

- [Agent API index](https://neotask.ai/docs/llms.txt)
- [OpenAPI JSON](https://neotask.ai/openapi.json)
- [Arazzo quickstart](https://neotask.ai/arazzo.yaml)
- [Knowledge manifest](https://neotask.ai/agent-public-contracts/v1/knowledge-manifest.json)