Create Admin-Balance Milestone

Creates a later milestone and marks it ACTIVE_FUNDED through OpenTrain’s restricted internal-balance workflow. This endpoint is for eligible OpenTrain platform administrators in the canonical admin organization; it is not an alternative funding method for ordinary employers.

At the funding step, the operation moves $0 and creates no Stripe charge or PaymentIntent. Releasing the funded milestone later is a separate action that still requires human authorization.

For hourly and per-label contracts, send a positive volume or omit it so OpenTrain derives the value from amountUsd and the canonical contract rate. When all three values are present, they must agree.

Authorization

The server independently verifies the restricted scope, claimed account, platform-admin status, canonical admin-organization membership, Admin Pay eligibility, matching token organization, target organization, and the default-off rollout. Possessing the scope alone never grants access.

Request

contractIdstringpathrequired

Contract that will own the new milestone.

idempotencyKeystringbodyrequired

Stable request key, 1–128 characters. Reuse it only for an identical retry.

milestone.descriptionstringbodyrequired

Work covered by the milestone.

milestone.amountUsdnumberbodyrequired

Positive milestone amount in USD.

milestone.volumenumberbody

Positive hours or labels for a volume-based contract. Omit to derive it from the amount and canonical rate.

milestone.namestringbody

Optional short milestone name.

milestone.dueDatestringbody

Optional ISO 8601 due date.

Response

Returns 201 for a new milestone or 200 for an identical idempotent replay. The result includes the contract and job IDs, the milestone ID and 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.createAdminBalanceMilestone('<CONTRACT_ID>', {
  idempotencyKey: 'later-milestone-2026-09',
  milestone: {
    description: 'Complete the approved bonus work',
    amountUsd: 300,
    volume: 2.5,
  },
});

Errors

Status	Meaning
400	Invalid key or milestone fields, including an invalid or inconsistent volume
401	Missing or invalid token
403	One or more restricted platform-admin authorization conditions failed
404	Contract not found within the authorized organization boundary
409	Conflicting idempotency reuse, an in-progress request, or a milestone sequencing conflict

Request examples

curlCLIMCP: opentrain_create_admin_balance_milestone

curl

curl -sS -X POST https://app.opentrain.ai/api/public/v1/contracts/<CONTRACT_ID>/admin-balance-milestones \
  -H "Authorization: Bearer $OT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "later-milestone-2026-09",
    "milestone": {
      "name": "Approved bonus",
      "description": "Complete the approved bonus work",
      "amountUsd": 300,
      "volume": 2.5
    }
  }'

CLI

opentrain admin-balance-milestones create \
  --contract-id <CONTRACT_ID> \
  --idempotency-key later-milestone-2026-09 \
  --description "Complete the approved bonus work" \
  --name "Approved bonus" \
  --amount 300 \
  --volume 2.5 \
  --json

MCP: opentrain_create_admin_balance_milestone

{
  "contractId": "<CONTRACT_ID>",
  "idempotencyKey": "later-milestone-2026-09",
  "name": "Approved bonus",
  "description": "Complete the approved bonus work",
  "amountUsd": 300,
  "volume": 2.5
}