@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.
Files changed (76) hide show
  1. package/README.md +43 -27
  2. package/dist/config.d.ts +4 -0
  3. package/dist/config.js +30 -9
  4. package/dist/config.js.map +1 -1
  5. package/dist/docs/README.md +16 -0
  6. package/dist/docs/backend-integration/better-auth.md +369 -0
  7. package/dist/docs/backend-integration/node-sdk.md +373 -5
  8. package/dist/docs/backend-integration/python-sdk.md +444 -6
  9. package/dist/docs/changelog/api.md +516 -5
  10. package/dist/docs/changelog/app.md +162 -0
  11. package/dist/docs/changelog/cli.md +33 -0
  12. package/dist/docs/changelog/mcp-server.md +23 -0
  13. package/dist/docs/changelog/node-sdk.md +124 -0
  14. package/dist/docs/changelog/python-sdk.md +135 -0
  15. package/dist/docs/changelog.md +3968 -0
  16. package/dist/docs/checkout/apply-a-discount-code.md +150 -0
  17. package/dist/docs/checkout/checkout-configuration.md +88 -22
  18. package/dist/docs/checkout/checkout-metadata.md +219 -0
  19. package/dist/docs/checkout/static-checkout-url.md +201 -0
  20. package/dist/docs/cli/commands.md +1 -1
  21. package/dist/docs/cli/environments.md +17 -9
  22. package/dist/docs/cli/kelviq-config.md +35 -1
  23. package/dist/docs/cli/overview.md +2 -0
  24. package/dist/docs/coustomers-management/overview.md +15 -19
  25. package/dist/docs/customer-portal/managing-payment-methods.md +30 -48
  26. package/dist/docs/frontend-integration/react-ui.md +51 -16
  27. package/dist/docs/getstarted/fees.md +45 -54
  28. package/dist/docs/getstarted/payment-security-and-seller-funds.md +98 -0
  29. package/dist/docs/getstarted/review-process.md +3 -3
  30. package/dist/docs/guides/agent-toolkit.md +143 -0
  31. package/dist/docs/guides/mcp-server.md +138 -35
  32. package/dist/docs/guides/migrate-from-cashfree.md +7 -0
  33. package/dist/docs/guides/sandbox.md +34 -0
  34. package/dist/docs/guides/subscription-integration-for-nextjs.md +44 -18
  35. package/dist/docs/guides/subscription-integration.md +28 -4
  36. package/dist/docs/guides/webhooks.md +367 -6
  37. package/dist/docs/manifest.json +98 -56
  38. package/dist/docs/openapi.json +7411 -2648
  39. package/dist/docs/payouts/overview.md +30 -0
  40. package/dist/docs/payouts/transactions.md +50 -6
  41. package/dist/docs/product-catalog/create-a-feature.md +113 -0
  42. package/dist/docs/product-catalog/create-an-enterprise-plan.md +133 -0
  43. package/dist/docs/product-catalog/discounts.md +25 -12
  44. package/dist/docs/product-catalog/entitlements.md +53 -16
  45. package/dist/docs/product-catalog/free-and-trials.md +8 -4
  46. package/dist/docs/product-catalog/location-based-pricing.md +2 -0
  47. package/dist/docs/product-catalog/one-time-payments.md +4 -0
  48. package/dist/docs/product-catalog/pay-as-you-go.md +177 -0
  49. package/dist/docs/product-catalog/plans.md +14 -0
  50. package/dist/docs/product-catalog/products.md +5 -13
  51. package/dist/docs/product-catalog/seat-based-pricing.md +233 -0
  52. package/dist/docs/product-catalog/subscriptions.md +109 -12
  53. package/dist/docs/product-catalog/usage-alerts.md +257 -0
  54. package/dist/docs/product-catalog/usage-based-billing.md +49 -12
  55. package/dist/docs/quickstart/dashboard-setup.md +1 -1
  56. package/dist/docs/sales/abandoned-cart-recovery.md +64 -0
  57. package/dist/docs/sales/create-a-one-time-charge.md +144 -0
  58. package/dist/http/client.js +9 -2
  59. package/dist/http/client.js.map +1 -1
  60. package/dist/http/errors.d.ts +8 -0
  61. package/dist/http/errors.js +20 -0
  62. package/dist/http/errors.js.map +1 -1
  63. package/dist/schemas/kelviq.d.ts +199 -0
  64. package/dist/schemas/kelviq.js +173 -0
  65. package/dist/schemas/kelviq.js.map +1 -1
  66. package/dist/server.js +11 -1
  67. package/dist/server.js.map +1 -1
  68. package/dist/tools/discounts.d.ts +3 -0
  69. package/dist/tools/discounts.js +74 -0
  70. package/dist/tools/discounts.js.map +1 -0
  71. package/dist/tools/index.js +4 -0
  72. package/dist/tools/index.js.map +1 -1
  73. package/dist/tools/webhooks.d.ts +10 -0
  74. package/dist/tools/webhooks.js +114 -0
  75. package/dist/tools/webhooks.js.map +1 -0
  76. 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
- **45 tools** spanning customers, checkout, subscriptions, entitlements, licenses, usage, offerings, promotions, the customer portal, and full catalog management (products, plans, features) — plus **69 resources** including 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.
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
- 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, 45 tools`.
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
- ### Cursor
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
- Open **Cursor Settings → MCP**, click **Add new MCP server**, and configure:
99
+ Project-level config overrides global config when a server of the same name exists in both.
82
100
 
83
- | Field | Value |
84
- |-------|-------|
85
- | Command | `npx` |
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
- ### Other Clients
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 | `production` | Set to `sandbox` to target your sandbox environment — switches both API hosts automatically. Use a sandbox key with it: keys only work against their own environment. |
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 conceptual page in the Kelviq docs (~59 pages) |
243
- | `kelviq://openapi.json` | The full OpenAPI 3.0 spec (49 operations, every schema) |
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: your key is for **production** but the identifier exists only in **staging** (or vice versa). Check `KELVIQ_BASE_URL`.
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
- 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
  ---