Sustema

ENTITY developer reference

CreditBalances

Candidate documentation for reading and synthetic examples. Account creation, live API access, SDKs, collections and MCP are not available here. A released service profile and matching integration instructions are required before use.

This is a documentation reading view of an unreleased candidate, not a downloadable replacement schema. Public wire names, types and constraints are retained except for the explicitly marked private-only subsets and route patterns. Private governance references are explained in public language. Use only a separately released, verified generation for clients. Read the explicit exclusions.

This is the public candidate schema reading view. Read it with the operation that uses it; a representable field does not establish enabled coverage or entitlement.

One authoritative funding-ledger projection, in this owned workspace/environment and current unit/scale. Total available is subscription_available_units + top_up_available_units + service_adjustment_available_units. Only active, unexpired, otherwise eligible grants enter available; reserved, held, pending, expired and revoked amounts do not. Service adjustments retain their original permitted product/target scope; totals and spendable_at_snapshot are upper bounds, never permission to spend restricted grants on another operation. Every proposed operation intersects scope, terms, rights, duration and current ceilings before reservation. Pending is qualified intended credit, not granted/spendable money. next_service_adjustment_expiry_at is the earliest original expiry among active unexpired grants with available or reserved units; null if none. No extra balance, rollover, cap reset or unit-to-money conversion.

Declared type: "object"

Declared fields

This list shows only properties declared directly in this schema. Required labels refer only to this schema’s own required array. Referenced, composed and conditional rules can add constraints; a field not listed as required here is not guaranteed to be optional.

subscription_available_units

Listed in this schema’s required array.

Declared type
"string"
Reading definition for subscription_available_units
{
  "type": "string",
  "pattern": "^(0|[1-9][0-9]*)$",
  "x-profile-maxLength": "string_characters_max",
  "maxLength": 30
}

top_up_available_units

Listed in this schema’s required array.

Declared type
"string"
Reading definition for top_up_available_units
{
  "type": "string",
  "pattern": "^(0|[1-9][0-9]*)$",
  "x-profile-maxLength": "string_characters_max",
  "maxLength": 30
}

top_up_reserved_units

Listed in this schema’s required array.

Declared type
"string"
Reading definition for top_up_reserved_units
{
  "type": "string",
  "pattern": "^(0|[1-9][0-9]*)$",
  "x-profile-maxLength": "string_characters_max",
  "maxLength": 30
}

top_up_held_units

Listed in this schema’s required array.

Declared type
"string"
Reading definition for top_up_held_units
{
  "type": "string",
  "pattern": "^(0|[1-9][0-9]*)$",
  "x-profile-maxLength": "string_characters_max",
  "maxLength": 30
}

total_available_units

Listed in this schema’s required array.

Declared type
"string"
Reading definition for total_available_units
{
  "type": "string",
  "pattern": "^(0|[1-9][0-9]*)$",
  "x-profile-maxLength": "string_characters_max",
  "maxLength": 30
}

next_top_up_expiry_at

Listed in this schema’s required array.

Declared type
Not declared directly; consult the complete field definition.
Reading definition for next_top_up_expiry_at
{
  "anyOf": [
    {
      "type": "string",
      "format": "date-time",
      "x-profile-maxLength": "string_characters_max"
    },
    {
      "type": "null"
    }
  ]
}

replenishment_status

Listed in this schema’s required array.

Declared type
"string"
Reading definition for replenishment_status
{
  "type": "string",
  "enum": [
    "not_applicable",
    "disabled",
    "setup_required",
    "armed",
    "payment_pending",
    "payment_action_required",
    "failed",
    "cap_reached",
    "paused",
    "unavailable"
  ],
  "x-profile-maxLength": "string_characters_max"
}

recovery_path

Listed in this schema’s required array.

Declared type
Not declared directly; consult the complete field definition.
Reading definition for recovery_path
{
  "anyOf": [
    {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "x-profile-maxLength": "string_characters_max"
    },
    {
      "type": "null"
    }
  ]
}

service_adjustment_available_units

Listed in this schema’s required array.

Declared type
"string"
Reading definition for service_adjustment_available_units
{
  "type": "string",
  "pattern": "^(0|[1-9][0-9]*)$",
  "maxLength": 30,
  "x-profile-maxLength": "string_characters_max"
}

service_adjustment_reserved_units

Listed in this schema’s required array.

Declared type
"string"
Reading definition for service_adjustment_reserved_units
{
  "type": "string",
  "pattern": "^(0|[1-9][0-9]*)$",
  "maxLength": 30,
  "x-profile-maxLength": "string_characters_max"
}

service_adjustment_held_units

Listed in this schema’s required array.

Declared type
"string"
Reading definition for service_adjustment_held_units
{
  "type": "string",
  "pattern": "^(0|[1-9][0-9]*)$",
  "maxLength": 30,
  "x-profile-maxLength": "string_characters_max"
}

service_adjustment_pending_units

Listed in this schema’s required array.

Declared type
"string"
Reading definition for service_adjustment_pending_units
{
  "type": "string",
  "pattern": "^(0|[1-9][0-9]*)$",
  "maxLength": 30,
  "x-profile-maxLength": "string_characters_max"
}

next_service_adjustment_expiry_at

Listed in this schema’s required array.

Declared type
Not declared directly; consult the complete field definition.
Reading definition for next_service_adjustment_expiry_at
{
  "anyOf": [
    {
      "type": "string",
      "format": "date-time",
      "x-profile-maxLength": "string_characters_max"
    },
    {
      "type": "null"
    }
  ]
}

Schema reading view

Read all retained constraints, including any allOf, oneOf, anyOf, conditional and additional-property constraints. The field list does not combine branches. Explicitly marked private-only omissions mean this view is not an executable substitute for the original schema or a released contract.

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "subscription_available_units": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]*)$",
      "x-profile-maxLength": "string_characters_max",
      "maxLength": 30
    },
    "top_up_available_units": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]*)$",
      "x-profile-maxLength": "string_characters_max",
      "maxLength": 30
    },
    "top_up_reserved_units": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]*)$",
      "x-profile-maxLength": "string_characters_max",
      "maxLength": 30
    },
    "top_up_held_units": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]*)$",
      "x-profile-maxLength": "string_characters_max",
      "maxLength": 30
    },
    "total_available_units": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]*)$",
      "x-profile-maxLength": "string_characters_max",
      "maxLength": 30
    },
    "next_top_up_expiry_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "x-profile-maxLength": "string_characters_max"
        },
        {
          "type": "null"
        }
      ]
    },
    "replenishment_status": {
      "type": "string",
      "enum": [
        "not_applicable",
        "disabled",
        "setup_required",
        "armed",
        "payment_pending",
        "payment_action_required",
        "failed",
        "cap_reached",
        "paused",
        "unavailable"
      ],
      "x-profile-maxLength": "string_characters_max"
    },
    "recovery_path": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "x-profile-maxLength": "string_characters_max"
        },
        {
          "type": "null"
        }
      ]
    },
    "service_adjustment_available_units": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]*)$",
      "maxLength": 30,
      "x-profile-maxLength": "string_characters_max"
    },
    "service_adjustment_reserved_units": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]*)$",
      "maxLength": 30,
      "x-profile-maxLength": "string_characters_max"
    },
    "service_adjustment_held_units": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]*)$",
      "maxLength": 30,
      "x-profile-maxLength": "string_characters_max"
    },
    "service_adjustment_pending_units": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]*)$",
      "maxLength": 30,
      "x-profile-maxLength": "string_characters_max"
    },
    "next_service_adjustment_expiry_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "x-profile-maxLength": "string_characters_max"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "subscription_available_units",
    "top_up_available_units",
    "top_up_reserved_units",
    "top_up_held_units",
    "total_available_units",
    "next_top_up_expiry_at",
    "replenishment_status",
    "recovery_path",
    "service_adjustment_available_units",
    "service_adjustment_reserved_units",
    "service_adjustment_held_units",
    "service_adjustment_pending_units",
    "next_service_adjustment_expiry_at"
  ],
  "description": "One authoritative funding-ledger projection, in this owned workspace/environment and current unit/scale. Total available is subscription_available_units + top_up_available_units + service_adjustment_available_units. Only active, unexpired, otherwise eligible grants enter available; reserved, held, pending, expired and revoked amounts do not. Service adjustments retain their original permitted product/target scope; totals and spendable_at_snapshot are upper bounds, never permission to spend restricted grants on another operation. Every proposed operation intersects scope, terms, rights, duration and current ceilings before reservation. Pending is qualified intended credit, not granted/spendable money. next_service_adjustment_expiry_at is the earliest original expiry among active unexpired grants with available or reserved units; null if none. No extra balance, rollover, cap reset or unit-to-money conversion."
}

All API operations