---
title: "billing.credit-hold-settle-request@1 · OpenVibe.Services"
canonical: "https://openvibe.services/docs/contracts/billing.credit-hold-settle-request"
updated: null
---

# billing.credit-hold-settle-request@1 · OpenVibe.Services

HTML: [billing.credit-hold-settle-request@1 · OpenVibe.Services](https://openvibe.services/docs/contracts/billing.credit-hold-settle-request)

# BillingCreditHoldSettleRequest `billing.credit-hold-settle-request@1`

Generated at 2026-11-13 06:25:48 UTC from [`openvibe-contracts v0.419.0`](https://github.com/OpenVibers/OpenVibe.Contracts/tree/v0.419.0) and [`openvibe-sdk v0.161.0`](https://github.com/OpenVibers/OpenVibe.SDK/tree/v0.161.0).

- Version: 1.0.0
- Owner: billing
- Visibility: internal
- Status: active
- Compatibility: backward
- Schema: [`https://openvibe.network/contracts/billing/credit-hold-settle-request.v1.json`](/docs/contracts/billing.credit-hold-settle-request.json)

billing.credit-hold-settle-request@1: body of POST /internal/credits/holds/:id/settle. Idempotent: the same key and fingerprint return the same settlement.

## Fields

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `idempotency_key` | string | yes |  | - `pattern ^[A-Za-z0-9._:-]{8,128}$` |
| `usage` | object | yes |  | - `no other fields` |
| `usage.input_tokens` | integer | yes |  | - `minimum 0` |
| `usage.cached_read_tokens` | integer | yes |  | - `minimum 0` |
| `usage.cache_write_tokens` | integer | yes |  | - `minimum 0` |
| `usage.output_tokens` | integer | yes |  | - `minimum 0` |
| `retail` | object | yes |  | - `no other fields` |
| `retail.version` | string | yes |  |  |
| `retail.nano_usd_per_m` | object | yes |  | - `no other fields` |
| `retail.nano_usd_per_m.input` | `https://openvibe.network/contracts/billing/credit-hold-settle-request.v1.json#/$defs/money-nano-usd` | yes |  |  |
| `retail.nano_usd_per_m.cached_read` | `https://openvibe.network/contracts/billing/credit-hold-settle-request.v1.json#/$defs/money-nano-usd` | yes |  |  |
| `retail.nano_usd_per_m.cache_write` | `https://openvibe.network/contracts/billing/credit-hold-settle-request.v1.json#/$defs/money-nano-usd` | yes |  |  |
| `retail.nano_usd_per_m.output` | `https://openvibe.network/contracts/billing/credit-hold-settle-request.v1.json#/$defs/money-nano-usd` | yes |  |  |
| `retail.per_request_nano_usd` | `https://openvibe.network/contracts/billing/credit-hold-settle-request.v1.json#/$defs/money-nano-usd` | yes |  |  |
| `supply_cost_nano_usd` | `https://openvibe.network/contracts/billing/credit-hold-settle-request.v1.json#/$defs/money-nano-usd` | yes |  |  |
| `byok` | boolean | yes |  |  |
| `attempts` | array of object | yes |  | - `items: no other fields` |
| `attempts[].deployment_id` | string | yes |  |  |
| `attempts[].provider_access` | enum |  |  | - `one of "OWN_DEPLOYMENT", "AUTHORIZED_WHOLESALE", "CUSTOMER_BYOK", "RESTRICTED", "UNVERIFIED"` |
| `attempts[].started_at` | string | yes |  | - `format date-time` |
| `attempts[].ended_at` | string | yes |  | - `format date-time` |
| `attempts[].error_code` | string \| null |  |  |  |

## Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

 Valid: byok

~~~~
{
  "idempotency_key": "settle-key-002",
  "usage": {
    "input_tokens": 500,
    "cached_read_tokens": 0,
    "cache_write_tokens": 0,
    "output_tokens": 200
  },
  "retail": {
    "version": "rr-2026-11-03-001",
    "nano_usd_per_m": {
      "input": "0",
      "cached_read": "0",
      "cache_write": "0",
      "output": "0"
    },
    "per_request_nano_usd": "0"
  },
  "supply_cost_nano_usd": "0",
  "byok": true,
  "attempts": [
    {
      "deployment_id": "dep-owner-byok",
      "provider_access": "CUSTOMER_BYOK",
      "started_at": "2026-11-03T00:00:01.000Z",
      "ended_at": "2026-11-03T00:00:04.000Z",
      "error_code": null
    }
  ]
}
~~~~

Valid: full

~~~~
{
  "idempotency_key": "settle-key-001",
  "usage": {
    "input_tokens": 1000,
    "cached_read_tokens": 0,
    "cache_write_tokens": 0,
    "output_tokens": 500
  },
  "retail": {
    "version": "rr-2026-11-03-001",
    "nano_usd_per_m": {
      "input": "3000",
      "cached_read": "300",
      "cache_write": "3000",
      "output": "15000"
    },
    "per_request_nano_usd": "0"
  },
  "supply_cost_nano_usd": "9000",
  "byok": false,
  "attempts": [
    {
      "deployment_id": "dep-qwen-9b-us-east-001",
      "provider_access": "OWN_DEPLOYMENT",
      "started_at": "2026-11-03T00:00:01.000Z",
      "ended_at": "2026-11-03T00:00:05.000Z",
      "error_code": null
    }
  ]
}
~~~~

Rejected: missing-key

~~~~
{
  "usage": {
    "input_tokens": 1000,
    "cached_read_tokens": 0,
    "cache_write_tokens": 0,
    "output_tokens": 500
  },
  "retail": {
    "version": "rr-2026-11-03-001",
    "nano_usd_per_m": {
      "input": "3000",
      "cached_read": "300",
      "cache_write": "3000",
      "output": "15000"
    },
    "per_request_nano_usd": "0"
  },
  "supply_cost_nano_usd": "9000",
  "byok": false,
  "attempts": []
}
~~~~

Rejected: missing-usage

~~~~
{
  "idempotency_key": "settle-key-001",
  "retail": {
    "version": "rr-2026-11-03-001",
    "nano_usd_per_m": {
      "input": "3000",
      "cached_read": "300",
      "cache_write": "3000",
      "output": "15000"
    },
    "per_request_nano_usd": "0"
  },
  "supply_cost_nano_usd": "9000",
  "byok": false,
  "attempts": []
}
~~~~

Rejected: money-number

~~~~
{
  "idempotency_key": "settle-key-001",
  "usage": {
    "input_tokens": 1000,
    "cached_read_tokens": 0,
    "cache_write_tokens": 0,
    "output_tokens": 500
  },
  "retail": {
    "version": "rr-2026-11-03-001",
    "nano_usd_per_m": {
      "input": "3000",
      "cached_read": "300",
      "cache_write": "3000",
      "output": 15000
    },
    "per_request_nano_usd": "0"
  },
  "supply_cost_nano_usd": "9000",
  "byok": false,
  "attempts": []
}
~~~~

## Validate

~~~~
const contracts = require('openvibe-contracts');
contracts.validate('billing.credit-hold-settle-request@1', value);   // { valid, errors: [{ path, message }] }
~~~~