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

# billing.credit-settlement@1 · OpenVibe.Services

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

# BillingCreditSettlement `billing.credit-settlement@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-settlement.v1.json`](/docs/contracts/billing.credit-settlement.json)

billing.credit-settlement@1: the final charge for one inference hold. Carries the measured usage, the retail rate version applied, the supply-side cost, whether the route was BYOK, and any attempts/fallbacks. Money fields are integer nano-USD, as strings.

## Fields

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `settlement_id` | string | yes |  | - `pattern ^stl_[0-9A-HJKMNP-TV-Z]{26}$` |
| `hold_id` | string | yes |  | - `pattern ^hld_[0-9A-HJKMNP-TV-Z]{26}$` |
| `subject` | [identity.subject-ref](/docs/contracts/identity.subject-ref) | yes |  |  |
| `project_id` | string | yes |  | - `pattern ^prj_[0-9A-HJKMNP-TV-Z]{26}$` |
| `charge_nano_usd` | `https://openvibe.network/contracts/billing/credit-settlement.v1.json#/$defs/money-nano-usd` | yes |  |  |
| `released_nano_usd` | `https://openvibe.network/contracts/billing/credit-settlement.v1.json#/$defs/money-nano-usd` | yes |  |  |
| `journal_id` | string | yes |  | - `pattern ^txn_` |
| `usage` | `https://openvibe.network/contracts/billing/credit-settlement.v1.json#/$defs/token-usage` |  |  |  |
| `retail` | `https://openvibe.network/contracts/billing/credit-settlement.v1.json#/$defs/rate-versioned` |  |  |  |
| `supply_cost_nano_usd` | `https://openvibe.network/contracts/billing/credit-settlement.v1.json#/$defs/money-nano-usd` |  |  |  |
| `byok` | boolean |  | True when the caller supplied their own provider key; retail charge is 0. |  |
| `attempts` | array of object |  |  | - `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 |  |  |  |
| `created_at` | string |  |  | - `format date-time` |
| `shortfall_nano_usd` | string |  | Usage beyond the hold and the free balance: owed, not collected (nano-USD, D1). | - `pattern ^[0-9]{1,19}$` |

## Examples

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

 Valid: byok-zero

~~~~
{
  "settlement_id": "stl_01JAB2C3D4E5F6G7H8J9K0MNPR",
  "hold_id": "hld_01JAB2C3D4E5F6G7H8J9K0MNPR",
  "subject": {
    "type": "user",
    "id": "usr_01JAB2C3D4E5F6G7H8J9K0MNPQ"
  },
  "project_id": "prj_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "charge_nano_usd": "0",
  "released_nano_usd": "50000000",
  "journal_id": "txn_01JAB2C3D4E5F6G7H8J9K0MNPR",
  "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
    }
  ],
  "created_at": "2026-11-03T00:00:04.000Z"
}
~~~~

Valid: paid

~~~~
{
  "settlement_id": "stl_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "hold_id": "hld_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "subject": {
    "type": "user",
    "id": "usr_01JAB2C3D4E5F6G7H8J9K0MNPQ"
  },
  "project_id": "prj_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "charge_nano_usd": "18000",
  "released_nano_usd": "82000000",
  "journal_id": "txn_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "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
    }
  ],
  "created_at": "2026-11-03T00:00:05.000Z"
}
~~~~

Rejected: missing-usage

~~~~
{
  "settlement_id": "stl_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "hold_id": "hld_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "subject": {
    "type": "user",
    "id": "usr_01JAB2C3D4E5F6G7H8J9K0MNPQ"
  },
  "project_id": "prj_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "charge_nano_usd": "18000",
  "released_nano_usd": "82000000",
  "journal_id": "txn_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "usage": {
    "input_tokens": 1000,
    "cached_read_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: money-float

~~~~
{
  "settlement_id": "stl_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "hold_id": "hld_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "subject": {
    "type": "user",
    "id": "usr_01JAB2C3D4E5F6G7H8J9K0MNPQ"
  },
  "project_id": "prj_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "charge_nano_usd": "18.5",
  "released_nano_usd": "82000000",
  "journal_id": "txn_01JAB2C3D4E5F6G7H8J9K0MNPQ"
}
~~~~

Rejected: money-number

~~~~
{
  "settlement_id": "stl_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "hold_id": "hld_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "subject": {
    "type": "user",
    "id": "usr_01JAB2C3D4E5F6G7H8J9K0MNPQ"
  },
  "project_id": "prj_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "charge_nano_usd": 18000,
  "released_nano_usd": "82000000",
  "journal_id": "txn_01JAB2C3D4E5F6G7H8J9K0MNPQ"
}
~~~~

## Validate

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