Fund Existing Milestone with Admin Balance

Applies OpenTrain’s restricted ADMIN_BALANCE funding marker to one existing eligible NOT_FUNDED milestone. The operation updates that milestone in place; it never creates a replacement contract or milestone.

This endpoint is available only to eligible OpenTrain platform administrators in the canonical admin organization. It is deliberately separate from ordinary employer milestone funding, and it does not accept a client-controlled funding source.

Success transitions the existing milestone to ACTIVE_FUNDED, moves $0, and creates no Stripe charge or PaymentIntent. Releasing payment later remains a separate human-authorized action.

Authorization and validation

The server independently verifies every restricted platform-admin condition described on Create Admin-Balance Milestone. It also verifies that:

• the milestone belongs to the named contract and authorized organization;
• the milestone is still eligible and NOT_FUNDED;
• its amount, contract rate, and volume are internally consistent; and
• sequencing and unresolved-payment rules allow funding.

Request

contractIdstringpathrequired

Contract that must own the milestone.

milestoneIdstringpathrequired

Existing eligible NOT_FUNDED milestone.

idempotencyKeystringbodyrequired

Stable request key, 1–128 characters. Identical retries return the original result; conflicting reuse fails closed.

No funding-source field is accepted.

Response

Returns 200. The result includes the contract and job IDs, the existing milestone ID and new status, fundingSource: "ADMIN_BALANCE", moneyMoved: false, releaseRequiresHumanApproval: true, and idempotentReplay.

TypeScript SDK

@opentrain-ai/sdk 0.22.0 or later exposes the same operation:

import { OpenTrainClient } from '@opentrain-ai/sdk';

const opentrain = new OpenTrainClient({
  apiToken: process.env.OPENTRAIN_API_TOKEN!,
});

const result = await opentrain.fundAdminBalanceMilestone(
  '<CONTRACT_ID>',
  '<MILESTONE_ID>',
  { idempotencyKey: 'fund-existing-milestone-2026-09' }
);

Errors

Status	Meaning
400	Invalid key or internally inconsistent amount/rate/volume data
401	Missing or invalid token
403	A restricted authorization condition failed, or a payment hold blocks the operation
404	Contract or milestone not found within the authorized organization boundary
409	Idempotency conflict, ineligible milestone state, existing funding-source conflict, or sequencing blocker

Request examples

curlCLIMCP: opentrain_fund_admin_balance_milestone

curl

curl -sS -X POST https://app.opentrain.ai/api/public/v1/contracts/<CONTRACT_ID>/admin-balance-milestones/<MILESTONE_ID>/fund \
  -H "Authorization: Bearer $OT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"idempotencyKey":"fund-existing-milestone-2026-09"}'

CLI

opentrain admin-balance-milestones fund \
  --contract-id <CONTRACT_ID> \
  --milestone-id <MILESTONE_ID> \
  --idempotency-key fund-existing-milestone-2026-09 \
  --json

MCP: opentrain_fund_admin_balance_milestone

{
  "contractId": "<CONTRACT_ID>",
  "milestoneId": "<MILESTONE_ID>",
  "idempotencyKey": "fund-existing-milestone-2026-09"
}