kelviq.config.ts reference

kelviq.config.ts is a plain TypeScript file that declares your pricing catalog. You author it by hand (starting from kelviq init) or generate it from a live environment with kelviq pull — the two are interchangeable starting points. The format follows one design idea: the file describes the desired state of your catalog, and nothing else. Anything that’s an artifact of a particular deployment — UUIDs, draft/published status, server-generated timestamps — stays out, which is what makes the same file portable across sandbox and production and meaningful to diff over time. It’s TypeScript rather than YAML or JSON for one reason: types. Your editor autocompletes every field, invalid enums fail to compile, and a config that type-checks is a config the CLI can read. A config file imports three builders from @kelviq/cli/config and exports the results:

import { product, feature, plan } from '@kelviq/cli/config';

export const app = product({
  identifier: 'my-app',
  name: 'My App',
  taxCode: 'saas',
});

export const apiCalls = feature({
  identifier: 'api-calls',
  name: 'API calls',
  type: 'METER',
  featureDetails: {
    featureSubType: 'PRE_AGGREGATED_USAGE',
    units: { singular: 'call', plural: 'calls' },
  },
});

export const historyRetention = feature({
  identifier: 'history-retention',
  name: 'History retention (days)',
  type: 'CUSTOMIZABLE',
});

export const pro = plan({
  identifier: 'pro',
  name: 'Pro',
  product: 'my-app',
  entitlements: [
    { feature: 'history-retention', value: 30 },
    { feature: 'api-calls', value: 10000, reset: 'EVERY_MONTH', hardLimit: false },
  ],
  prices: [
    {
      priceType: 'PAID',
      currency: 'USD',
      freeTrial: false,
      trialPeriod: 0,
      enabled: true,
      taxBehavior: 'EXCLUSIVE',
      chargeCatalogPrice: [
        {
          feature: null,
          priceModel: 'FLAT',
          paymentType: 'ADVANCE_COMMITMENT',
          reset: 'NEVER',
          charges: [
            { chargePeriod: 'MONTHLY', priceData: { amount: 29 } },
            { chargePeriod: 'YEARLY', priceData: { amount: 290 } },
          ],
        },
      ],
    },
  ],
});

The builders are typed: your editor autocompletes every field, and a misspelled or wrongly-typed field is a compile-time error with a “did you mean” suggestion — validation happens before any API call. How the CLI reads the file: every export created by product() / feature() / plan() is collected, regardless of its export name. Other exports (helper constants, functions) are ignored, so you can organize the file however you like — split values, comment freely, generate plans in a loop. Duplicate identifiers within a kind are a hard error.

The identity rule

Every cross-reference in the format — plan.product, entitlements[].feature — is an identifier slug, never a UUID. Identifiers are lowercase URL-safe slugs matching ^[a-z0-9][a-z0-9-_]*$ (for example pro, api-calls, seats_v2). The Kelviq API sometimes wants UUIDs internally; the CLI resolves identifiers to UUIDs at sync time so your config file stays portable — the same file works against sandbox and production, where the same catalog has different UUIDs. The plan lifecycle (draft → published) is also deliberately absent: the config describes desired state, not deployment state. Lifecycle is handled at sync time.

product()

Field	Type	Required	Description
`identifier`	slug	yes	Stable identifier, the join key across environments.
`name`	string	yes	Display name.
`taxCode`	enum	yes	One of: `saas`, `saas_business`, `software`, `videocontent`, `informationservice`, `ebook`, `digitalgraphic`, `videogame`, `eservice`, `training`.
`description`	string	no	Free-text description.

feature()

Field	Type	Required	Description
`identifier`	slug	yes	Stable identifier, referenced from plan entitlements.
`name`	string	yes	Display name.
`type`	enum	yes	`BOOLEAN` (on/off), `CUSTOMIZABLE` (a setting the plan configures, such as days of history retention), or `METER` (a counted quantity — usage that resets, or seats a customer buys). Seats are a `METER`, not `CUSTOMIZABLE`: only a meter can carry a per-unit price and take a quantity at checkout — see seat-based pricing.
`description`	string	no	Free-text description.
`featureDetails`	object	for `METER`	Type-specific detail payload, passed through to the API. A `METER` feature needs `featureSubType` (`PRE_AGGREGATED_USAGE`) and `units` (`{ singular, plural }`): `kelviq push` refuses to create one without them, before writing anything, because the API rejects it. See Create a feature.
`meter`	object	no	Meter configuration for `METER` features, passed through to the API.
`metadata`	object	no	Arbitrary key-value metadata.

plan()

Field	Type	Required	Description
`identifier`	slug	yes	Stable identifier.
`name`	string	yes	Display name.
`product`	slug	yes	Identifier of the parent product.
`description`	string	no	Free-text description.
`isVisible`	boolean	no	Whether the plan is publicly visible.
`license`	object	no	License-key issuance settings for orders on this plan — see below.
`entitlements`	array	no	What the plan grants — see below.
`prices`	array	no	The plan’s price set — see below.
`metadata`	object	no	Arbitrary key-value metadata.

Entitlements

Each entry grants a feature to the plan:

Field	Type	Required	Description
`feature`	slug	yes	Identifier of the granted feature.
`value`	boolean or number	no	The grant: `true`/`false` for `BOOLEAN` features, a number for limits.
`hasUnlimitedUsage`	boolean	no	Grant unlimited usage instead of a numeric value. Omit `value` when this is `true`; `kelviq pull` writes unlimited entitlements this way.
`reset`	enum	no	Usage reset cadence: `NEVER`, `EVERY_DAY`, `EVERY_28_DAYS`, `EVERY_MONTH`, `EVERY_QUARTER`, `EVERY_YEAR`.
`hardLimit`	boolean	no	Whether usage is blocked at the limit.
`usageAlerts`	object	no	Alert configuration, passed through to the API.

Entitlements accept additional keys beyond these — the shape varies by feature type, and unrecognized keys are passed through to the API rather than rejected.

Some enum values (for example EVERY_28_DAYS) are only available when enabled for your account. The CLI’s enum fields autocomplete the standard values but accept any string: values it doesn’t recognize are passed through verbatim, and the API validates them when you push. This means new server-side values work without a CLI update.

License keys

When license keys are enabled on a plan, every order generates a key. The license object holds the plan-level issuance settings — the same controls as the dashboard’s License keys section:

export const team = plan({
  identifier: 'team',
  name: 'Team',
  product: 'my-app',
  license: {
    enabled: true,
    activationLimitEnabled: true,
    activationLimit: 5,        // up to 5 devices per key
    hasExpiry: true,
    durationValue: 12,
    durationUnit: 'MONTH',     // keys expire 12 months after purchase
  },
});

Field	Type	Required	Description
`enabled`	boolean	no	Whether orders for this plan issue license keys.
`activationLimitEnabled`	boolean	no	Cap how many devices one key can be activated on. When `false`, activations are unlimited.
`activationLimit`	integer ≥ 1	no	The cap, when `activationLimitEnabled` is `true`.
`hasExpiry`	boolean	no	Whether keys expire. When `false`, keys never expire.
`durationValue`	integer ≥ 1	no	How long a key stays valid after purchase, in `durationUnit`s.
`durationUnit`	enum	no	`DAY`, `MONTH`, or `YEAR`.

The object is compared and sent as one unit: kelviq push shows the old and new license config side by side and sends the whole object when anything in it differs. A plan that omits license leaves the remote license settings untouched, so a config file that doesn’t mention license keys never disables them. Additional keys are passed through to the API. Individual issued keys — activating, validating, or deactivating a customer’s key — are per-customer runtime operations, not catalog state. They live in the API, the SDKs, and the MCP server, not in this file.

Prices

The price envelope is validated; the charge structures inside it are deliberately loose and passed through to the API as-is:

Field	Type	Required	Description
`priceType`	enum	yes	`FREE`, `PAID`, or `CUSTOM`.
`currency`	string	no	ISO currency code, e.g. `USD`.
`freeTrial`	boolean	no	Whether the price includes a free trial.
`trialPeriod`	number	no	Trial length in days.
`taxBehavior`	enum	no	`INCLUSIVE`, `EXCLUSIVE`, or `UNSPECIFIED`.
`enabled`	boolean	no	Whether the price is available for purchase.
`chargeCatalogPrice`	array of objects	no	The full charge structure (price models, tiers, billing periods). Passed through verbatim — see the plan-prices endpoints in the API Reference for the shape.

A pulled config reproduces your remote prices in full, including nested charge structures. To author one by hand, start from kelviq init --template saas|usage|license or pull an existing plan and adapt it. Fields you leave out — freeTrial, taxBehavior, a charge’s paymentType or reset — take the server’s defaults, and kelviq push compares prices only on the fields you set, so leaving them out never shows up as a change.

Schemas as values

Everything the builders validate against is exported from @kelviq/cli/config if you want to reuse it — productDefSchema, featureDefSchema, planDefSchema, entitlementDefSchema, priceDefSchema, licenseDefSchema, kelviqConfigSchema, the enums (taxCodeSchema, featureTypeSchema, priceTypeSchema, resetSchema, taxBehaviorSchema, durationUnitSchema, identifierSchema), and their TypeScript types (ProductDef, FeatureDef, PlanDef, LicenseDef, and so on). They’re standard Zod schemas.

Backend Integration

Frontend Integration

Promotions UI

CLI

The identity rule

product()

feature()

plan()

Entitlements

License keys

Prices

Schemas as values

​The identity rule

​product()

​feature()

​plan()

​Entitlements

​License keys

​Prices

​Schemas as values

The identity rule

product()

feature()

plan()

Entitlements

License keys

Prices

Schemas as values