@kelviq/mcp-server 0.2.1 → 0.3.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 (49) hide show
  1. package/README.md +22 -20
  2. package/dist/config.d.ts +8 -2
  3. package/dist/config.js +42 -9
  4. package/dist/config.js.map +1 -1
  5. package/dist/docs/api-reference/authentication.md +7 -3
  6. package/dist/docs/api-reference/introduction.md +143 -0
  7. package/dist/docs/backend-integration/node-sdk.md +148 -6
  8. package/dist/docs/backend-integration/python-sdk.md +195 -11
  9. package/dist/docs/changelog/api.md +119 -0
  10. package/dist/docs/changelog/app.md +693 -0
  11. package/dist/docs/changelog/node-sdk.md +153 -0
  12. package/dist/docs/changelog/python-sdk.md +182 -0
  13. package/dist/docs/cli/commands.md +225 -0
  14. package/dist/docs/cli/environments.md +95 -0
  15. package/dist/docs/cli/kelviq-config.md +141 -0
  16. package/dist/docs/cli/overview.md +223 -0
  17. package/dist/docs/customer-portal/managing-payment-methods.md +72 -0
  18. package/dist/docs/guides/mcp-server.md +374 -0
  19. package/dist/docs/guides/sandbox.md +107 -0
  20. package/dist/docs/guides/webhooks.md +81 -0
  21. package/dist/docs/manifest.json +64 -8
  22. package/dist/docs/openapi.json +1208 -52
  23. package/dist/docs/product-catalog/one-time-payments.md +3 -1
  24. package/dist/docs/product-catalog/usage-based-billing.md +86 -7
  25. package/dist/docs/quickstart/dashboard-setup.md +1 -1
  26. package/dist/http/client.d.ts +1 -1
  27. package/dist/http/client.js +1 -5
  28. package/dist/http/client.js.map +1 -1
  29. package/dist/schemas/kelviq.d.ts +0 -128
  30. package/dist/schemas/kelviq.js +0 -63
  31. package/dist/schemas/kelviq.js.map +1 -1
  32. package/dist/server.js +2 -2
  33. package/dist/server.js.map +1 -1
  34. package/dist/tools/entitlements.js +1 -1
  35. package/dist/tools/entitlements.js.map +1 -1
  36. package/dist/tools/index.js +0 -4
  37. package/dist/tools/index.js.map +1 -1
  38. package/dist/tools/plan-files.js +1 -1
  39. package/dist/tools/plan-files.js.map +1 -1
  40. package/dist/tools/plans.js +1 -15
  41. package/dist/tools/plans.js.map +1 -1
  42. package/dist/tools/portal.d.ts +11 -1
  43. package/dist/tools/portal.js +27 -2
  44. package/dist/tools/portal.js.map +1 -1
  45. package/dist/tools/products.js +1 -1
  46. package/dist/tools/products.js.map +1 -1
  47. package/dist/tools/subscriptions.js +1 -1
  48. package/dist/tools/subscriptions.js.map +1 -1
  49. package/package.json +5 -2
@@ -0,0 +1,374 @@
1
+ ---
2
+ title: "MCP Server"
3
+ slug: "guides/mcp-server"
4
+ section: "guides"
5
+ description: "Control Kelviq from Claude, Cursor, and any AI assistant that speaks the Model Context Protocol."
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**.
8
+
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
+
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.
12
+
13
+ ---
14
+
15
+ ## How It Works
16
+
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.
18
+
19
+ When the LLM decides to call a Kelviq tool, the server:
20
+
21
+ 1. Validates the LLM-provided arguments against a Zod schema derived from Kelviq's OpenAPI spec.
22
+ 2. Adds your API key as a Bearer token and sends the HTTPS request to the appropriate Kelviq host.
23
+ 3. Returns the JSON response (or a structured `{"error": {...}}` object) back to the LLM.
24
+
25
+ API errors are returned as content, not exceptions — the LLM reads them and reacts (retries with a fix, asks you to clarify, etc).
26
+
27
+ ---
28
+
29
+ ## Step 1: Get Your API Keys
30
+
31
+ 1. Sign in at [app.kelviq.com](https://app.kelviq.com).
32
+ 2. Navigate to **Settings → API Keys**.
33
+ 3. Copy:
34
+ - **Server API Key** — required for all API tools.
35
+ - **Client API Key** — required only for the `promotion_get` tool.
36
+
37
+ Never commit API keys to version control or paste them into shared chats. Use your MCP client's `env` configuration mechanism — most clients store secrets in their own credentials file.
38
+
39
+ ---
40
+
41
+ ## Step 2: Add the Server to Your AI Client
42
+
43
+ Pick the section that matches your client.
44
+
45
+ ### Claude Code (CLI)
46
+
47
+ ```bash
48
+ claude mcp add kelviq \
49
+ --env KELVIQ_SERVER_API_KEY=<your-server-key> \
50
+ --env KELVIQ_CLIENT_API_KEY=<your-client-key> \
51
+ -- npx -y @kelviq/mcp-server
52
+ ```
53
+
54
+ The `--` separator is required so that `claude` doesn't intercept `-y` as one of its own flags. Put all `--env` arguments **before** the `--`.
55
+
56
+ Verify the connection with `/mcp` inside a Claude Code session — you should see `kelviq ✓ Connected, 51 tools`.
57
+
58
+ ### Claude Desktop
59
+
60
+ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent for your OS:
61
+
62
+ ```json
63
+ {
64
+ "mcpServers": {
65
+ "kelviq": {
66
+ "command": "npx",
67
+ "args": ["-y", "@kelviq/mcp-server"],
68
+ "env": {
69
+ "KELVIQ_SERVER_API_KEY": "server-...",
70
+ "KELVIQ_CLIENT_API_KEY": "client-..."
71
+ }
72
+ }
73
+ }
74
+ }
75
+ ```
76
+
77
+ Restart Claude Desktop — the hammer icon shows `kelviq` with all tools.
78
+
79
+ ### Cursor
80
+
81
+ Open **Cursor Settings → MCP**, click **Add new MCP server**, and configure:
82
+
83
+ | Field | Value |
84
+ |-------|-------|
85
+ | Command | `npx` |
86
+ | Args | `-y @kelviq/mcp-server` |
87
+ | Environment Variables | `KELVIQ_SERVER_API_KEY`, `KELVIQ_CLIENT_API_KEY` |
88
+
89
+ ### Other Clients
90
+
91
+ Any client supporting stdio MCP servers works. Point it at:
92
+
93
+ ```bash
94
+ npx -y @kelviq/mcp-server
95
+ ```
96
+
97
+ with the env vars listed below.
98
+
99
+ ---
100
+
101
+ ## Step 3: Try It
102
+
103
+ In a new session, type a prompt like:
104
+
105
+ > *Search Kelviq docs for license keys.*
106
+
107
+ or
108
+
109
+ > *List my Kelviq products.*
110
+
111
+ Your AI client should pick the right tool, call it, and show the result inline. If you see a `Configuration error`, your env vars didn't make it through — re-check the config above.
112
+
113
+ ---
114
+
115
+ ## Environment Variables
116
+
117
+ | Variable | Required | Default | Purpose |
118
+ |----------|----------|---------|---------|
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) |
123
+
124
+ 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
+
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
+ ---
136
+
137
+ ## Tool Reference
138
+
139
+ Tools are grouped by domain. Each tool name uses `domain_action` form (`customer_create`, `plan_publish`). The LLM picks the right tool from the description automatically — you rarely need to name a tool explicitly.
140
+
141
+ ### Customers
142
+
143
+ | Tool | Description |
144
+ |------|-------------|
145
+ | `customer_create` | Create a customer. Required: `customerId`. Optional: `email`, `name`, `metadata`, `billingAddress`. |
146
+ | `customer_update` | Patch an existing customer by `customerId`. Only fields you pass are updated. |
147
+
148
+ ### Checkout & Portal
149
+
150
+ | Tool | Description |
151
+ |------|-------------|
152
+ | `checkout_create_session` | Create a hosted checkout session. Returns `checkoutUrl` + `checkoutSessionId`. |
153
+ | `portal_session_create` | Mint a pre-authenticated customer portal URL. |
154
+
155
+ ### Subscriptions
156
+
157
+ | Tool | Description |
158
+ |------|-------------|
159
+ | `subscription_create` | Create a subscription directly (skip checkout). |
160
+ | `subscription_list` | List subscriptions, filter by customer, paginated. |
161
+ | `subscription_update` | Change plan / charge period / features. Free plans must use `checkout_create_session` to upgrade. |
162
+ | `subscription_cancel` | Cancel `IMMEDIATE`, `CURRENT_PERIOD_ENDS`, or `SPECIFIC_DATE`. |
163
+
164
+ ### Entitlements, Licenses, Usage
165
+
166
+ | Tool | Description |
167
+ |------|-------------|
168
+ | `entitlements_get` | Fetch entitlements for a customer. Pass `featureId` to scope. |
169
+ | `license_activate` | Activate a license key for a specific instance. Returns `instanceId`. |
170
+ | `license_deactivate` | Deactivate a license instance. |
171
+ | `license_validate` | Validate a license key (optionally bound to an instance). |
172
+ | `usage_report` | Report metered usage. `behaviour: SET` replaces, `DELTA` increments. |
173
+
174
+ ### Offerings & Promotions
175
+
176
+ | Tool | Description |
177
+ |------|-------------|
178
+ | `offering_get_product` | Fetch public pricing scoped to a product UUID. Includes localized prices + customer subscription state. |
179
+ | `promotion_get` | Resolve the active promotion for the caller's location. Uses Client API key. |
180
+
181
+ ### Catalog: Products
182
+
183
+ | Tool | Description |
184
+ |------|-------------|
185
+ | `product_list` | List catalog products. Optional `search` substring + `page`. |
186
+ | `product_create` | Create a product. Required: `name`, `taxCode`. Optional `imageKeys` from `media_presigned_upload`. |
187
+ | `product_retrieve` | Fetch one product by UUID or identifier. |
188
+ | `product_update` | Patch a product. |
189
+ | `product_archive` | Archive (soft-delete) a product. |
190
+ | `product_settings_get` | VPN / Tor / proxy policy, default currency, product URL. |
191
+ | `product_settings_update` | Patch any subset of those settings. |
192
+ | `product_image_update` | Edit display fields of a product image (`name`, `ordering`, `thumbnail`, `enabled`). |
193
+ | `product_image_delete` | Remove an image from a product. |
194
+
195
+ ### Catalog: Features
196
+
197
+ | Tool | Description |
198
+ |------|-------------|
199
+ | `feature_list` | List catalog features. |
200
+ | `feature_create` | Create a feature. Required: `name`, `featureType` (`BOOLEAN` / `CUSTOMIZABLE` / `METER`). |
201
+ | `feature_retrieve` | Fetch one feature. |
202
+ | `feature_archive` | Archive a feature. Plans referencing it keep working. |
203
+
204
+ ### Catalog: Plans
205
+
206
+ Plans are versioned. Updates create a draft; `plan_publish` releases it.
207
+
208
+ | Tool | Description |
209
+ |------|-------------|
210
+ | `plan_list` | List all plans in the account. |
211
+ | `plan_create` | Create a plan under a product. Plan starts in `DRAFT`. |
212
+ | `plan_retrieve` | Fetch one plan. |
213
+ | `plan_update` | Patch a plan. Updates to a published plan automatically create a new draft. |
214
+ | `plan_archive` | Archive a plan. Existing subscriptions keep working. |
215
+ | `plan_publish` | Publish the latest draft. `updateFeatures` / `updatePricing` flags migrate existing customers. |
216
+ | `plan_discard_draft` | Drop the current draft, keep the published version. |
217
+ | `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
+ | `plan_entitlements_list` | List feature entitlements on a plan. |
220
+ | `plan_entitlements_add` | Attach feature entitlements. |
221
+ | `plan_entitlement_update` | Patch a single entitlement's `details`. |
222
+ | `plan_entitlement_delete` | Remove an entitlement. |
223
+ | `plan_file_update` | Edit display fields of a plan-attached file. |
224
+ | `plan_file_delete` | Remove a file from a plan. |
225
+ | `plan_file_download` | Download URL/stream for a plan file (buyer-facing deliverables). |
226
+
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
+ ### Docs (no API key required)
243
+
244
+ | Tool | Description |
245
+ |------|-------------|
246
+ | `docs_search` | Full-text search across the bundled Kelviq docs. Returns `{slug, title, snippet, score}`. |
247
+ | `docs_read` | Fetch a full markdown doc by slug. |
248
+
249
+ ---
250
+
251
+ ## Resources
252
+
253
+ Resources let your AI client pin pages into context. The server advertises three categories:
254
+
255
+ | URI pattern | Content |
256
+ |-------------|---------|
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) |
259
+ | `kelviq://README` | Top-level Kelviq overview |
260
+
261
+ 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
+
263
+ ---
264
+
265
+ ## Example Prompts
266
+
267
+ Describe the outcome, not the API call. A few realistic prompts that exercise the toolchain:
268
+
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.*
270
+
271
+ Calls (in order): `product_create` → `feature_create` → `plan_create` × 3 → `plan_entitlements_add` × 3 → `plan_prices_bulk_set` × 3 → `plan_publish` × 3.
272
+
273
+ > *Create a checkout session for plan `pro-monthly` for a new customer, success URL https://example.com/done.*
274
+
275
+ Calls: `checkout_create_session`. Returns the `checkoutUrl` you can hand to your buyer.
276
+
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
+ > *Activate license `LIC-ABCDE` for customer `geojacob`, instance name "MacBook Pro M3", then validate it.*
282
+
283
+ Calls: `license_activate` → `license_validate`.
284
+
285
+ > *Show me all subscriptions for customer `acme-42` and tell me which features they have access to.*
286
+
287
+ Calls: `subscription_list` → `entitlements_get`.
288
+
289
+ > *How do digital downloads work in Kelviq? What's the file-size limit?*
290
+
291
+ Calls: `docs_search` → `docs_read`. No API key needed — works offline.
292
+
293
+ ---
294
+
295
+ ## Tips for Effective Prompts
296
+
297
+ - **Mention "Kelviq" early.** LLMs typically have many MCP tools loaded. Saying "create a *Kelviq* customer" steers the model toward this server's tools instead of guessing.
298
+ - **Use `docs_search` for fuzzy questions.** When you're unsure of an identifier or behaviour, ask the LLM to *"search Kelviq docs"* first — it grounds the follow-up calls in real semantics.
299
+ - **Trust the errors.** Tools return `{"error": {"status", "message"}}` shapes for API errors. The LLM reads them and adjusts automatically (e.g. "Invalid product identifier" → asks you for the right one).
300
+ - **Combine tools in one prompt.** The LLM is happy to chain calls. "Create the product, then publish all its plans" is one prompt, not five.
301
+
302
+ ---
303
+
304
+ ## Troubleshooting
305
+
306
+ ### `Executable not found in $PATH: "node"` in Claude Code
307
+
308
+ GUI/launcher processes don't source `~/.zshrc`, so nvm's `node` isn't visible to them. Pick one fix:
309
+
310
+ 1. **Symlink node into a system path** (recommended):
311
+ ```bash
312
+ sudo ln -s "$(which node)" /usr/local/bin/node
313
+ ```
314
+ One-time fix for every MCP server you'll ever add.
315
+
316
+ 2. **Use the absolute node path:**
317
+ ```bash
318
+ claude mcp add kelviq \
319
+ --env KELVIQ_SERVER_API_KEY=... \
320
+ -- /Users/you/.nvm/versions/node/v20.19.0/bin/node \
321
+ $(npm root -g)/@kelviq/mcp-server/dist/server.js
322
+ ```
323
+
324
+ 3. **Install Node via Homebrew:**
325
+ ```bash
326
+ brew install node
327
+ ```
328
+ Puts `node` on the system PATH so all GUI tools see it.
329
+
330
+ ### `error: unknown option '-y'` from `claude mcp add`
331
+
332
+ `claude` is intercepting `-y` as one of its own flags. Use `--` to separate Claude's args from the actual command:
333
+
334
+ ```bash
335
+ claude mcp add kelviq \
336
+ --env KELVIQ_SERVER_API_KEY=... \
337
+ -- npx -y @kelviq/mcp-server
338
+ ```
339
+
340
+ ### Tool returns `{"error": {"status": "Configuration error", ...}}`
341
+
342
+ A required env var is missing. The error message names which one — set it in your client config and reconnect.
343
+
344
+ ### Tool returns `{"error": {"status": "Bad request", "message": "Invalid product identifier"}}`
345
+
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`.
347
+
348
+ ### Test Without an AI Client
349
+
350
+ Use the official [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to browse and call tools directly from a browser:
351
+
352
+ ```bash
353
+ KELVIQ_SERVER_API_KEY=... KELVIQ_CLIENT_API_KEY=... \
354
+ npx -y @modelcontextprotocol/inspector \
355
+ npx -y @kelviq/mcp-server
356
+ ```
357
+
358
+ ---
359
+
360
+ ## Source & Contributing
361
+
362
+ - **npm** — [`@kelviq/mcp-server`](https://www.npmjs.com/package/@kelviq/mcp-server)
363
+ - **GitHub** — [`kelviq/kelviq-mcp-server`](https://github.com/kelviq/kelviq-mcp-server)
364
+ - **Issues** — [github.com/kelviq/kelviq-mcp-server/issues](https://github.com/kelviq/kelviq-mcp-server/issues)
365
+ - **License** — MIT
366
+
367
+ The repo is the canonical reference for tool schemas, build process, and contribution guidelines. New Kelviq API endpoints are added by extending the hand-written Zod schemas in `src/schemas/kelviq.ts` and the per-domain files in `src/tools/`.
368
+
369
+ ---
370
+
371
+ ## Need Help?
372
+
373
+ - Email us at **hi@kelviq.com**
374
+ - [Book a demo](https://tidycal.com/neravath/15-minute-meeting)
@@ -0,0 +1,107 @@
1
+ ---
2
+ title: "Sandbox"
3
+ slug: "guides/sandbox"
4
+ section: "guides"
5
+ description: "Build and test your Kelviq integration without affecting production data or processing real payments"
6
+ ---
7
+ Kelviq's sandbox is a separate environment for development and testing. You can configure products and plans, create customers, exercise checkout flows, and test your integration without affecting your live organization or processing real payments.
8
+
9
+ ## How isolation works
10
+
11
+ Sandbox and production use separate data and credentials.
12
+
13
+ | Resource | Sandbox behavior |
14
+ | --- | --- |
15
+ | Data | Products, plans, customers, subscriptions, and orders are isolated from production |
16
+ | API keys | Work only with sandbox hosts |
17
+ | Payments | Use test card details; no real charge is made |
18
+
19
+ This separation prevents development activity from changing live customer or billing data. Before launch, configure the resources your integration needs in production and replace all sandbox credentials and URLs.
20
+
21
+ ## Get started
22
+
23
+ 1. Sign in to the [Kelviq dashboard](https://app.kelviq.com).
24
+ 2. Open the organization dropdown and click **Enter sandbox**.
25
+ 3. Create the products, plans, prices, and other test data you need.
26
+ 4. Open **Settings → API keys** and copy the sandbox key required by your integration.
27
+
28
+ Never use a production Server API Key in test code. Store Server API Keys in environment variables and use Client API Keys only in supported browser integrations.
29
+
30
+ ## Connect to the sandbox API
31
+
32
+ Use the sandbox hosts with sandbox-scoped credentials:
33
+
34
+ | API | Sandbox base URL |
35
+ | --- | --- |
36
+ | Core API | `https://sandboxapi.kelviq.com/api/v1` |
37
+ | Edge API | `https://edge.sandboxapi.kelviq.com/api/v1` |
38
+
39
+ For example:
40
+
41
+ ```bash
42
+ curl https://sandboxapi.kelviq.com/api/v1/catalog/products/ \
43
+ --header "Authorization: Bearer $KELVIQ_SANDBOX_SERVER_API_KEY" \
44
+ --header "Accept: application/json"
45
+ ```
46
+
47
+ Changing only the URL is not enough: the request must also use an API key created while the dashboard is in Sandbox mode.
48
+
49
+ ## Use the sandbox with an SDK
50
+
51
+ Set `environment` to `sandbox` when initializing an official SDK.
52
+
53
+ ```typescript Node.js
54
+ import { Kelviq } from "@kelviq/node-sdk";
55
+
56
+ const client = new Kelviq({
57
+ accessToken: process.env.KELVIQ_SANDBOX_SERVER_API_KEY,
58
+ environment: "sandbox",
59
+ });
60
+ ```
61
+
62
+ ```python Python
63
+ from kelviq_sdk import Kelviq
64
+
65
+ client = Kelviq.create_sync_client(
66
+ access_token=KELVIQ_SANDBOX_SERVER_API_KEY,
67
+ environment="sandbox",
68
+ )
69
+ ```
70
+
71
+ ```tsx React
72
+ <KelviqProvider
73
+ customerId="YOUR_TEST_CUSTOMER_ID"
74
+ accessToken="YOUR_SANDBOX_CLIENT_API_KEY"
75
+ environment="sandbox"
76
+ >
77
+ {children}
78
+ </KelviqProvider>
79
+ ```
80
+
81
+ See the [Node SDK](/backend-integration/node-sdk), [Python SDK](/backend-integration/python-sdk), or [frontend SDK guides](/frontend-integration/react-sdk) for full setup instructions.
82
+
83
+ ## Test checkout
84
+
85
+ Create a checkout in the sandbox and use Stripe test card details. Use any future expiration date and a valid test CVC.
86
+
87
+ | Card number | Result |
88
+ | --- | --- |
89
+ | `4242 4242 4242 4242` | Successful payment |
90
+ | `4000 0000 0000 0002` | Declined payment |
91
+ | `4000 0025 0000 3155` | Payment requiring authentication |
92
+
93
+ Do not enter a real card number in the sandbox.
94
+
95
+ After payment, confirm that the test order, customer, subscription, and entitlements have the expected state in Sandbox mode.
96
+
97
+ ## Prepare for production
98
+
99
+ Before accepting live payments:
100
+
101
+ 1. Complete the required [business review and payout setup](/getstarted/review-process).
102
+ 2. Configure and publish your production products and plans.
103
+ 3. Replace sandbox API keys with production API keys.
104
+ 4. Replace sandbox base URLs or set each SDK's environment to `production`.
105
+ 5. Run a final check that no sandbox credentials or hosts remain in your production configuration.
106
+
107
+ Use clearly named variables such as `KELVIQ_SANDBOX_SERVER_API_KEY` and `KELVIQ_PRODUCTION_SERVER_API_KEY` to reduce the chance of mixing environments.
@@ -100,6 +100,20 @@ The request body is a JSON object with the following top-level fields:
100
100
  "status": "success",
101
101
  "checkout_type": "ONE_TIME",
102
102
  "customer_id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
103
+ "customer": {
104
+ "id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
105
+ "name": "Geo Jacob",
106
+ "email": "geojacob@example.com",
107
+ "customer_id": "geo-jacob",
108
+ "billing_address": {
109
+ "line1": null,
110
+ "line2": null,
111
+ "city": null,
112
+ "state": null,
113
+ "postal_code": "680121",
114
+ "country": "IN"
115
+ }
116
+ },
103
117
  "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
104
118
  "amount": "10.00",
105
119
  "amount_units": 1000,
@@ -124,6 +138,10 @@ The request body is a JSON object with the following top-level fields:
124
138
  "country": "IN"
125
139
  },
126
140
  "metadata": {
141
+ "order_ref": "ABC-123",
142
+ "source": "pricing_page"
143
+ },
144
+ "data": {
127
145
  "name": "Geo",
128
146
  "email": "geojacob@example.com",
129
147
  "referer": null,
@@ -202,6 +220,13 @@ The request body is a JSON object with the following top-level fields:
202
220
  "status": "COMPLETE",
203
221
  "billing_type": "ONE_TIME",
204
222
  "customer_id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
223
+ "customer": {
224
+ "id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
225
+ "name": "Geo Jacob",
226
+ "email": "geojacob@example.com",
227
+ "customer_id": "geo-jacob",
228
+ "billing_address": {}
229
+ },
205
230
  "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
206
231
  "is_renewal": false,
207
232
  "paid_at": "2026-04-01T17:36:41Z",
@@ -238,6 +263,20 @@ The request body is a JSON object with the following top-level fields:
238
263
  "status": "COMPLETE",
239
264
  "billing_type": "ONE_TIME",
240
265
  "customer_id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
266
+ "customer": {
267
+ "id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
268
+ "name": "Geo Jacob",
269
+ "email": "geojacob@example.com",
270
+ "customer_id": "geo-jacob",
271
+ "billing_address": {
272
+ "line1": null,
273
+ "line2": null,
274
+ "city": null,
275
+ "state": null,
276
+ "postal_code": "680121",
277
+ "country": "IN"
278
+ }
279
+ },
241
280
  "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
242
281
  "is_renewal": false,
243
282
  "paid_at": "2026-04-01T17:36:41Z",
@@ -277,6 +316,20 @@ The request body is a JSON object with the following top-level fields:
277
316
  "status": "REFUNDED",
278
317
  "billing_type": "ONE_TIME",
279
318
  "customer_id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
319
+ "customer": {
320
+ "id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
321
+ "name": "Geo Jacob",
322
+ "email": "geojacob@example.com",
323
+ "customer_id": "geo-jacob",
324
+ "billing_address": {
325
+ "line1": null,
326
+ "line2": null,
327
+ "city": null,
328
+ "state": null,
329
+ "postal_code": "680121",
330
+ "country": "IN"
331
+ }
332
+ },
280
333
  "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
281
334
  "is_renewal": false,
282
335
  "paid_at": "2026-04-01T17:36:41Z",
@@ -598,6 +651,20 @@ The request body is a JSON object with the following top-level fields:
598
651
  "due_date": null,
599
652
  "order_id": null,
600
653
  "customer_id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
654
+ "customer": {
655
+ "id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
656
+ "name": "Geo Jacob",
657
+ "email": "geojacob@example.com",
658
+ "customer_id": "geo-jacob",
659
+ "billing_address": {
660
+ "line1": null,
661
+ "line2": null,
662
+ "city": null,
663
+ "state": null,
664
+ "postal_code": "680121",
665
+ "country": "IN"
666
+ }
667
+ },
601
668
  "subscription_id": "a2951973-aca5-408d-bd9c-1d86827ed463",
602
669
  "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
603
670
  "product": {
@@ -628,6 +695,20 @@ The request body is a JSON object with the following top-level fields:
628
695
  "due_date": null,
629
696
  "order_id": null,
630
697
  "customer_id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
698
+ "customer": {
699
+ "id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
700
+ "name": "Geo Jacob",
701
+ "email": "geojacob@example.com",
702
+ "customer_id": "geo-jacob",
703
+ "billing_address": {
704
+ "line1": null,
705
+ "line2": null,
706
+ "city": null,
707
+ "state": null,
708
+ "postal_code": "680121",
709
+ "country": "IN"
710
+ }
711
+ },
631
712
  "subscription_id": "a2951973-aca5-408d-bd9c-1d86827ed463",
632
713
  "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
633
714
  "product": {