@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.
- package/README.md +34 -26
- package/dist/config.d.ts +4 -0
- package/dist/config.js +30 -9
- package/dist/config.js.map +1 -1
- package/dist/docs/backend-integration/better-auth.md +369 -0
- package/dist/docs/backend-integration/node-sdk.md +373 -5
- package/dist/docs/backend-integration/python-sdk.md +444 -6
- package/dist/docs/changelog/api.md +516 -5
- package/dist/docs/changelog/app.md +162 -0
- package/dist/docs/changelog/cli.md +33 -0
- package/dist/docs/changelog/mcp-server.md +23 -0
- package/dist/docs/changelog/node-sdk.md +124 -0
- package/dist/docs/changelog/python-sdk.md +135 -0
- package/dist/docs/checkout/apply-a-discount-code.md +150 -0
- package/dist/docs/checkout/checkout-configuration.md +88 -22
- package/dist/docs/checkout/checkout-metadata.md +219 -0
- package/dist/docs/checkout/static-checkout-url.md +201 -0
- package/dist/docs/cli/commands.md +1 -1
- package/dist/docs/cli/environments.md +17 -9
- package/dist/docs/cli/kelviq-config.md +35 -1
- package/dist/docs/cli/overview.md +2 -0
- package/dist/docs/coustomers-management/overview.md +15 -19
- package/dist/docs/customer-portal/managing-payment-methods.md +30 -48
- package/dist/docs/frontend-integration/react-ui.md +51 -16
- package/dist/docs/getstarted/fees.md +45 -54
- package/dist/docs/getstarted/payment-security-and-seller-funds.md +98 -0
- package/dist/docs/getstarted/review-process.md +3 -3
- package/dist/docs/guides/agent-toolkit.md +143 -0
- package/dist/docs/guides/mcp-server.md +114 -34
- package/dist/docs/guides/migrate-from-cashfree.md +7 -0
- package/dist/docs/guides/sandbox.md +34 -0
- package/dist/docs/guides/subscription-integration-for-nextjs.md +44 -18
- package/dist/docs/guides/subscription-integration.md +28 -4
- package/dist/docs/guides/webhooks.md +367 -6
- package/dist/docs/manifest.json +102 -4
- package/dist/docs/openapi.json +7411 -2648
- package/dist/docs/payouts/overview.md +30 -0
- package/dist/docs/payouts/transactions.md +50 -6
- package/dist/docs/product-catalog/create-a-feature.md +113 -0
- package/dist/docs/product-catalog/create-an-enterprise-plan.md +133 -0
- package/dist/docs/product-catalog/discounts.md +25 -12
- package/dist/docs/product-catalog/entitlements.md +53 -16
- package/dist/docs/product-catalog/free-and-trials.md +8 -4
- package/dist/docs/product-catalog/location-based-pricing.md +2 -0
- package/dist/docs/product-catalog/one-time-payments.md +4 -0
- package/dist/docs/product-catalog/pay-as-you-go.md +177 -0
- package/dist/docs/product-catalog/plans.md +14 -0
- package/dist/docs/product-catalog/products.md +5 -13
- package/dist/docs/product-catalog/seat-based-pricing.md +233 -0
- package/dist/docs/product-catalog/subscriptions.md +109 -12
- package/dist/docs/product-catalog/usage-alerts.md +257 -0
- package/dist/docs/product-catalog/usage-based-billing.md +49 -12
- package/dist/docs/quickstart/dashboard-setup.md +1 -1
- package/dist/docs/sales/abandoned-cart-recovery.md +64 -0
- package/dist/docs/sales/create-a-one-time-charge.md +144 -0
- package/dist/http/client.js +9 -2
- package/dist/http/client.js.map +1 -1
- package/dist/http/errors.d.ts +8 -0
- package/dist/http/errors.js +20 -0
- package/dist/http/errors.js.map +1 -1
- package/dist/server.js +10 -1
- package/dist/server.js.map +1 -1
- 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
|
-
|
|
33
|
+
A production checkout link starts with your product UUID:
|
|
36
34
|
|
|
37
35
|
```
|
|
38
|
-
https://
|
|
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
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
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=
|
|
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
|
|
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
|
-
###
|
|
190
|
+
### Success and Cancellation URLs
|
|
177
191
|
|
|
178
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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=
|
|
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=
|
|
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=
|
|
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 `
|
|
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
|
|