Skip to main content
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; for detaching a payment (which optionally does the same patient→insurance move afterward), see 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.

​
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).
  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

​
Partial Transfer Example

​
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.