BillingCreditSettlement `billing.credit-settlement@1`

Generated at 2026-11-13 06:25:48 UTC from openvibe-contracts v0.419.0 and openvibe-sdk 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

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	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 }] }

BillingCreditSettlement billing.credit-settlement@1

Fields

Examples

Validate

BillingCreditSettlement `billing.credit-settlement@1`