@kelviq/mcp-server 0.4.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/README.md +34 -26
  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/backend-integration/better-auth.md +369 -0
  6. package/dist/docs/backend-integration/node-sdk.md +373 -5
  7. package/dist/docs/backend-integration/python-sdk.md +444 -6
  8. package/dist/docs/changelog/api.md +516 -5
  9. package/dist/docs/changelog/app.md +162 -0
  10. package/dist/docs/changelog/cli.md +33 -0
  11. package/dist/docs/changelog/mcp-server.md +23 -0
  12. package/dist/docs/changelog/node-sdk.md +124 -0
  13. package/dist/docs/changelog/python-sdk.md +135 -0
  14. package/dist/docs/checkout/apply-a-discount-code.md +150 -0
  15. package/dist/docs/checkout/checkout-configuration.md +88 -22
  16. package/dist/docs/checkout/checkout-metadata.md +219 -0
  17. package/dist/docs/checkout/static-checkout-url.md +201 -0
  18. package/dist/docs/cli/commands.md +1 -1
  19. package/dist/docs/cli/environments.md +17 -9
  20. package/dist/docs/cli/kelviq-config.md +35 -1
  21. package/dist/docs/cli/overview.md +2 -0
  22. package/dist/docs/coustomers-management/overview.md +15 -19
  23. package/dist/docs/customer-portal/managing-payment-methods.md +30 -48
  24. package/dist/docs/frontend-integration/react-ui.md +51 -16
  25. package/dist/docs/getstarted/fees.md +45 -54
  26. package/dist/docs/getstarted/payment-security-and-seller-funds.md +98 -0
  27. package/dist/docs/getstarted/review-process.md +3 -3
  28. package/dist/docs/guides/agent-toolkit.md +143 -0
  29. package/dist/docs/guides/mcp-server.md +114 -34
  30. package/dist/docs/guides/migrate-from-cashfree.md +7 -0
  31. package/dist/docs/guides/sandbox.md +34 -0
  32. package/dist/docs/guides/subscription-integration-for-nextjs.md +44 -18
  33. package/dist/docs/guides/subscription-integration.md +28 -4
  34. package/dist/docs/guides/webhooks.md +367 -6
  35. package/dist/docs/manifest.json +102 -4
  36. package/dist/docs/openapi.json +7411 -2648
  37. package/dist/docs/payouts/overview.md +30 -0
  38. package/dist/docs/payouts/transactions.md +50 -6
  39. package/dist/docs/product-catalog/create-a-feature.md +113 -0
  40. package/dist/docs/product-catalog/create-an-enterprise-plan.md +133 -0
  41. package/dist/docs/product-catalog/discounts.md +25 -12
  42. package/dist/docs/product-catalog/entitlements.md +53 -16
  43. package/dist/docs/product-catalog/free-and-trials.md +8 -4
  44. package/dist/docs/product-catalog/location-based-pricing.md +2 -0
  45. package/dist/docs/product-catalog/one-time-payments.md +4 -0
  46. package/dist/docs/product-catalog/pay-as-you-go.md +177 -0
  47. package/dist/docs/product-catalog/plans.md +14 -0
  48. package/dist/docs/product-catalog/products.md +5 -13
  49. package/dist/docs/product-catalog/seat-based-pricing.md +233 -0
  50. package/dist/docs/product-catalog/subscriptions.md +109 -12
  51. package/dist/docs/product-catalog/usage-alerts.md +257 -0
  52. package/dist/docs/product-catalog/usage-based-billing.md +49 -12
  53. package/dist/docs/quickstart/dashboard-setup.md +1 -1
  54. package/dist/docs/sales/abandoned-cart-recovery.md +64 -0
  55. package/dist/docs/sales/create-a-one-time-charge.md +144 -0
  56. package/dist/http/client.js +9 -2
  57. package/dist/http/client.js.map +1 -1
  58. package/dist/http/errors.d.ts +8 -0
  59. package/dist/http/errors.js +20 -0
  60. package/dist/http/errors.js.map +1 -1
  61. package/dist/server.js +10 -1
  62. package/dist/server.js.map +1 -1
  63. package/package.json +1 -1
@@ -28,27 +28,38 @@ Checkout links are generated at the **product level**. Each link can include one
28
28
  4. **Configure options** → Set defaults and features
29
29
  5. **Copy link** → Share with customers
30
30
 
31
- <img height="200" src="/images/generate-checkout.png" />
32
-
33
31
  ### Link Format
34
32
 
35
- Generated checkout links follow this pattern:
33
+ A production checkout link starts with your product UUID:
36
34
 
37
35
  ```
38
- https://checkout.kelviq.com/products/{PRODUCT_ID}
39
- ?enabled={PLAN_1_ID},{PLAN_2_ID}
40
- &plan_identifier={DEFAULT_PLAN_ID}
41
- &charge_period={DEFAULT_PERIOD}
36
+ https://www.kelviq.com/buy/{PRODUCT_UUID}/
42
37
  ```
43
38
 
44
- Example:
45
- ```
46
- https://checkout.kelviq.com/products/prod_abc123
47
- ?enabled=plan_basic,plan_pro
48
- &plan_identifier=plan_pro
49
- &charge_period=monthly
39
+ Sandbox links use `https://www.kelviq.com/sandbox/buy/{PRODUCT_UUID}/`. Copy the link from the dashboard so the environment and product UUID are correct. The old product identifier is not used in checkout URLs.
40
+
41
+ Add query parameters to control what the customer sees:
42
+
43
+ | Parameter | What it controls | Example |
44
+ | --- | --- | --- |
45
+ | `enabled` | Comma-separated plan identifiers shown at checkout | `basic,pro` |
46
+ | `plan_identifier` | Plan selected when checkout opens | `pro` |
47
+ | `charge_period` | Billing period selected when checkout opens | `MONTHLY` |
48
+ | `discounts_enabled` | Whether the discount-code field is available | `true` |
49
+ | `discount_code` | A valid discount code to apply automatically | `LAUNCH20` |
50
+ | `customer_id` | Customer record associated with checkout | `cust_789` |
51
+ | `success_url` | Where to send the customer after a successful checkout | `https://example.com/checkout/success` |
52
+
53
+ For example:
54
+
55
+ ```text
56
+ https://www.kelviq.com/buy/123e4567-e89b-12d3-a456-426614174000/?enabled=basic,pro&plan_identifier=pro&charge_period=MONTHLY&discounts_enabled=true&discount_code=LAUNCH20&customer_id=cust_789&success_url=https%3A%2F%2Fexample.com%2Fcheckout%2Fsuccess
50
57
  ```
51
58
 
59
+ URL-encode `success_url` and any other parameter value that contains reserved characters.
60
+
61
+ [See every supported static checkout parameter and complete examples →](/checkout/static-checkout-url)
62
+
52
63
  ## Multi-Plan Checkout
53
64
 
54
65
  Include multiple plans in a single checkout to let customers choose their tier.
@@ -97,9 +108,12 @@ Plans in Kelviq can support multiple billing periods:
97
108
  |--------|----------|----------|
98
109
  | **Monthly** | 1 month | Recurring subscriptions |
99
110
  | **3 Months** | 3 months | Quarterly billing |
111
+ | **6 Months** | 6 months | Biannual billing |
100
112
  | **Yearly** | 12 months | Annual billing, often with discounts |
101
113
  | **One Time** | One-off payment | Digital products, courses, lifetime access |
102
114
 
115
+ We can also add custom billing periods such as weekly, daily, or 28 days upon request. Contact [hi@kelviq.com](mailto:hi@kelviq.com) to enable these options.
116
+
103
117
  ### Setting Default Billing Period
104
118
 
105
119
  Configure which billing period is pre-selected for each plan:
@@ -113,7 +127,7 @@ Plan: Pro
113
127
 
114
128
  In your checkout link:
115
129
  ```
116
- &charge_period=monthly
130
+ &charge_period=MONTHLY
117
131
  ```
118
132
 
119
133
  ### Pricing by Period
@@ -144,7 +158,7 @@ Offer free trial periods before charging customers.
144
158
 
145
159
  1. **Open your plan** → Go to the plan's pricing section
146
160
  2. **Enable Free Trial** → Toggle the trial option
147
- 3. **Set duration** → 1-365 days (default 30)
161
+ 3. **Set duration** → 1-365 days (default 7 days)
148
162
  4. **Save plan**
149
163
 
150
164
  ### Trial Behavior
@@ -173,9 +187,9 @@ Plan: Professional
173
187
 
174
188
  ## Advanced Checkout Configuration
175
189
 
176
- ### Custom Return URL
190
+ ### Success and Cancellation URLs
177
191
 
178
- After checkout succeeds, redirect customers to your custom URL:
192
+ The success URL is optional when you link to or embed Kelviq Checkout directly. Add it only when you want Kelviq to redirect the customer to your own confirmation or onboarding page after checkout succeeds:
179
193
 
180
194
  ```
181
195
  Customer completes purchase
@@ -189,9 +203,54 @@ You can:
189
203
  - Continue onboarding
190
204
  ```
191
205
 
192
- Configure in your checkout link via API or dashboard:
206
+ For a static checkout link, add the URL-encoded `success_url` parameter when you want this redirect:
207
+
208
+ ```text
209
+ &success_url=https%3A%2F%2Fyourdomain.com%2Fcheckout-success
193
210
  ```
194
- &return_url=https://yourdomain.com/checkout-success
211
+
212
+ When creating a checkout session through the API, the `successUrl` field is required. You can also optionally provide a `cancelUrl` to redirect the customer if they cancel payment.
213
+
214
+ ### Checkout Session Options
215
+
216
+ `POST /api/v1/checkout/` accepts options that let you tailor a checkout session without changing the underlying plan.
217
+
218
+ | Field | What it does |
219
+ | --- | --- |
220
+ | `successUrl` | Redirects the customer after a successful checkout |
221
+ | `cancelUrl` | Redirects the customer if payment is cancelled |
222
+ | `plansEnabled` | Limits checkout to a comma-separated list of plan identifiers |
223
+ | `discountsEnabled` | Shows or hides discount-code entry; defaults to `true` |
224
+ | `discountCode` | Applies a valid discount code before checkout opens |
225
+ | `lockEmail` | Prevents the customer from changing the pre-filled email address |
226
+ | `defaultBillingCountry` | Pre-fills the billing country using a two-letter ISO country code |
227
+ | `currencyCode`, `customAmount`, `taxBehavior` | Sets a custom charge and its tax treatment |
228
+ | `metadata` | Attaches your own key-value data to the checkout session |
229
+
230
+ For a complete request, webhook example, and implementation guidance, see [Add metadata to checkout](/checkout/checkout-metadata).
231
+
232
+ ```javascript
233
+ const response = await fetch("https://api.kelviq.com/api/v1/checkout/", {
234
+ method: "POST",
235
+ headers: {
236
+ "Content-Type": "application/json",
237
+ Authorization: `Bearer ${process.env.KELVIQ_SERVER_API_KEY}`,
238
+ },
239
+ body: JSON.stringify({
240
+ planIdentifier: "pro",
241
+ chargePeriod: "MONTHLY",
242
+ customerId: "customer-123",
243
+ successUrl: "https://example.com/checkout/success",
244
+ cancelUrl: "https://example.com/pricing",
245
+ plansEnabled: "basic,pro",
246
+ discountsEnabled: true,
247
+ discountCode: "LAUNCH20",
248
+ lockEmail: true,
249
+ defaultBillingCountry: "US",
250
+ }),
251
+ });
252
+
253
+ const { checkoutUrl } = await response.json();
195
254
  ```
196
255
 
197
256
  ### Discount Code Integration
@@ -210,6 +269,8 @@ Customer at checkout:
210
269
 
211
270
  Discount codes are applied automatically if the customer enters a valid code.
212
271
 
272
+ [See API and static-link examples for applying a discount code →](/checkout/apply-a-discount-code)
273
+
213
274
  ### Tax Collection
214
275
 
215
276
  Kelviq can collect and handle taxes:
@@ -331,7 +392,7 @@ Product: My Course
331
392
  ├─ Plan: Full Access ($49)
332
393
  └─ Billing: One-time payment
333
394
 
334
- Link: ?enabled=full_access&plan_identifier=full_access&charge_period=one_time
395
+ Link: ?enabled=full_access&plan_identifier=full_access&charge_period=ONE_TIME
335
396
  ```
336
397
 
337
398
  ### Example 2: Tiered Plans
@@ -346,7 +407,7 @@ Product: Pro Templates
346
407
 
347
408
  Link: ?enabled=starter,pro,enterprise
348
409
  &plan_identifier=pro
349
- &charge_period=monthly
410
+ &charge_period=MONTHLY
350
411
  ```
351
412
 
352
413
  ### Example 3: Free + Paid
@@ -360,7 +421,7 @@ Product: Productivity App
360
421
 
361
422
  Link: ?enabled=free,premium
362
423
  &plan_identifier=free
363
- &charge_period=monthly
424
+ &charge_period=MONTHLY
364
425
  ```
365
426
 
366
427
  ## Payment Methods
@@ -369,6 +430,7 @@ Kelviq uses **Stripe** as its payment processor. Stripe supports:
369
430
 
370
431
  - **Credit/Debit Cards** - Visa, Mastercard, American Express, Discover
371
432
  - **Digital Wallets** - Apple Pay, Google Pay
433
+ - **UPI and UPI AutoPay** - UPI payments and recurring subscription mandates for eligible customers in India
372
434
  - **Bank Transfers** - ACH, SEPA, etc. (regional)
373
435
  - **Local Methods** - iDEAL, Bancontact, Giropay, EPS (regional)
374
436
 
@@ -376,6 +438,10 @@ Customers select their preferred payment method at checkout.
376
438
 
377
439
  Payment method availability depends on customer location and Stripe's local support. Cards are universally supported.
378
440
 
441
+ ### Does Kelviq support UPI AutoPay?
442
+
443
+ Yes. Kelviq supports UPI AutoPay for recurring subscriptions. Eligible customers in India can authorize the recurring payment at checkout. Availability depends on support from the customer's bank and UPI app.
444
+
379
445
  ## Currency & Localization
380
446
 
381
447
  ### Multi-Currency Support
@@ -0,0 +1,219 @@
1
+ ---
2
+ title: "Add metadata to checkout"
3
+ slug: "checkout/checkout-metadata"
4
+ section: "checkout"
5
+ description: "Attach your own IDs and context to a checkout session, then read them from the checkout.completed webhook"
6
+ ---
7
+ Metadata lets you carry context from your application through a Kelviq checkout. Add an object when you create the session, and Kelviq returns the same object in the `checkout.completed` webhook.
8
+
9
+ A common example is an order reference:
10
+
11
+ ```json
12
+ {
13
+ "metadata": {
14
+ "order_ref": "ABC-123",
15
+ "workspace_id": "ws_acme",
16
+ "source": "pricing_page"
17
+ }
18
+ }
19
+ ```
20
+
21
+ Use metadata for values that help your backend connect a completed checkout to its own records, such as an internal order ID, workspace ID, campaign, or signup source.
22
+
23
+ Do not put API keys, passwords, card details, or other sensitive information in metadata. Metadata is returned in webhook payloads and may appear in operational logs.
24
+
25
+ ## Before you start
26
+
27
+ You need:
28
+
29
+ - a server API key from **Settings → API Keys**;
30
+ - a plan identifier and supported charge period;
31
+ - a backend endpoint that creates checkout sessions.
32
+
33
+ A webhook endpoint is optional. Subscribe it to `checkout.completed` if you want to receive the metadata when checkout finishes.
34
+
35
+ Keep the server API key in your backend. Never expose it in browser or mobile code.
36
+
37
+ ## Add metadata when creating the session
38
+
39
+ Pass `metadata` at the top level of the Checkout API request body. Kelviq preserves the keys exactly as supplied, so `order_ref` and `orderRef` are different keys.
40
+
41
+ ```bash cURL
42
+ curl --request POST \
43
+ --url https://sandboxapi.kelviq.com/api/v1/checkout/ \
44
+ --header "Authorization: Bearer $KELVIQ_SANDBOX_SERVER_API_KEY" \
45
+ --header "Content-Type: application/json" \
46
+ --data '{
47
+ "planIdentifier": "pro",
48
+ "chargePeriod": "MONTHLY",
49
+ "customerId": "cust_789",
50
+ "successUrl": "https://example.com/checkout/success",
51
+ "metadata": {
52
+ "order_ref": "ABC-123",
53
+ "workspace_id": "ws_acme",
54
+ "source": "pricing_page"
55
+ }
56
+ }'
57
+ ```
58
+
59
+ ```typescript Node.js SDK
60
+ import { Kelviq, CHARGE_PERIOD_CHOICES } from "@kelviq/node-sdk";
61
+
62
+ const client = new Kelviq({
63
+ accessToken: process.env.KELVIQ_SANDBOX_SERVER_API_KEY,
64
+ });
65
+
66
+ const session = await client.checkout.createSession({
67
+ planIdentifier: "pro",
68
+ chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
69
+ customerId: "cust_789",
70
+ successUrl: "https://example.com/checkout/success",
71
+ metadata: {
72
+ order_ref: "ABC-123",
73
+ workspace_id: "ws_acme",
74
+ source: "pricing_page",
75
+ },
76
+ });
77
+ ```
78
+
79
+ ```python Python SDK
80
+ import os
81
+ from kelviq_sdk import Kelviq
82
+
83
+ client = Kelviq.create_sync_client(
84
+ access_token=os.environ["KELVIQ_SANDBOX_SERVER_API_KEY"]
85
+ )
86
+
87
+ session = client.checkout.create_session(
88
+ planIdentifier="pro",
89
+ chargePeriod="MONTHLY",
90
+ customerId="cust_789",
91
+ successUrl="https://example.com/checkout/success",
92
+ metadata={
93
+ "order_ref": "ABC-123",
94
+ "workspace_id": "ws_acme",
95
+ "source": "pricing_page",
96
+ },
97
+ )
98
+ ```
99
+
100
+ The response contains the hosted checkout URL and the Kelviq session ID:
101
+
102
+ ```json
103
+ {
104
+ "checkoutUrl": "https://kelviq.com/checkout/cs_eeCGdGayc5oTMdGNV5XocfRk6o87K0vlwwCuKeiE7BLU9/",
105
+ "checkoutSessionId": "cs_eeCGdGayc5oTMdGNV5XocfRk6o87K0vlwwCuKeiE7BLU9"
106
+ }
107
+ ```
108
+
109
+ Redirect the customer to `checkoutUrl`. The create response does not echo the metadata, so save `checkoutSessionId` alongside your internal record if you also need to look up the Kelviq session later.
110
+
111
+ This guide uses the sandbox host and a sandbox server API key. Switch both to production together when you are ready to accept live payments.
112
+
113
+ ## Read metadata after checkout
114
+
115
+ When payment succeeds, the `checkout.completed` event includes the metadata at `data.object.metadata`:
116
+
117
+ ```json
118
+ {
119
+ "id": "1619afec-caab-40c7-827c-6af4f3acc9a3",
120
+ "type": "checkout.completed",
121
+ "data": {
122
+ "object": {
123
+ "id": "cs_jBy6ViggULoyDMW9ikaw4ydur1NUa6dCORT6vqKPbPPW8",
124
+ "metadata": {
125
+ "order_ref": "ABC-123",
126
+ "workspace_id": "ws_acme",
127
+ "source": "pricing_page"
128
+ }
129
+ }
130
+ }
131
+ }
132
+ ```
133
+
134
+ Verify the webhook signature before reading or acting on the payload. After verification, you can use the metadata to find the matching record in your system:
135
+
136
+ ```typescript
137
+ import { validateEvent } from "@kelviq/node-sdk";
138
+ import express from "express";
139
+
140
+ const app = express();
141
+
142
+ app.post(
143
+ "/webhooks/kelviq",
144
+ express.raw({ type: "application/json" }),
145
+ async (req, res) => {
146
+ let event;
147
+
148
+ try {
149
+ event = validateEvent(
150
+ req.body,
151
+ req.headers,
152
+ process.env.KELVIQ_WEBHOOK_SECRET,
153
+ );
154
+ } catch {
155
+ return res.status(400).send("Invalid webhook signature");
156
+ }
157
+
158
+ if (event.type === "checkout.completed") {
159
+ const metadata = event.data.object.metadata ?? {};
160
+
161
+ // Replace this with your queue or application service.
162
+ await queueCheckoutProvisioning({
163
+ eventId: event.id,
164
+ orderRef: metadata.order_ref,
165
+ checkoutSessionId: event.data.object.id,
166
+ });
167
+ }
168
+
169
+ return res.sendStatus(202);
170
+ },
171
+ );
172
+ ```
173
+
174
+ Use the webhook event `id`, not a metadata value, as your idempotency key. Kelviq can deliver the same event more than once during automatic retries or a manual resend.
175
+
176
+ [Learn how to register an endpoint and verify signatures →](/guides/webhooks)
177
+
178
+ ## Choose useful metadata
179
+
180
+ Keep the object small and focused on correlation. A stable naming convention makes webhook handlers easier to maintain.
181
+
182
+ | Value | Example | Why keep it |
183
+ | --- | --- | --- |
184
+ | Internal order reference | `order_ref: "ABC-123"` | Finds the pending order in your database |
185
+ | Account or workspace ID | `workspace_id: "ws_acme"` | Connects the purchase to the right tenant |
186
+ | Signup source | `source: "pricing_page"` | Records where the checkout started |
187
+ | Campaign reference | `campaign: "launch_2026"` | Attributes the checkout to a campaign |
188
+
189
+ Metadata is helpful context, but it is not proof of payment or authorization. Confirm `event.type`, verify the signature, and use Kelviq's resource IDs when calling Kelviq APIs.
190
+
191
+ ### Checkout metadata and customer metadata are different
192
+
193
+ Checkout metadata describes one checkout session. Customer metadata describes the customer record and can be managed through the Customers API. Adding metadata to a checkout session does not replace or update customer metadata.
194
+
195
+ ## Test the complete flow
196
+
197
+ 1. Create a session with a sandbox server API key and recognizable test metadata.
198
+ 2. Open the returned `checkoutUrl` and complete a sandbox payment.
199
+ 3. Open **Settings → Webhooks**, then inspect the `checkout.completed` delivery.
200
+ 4. Confirm that `data.object.metadata` contains the same keys and values.
201
+ 5. Resend the delivery and confirm that your idempotency check prevents duplicate work.
202
+
203
+ ## Troubleshooting
204
+
205
+ | Problem | Check |
206
+ | --- | --- |
207
+ | Metadata is missing from the webhook | Make sure `metadata` is at the top level of the checkout request and that you are inspecting `checkout.completed`. |
208
+ | A handler cannot find a key | Key names are preserved verbatim. Check spelling, capitalization, and underscores. |
209
+ | The request returns `401` | Use a server API key for the same environment as the API host. |
210
+ | Signature verification fails | Verify the raw request body before JSON parsing. In Express, use `express.raw()` on the webhook route. |
211
+ | Provisioning runs twice | Deduplicate by the event `id` or `webhook-id`, including deliveries triggered by **Resend**. |
212
+
213
+ ## Related documentation
214
+
215
+ - [Checkout configuration](/checkout/checkout-configuration)
216
+ - [Checkout API reference](/api-reference/checkout/create-a-checkout-session)
217
+ - [Webhooks](/guides/webhooks)
218
+ - [Node SDK](/backend-integration/node-sdk)
219
+ - [Python SDK](/backend-integration/python-sdk)
@@ -0,0 +1,201 @@
1
+ ---
2
+ title: "Customize a static checkout URL"
3
+ slug: "checkout/static-checkout-url"
4
+ section: "checkout"
5
+ description: "Choose plans, set a billing period, attach a customer, apply a discount, and control the success redirect in a Kelviq checkout link"
6
+ ---
7
+ A static checkout URL is a shareable link for one published product. You can use the link exactly as Kelviq generates it, or add query parameters to control what the customer sees when checkout opens.
8
+
9
+ Static links work well on pricing pages, in emails, and behind a purchase button. If the checkout needs data that only your backend knows, use the [Checkout API](/api-reference/checkout/create-a-checkout-session) instead.
10
+
11
+ ## Copy the checkout URL
12
+
13
+ 1. Open **Product Catalog → Products**.
14
+ 2. Select a published product.
15
+ 3. Click **Get link** or **Copy checkout link**.
16
+ 4. Choose the plans and default billing period.
17
+ 5. Copy the generated URL.
18
+
19
+ Production links use this format:
20
+
21
+ ```text
22
+ https://www.kelviq.com/buy/{PRODUCT_UUID}/
23
+ ```
24
+
25
+ Sandbox links include `/sandbox/`:
26
+
27
+ ```text
28
+ https://www.kelviq.com/sandbox/buy/{PRODUCT_UUID}/
29
+ ```
30
+
31
+ The product UUID is part of the copied link. Do not replace it with the old product identifier.
32
+
33
+ ## Available query parameters
34
+
35
+ The dashboard adds the plan, billing-period, and discount options you select. You can add `customer_id` and `success_url` when your integration needs them.
36
+
37
+ | Parameter | Value | What it changes |
38
+ | --- | --- | --- |
39
+ | `enabled` | Comma-separated plan identifiers | Limits checkout to the listed plans |
40
+ | `plan_identifier` | One plan identifier | Selects the plan shown first |
41
+ | `charge_period` | A supported billing-period value | Selects the initial billing period |
42
+ | `discounts_enabled` | `true` or `false` | Shows or hides discount-code entry |
43
+ | `discount_code` | An active discount code | Applies the code when checkout opens |
44
+ | `customer_id` | Your unique customer ID | Links checkout to a specific customer record |
45
+ | `success_url` | A URL-encoded URL | Redirects the customer after successful checkout |
46
+
47
+ Use these values for `charge_period`:
48
+
49
+ | Value | Billing period |
50
+ | --- | --- |
51
+ | `ONE_TIME` | One-time payment |
52
+ | `DAILY` | Daily |
53
+ | `WEEKLY` | Weekly |
54
+ | `TWENTY_EIGHT_DAYS` | Every 28 days |
55
+ | `MONTHLY` | Monthly |
56
+ | `THREE_MONTHS` | Every three months |
57
+ | `SIX_MONTHS` | Every six months |
58
+ | `YEARLY` | Yearly |
59
+
60
+ The selected plan must support the selected period. If you use `enabled`, include the value from `plan_identifier` in that list.
61
+
62
+ ## Build a link safely
63
+
64
+ Use `?` before the first query parameter and `&` before each additional parameter:
65
+
66
+ ```text
67
+ https://www.kelviq.com/buy/{PRODUCT_UUID}/?enabled=starter,pro&plan_identifier=pro&charge_period=MONTHLY
68
+ ```
69
+
70
+ Using `URL` and `URLSearchParams` is safer than joining strings by hand. It handles characters that must be encoded:
71
+
72
+ ```javascript
73
+ const checkoutUrl = new URL(
74
+ "https://www.kelviq.com/buy/{PRODUCT_UUID}/",
75
+ );
76
+
77
+ checkoutUrl.searchParams.set("enabled", "starter,pro");
78
+ checkoutUrl.searchParams.set("plan_identifier", "pro");
79
+ checkoutUrl.searchParams.set("charge_period", "MONTHLY");
80
+ checkoutUrl.searchParams.set("discounts_enabled", "true");
81
+ checkoutUrl.searchParams.set("discount_code", "LAUNCH20");
82
+ checkoutUrl.searchParams.set("customer_id", "cust_789");
83
+ checkoutUrl.searchParams.set(
84
+ "success_url",
85
+ "https://example.com/checkout/success",
86
+ );
87
+
88
+ console.log(checkoutUrl.toString());
89
+ ```
90
+
91
+ The resulting URL is equivalent to:
92
+
93
+ ```text
94
+ https://www.kelviq.com/buy/{PRODUCT_UUID}/?enabled=starter%2Cpro&plan_identifier=pro&charge_period=MONTHLY&discounts_enabled=true&discount_code=LAUNCH20&customer_id=cust_789&success_url=https%3A%2F%2Fexample.com%2Fcheckout%2Fsuccess
95
+ ```
96
+
97
+ ## Common configurations
98
+
99
+ ### Select a plan and billing period
100
+
101
+ Show the Starter and Pro plans, with Pro monthly selected when checkout opens:
102
+
103
+ ```text
104
+ ?enabled=starter,pro&plan_identifier=pro&charge_period=MONTHLY
105
+ ```
106
+
107
+ ### Hide discount-code entry
108
+
109
+ ```text
110
+ ?discounts_enabled=false
111
+ ```
112
+
113
+ `discounts_enabled` defaults to `true`.
114
+
115
+ ### Apply a discount code
116
+
117
+ ```text
118
+ ?discounts_enabled=true&discount_code=LAUNCH20
119
+ ```
120
+
121
+ The discount must be active and valid for the selected product, plan, currency, and date. [Learn how checkout discounts work →](/checkout/apply-a-discount-code)
122
+
123
+ ### Link checkout to a customer
124
+
125
+ ```text
126
+ ?customer_id=cust_789
127
+ ```
128
+
129
+ Use the stable, unique customer ID from your application. When the customer record already has an email address, Kelviq can prefill it at checkout.
130
+
131
+ A customer-specific URL should not be published as a general checkout link. Query parameters can appear in browser history, analytics, and server logs. Use an opaque customer ID and never put an email address, API key, or secret in the URL.
132
+
133
+ ### Redirect after successful checkout
134
+
135
+ ```text
136
+ ?success_url=https%3A%2F%2Fexample.com%2Fcheckout%2Fsuccess
137
+ ```
138
+
139
+ Encode the full destination URL. In JavaScript, `URLSearchParams` does this for you. In other environments, use the standard URL-encoding function provided by the language or framework.
140
+
141
+ A visit to `success_url` is not proof of payment. Customers can open that page directly. Confirm payment through `checkout.completed`, the resulting subscription or order, or a current entitlement check.
142
+
143
+ ## Static URL names and API names
144
+
145
+ Static checkout links use snake_case query parameters. The Checkout API and backend SDKs use camelCase request fields.
146
+
147
+ | Static URL | Checkout API or SDK |
148
+ | --- | --- |
149
+ | `enabled` | `plansEnabled` |
150
+ | `plan_identifier` | `planIdentifier` |
151
+ | `charge_period` | `chargePeriod` |
152
+ | `discounts_enabled` | `discountsEnabled` |
153
+ | `discount_code` | `discountCode` |
154
+ | `customer_id` | `customerId` |
155
+ | `success_url` | `successUrl` |
156
+
157
+ Do not put camelCase names into the URL. For example, `successUrl` belongs in an API request; `success_url` belongs in a static checkout URL.
158
+
159
+ ## When to use the Checkout API
160
+
161
+ Use the Checkout API or a backend SDK when you need per-session options that are not part of the static URL contract, including:
162
+
163
+ - a cancellation URL;
164
+ - feature quantities;
165
+ - location-based pricing through the customer's IP address;
166
+ - custom amounts, currency, or tax behavior;
167
+ - a locked email or default billing country; or
168
+ - checkout metadata for webhook correlation.
169
+
170
+ The API creates a short-lived checkout session and returns `checkoutUrl` and `checkoutSessionId`. Keep the server API key on your backend.
171
+
172
+ [Create a checkout session with the API →](/api-reference/checkout/create-a-checkout-session)
173
+
174
+ ## Test the link
175
+
176
+ 1. Enter sandbox mode and copy a sandbox checkout link.
177
+ 2. Add one customization at a time.
178
+ 3. Open the link and confirm the visible plans, selected period, discount behavior, and customer details.
179
+ 4. Complete a sandbox checkout.
180
+ 5. Confirm the success redirect and the `checkout.completed` webhook.
181
+
182
+ Keep sandbox products, customers, discounts, and API credentials together. A live customer ID or discount code will not work against a sandbox checkout.
183
+
184
+ ## Troubleshooting
185
+
186
+ | Problem | Check |
187
+ | --- | --- |
188
+ | A parameter is ignored | Match the snake_case name exactly. Query parameter names are case-sensitive. |
189
+ | The wrong billing period opens | Use an uppercase value such as `MONTHLY`, and confirm that the selected plan supports it. |
190
+ | The default plan is not available | Add that plan identifier to `enabled`, or remove `enabled` to show every available plan. |
191
+ | The success URL breaks the checkout link | URL-encode the complete value instead of inserting an unescaped URL. |
192
+ | A discount does not apply | Check its status, dates, redemption limit, product and plan restrictions, and currency. |
193
+ | The wrong customer is selected | Check `customer_id` and make sure the customer exists in the same environment as the checkout link. |
194
+ | A sandbox link cannot find live data | Create or select the matching record in sandbox. Sandbox and production data are separate. |
195
+
196
+ ## Related documentation
197
+
198
+ - [Checkout configuration](/checkout/checkout-configuration)
199
+ - [Apply a discount code at checkout](/checkout/apply-a-discount-code)
200
+ - [Add metadata to checkout](/checkout/checkout-metadata)
201
+ - [Webhooks](/guides/webhooks)
@@ -117,7 +117,7 @@ kelviq pull --force # overwrite an existing file
117
117
 
118
118
  What it fetches: all products, all features, the **latest version** of each plan, and each plan's prices and entitlements. Every cross-reference in the generated file uses `identifier` slugs, never UUIDs — the file is stable across environments that share identifiers.
119
119
 
120
- On success, `pull` prints the path it wrote and a **warnings list** for anything it couldn't represent in the config format (for example, plan fields like `license`, `links`, `countries`, and `files` are dropped, with one warning each). Warnings are informational — the file it wrote is still valid.
120
+ On success, `pull` prints the path it wrote and a **warnings list** for anything it couldn't represent in the config format (for example, plan fields like `links`, `countries`, and `files` are dropped, with one warning each; a plan's `license` settings are pulled into the file). Warnings are informational — the file it wrote is still valid.
121
121
 
122
122
  On failure — missing key, network error, unexpected API response — `pull` writes `pull failed: <reason>` to stderr and exits non-zero without touching the output file.
123
123