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

# Create Admin-Balance Milestone

> Create and internally fund a later milestone through OpenTrain's restricted platform-admin workflow.

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

<ParamField path="contractId" type="string" required>
  Contract that will own the new milestone.
</ParamField>

<ParamField body="idempotencyKey" type="string" required>
  Stable request key, 1–128 characters. Reuse it only for an identical retry.
</ParamField>

<ParamField body="milestone.description" type="string" required>
  Work covered by the milestone.
</ParamField>

<ParamField body="milestone.amountUsd" type="number" required>
  Positive milestone amount in USD.
</ParamField>

<ParamField body="milestone.volume" type="number">
  Positive hours or labels for a volume-based contract. Omit to derive it from the amount and canonical rate.
</ParamField>

<ParamField body="milestone.name" type="string">
  Optional short milestone name.
</ParamField>

<ParamField body="milestone.dueDate" type="string">
  Optional ISO 8601 due date.
</ParamField>

## 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:

```ts theme={null}
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 |

<RequestExample>
  ```bash curl theme={null}
  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
      }
    }'
  ```

  ```bash CLI theme={null}
  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
  ```

  ```json MCP: opentrain_create_admin_balance_milestone theme={null}
  {
    "contractId": "<CONTRACT_ID>",
    "idempotencyKey": "later-milestone-2026-09",
    "name": "Approved bonus",
    "description": "Complete the approved bonus work",
    "amountUsd": 300,
    "volume": 2.5
  }
  ```
</RequestExample>