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	Provides a gate bundle candidate for account bundle projection.
grants[]	Declares grant templates that can be compiled into grant assignments 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, assignment metadata can override plan metadata.
• For billing defaults, assignment metadata can override plan metadata.

Related guides:

• Plans overview
• Plan assignments
• Gate policies and bundles

Feature and meter metadata

Objects:

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

Supported keys

Object	Key path	Purpose
meters.metadata	residual_mode	Controls residual carry mode for pricing rounding behavior.

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.
gating.bundle	Adds a purchase-time bundle candidate in bundle projection.

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.
billing_feature_code	For seats billing, defines which feature receives billing records.
billing_meter_code	For seats billing, defines which meter receives billing records.
billing_mode	For seats billing, supports assigned or active_window.

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[]	Campaign-level grant binding list.
grant_assignments.metadata	grant_override	Per-assignment override payload used for manual/ops assignment behavior.
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