Metadata-driven configuration

Vluna has several configuration points that use JSON objects. This page defines the keys that are currently consumed by system behavior.

Use this page for semantic contracts. For endpoint schema details, use API reference.

Design rule

• If a JSON key is listed here, runtime or orchestration logic reads it.
• If a JSON key is not listed here, treat it as application-owned annotation only.

Plan metadata

Object: billing_plans.metadata

Supported keys

Key path	Purpose
gate_bundle_key	Selects the runtime gate bundle for this plan/package.
grants[]	Declares strict per-program issuance-period targets for active plan assignments.
billing_defaults.period.billing_mode	Plan-level billing mode default.
billing_defaults.period.issue_anchor	Plan-level issue anchor default.

Priority notes

• For bundle key resolution, plan metadata is the runtime source of truth.
• For billing defaults, assignment metadata can override plan metadata.
• Every plan grant requires exactly grant_program_code and non-negative integer-string amount_xusd.
• A program may occur only once per plan. Plan grant bindings do not accept template identity, arbitrary metadata, quantity scaling, or structural overrides; those semantics belong to the grant program.
• Vluna does not impose a plan-versioning policy. Updating a plan changes the target observed by its active assignments on subsequent reconciliation; existing ledger grant lots remain unchanged.

Related guides:

• Plans overview
• Plan assignments
• Gate policies and bundles

Feature and meter metadata

Objects:

• meters.metadata
• feature_families.metadata
• features.metadata

Pricing metadata

Meter metadata does not select a pricing algorithm or residual mode. Meter prices use exact unit-price/reference-quantity fields, and revenue/cost rating always uses integer_rational_floor_v1.

Internal keys

• Auto-registration flows may write metadata markers such as auto, source, and fallback on feature families/features/meters.
• Treat these markers as system-internal state, not integration contract keys.

Related guide:

• Features and meters

Catalog metadata

Objects:

• catalog_products.metadata
• catalog_prices.metadata

Supported keys

Key path	Purpose
billing_plan_code	Maps a purchased price to a billing plan assignment flow.
grants[]	Declares grant bindings for purchase-driven issuance.
gate_bundle_key	Optional catalog packaging input that should be materialized onto the billing plan; runtime does not read catalog metadata directly.

Merge behavior

• Grant bindings are read from both product and price metadata.
• For the same grant program, price-level fields override product-level fields.

Validation notes

• metadata.grants must not contain duplicate grant_program_code values.

Related guides:

• Define your product catalog
• Operate the product catalog
• Self-serve orchestration

Catalog presentation config

Object: catalog_products.presentation_config

• Must be a JSON object.
• Used as product presentation configuration (for example, recommended badge, tagline, CTA, sale display).

Related guide:

• Operate the product catalog

Gate policy metadata

Object: gate_policies.metadata

Supported keys used by runtime

Key path	Purpose
feature_code or params.feature_code	Overrides policy feature target in quota/rate window projection.
counter_key or params.counter_key	Overrides quota/rate counter key.
seat_limit	Account seat-capacity packaging, resolved onto billing_accounts.seat_limit.

Important boundary

• gate_policy_bundles.metadata is currently not used by runtime decision logic.
• Keep bundle metadata for labels or application annotations only.

Related guides:

• Gate policies and bundles
• Policy model

Grants and campaign metadata

Objects:

• grant_campaigns.metadata
• grant_assignments.metadata
• grant_programs.eligibility_payload

Supported keys

Object	Key path	Purpose
grant_campaigns.metadata	grants[]	Exact {grant_program_code, amount_xusd} campaign binding list.
grant_assignments.metadata	annotation keys only	Public assignment metadata; grant_override and grants are reserved internal keys.
grant_programs.eligibility_payload	subscription_group_id / group_key	Eligibility targeting for subscription_group programs.

Related guides:

• Campaigns
• Grants operations

Contract term JSON

Object: contract_terms.value_json

• Required payload for each term version.
• Version identity is (kind, term_key, effective_at).
• Writing the same identity with different value_json is rejected.

Related guide:

• Contract terms