Policy Reference

A single document for your entire pricing & enforcement.

The policy is the source of truth for everything Limitr does at runtime — enforcement, metering, margin, and alerting. This section documents every field, type, constraint, and behavior.

---

What a policy is

A Limitr policy is a document. You write it in YAML, JSON, TOML, or Stof. At runtime it's parsed into the Limitr type — a WebAssembly-powered object that runs in-process with your application. There are no network calls on the enforcement path.

The top-level structure:

policy:
  credits: {}       # Credit definitions
  exchange: {}      # Exchange table
  plans: {}         # Plan definitions (entitlements, topups)
  notifications: {} # In-policy event handlers (optional)
  customers: {}     # Customer state (managed by the SDK)
  capabilities: {}  # Callable policy logic (Cloud/Network)

You define credits, exchange, plans, and notifications. The SDK manages customers. capabilities are an advanced Cloud and Limitr Network concept.

---

Loading a policy

Local (open source)

import { Limitr } from '@formata/limitr';
import { readFileSync } from 'fs';

// From a file
const policy = await Limitr.new(readFileSync('./policy.yaml', 'utf-8'), 'yaml');

// From a string
const policy = await Limitr.new(`
  policy:
    credits:
      seats:
        overhead_cost: 0
`, 'yaml');

// Supported formats: 'yaml' | 'json' | 'toml' | 'stof'

Limitr.new() initializes WebAssembly and validates the policy before returning. Throws on validation failure.

Cloud (managed)

const policy = await Limitr.cloud({ token: 'limitr_...' });

Your policy lives in the Cloud dashboard. The SDK connects and syncs it automatically. The policy.allow() call — and every other enforcement call — is identical to local. Nothing in your application code changes.

---

Validation

Every Limitr.new() call validates the policy by default. To skip validation (not recommended in production):

const policy = await Limitr.new(doc, 'yaml', false); // third arg: validate

To validate manually after loading:

const [valid, error] = await policy.valid();
if (!valid) console.error(error);

---

Serializing the policy document

The policy document is fully serializable at any time. Useful for driving pricing UI, syncing state, or inspecting the policy at runtime.

const json = policy.doc.stringify('json');
const yaml = policy.doc.stringify('yaml');
const toml = policy.doc.stringify('toml');
const obj  = policy.doc.record();  // plain JS object

---

Reference pages

Page	What it covers
Credits	Credit types, pricing models, units, overhead cost and price
Exchange	Rune system, exchange pairs, grant strategy, credit conversion
Plans	Plan structure, billing period, subscription, trial period
Entitlements	Entitlement and limit types, modes, resets, scope, overrides
Customers	Customer type, refs, alt IDs, overrides, metadata
Topups & Grants	Topup definitions, grant lifecycle, reset modes, rollover
Enforcement	allow, increment, decrement, check, value, remaining, events
Margin	customerMarginSnapshot, marginSnapshot, overhead_cost and price
Notifications	Notification type, event matching, in-process and Cloud routing