@kelviq/mcp-server 0.3.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (103) hide show
  1. package/README.md +37 -30
  2. package/dist/config.d.ts +5 -0
  3. package/dist/config.js +31 -10
  4. package/dist/config.js.map +1 -1
  5. package/dist/docs/backend-integration/better-auth.md +369 -0
  6. package/dist/docs/backend-integration/node-sdk.md +373 -5
  7. package/dist/docs/backend-integration/python-sdk.md +444 -6
  8. package/dist/docs/changelog/api.md +516 -5
  9. package/dist/docs/changelog/app.md +162 -0
  10. package/dist/docs/changelog/cli.md +33 -0
  11. package/dist/docs/changelog/mcp-server.md +84 -0
  12. package/dist/docs/changelog/node-sdk.md +124 -0
  13. package/dist/docs/changelog/python-sdk.md +135 -0
  14. package/dist/docs/checkout/apply-a-discount-code.md +150 -0
  15. package/dist/docs/checkout/checkout-configuration.md +88 -22
  16. package/dist/docs/checkout/checkout-metadata.md +219 -0
  17. package/dist/docs/checkout/static-checkout-url.md +201 -0
  18. package/dist/docs/cli/commands.md +1 -1
  19. package/dist/docs/cli/environments.md +17 -9
  20. package/dist/docs/cli/kelviq-config.md +35 -1
  21. package/dist/docs/cli/overview.md +2 -0
  22. package/dist/docs/coustomers-management/overview.md +15 -19
  23. package/dist/docs/customer-portal/managing-payment-methods.md +30 -48
  24. package/dist/docs/frontend-integration/react-ui.md +51 -16
  25. package/dist/docs/getstarted/fees.md +45 -54
  26. package/dist/docs/getstarted/payment-security-and-seller-funds.md +98 -0
  27. package/dist/docs/getstarted/review-process.md +3 -3
  28. package/dist/docs/guides/agent-toolkit.md +143 -0
  29. package/dist/docs/guides/mcp-server.md +134 -63
  30. package/dist/docs/guides/migrate-from-cashfree.md +7 -0
  31. package/dist/docs/guides/sandbox.md +34 -0
  32. package/dist/docs/guides/subscription-integration-for-nextjs.md +44 -18
  33. package/dist/docs/guides/subscription-integration.md +28 -4
  34. package/dist/docs/guides/webhooks.md +367 -6
  35. package/dist/docs/manifest.json +109 -4
  36. package/dist/docs/openapi.json +7411 -2648
  37. package/dist/docs/payouts/overview.md +30 -0
  38. package/dist/docs/payouts/transactions.md +50 -6
  39. package/dist/docs/product-catalog/create-a-feature.md +113 -0
  40. package/dist/docs/product-catalog/create-an-enterprise-plan.md +133 -0
  41. package/dist/docs/product-catalog/discounts.md +25 -12
  42. package/dist/docs/product-catalog/entitlements.md +53 -16
  43. package/dist/docs/product-catalog/free-and-trials.md +8 -4
  44. package/dist/docs/product-catalog/location-based-pricing.md +2 -0
  45. package/dist/docs/product-catalog/one-time-payments.md +4 -0
  46. package/dist/docs/product-catalog/pay-as-you-go.md +177 -0
  47. package/dist/docs/product-catalog/plans.md +14 -0
  48. package/dist/docs/product-catalog/products.md +5 -13
  49. package/dist/docs/product-catalog/seat-based-pricing.md +233 -0
  50. package/dist/docs/product-catalog/subscriptions.md +109 -12
  51. package/dist/docs/product-catalog/usage-alerts.md +257 -0
  52. package/dist/docs/product-catalog/usage-based-billing.md +49 -12
  53. package/dist/docs/quickstart/dashboard-setup.md +1 -1
  54. package/dist/docs/sales/abandoned-cart-recovery.md +64 -0
  55. package/dist/docs/sales/create-a-one-time-charge.md +144 -0
  56. package/dist/http/client.js +9 -2
  57. package/dist/http/client.js.map +1 -1
  58. package/dist/http/errors.d.ts +8 -0
  59. package/dist/http/errors.js +20 -0
  60. package/dist/http/errors.js.map +1 -1
  61. package/dist/prompts/index.d.ts +2 -0
  62. package/dist/prompts/index.js +107 -0
  63. package/dist/prompts/index.js.map +1 -0
  64. package/dist/schemas/kelviq.d.ts +30 -0
  65. package/dist/schemas/kelviq.js +50 -0
  66. package/dist/schemas/kelviq.js.map +1 -1
  67. package/dist/server.js +15 -3
  68. package/dist/server.js.map +1 -1
  69. package/dist/tools/checkout.js +2 -1
  70. package/dist/tools/checkout.js.map +1 -1
  71. package/dist/tools/customers.js +2 -0
  72. package/dist/tools/customers.js.map +1 -1
  73. package/dist/tools/docs.js +2 -0
  74. package/dist/tools/docs.js.map +1 -1
  75. package/dist/tools/entitlements.js +1 -0
  76. package/dist/tools/entitlements.js.map +1 -1
  77. package/dist/tools/features.js +4 -0
  78. package/dist/tools/features.js.map +1 -1
  79. package/dist/tools/licenses.js +3 -0
  80. package/dist/tools/licenses.js.map +1 -1
  81. package/dist/tools/offerings.js +1 -0
  82. package/dist/tools/offerings.js.map +1 -1
  83. package/dist/tools/plan-entitlements.js +4 -0
  84. package/dist/tools/plan-entitlements.js.map +1 -1
  85. package/dist/tools/plan-files.js +3 -0
  86. package/dist/tools/plan-files.js.map +1 -1
  87. package/dist/tools/plans.js +8 -0
  88. package/dist/tools/plans.js.map +1 -1
  89. package/dist/tools/portal.js +1 -0
  90. package/dist/tools/portal.js.map +1 -1
  91. package/dist/tools/product-files.js +2 -0
  92. package/dist/tools/product-files.js.map +1 -1
  93. package/dist/tools/product-settings.js +2 -0
  94. package/dist/tools/product-settings.js.map +1 -1
  95. package/dist/tools/products.js +5 -0
  96. package/dist/tools/products.js.map +1 -1
  97. package/dist/tools/promotions.js +1 -0
  98. package/dist/tools/promotions.js.map +1 -1
  99. package/dist/tools/subscriptions.js +5 -1
  100. package/dist/tools/subscriptions.js.map +1 -1
  101. package/dist/tools/usage.js +1 -0
  102. package/dist/tools/usage.js.map +1 -1
  103. package/package.json +1 -1
@@ -4,17 +4,19 @@ slug: "guides/mcp-server"
4
4
  section: "guides"
5
5
  description: "Control Kelviq from Claude, Cursor, and any AI assistant that speaks the Model Context Protocol."
6
6
  ---
7
- `@kelviq/mcp-server` is the official [Model Context Protocol](https://modelcontextprotocol.io) server for Kelviq. It plugs into any MCP-compatible client — Claude Code, Claude Desktop, Cursor, Zed — and exposes the full Kelviq API as **typed tools** that the LLM can call directly, plus the entire Kelviq documentation as **searchable resources**.
7
+ `@kelviq/mcp-server` is the official [Model Context Protocol](https://modelcontextprotocol.io) server for Kelviq. It plugs into any MCP-compatible client — Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Antigravity — and exposes the full Kelviq API as **typed tools** that the LLM can call directly, plus the entire Kelviq documentation as **searchable resources**.
8
8
 
9
9
  Instead of asking your assistant to "write me a curl command," you describe the outcome ("create a Pro plan under product X and publish it") and it does the work in a single turn.
10
10
 
11
- **51 tools across 13 domains** (customers, checkout, subscriptions, entitlements, licenses, usage, offerings, promotions, portal, catalog products, catalog plans, catalog features, partner organizations) plus **61 resources** including the full OpenAPI spec.
11
+ **Using Claude Code?** The fastest install is the [Agent Toolkit](/guides/agent-toolkit) plugin — two commands set up this MCP server *and* five Kelviq skills that teach Claude the workflows. This page covers manual setup for every MCP client.
12
+
13
+ **45 tools** spanning customers, checkout, subscriptions, entitlements, licenses, usage, offerings, promotions, the customer portal, and full catalog management (products, plans, features) — plus a resource for every docs page and the full OpenAPI spec, and **3 guided prompts** for the most common workflows. Every tool carries [MCP safety annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations), so clients can auto-approve read-only calls while confirming destructive ones.
12
14
 
13
15
  ---
14
16
 
15
17
  ## How It Works
16
18
 
17
- The server runs locally on your machine as a Node process started by your AI client. It speaks the MCP **stdio transport** — your client launches `npx -y @kelviq/mcp-server`, connects over stdio, and discovers the tools and resources advertised by the server.
19
+ The server runs locally on your machine as a Node process started by your AI client. It speaks the MCP **stdio transport** — your client launches `npx -y @kelviq/mcp-server@latest`, connects over stdio, and discovers the tools and resources advertised by the server.
18
20
 
19
21
  When the LLM decides to call a Kelviq tool, the server:
20
22
 
@@ -40,22 +42,21 @@ Never commit API keys to version control or paste them into shared chats. Use yo
40
42
 
41
43
  ## Step 2: Add the Server to Your AI Client
42
44
 
43
- Pick the section that matches your client.
45
+ Every client uses the same underlying command — `npx -y @kelviq/mcp-server@latest` — with your API keys and `KELVIQ_ENV` passed as environment variables. What differs is the config file location and, in a few cases, the root JSON key. Pick the tab for your client.
44
46
 
45
- ### Claude Code (CLI)
47
+ The server uses your **sandbox** environment unless `KELVIQ_ENV=production`. Use keys from the same environment — to work with live data, use production keys and set `KELVIQ_ENV=production`.
46
48
 
47
49
  ```bash
48
50
  claude mcp add kelviq \
49
51
  --env KELVIQ_SERVER_API_KEY=<your-server-key> \
50
52
  --env KELVIQ_CLIENT_API_KEY=<your-client-key> \
51
- -- npx -y @kelviq/mcp-server
53
+ --env KELVIQ_ENV=sandbox \
54
+ -- npx -y @kelviq/mcp-server@latest
52
55
  ```
53
56
 
54
57
  The `--` separator is required so that `claude` doesn't intercept `-y` as one of its own flags. Put all `--env` arguments **before** the `--`.
55
58
 
56
- Verify the connection with `/mcp` inside a Claude Code session — you should see `kelviq ✓ Connected, 51 tools`.
57
-
58
- ### Claude Desktop
59
+ Verify the connection with `/mcp` inside a Claude Code session — you should see `kelviq ✓ Connected, 45 tools`.
59
60
 
60
61
  Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent for your OS:
61
62
 
@@ -64,10 +65,11 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o
64
65
  "mcpServers": {
65
66
  "kelviq": {
66
67
  "command": "npx",
67
- "args": ["-y", "@kelviq/mcp-server"],
68
+ "args": ["-y", "@kelviq/mcp-server@latest"],
68
69
  "env": {
69
70
  "KELVIQ_SERVER_API_KEY": "server-...",
70
- "KELVIQ_CLIENT_API_KEY": "client-..."
71
+ "KELVIQ_CLIENT_API_KEY": "client-...",
72
+ "KELVIQ_ENV": "sandbox"
71
73
  }
72
74
  }
73
75
  }
@@ -76,22 +78,101 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o
76
78
 
77
79
  Restart Claude Desktop — the hammer icon shows `kelviq` with all tools.
78
80
 
79
- ### Cursor
81
+ Open **Cursor Settings → Tools and MCP → Add new MCP server**, or edit `.cursor/mcp.json` (project) / `~/.cursor/mcp.json` (global) directly:
80
82
 
81
- Open **Cursor Settings → MCP**, click **Add new MCP server**, and configure:
83
+ ```json
84
+ {
85
+ "mcpServers": {
86
+ "kelviq": {
87
+ "command": "npx",
88
+ "args": ["-y", "@kelviq/mcp-server@latest"],
89
+ "env": {
90
+ "KELVIQ_SERVER_API_KEY": "server-...",
91
+ "KELVIQ_CLIENT_API_KEY": "client-...",
92
+ "KELVIQ_ENV": "sandbox"
93
+ }
94
+ }
95
+ }
96
+ }
97
+ ```
82
98
 
83
- | Field | Value |
84
- |-------|-------|
85
- | Command | `npx` |
86
- | Args | `-y @kelviq/mcp-server` |
87
- | Environment Variables | `KELVIQ_SERVER_API_KEY`, `KELVIQ_CLIENT_API_KEY` |
99
+ Project-level config overrides global config when a server of the same name exists in both.
88
100
 
89
- ### Other Clients
101
+ As of June 2026, Windsurf was rebranded **Devin Desktop** by Cognition. Existing installs update automatically — same editor, new name. The MCP config location also changed with the rebrand:
102
+ - **Devin Desktop (current):** `%APPDATA%\devin\config.json` (Windows) — via **Settings → Devin Local → Configuration → MCP servers**
103
+ - **Legacy Windsurf installs:** `~/.codeium/windsurf/mcp_config.json`
104
+
105
+ Add Kelviq under the `mcpServers` key:
106
+
107
+ ```json
108
+ {
109
+ "mcpServers": {
110
+ "kelviq": {
111
+ "command": "npx",
112
+ "args": ["-y", "@kelviq/mcp-server@latest"],
113
+ "env": {
114
+ "KELVIQ_SERVER_API_KEY": "server-...",
115
+ "KELVIQ_CLIENT_API_KEY": "client-...",
116
+ "KELVIQ_ENV": "sandbox"
117
+ }
118
+ }
119
+ }
120
+ }
121
+ ```
122
+
123
+ Save, then refresh or restart the app — `kelviq` should appear under **MCP servers** in Settings, where you can enable it and toggle individual tools.
124
+
125
+ If your `config.json` isn't empty, check its existing top-level structure before pasting — merge `kelviq` alongside whatever's already there rather than overwriting the file.
126
+
127
+ Add a `.vscode/mcp.json` in your workspace, or run **"MCP: Open User Configuration"** from the Command Palette for a global `mcp.json`. VS Code uses `servers`, not `mcpServers`, as the root key:
128
+
129
+ ```json
130
+ {
131
+ "servers": {
132
+ "kelviq": {
133
+ "command": "npx",
134
+ "args": ["-y", "@kelviq/mcp-server@latest"],
135
+ "env": {
136
+ "KELVIQ_SERVER_API_KEY": "server-...",
137
+ "KELVIQ_CLIENT_API_KEY": "client-...",
138
+ "KELVIQ_ENV": "sandbox"
139
+ }
140
+ }
141
+ }
142
+ }
143
+ ```
144
+
145
+ Save, then click the **Start** CodeLens above the `kelviq` entry (or reload the window) and confirm it under the tools icon in Copilot Chat's Agent mode.
146
+
147
+ Already have Kelviq configured in Cursor or Windsurf? Under **Settings → Chat → MCP → Discovery**, check the matching box (e.g. "Windsurf configurations") to auto-import that server instead of retyping it. You can also use the `inputs` array to be prompted for the keys instead of storing them in plaintext.
148
+
149
+ Open the "..." menu in the Agent panel → **MCP Servers** → **Manage MCP Servers** → **View raw config**. This opens `mcp_config.json` at:
150
+
151
+ - **Windows:** `C:\Users\<USERNAME>\.gemini\antigravity\mcp_config.json`
152
+ - **macOS/Linux:** `~/.gemini/antigravity/mcp_config.json`
153
+
154
+ ```json
155
+ {
156
+ "mcpServers": {
157
+ "kelviq": {
158
+ "command": "npx",
159
+ "args": ["-y", "@kelviq/mcp-server@latest"],
160
+ "env": {
161
+ "KELVIQ_SERVER_API_KEY": "server-...",
162
+ "KELVIQ_CLIENT_API_KEY": "client-...",
163
+ "KELVIQ_ENV": "sandbox"
164
+ }
165
+ }
166
+ }
167
+ }
168
+ ```
169
+
170
+ The Antigravity **CLI** (as opposed to the IDE) uses a separate config path: `~/.gemini/antigravity-cli/mcp_config.json`.
90
171
 
91
172
  Any client supporting stdio MCP servers works. Point it at:
92
173
 
93
174
  ```bash
94
- npx -y @kelviq/mcp-server
175
+ npx -y @kelviq/mcp-server@latest
95
176
  ```
96
177
 
97
178
  with the env vars listed below.
@@ -116,22 +197,14 @@ Your AI client should pick the right tool, call it, and show the result inline.
116
197
 
117
198
  | Variable | Required | Default | Purpose |
118
199
  |----------|----------|---------|---------|
119
- | `KELVIQ_SERVER_API_KEY` | Yes, for all API tools | — | Bearer token for `api.kelviq.com` |
120
- | `KELVIQ_CLIENT_API_KEY` | Only for `promotion_get` | — | Bearer token for the edge host |
121
- | `KELVIQ_BASE_URL` | No | `https://api.kelviq.com/api/v1` | Override for sandbox / self-host |
122
- | `KELVIQ_EDGE_URL` | No | `https://edge.api.kelviq.com/api/v1` | Override the edge host (entitlements + promotions) |
200
+ | `KELVIQ_SERVER_API_KEY` | Yes, for all API tools | — | Server API key (Bearer token for the core API) |
201
+ | `KELVIQ_CLIENT_API_KEY` | Only for `promotion_get` | — | Client API key (Bearer token for the edge host) |
202
+ | `KELVIQ_ENV` | No | `sandbox` | `sandbox` or `production`. Set to `production` to work with live data — switches both API hosts automatically. Use a key from the same environment: keys only work against their own environment. |
203
+ | `KELVIQ_BASE_URL` | No | per `KELVIQ_ENV` | Advanced: override the core API host |
204
+ | `KELVIQ_EDGE_URL` | No | per `KELVIQ_ENV` | Advanced: override the edge host (entitlements + promotions) |
123
205
 
124
206
  Docs tools (`docs_search`, `docs_read`) work with no API keys at all. Even without a key, the LLM can answer Kelviq questions from the bundled documentation.
125
207
 
126
- ### Point at Staging
127
-
128
- ```env
129
- KELVIQ_BASE_URL=https://stagingapi.kelviq.com/api/v1
130
- KELVIQ_EDGE_URL=https://edge.stagingapi.kelviq.com/api/v1
131
- ```
132
-
133
- Pair these with a **staging-scoped** Server API Key from your dashboard's staging environment.
134
-
135
208
  ---
136
209
 
137
210
  ## Tool Reference
@@ -150,13 +223,13 @@ Tools are grouped by domain. Each tool name uses `domain_action` form (`customer
150
223
  | Tool | Description |
151
224
  |------|-------------|
152
225
  | `checkout_create_session` | Create a hosted checkout session. Returns `checkoutUrl` + `checkoutSessionId`. |
153
- | `portal_session_create` | Mint a pre-authenticated customer portal URL. |
226
+ | `portal_session_create` | Create a customer portal session. Share the returned `signedPortalUrl` with the customer — the bare `customerPortalUrl` does not authenticate on its own. |
154
227
 
155
228
  ### Subscriptions
156
229
 
157
230
  | Tool | Description |
158
231
  |------|-------------|
159
- | `subscription_create` | Create a subscription directly (skip checkout). |
232
+ | `subscription_create` | Create a subscription directly (skip checkout). Requires off-session charging to be enabled for your organization — otherwise use `checkout_create_session`. |
160
233
  | `subscription_list` | List subscriptions, filter by customer, paginated. |
161
234
  | `subscription_update` | Change plan / charge period / features. Free plans must use `checkout_create_session` to upgrade. |
162
235
  | `subscription_cancel` | Cancel `IMMEDIATE`, `CURRENT_PERIOD_ENDS`, or `SPECIFIC_DATE`. |
@@ -183,7 +256,7 @@ Tools are grouped by domain. Each tool name uses `domain_action` form (`customer
183
256
  | Tool | Description |
184
257
  |------|-------------|
185
258
  | `product_list` | List catalog products. Optional `search` substring + `page`. |
186
- | `product_create` | Create a product. Required: `name`, `taxCode`. Optional `imageKeys` from `media_presigned_upload`. |
259
+ | `product_create` | Create a product. Required: `name`, `taxCode`. Optional `imageKeys` (S3 file keys from the `POST /media/` API endpoint). |
187
260
  | `product_retrieve` | Fetch one product by UUID or identifier. |
188
261
  | `product_update` | Patch a product. |
189
262
  | `product_archive` | Archive (soft-delete) a product. |
@@ -215,7 +288,6 @@ Plans are versioned. Updates create a draft; `plan_publish` releases it.
215
288
  | `plan_publish` | Publish the latest draft. `updateFeatures` / `updatePricing` flags migrate existing customers. |
216
289
  | `plan_discard_draft` | Drop the current draft, keep the published version. |
217
290
  | `plan_prices_list` | List all prices configured on a plan. |
218
- | `plan_prices_bulk_set` | Atomically replace all prices. Supports `FLAT` / `PACKAGE` / `TIERED` / `VOLUME` / `STAIRSTEP` models. |
219
291
  | `plan_entitlements_list` | List feature entitlements on a plan. |
220
292
  | `plan_entitlements_add` | Attach feature entitlements. |
221
293
  | `plan_entitlement_update` | Patch a single entitlement's `details`. |
@@ -224,21 +296,6 @@ Plans are versioned. Updates create a draft; `plan_publish` releases it.
224
296
  | `plan_file_delete` | Remove a file from a plan. |
225
297
  | `plan_file_download` | Download URL/stream for a plan file (buyer-facing deliverables). |
226
298
 
227
- ### Media
228
-
229
- | Tool | Description |
230
- |------|-------------|
231
- | `media_presigned_upload` | Get a presigned S3 POST policy (max 5 GB). Returns a `fileKey` to pass into `product_create`/`product_update` (`imageKeys`) or `plan_create`/`plan_update` (`fileKeys`). |
232
-
233
- ### Partner
234
-
235
- | Tool | Description |
236
- |------|-------------|
237
- | `partner_org_provision` | Provision a Kelviq org under your partner account. Required: `externalId`, `email`. Optional `businessName`. |
238
- | `partner_org_list` | List orgs you've provisioned. Optional `externalId` filter. |
239
- | `partner_org_retrieve` | Fetch a partner org by its Kelviq identifier. |
240
- | `partner_org_retrieve_by_external_id` | Fetch a partner org by your partner-side ID. |
241
-
242
299
  ### Docs (no API key required)
243
300
 
244
301
  | Tool | Description |
@@ -254,30 +311,36 @@ Resources let your AI client pin pages into context. The server advertises three
254
311
 
255
312
  | URI pattern | Content |
256
313
  |-------------|---------|
257
- | `kelviq://docs/{section}/{slug}` | Every conceptual page in the Kelviq docs (~59 pages) |
258
- | `kelviq://openapi.json` | The full OpenAPI 3.0 spec (49 operations, every schema) |
314
+ | `kelviq://docs/{section}/{slug}` | Every page in the Kelviq docs |
315
+ | `kelviq://openapi.json` | The full OpenAPI 3.0 spec (every operation and schema) |
259
316
  | `kelviq://README` | Top-level Kelviq overview |
260
317
 
261
318
  For exhaustive per-endpoint request/response shapes, the **OpenAPI spec is the source of truth**. Ask your assistant *"check the OpenAPI spec for createSubscription"* and it will read the resource directly.
262
319
 
263
320
  ---
264
321
 
322
+ ## Built-in Prompts
323
+
324
+ The server ships three MCP prompts that encode Kelviq's golden-path workflows — including the gotchas (plans start as invisible drafts until published; entitlements attach by feature UUID; pricing is set in the dashboard or with the [Kelviq CLI](/cli/overview), not through the MCP server). In Claude Code they appear as slash commands (e.g. `/kelviq:setup_product`); other MCP clients list them under prompts.
325
+
326
+ | Prompt | Arguments | What it guides |
327
+ |--------|-----------|----------------|
328
+ | `setup_product` | `productName?`, `planName?` | Full catalog bootstrap: product → features → plan → entitlements → publish → verify. |
329
+ | `launch_plan` | `productId?`, `planName?` | Add and publish a new plan on an existing product, reusing existing features. |
330
+ | `diagnose_customer` | `customerId` | Cross-check a customer's entitlements, subscriptions, and plan configuration; ends with concrete next actions. |
331
+
265
332
  ## Example Prompts
266
333
 
267
334
  Describe the outcome, not the API call. A few realistic prompts that exercise the toolchain:
268
335
 
269
- > *Create a Kelviq product called "Notion Plus" with tax code `saas`, then create three plans (Free, Pro Monthly $19, Pro Yearly $190), add an `api-calls` feature with limits 1000 / 50000 / unlimited, and publish all three plans.*
336
+ > *Create a Kelviq product called "Notion Plus" with tax code `saas`, then create three plans (Free, Pro Monthly, Pro Yearly), add an `api-calls` feature with limits 1000 / 50000 / unlimited, and publish all three plans.*
270
337
 
271
- Calls (in order): `product_create` → `feature_create` → `plan_create` × 3 → `plan_entitlements_add` × 3 → `plan_prices_bulk_set` × 3 → `plan_publish` × 3.
338
+ Calls (in order): `product_create` → `feature_create` → `plan_create` × 3 → `plan_entitlements_add` × 3 → `plan_publish` × 3. Set each plan's prices in the [dashboard](https://app.kelviq.com) or with the [Kelviq CLI](/cli/overview), which manages pricing as reviewable code.
272
339
 
273
340
  > *Create a checkout session for plan `pro-monthly` for a new customer, success URL https://example.com/done.*
274
341
 
275
342
  Calls: `checkout_create_session`. Returns the `checkoutUrl` you can hand to your buyer.
276
343
 
277
- > *Provision a Kelviq org for partner external ID `acme-99`, owner email `ops@acme.com`, business name "Acme Corp".*
278
-
279
- Calls: `partner_org_provision`. Returns the new org's identifier + API keys.
280
-
281
344
  > *Activate license `LIC-ABCDE` for customer `geojacob`, instance name "MacBook Pro M3", then validate it.*
282
345
 
283
346
  Calls: `license_activate` → `license_validate`.
@@ -334,16 +397,24 @@ GUI/launcher processes don't source `~/.zshrc`, so nvm's `node` isn't visible to
334
397
  ```bash
335
398
  claude mcp add kelviq \
336
399
  --env KELVIQ_SERVER_API_KEY=... \
337
- -- npx -y @kelviq/mcp-server
400
+ -- npx -y @kelviq/mcp-server@latest
338
401
  ```
339
402
 
340
403
  ### Tool returns `{"error": {"status": "Configuration error", ...}}`
341
404
 
342
405
  A required env var is missing. The error message names which one — set it in your client config and reconnect.
343
406
 
407
+ ### Tool returns HTTP 401 or 403
408
+
409
+ Almost always, the key belongs to the other environment: a sandbox key only works against sandbox, and a production key only against production.
410
+
411
+ - The server uses sandbox unless `KELVIQ_ENV=production`. If your key is a production key, add `KELVIQ_ENV=production` to the server's environment and reconnect.
412
+ - The error message includes a hint naming the environment the server is using, and the startup log shows it too (`kelviq-mcp ready (env=…`). Make sure it matches your key.
413
+ - If neither shows an environment, your client is running an outdated copy of the server. Use `npx -y @kelviq/mcp-server@latest` in your client config.
414
+
344
415
  ### Tool returns `{"error": {"status": "Bad request", "message": "Invalid product identifier"}}`
345
416
 
346
- Your API key works but the identifier doesn't exist on this account. Most common cause: your key is for **production** but the identifier exists only in **staging** (or vice versa). Check `KELVIQ_BASE_URL`.
417
+ Your API key works but the identifier doesn't exist on this account. Most common cause: the identifier exists in the other environment — sandbox and production have separate catalogs. Check `KELVIQ_ENV`.
347
418
 
348
419
  ### Test Without an AI Client
349
420
 
@@ -352,7 +423,7 @@ Use the official [MCP Inspector](https://github.com/modelcontextprotocol/inspect
352
423
  ```bash
353
424
  KELVIQ_SERVER_API_KEY=... KELVIQ_CLIENT_API_KEY=... \
354
425
  npx -y @modelcontextprotocol/inspector \
355
- npx -y @kelviq/mcp-server
426
+ npx -y @kelviq/mcp-server@latest
356
427
  ```
357
428
 
358
429
  ---
@@ -0,0 +1,7 @@
1
+ ---
2
+ title: "Migrate from Cashfree"
3
+ slug: "guides/migrate-from-cashfree"
4
+ section: "guides"
5
+ description: "Get help moving from Cashfree to Kelviq"
6
+ ---
7
+ Need help moving from Cashfree to Kelviq? Contact [hi@kelviq.com](mailto:hi@kelviq.com) to discuss your current setup.
@@ -94,6 +94,40 @@ Do not enter a real card number in the sandbox.
94
94
 
95
95
  After payment, confirm that the test order, customer, subscription, and entitlements have the expected state in Sandbox mode.
96
96
 
97
+ ## Test a subscription renewal
98
+
99
+ Daily billing is not enabled by default. Any sandbox organization can request it by contacting [Kelviq support](mailto:hi@kelviq.com).
100
+
101
+ After Daily billing is enabled, use it to test a renewal without waiting for a monthly or yearly billing cycle.
102
+
103
+ 1. Enter Sandbox mode in the Kelviq dashboard.
104
+ 2. Open the test plan you want to use.
105
+ 3. Under **Billing cycles**, select **Daily** and enter a test price.
106
+ 4. Publish the plan.
107
+ 5. Start a subscription with a sandbox test card.
108
+ 6. After the next billing cycle, check the order, invoice, subscription status, and entitlements in Sandbox mode.
109
+
110
+ If you create the checkout session through the API, set `chargePeriod` to `DAILY`:
111
+
112
+ ```json
113
+ {
114
+ "planIdentifier": "sandbox-renewal-test",
115
+ "chargePeriod": "DAILY",
116
+ "customerId": "test-customer-001",
117
+ "successUrl": "https://example.com/billing/success"
118
+ }
119
+ ```
120
+
121
+ ## Can I test production with my own card?
122
+
123
+ No. Do not place a live order using your own card just to test production credentials. Payment providers can treat a self-payment as suspicious and block the card, even when the amount is small. There is no safe minimum price for this test.
124
+
125
+ Use one of these options instead:
126
+
127
+ * Keep payment and renewal testing in Sandbox.
128
+ * If you need to inspect the production checkout, [create a 100% discount code](/product-catalog/discounts) so no real payment is collected.
129
+ * Check production credentials, URLs, and environment settings without completing a purchase.
130
+
97
131
  ## Prepare for production
98
132
 
99
133
  Before accepting live payments:
@@ -30,21 +30,32 @@ Add these to your `.env.local` file:
30
30
 
31
31
  ```env
32
32
  # Backend (server-side only)
33
- KELVIQ_API_KEY=server-xxxxxxxx
34
-
35
- # API URLs
36
- KELVIQ_API_BASE_URL=https://api.kelviq.com/api/v1
33
+ KELVIQ_SERVER_API_KEY=server-xxxxxxxx
34
+ KELVIQ_ENV=sandbox
37
35
 
38
36
  # Frontend (can be exposed to client)
39
- NEXT_PUBLIC_KELVIQ_CLIENT_KEY=client-xxxxxxxx
40
- NEXT_PUBLIC_KELVIQ_EDGE_URL=https://edge.api.kelviq.com/api/v1/
37
+ NEXT_PUBLIC_KELVIQ_CLIENT_API_KEY=client-xxxxxxxx
38
+ NEXT_PUBLIC_KELVIQ_ENV=sandbox
41
39
 
42
40
  # Your app URL (for redirects)
43
41
  NEXT_PUBLIC_APP_URL=https://yourdomain.com
44
42
  ```
45
43
 
44
+ Build with sandbox keys — keys only work against their own environment. When you go live, switch both keys to production keys and set both `KELVIQ_ENV` values to `production`.
45
+
46
46
  Never expose your server API key to the frontend or commit it to version control.
47
47
 
48
+ ### Point API Routes at the Right Environment
49
+
50
+ Create `lib/kelviq.ts` so every API route calls the host that matches `KELVIQ_ENV`:
51
+
52
+ ```typescript
53
+ export const KELVIQ_API_URL =
54
+ process.env.KELVIQ_ENV === "production"
55
+ ? "https://api.kelviq.com/api/v1"
56
+ : "https://sandboxapi.kelviq.com/api/v1";
57
+ ```
58
+
48
59
  ---
49
60
 
50
61
  ## Step 2: Define Your Plans
@@ -101,17 +112,18 @@ Create a customer record when a user signs up. This gives you more control and l
101
112
 
102
113
  ```typescript
103
114
  import { NextRequest, NextResponse } from "next/server";
115
+ import { KELVIQ_API_URL } from "@/lib/kelviq";
104
116
 
105
117
  export async function POST(request: NextRequest) {
106
118
  const { customerId, name, email } = await request.json();
107
119
 
108
120
  const response = await fetch(
109
- `${process.env.KELVIQ_API_BASE_URL}/customers/`,
121
+ `${KELVIQ_API_URL}/customers/`,
110
122
  {
111
123
  method: "POST",
112
124
  headers: {
113
125
  "Content-Type": "application/json",
114
- Authorization: `Bearer ${process.env.KELVIQ_API_KEY}`,
126
+ Authorization: `Bearer ${process.env.KELVIQ_SERVER_API_KEY}`,
115
127
  },
116
128
  body: JSON.stringify({ customerId, name, email }),
117
129
  }
@@ -152,17 +164,18 @@ Create `app/api/checkout/route.ts`:
152
164
 
153
165
  ```typescript
154
166
  import { NextRequest, NextResponse } from "next/server";
167
+ import { KELVIQ_API_URL } from "@/lib/kelviq";
155
168
 
156
169
  export async function POST(request: NextRequest) {
157
170
  const { planIdentifier, customerId, chargePeriod } = await request.json();
158
171
 
159
172
  const response = await fetch(
160
- `${process.env.KELVIQ_API_BASE_URL}/checkout/`,
173
+ `${KELVIQ_API_URL}/checkout/`,
161
174
  {
162
175
  method: "POST",
163
176
  headers: {
164
177
  "Content-Type": "application/json",
165
- Authorization: `Bearer ${process.env.KELVIQ_API_KEY}`,
178
+ Authorization: `Bearer ${process.env.KELVIQ_SERVER_API_KEY}`,
166
179
  },
167
180
  body: JSON.stringify({
168
181
  planIdentifier,
@@ -246,15 +259,16 @@ Create `app/api/subscriptions/route.ts`:
246
259
 
247
260
  ```typescript
248
261
  import { NextRequest, NextResponse } from "next/server";
262
+ import { KELVIQ_API_URL } from "@/lib/kelviq";
249
263
 
250
264
  export async function GET(request: NextRequest) {
251
265
  const customerId = request.nextUrl.searchParams.get("customerId");
252
266
 
253
267
  const response = await fetch(
254
- `${process.env.KELVIQ_API_BASE_URL}/subscriptions/?customer_id=${customerId}`,
268
+ `${KELVIQ_API_URL}/subscriptions/?customer_id=${customerId}`,
255
269
  {
256
270
  headers: {
257
- Authorization: `Bearer ${process.env.KELVIQ_API_KEY}`,
271
+ Authorization: `Bearer ${process.env.KELVIQ_SERVER_API_KEY}`,
258
272
  },
259
273
  }
260
274
  );
@@ -270,21 +284,28 @@ Create `app/api/subscriptions/update/route.ts`:
270
284
 
271
285
  ```typescript
272
286
  import { NextRequest, NextResponse } from "next/server";
287
+ import { KELVIQ_API_URL } from "@/lib/kelviq";
273
288
 
274
289
  export async function POST(request: NextRequest) {
275
- const { subscriptionId, planIdentifier, chargePeriod } = await request.json();
290
+ const {
291
+ subscriptionId,
292
+ planIdentifier,
293
+ chargePeriod,
294
+ paymentBehavior,
295
+ } = await request.json();
276
296
 
277
297
  const response = await fetch(
278
- `${process.env.KELVIQ_API_BASE_URL}/subscriptions/${subscriptionId}/update/`,
298
+ `${KELVIQ_API_URL}/subscriptions/${subscriptionId}/update/`,
279
299
  {
280
300
  method: "POST",
281
301
  headers: {
282
302
  "Content-Type": "application/json",
283
- Authorization: `Bearer ${process.env.KELVIQ_API_KEY}`,
303
+ Authorization: `Bearer ${process.env.KELVIQ_SERVER_API_KEY}`,
284
304
  },
285
305
  body: JSON.stringify({
286
306
  planIdentifier,
287
307
  chargePeriod: chargePeriod || "MONTHLY",
308
+ paymentBehavior,
288
309
  }),
289
310
  }
290
311
  );
@@ -312,16 +333,21 @@ async function handlePlanChange(newPlanId: string) {
312
333
  subscriptionId: current.id,
313
334
  planIdentifier: newPlanId,
314
335
  chargePeriod: "MONTHLY",
336
+ paymentBehavior: "activate_on_payment",
315
337
  }),
316
338
  });
317
339
 
318
- alert("Plan updated!");
340
+ alert("Plan change started. The new plan becomes active after payment succeeds.");
319
341
  } else {
320
342
  // No subscription, redirect to checkout
321
343
  }
322
344
  }
323
345
  ```
324
346
 
347
+ With `activate_on_payment`, the existing subscription remains `active` while payment is pending. If the payment method requires UPI approval or 3DS authentication, the updated subscription starts as `incomplete`. After payment succeeds, the updated subscription becomes `active` and the previous subscription becomes `superseded`. If an immediate charge fails, or the customer does not complete payment before expiry, the updated subscription becomes `incomplete_expired` and the existing subscription stays active.
348
+
349
+ Do not unlock the new plan immediately after this route returns. Check the updated subscription status or fetch the customer's current entitlements first.
350
+
325
351
  ---
326
352
 
327
353
  ## Step 7: Gate Features with Entitlements
@@ -341,8 +367,8 @@ export default function RootLayout({ children }: { children: React.ReactNode })
341
367
  <body>
342
368
  <KelviqProvider
343
369
  customerId={getCurrentUserId()}
344
- accessToken={process.env.NEXT_PUBLIC_KELVIQ_CLIENT_KEY!}
345
- apiUrl={process.env.NEXT_PUBLIC_KELVIQ_EDGE_URL!}
370
+ accessToken={process.env.NEXT_PUBLIC_KELVIQ_CLIENT_API_KEY!}
371
+ environment={process.env.NEXT_PUBLIC_KELVIQ_ENV === "production" ? "production" : "sandbox"}
346
372
  >
347
373
  {children}
348
374
  </KelviqProvider>
@@ -95,7 +95,7 @@ Redirect user to `checkoutUrl` → They complete payment → Redirected back to
95
95
  | Parameter | Description |
96
96
  |-----------|-------------|
97
97
  | `planIdentifier` | The identifier of the plan (e.g., `"pro"`, `"enterprise"`) |
98
- | `chargePeriod` | Billing cycle: `"MONTHLY"`, `"YEARLY"`, `"ONE_TIME"`, `"WEEKLY"`, `"DAILY"`, `"THREE_MONTHS"`, `"SIX_MONTHS"` |
98
+ | `chargePeriod` | Billing cycle: `"MONTHLY"`, `"YEARLY"`, `"ONE_TIME"`, `"WEEKLY"`, `"DAILY"`, `"TWENTY_EIGHT_DAYS"`, `"THREE_MONTHS"`, `"SIX_MONTHS"` |
99
99
  | `successUrl` | URL to redirect after successful payment |
100
100
 
101
101
  ### Optional Parameters
@@ -155,6 +155,8 @@ const activeSubscription = results.find(s => s.status === "active");
155
155
  }
156
156
  ```
157
157
 
158
+ Kelviq handles failed card payment retries and emails the customer a link to pay. Your application does not need its own retry process or payment recovery screen. See [Failed subscription payments](/product-catalog/subscriptions#failed-subscription-payments).
159
+
158
160
  ---
159
161
 
160
162
  ## Step 4: Update Subscription
@@ -174,7 +176,8 @@ const response = await fetch(
174
176
  },
175
177
  body: JSON.stringify({
176
178
  planIdentifier: "enterprise",
177
- chargePeriod: "MONTHLY"
179
+ chargePeriod: "MONTHLY",
180
+ paymentBehavior: "activate_on_payment"
178
181
  })
179
182
  }
180
183
  );
@@ -197,6 +200,25 @@ const data = await response.json();
197
200
  | `planIdentifier` | The identifier of the new plan |
198
201
  | `chargePeriod` | Billing cycle: `"MONTHLY"`, `"YEARLY"`, etc. |
199
202
 
203
+ ### Optional Parameters
204
+
205
+ | Parameter | Description |
206
+ |-----------|-------------|
207
+ | `paymentBehavior` | Set to `"activate_on_payment"` to keep the current subscription active until payment for the change succeeds. Omit it to apply the update immediately. |
208
+
209
+ ### Activation after payment
210
+
211
+ Use `activate_on_payment` when a plan change should not affect access until Kelviq has collected payment.
212
+
213
+ | Payment path | What happens |
214
+ | --- | --- |
215
+ | Saved card with no customer action | Kelviq processes the payment immediately. The updated subscription becomes `active`, and the previous subscription becomes `superseded`. |
216
+ | UPI, 3DS, or another method requiring customer action | The updated subscription starts as `incomplete`. The existing subscription stays `active` until payment succeeds. |
217
+ | Payment succeeds | The updated subscription becomes `active`, and the previous subscription becomes `superseded`. |
218
+ | The immediate charge fails, or payment is not completed before expiry | The updated subscription becomes `incomplete_expired`. The existing subscription remains `active`. |
219
+
220
+ Do not grant the new plan's entitlements just because the update request returned successfully. Confirm that the updated subscription is `active`, or read the customer's current entitlements.
221
+
200
222
  ---
201
223
 
202
224
  ## Step 5: Check Entitlements
@@ -277,8 +299,10 @@ Use your **Client API Key** for this endpoint, not your Server API Key.
277
299
  → Show/hide features based on access
278
300
 
279
301
  4. User wants to upgrade
280
- → Update subscription via API
281
- → Entitlements update automatically
302
+ → Update the subscription with paymentBehavior: "activate_on_payment"
303
+ → Keep the existing subscription active while payment is pending
304
+ → After payment succeeds, the new subscription becomes active
305
+ → The previous subscription becomes superseded
282
306
  ```
283
307
 
284
308
  ---