Pricing plans

Build and publish the Kelviq catalog: products contain plans, plans grant entitlements to features, and nothing is live until published.

Setup

Needs the kelviq: MCP tools (@kelviq/mcp-server, KELVIQSERVERAPIKEY). See the kelviq skill's Setup section for the .mcp.json snippet and sandbox testing with KELVIQENV=sandbox.

Golden path: build and publish a plan

1. kelviq:product_create — required: name, taxCode. If the tax code is

unknown, ask the user rather than guessing; don't invent one. Keep the returned product UUID.

1. kelviq:feature_create for each feature this plan gates. Pick

featureType: BOOLEAN (flag), CUSTOMIZABLE (numeric quantity, e.g. seats), or METER (usage-tracked, e.g. API calls). Keep each returned feature UUID.

1. kelviq:plan_create — pass the product UUID from step 1 as product

(not the identifier). The plan lands in DRAFT: not visible, not purchasable, until published. Don't tell the user it's live yet.

1. kelviq:planentitlementsadd — attach entitlements using the feature

UUIDs from step 2, e.g. [{ feature: <uuid>, details: {...} }]. The details shape depends on the feature's type — check kelviq:docs_read on product-catalog/entitlements if unsure rather than guessing the shape.

1. Prices. There is no price-write tool in MCP — this is deliberate, not a

gap. Direct the user to set prices in the Kelviq dashboard, or use the pricing-as-code skill's kelviq push flow if they manage pricing in git. kelviq:planpriceslist reads prices back once they exist, to confirm.

1. kelviq:plan_publish — makes the plan (and its DRAFT-only entitlements

from step 4) live. Pass updateFeatures and/or updatePricing only if you also want to migrate customers already on a previous version of this plan to the new features/pricing — always confirm with the user before setting either; unset, existing subscribers keep what they had.

1. Verify: kelviq:planretrieve (confirm published), kelviq:planprices_list

(confirm prices landed), kelviq:offeringgetproduct by product UUID (see the public pricing view a customer would see).

For the fully guided version of this flow, use the setupproduct MCP prompt (new product from nothing) or launchplan (new plan on an existing product) — don't re-derive their step lists here, just invoke them.

Free plans

A free plan uses chargePeriod: ONE_TIME rather than a recurring period. Free plans are a setup-payments concern once a customer needs to move off one — see that skill for the checkout-based upgrade path.

Updating a published plan

kelviq:planupdate on an already-published (islatest) plan does not change it in place — it creates a new draft. The previous version stays live until you kelviq:planpublish the new draft. Don't tell the user a planupdate call alone took effect.

Plan files

kelviq:planfileupdate (display fields: name, ordering, enabled), kelviq:planfiledelete, and kelviq:planfiledownload manage a plan's existing file attachments. None of them upload a new file — that happens outside these tools (media upload endpoint, or the dashboard). If the user wants to attach a brand-new file, say so plainly instead of trying to force it through planfileupdate.

Docs worth reading first

kelviq:docs_read on quickstart/core-concepts for the product/feature/plan model, product-catalog/plans and product-catalog/products for field-level detail, product-catalog/entitlements for entitlement shapes, and product-catalog/free-and-trials for free-plan specifics. Read before you answer a "what field does X take" question — don't enumerate the schema from memory here.