@kelviq/mcp-server 0.4.0 → 1.1.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.
- package/README.md +43 -27
- package/dist/config.d.ts +4 -0
- package/dist/config.js +30 -9
- package/dist/config.js.map +1 -1
- package/dist/docs/README.md +16 -0
- package/dist/docs/backend-integration/better-auth.md +369 -0
- package/dist/docs/backend-integration/node-sdk.md +373 -5
- package/dist/docs/backend-integration/python-sdk.md +444 -6
- package/dist/docs/changelog/api.md +516 -5
- package/dist/docs/changelog/app.md +162 -0
- package/dist/docs/changelog/cli.md +33 -0
- package/dist/docs/changelog/mcp-server.md +23 -0
- package/dist/docs/changelog/node-sdk.md +124 -0
- package/dist/docs/changelog/python-sdk.md +135 -0
- package/dist/docs/changelog.md +3968 -0
- package/dist/docs/checkout/apply-a-discount-code.md +150 -0
- package/dist/docs/checkout/checkout-configuration.md +88 -22
- package/dist/docs/checkout/checkout-metadata.md +219 -0
- package/dist/docs/checkout/static-checkout-url.md +201 -0
- package/dist/docs/cli/commands.md +1 -1
- package/dist/docs/cli/environments.md +17 -9
- package/dist/docs/cli/kelviq-config.md +35 -1
- package/dist/docs/cli/overview.md +2 -0
- package/dist/docs/coustomers-management/overview.md +15 -19
- package/dist/docs/customer-portal/managing-payment-methods.md +30 -48
- package/dist/docs/frontend-integration/react-ui.md +51 -16
- package/dist/docs/getstarted/fees.md +45 -54
- package/dist/docs/getstarted/payment-security-and-seller-funds.md +98 -0
- package/dist/docs/getstarted/review-process.md +3 -3
- package/dist/docs/guides/agent-toolkit.md +143 -0
- package/dist/docs/guides/mcp-server.md +138 -35
- package/dist/docs/guides/migrate-from-cashfree.md +7 -0
- package/dist/docs/guides/sandbox.md +34 -0
- package/dist/docs/guides/subscription-integration-for-nextjs.md +44 -18
- package/dist/docs/guides/subscription-integration.md +28 -4
- package/dist/docs/guides/webhooks.md +367 -6
- package/dist/docs/manifest.json +98 -56
- package/dist/docs/openapi.json +7411 -2648
- package/dist/docs/payouts/overview.md +30 -0
- package/dist/docs/payouts/transactions.md +50 -6
- package/dist/docs/product-catalog/create-a-feature.md +113 -0
- package/dist/docs/product-catalog/create-an-enterprise-plan.md +133 -0
- package/dist/docs/product-catalog/discounts.md +25 -12
- package/dist/docs/product-catalog/entitlements.md +53 -16
- package/dist/docs/product-catalog/free-and-trials.md +8 -4
- package/dist/docs/product-catalog/location-based-pricing.md +2 -0
- package/dist/docs/product-catalog/one-time-payments.md +4 -0
- package/dist/docs/product-catalog/pay-as-you-go.md +177 -0
- package/dist/docs/product-catalog/plans.md +14 -0
- package/dist/docs/product-catalog/products.md +5 -13
- package/dist/docs/product-catalog/seat-based-pricing.md +233 -0
- package/dist/docs/product-catalog/subscriptions.md +109 -12
- package/dist/docs/product-catalog/usage-alerts.md +257 -0
- package/dist/docs/product-catalog/usage-based-billing.md +49 -12
- package/dist/docs/quickstart/dashboard-setup.md +1 -1
- package/dist/docs/sales/abandoned-cart-recovery.md +64 -0
- package/dist/docs/sales/create-a-one-time-charge.md +144 -0
- package/dist/http/client.js +9 -2
- package/dist/http/client.js.map +1 -1
- package/dist/http/errors.d.ts +8 -0
- package/dist/http/errors.js +20 -0
- package/dist/http/errors.js.map +1 -1
- package/dist/schemas/kelviq.d.ts +199 -0
- package/dist/schemas/kelviq.js +173 -0
- package/dist/schemas/kelviq.js.map +1 -1
- package/dist/server.js +11 -1
- package/dist/server.js.map +1 -1
- package/dist/tools/discounts.d.ts +3 -0
- package/dist/tools/discounts.js +74 -0
- package/dist/tools/discounts.js.map +1 -0
- package/dist/tools/index.js +4 -0
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/webhooks.d.ts +10 -0
- package/dist/tools/webhooks.js +114 -0
- package/dist/tools/webhooks.js.map +1 -0
- 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,
|
|
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
|
-
**
|
|
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
|
+
**56 tools** spanning customers, checkout, subscriptions, discounts, webhooks, 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
|
-
|
|
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
|
-
|
|
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
|
-
--
|
|
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,
|
|
57
|
-
|
|
58
|
-
### Claude Desktop
|
|
59
|
+
Verify the connection with `/mcp` inside a Claude Code session — you should see `kelviq ✓ Connected, 56 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
|
-
|
|
81
|
+
Open **Cursor Settings → Tools and MCP → Add new MCP server**, or edit `.cursor/mcp.json` (project) / `~/.cursor/mcp.json` (global) directly:
|
|
82
|
+
|
|
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
|
+
```
|
|
80
98
|
|
|
81
|
-
|
|
99
|
+
Project-level config overrides global config when a server of the same name exists in both.
|
|
82
100
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
| Args | `-y @kelviq/mcp-server` |
|
|
87
|
-
| Environment Variables | `KELVIQ_SERVER_API_KEY`, `KELVIQ_CLIENT_API_KEY` |
|
|
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`
|
|
88
104
|
|
|
89
|
-
|
|
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.
|
|
@@ -118,21 +199,12 @@ Your AI client should pick the right tool, call it, and show the result inline.
|
|
|
118
199
|
|----------|----------|---------|---------|
|
|
119
200
|
| `KELVIQ_SERVER_API_KEY` | Yes, for all API tools | — | Server API key (Bearer token for the core API) |
|
|
120
201
|
| `KELVIQ_CLIENT_API_KEY` | Only for `promotion_get` | — | Client API key (Bearer token for the edge host) |
|
|
121
|
-
| `KELVIQ_ENV` | No | `
|
|
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. |
|
|
122
203
|
| `KELVIQ_BASE_URL` | No | per `KELVIQ_ENV` | Advanced: override the core API host |
|
|
123
204
|
| `KELVIQ_EDGE_URL` | No | per `KELVIQ_ENV` | Advanced: override the edge host (entitlements + promotions) |
|
|
124
205
|
|
|
125
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.
|
|
126
207
|
|
|
127
|
-
### Point at Staging
|
|
128
|
-
|
|
129
|
-
```env
|
|
130
|
-
KELVIQ_BASE_URL=https://stagingapi.kelviq.com/api/v1
|
|
131
|
-
KELVIQ_EDGE_URL=https://edge.stagingapi.kelviq.com/api/v1
|
|
132
|
-
```
|
|
133
|
-
|
|
134
|
-
Pair these with a **staging-scoped** Server API Key from your dashboard's staging environment.
|
|
135
|
-
|
|
136
208
|
---
|
|
137
209
|
|
|
138
210
|
## Tool Reference
|
|
@@ -179,6 +251,29 @@ Tools are grouped by domain. Each tool name uses `domain_action` form (`customer
|
|
|
179
251
|
| `offering_get_product` | Fetch public pricing scoped to a product UUID. Includes localized prices + customer subscription state. |
|
|
180
252
|
| `promotion_get` | Resolve the active promotion for the caller's location. Uses Client API key. |
|
|
181
253
|
|
|
254
|
+
### Discounts
|
|
255
|
+
|
|
256
|
+
| Tool | Description |
|
|
257
|
+
|------|-------------|
|
|
258
|
+
| `discount_list` | List discount codes. Optional `search` across name and code, paginated. |
|
|
259
|
+
| `discount_create` | Create a percentage or fixed-amount code, optionally limited to products or plans with `appliesTo`. Merchant of Record organizations only. |
|
|
260
|
+
| `discount_retrieve` | Fetch one discount, including how often it's been redeemed and whether it's active. |
|
|
261
|
+
| `discount_update` | Enable or disable a code with `isActive`. Nothing else can change after creation. |
|
|
262
|
+
| `discount_archive` | Archive a code so it can no longer be used. |
|
|
263
|
+
|
|
264
|
+
### Webhooks
|
|
265
|
+
|
|
266
|
+
| Tool | Description |
|
|
267
|
+
|------|-------------|
|
|
268
|
+
| `webhook_endpoint_list` | List endpoints with their URLs, events and enabled state. |
|
|
269
|
+
| `webhook_endpoint_create` | Register a public URL for the events you choose. Localhost and private addresses are rejected. |
|
|
270
|
+
| `webhook_endpoint_retrieve` | Fetch one endpoint. |
|
|
271
|
+
| `webhook_endpoint_update` | Change an endpoint's URL, events or enabled state. |
|
|
272
|
+
| `webhook_endpoint_delete` | Delete an endpoint. Deliveries stop immediately. |
|
|
273
|
+
| `webhook_log_list` | Delivery attempts from the last 30 days, with status codes and retries. |
|
|
274
|
+
|
|
275
|
+
Signing secrets are hidden in webhook tool results. Pass `revealSecret: true` only when you need the value — your app reads the secret from its env file, so it rarely needs to appear in a conversation.
|
|
276
|
+
|
|
182
277
|
### Catalog: Products
|
|
183
278
|
|
|
184
279
|
| Tool | Description |
|
|
@@ -239,8 +334,8 @@ Resources let your AI client pin pages into context. The server advertises three
|
|
|
239
334
|
|
|
240
335
|
| URI pattern | Content |
|
|
241
336
|
|-------------|---------|
|
|
242
|
-
| `kelviq://docs/{section}/{slug}` | Every
|
|
243
|
-
| `kelviq://openapi.json` | The full OpenAPI 3.0 spec (
|
|
337
|
+
| `kelviq://docs/{section}/{slug}` | Every page in the Kelviq docs |
|
|
338
|
+
| `kelviq://openapi.json` | The full OpenAPI 3.0 spec (every operation and schema) |
|
|
244
339
|
| `kelviq://README` | Top-level Kelviq overview |
|
|
245
340
|
|
|
246
341
|
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.
|
|
@@ -325,16 +420,24 @@ GUI/launcher processes don't source `~/.zshrc`, so nvm's `node` isn't visible to
|
|
|
325
420
|
```bash
|
|
326
421
|
claude mcp add kelviq \
|
|
327
422
|
--env KELVIQ_SERVER_API_KEY=... \
|
|
328
|
-
-- npx -y @kelviq/mcp-server
|
|
423
|
+
-- npx -y @kelviq/mcp-server@latest
|
|
329
424
|
```
|
|
330
425
|
|
|
331
426
|
### Tool returns `{"error": {"status": "Configuration error", ...}}`
|
|
332
427
|
|
|
333
428
|
A required env var is missing. The error message names which one — set it in your client config and reconnect.
|
|
334
429
|
|
|
430
|
+
### Tool returns HTTP 401 or 403
|
|
431
|
+
|
|
432
|
+
Almost always, the key belongs to the other environment: a sandbox key only works against sandbox, and a production key only against production.
|
|
433
|
+
|
|
434
|
+
- 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.
|
|
435
|
+
- 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.
|
|
436
|
+
- 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.
|
|
437
|
+
|
|
335
438
|
### Tool returns `{"error": {"status": "Bad request", "message": "Invalid product identifier"}}`
|
|
336
439
|
|
|
337
|
-
Your API key works but the identifier doesn't exist on this account. Most common cause:
|
|
440
|
+
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`.
|
|
338
441
|
|
|
339
442
|
### Test Without an AI Client
|
|
340
443
|
|
|
@@ -343,7 +446,7 @@ Use the official [MCP Inspector](https://github.com/modelcontextprotocol/inspect
|
|
|
343
446
|
```bash
|
|
344
447
|
KELVIQ_SERVER_API_KEY=... KELVIQ_CLIENT_API_KEY=... \
|
|
345
448
|
npx -y @modelcontextprotocol/inspector \
|
|
346
|
-
npx -y @kelviq/mcp-server
|
|
449
|
+
npx -y @kelviq/mcp-server@latest
|
|
347
450
|
```
|
|
348
451
|
|
|
349
452
|
---
|
|
@@ -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
|
-
|
|
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
|
-
|
|
40
|
-
|
|
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
|
-
`${
|
|
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.
|
|
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
|
-
`${
|
|
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.
|
|
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
|
-
`${
|
|
268
|
+
`${KELVIQ_API_URL}/subscriptions/?customer_id=${customerId}`,
|
|
255
269
|
{
|
|
256
270
|
headers: {
|
|
257
|
-
Authorization: `Bearer ${process.env.
|
|
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 {
|
|
290
|
+
const {
|
|
291
|
+
subscriptionId,
|
|
292
|
+
planIdentifier,
|
|
293
|
+
chargePeriod,
|
|
294
|
+
paymentBehavior,
|
|
295
|
+
} = await request.json();
|
|
276
296
|
|
|
277
297
|
const response = await fetch(
|
|
278
|
-
`${
|
|
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.
|
|
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
|
|
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.
|
|
345
|
-
|
|
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
|
|
281
|
-
→
|
|
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
|
---
|