billing_handoff

publ Reference
[Migration map](../reference/tool-name-migration.md).

# billing_handoff

Read current context and return the one relevant console destination for a person to handle a channel plan/payment or an installed feature's pricing. This tool performs no payment, plan/pricing change or credential refresh and creates no task. Neither branch accepts a request ID or a new price.

| Purpose | Required inputs | Result |
| --- | --- | --- |
| `channel-plan` | `channelCode` | `action_required / CHANNEL_PLAN_HUMAN_REQUIRED`, current channel and the plan screen |
| `papp-pricing` | `channelCode`, positive integer `installedPAppId`, matching `pAppCode` | `action_required / PAPP_PRICING_HUMAN_REQUIRED`, installed detail and its store screen |

```json
{"purpose":"channel-plan","channelCode":"selected-channel-code"}
```

```json
{"purpose":"papp-pricing","channelCode":"selected-channel-code","installedPAppId":123,"pAppCode":"A00003"}
```

Replace illustrative targets with current authorized values. `channelCode` cannot be empty, `.` or `..`; feature codes contain ASCII letters/digits/underscores. Unknown fields are rejected. Hosted selected-channel resources require their bound channel; hosted account resources exclude this tool.

The plan branch checks the connection and reads the requested channel identity. It does not invoke the install/uninstall permission gate; actual channel-read access still applies. The pricing branch requires OWNER or selected-channel DELEGATEE with `MANAGE_P_APP_INSTALL_UNINSTALL`, reads the specific installed ID and rejects a missing detail or mismatched installed ID/code with `PAPP_TARGET_MISMATCH`.

The centrally configured console origin is separate from API service origins. The plan path is `/channels/{channelCode}/plan/home`; feature pricing uses `/channels/{channelCode}/p-app-store/home?pAppCode={code}` with encoded components. Use the final result's common `navigation` and compatible `consoleUrl` instead of constructing URLs. It supplies one resolved destination; demo/unresolvable navigation supplies none. A dev API observation does not guarantee that the configured console displays that dev fixture.

Results explicitly retain `writesPerformed:false` and `verification.confirmed:false`. The latter prevents treating a navigation result as completed payment or a changed plan. After the person finishes a plan action, reread through the same handoff or channel discovery; after pricing, use [papps_get](publ_papps_get.md). Compare returned current and scheduled next pricing: a future plan is not active merely because a link was opened.

Paid or unverified-cost first installation is handled by the store destination returned from [install](publ_papp_install.md); `papp-pricing` requires an already installed instance. Do not invent an installed ID or collect payment credentials to turn a handoff into automation.

## Selected installed identity

The detail response must match both the selected numeric installed ID and feature
code. The same feature code alone is insufficient. A mismatch returns the
existing detail/target error before exposing detail or a console destination. No
payment, installation, removal or credential refresh is performed by this check.

## Inputs

| Field | Required here | Contract |
| --- | --- | --- |
| `purpose` | Yes | one of: `channel-plan`, `papp-pricing` |
| `app` | Yes | When `purpose` is `papp-pricing`: string; min length 1; max length 100; The installed feature: its code or exact store name. |