> ## Documentation Index
> Fetch the complete documentation index at: https://agents.nanonets.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AdvancedMD Transfer Balance

> AdvancedMD charge-balance transfer tool exposed through the Agents Platform.

This document covers `advancedmd_transfer_balance`, the AdvancedMD charge-balance transfer tool exposed through the Agents Platform. It reassigns responsibility on a single charge between the patient and insurance sides — moving the balance **and** the responsibility portion together — via the AdvancedMD `updvisitwithcharges` API. For locating the charge first, see [AdvancedMD Find Charge](/docs/tools/advancedmd-find-charge); for detaching a payment (which optionally does the same patient→insurance move afterward), see [AdvancedMD Unapply Payment](/docs/tools/advancedmd-unapply-payment).

## Authentication

AdvancedMD transfer balance uses the existing AdvancedMD connector:

* `office_code`
* `username`
* `password`

The tool uses the same audited AdvancedMD client as the other AdvancedMD tools. It does not accept raw AdvancedMD tokens or direct URLs — the client derives the tenant base from the login-returned URL and manages the security token itself.

If AdvancedMD is not connected, the tool returns a structured `advancedmd_not_connected` result with suggested actions (Connect AdvancedMD and try again / Stop task).

## Safety

`advancedmd_transfer_balance` is a mutating billing tool. It issues an `updvisitwithcharges` write, a non-idempotent financial write that never replays on HTTP 429.

`dry_run` defaults to `false` (the tool transfers immediately, matching `advancedmd_unapply_payment`). Set `dry_run=true` to preview the call without executing it.

The tool reads the charge's **live** balances/portions from AdvancedMD first, then writes the new split. Two guards protect against AdvancedMD's `CD_Balances` CHECK constraint ("Insurance Balance cannot be negative"):

* The transfer amount cannot exceed the source side's balance or its portion.
* Any transfer that would leave either side's balance below zero is refused before the write (this is what happens if a credit/overpayment is pushed onto a side).

The write echoes the charge's own FID references (`proccode`, `diagcodes`, `modcodes`, `respparty`) and line fields (`fee`, `allowed`, `netfee`, `units`, `pos`, `tos`, `finclasscode`, `billins`) alongside the new balances/portions, which AdvancedMD's `CD_FIDReferences` constraint requires on a charge write.

## Provider profile & facility preservation

`updvisitwithcharges` rewrites the visit record and clears any attribute it is not given, and the billing provider/facility are `@profile`/`@facility` on the **visit** element (AMD API docs June 2025) — omitting them is what reset 58 charges to a blank provider. This write now reads the visit record from `getchargedetaildataicd10`, echoes those values back, refuses to run if the provider cannot be read, and re-reads it afterwards to confirm it survived. `ADVANCEDMD_CHARGE_WRITE_ENABLED=false` is the ops kill switch. Full background: [AdvancedMD Unapply Payment — Provider profile & facility preservation](/docs/tools/advancedmd-unapply-payment#provider-profile--facility-preservation).

## Inputs

Required:

* `charge_id`: AdvancedMD charge ID whose balance to transfer (from `advancedmd_find_charge`'s `ehr_charge_id`). A leading `charge` prefix is stripped automatically.

Optional:

* `dry_run`: Defaults to `false`. When `true`, returns the transfer that would be made without executing it.
* `direction`: `to_insurance` (move patient responsibility onto insurance) or `to_patient` (move insurance responsibility onto the patient). Defaults to `to_insurance`.
* `amount`: Decimal amount to transfer. Omit to move the **full outstanding balance** of the source side. Must be positive and cannot exceed the source side's balance or portion.
* `patient_id` / `visit_id`: Only used when AdvancedMD's charge detail response doesn't identify the patient/visit itself (the tool errors asking for them if so). `advancedmd_find_charge` returns both (`ehr_patient_id`, `ehr_visit_id`).

## Recommended Workflow

1. Use `advancedmd_find_charge` to locate the charge (`ehr_charge_id`, plus `ehr_patient_id`/`ehr_visit_id`) and read its current balances/portions.
2. Call `advancedmd_transfer_balance` with `dry_run=true` and review the preview.
3. Call again with `dry_run=false` (or omit `dry_run`) to execute.
4. Confirm `transferred` is `true` and the before/after amounts in the summary table.

### Dry-Run Example

```json theme={null}
{
  "dry_run": true,
  "charge_id": "5128593",
  "direction": "to_insurance"
}
```

### Partial Transfer Example

```json theme={null}
{
  "charge_id": "5128593",
  "direction": "to_patient",
  "amount": "35.87"
}
```

## Error Handling

The tool returns a structured tool error for invalid inputs (missing `charge_id`, an unknown `direction`, a non-positive `amount`), for an amount that exceeds the source side's balance/portion, and for a transfer that would drive a balance negative. It surfaces AdvancedMD faults (e.g. a closed period) as tool errors and does not retry.

When the source side has no positive balance to move, the tool returns a **success** result with `transferred: false` and a message (e.g. "No patient responsibility to transfer") rather than an error — there is simply nothing to do.

## Output

The structured output includes:

* `transferred`: `true` when AdvancedMD accepted the write.
* `dry_run`: whether the call was a dry run.
* `charge_id`: the normalized charge ID.
* `direction`: `patient_to_insurance` or `insurance_to_patient`.
* `transfer`: the transfer outcome — `amount`, the previous patient/insurance balance and portion, and the new patient/insurance balance and portion; plus a `message` when nothing was transferred.

The markdown summary renders the action, direction, amount, and before → after balances/portions for both sides.